mcp

Documentation

Overview

Package mcp implements the csx MCP stdio server (plan contract C8, goal.md §12.4): newline-delimited JSON-RPC 2.0 over a provided reader and writer, exposing the eight local tools coding agents consume. The server is transport-only here; the actual behavior is injected through Deps so the daemonless in-process wiring (NewDeps) and tests share one protocol path. `publish_public_sample` is deliberately absent — MCP must never be able to publish autonomously (goal.md §3.11, §12.4).

Index

• Constants
• func SetUpdateNotice(text string)
• type Deps
  • func NewDeps(home string) (*Deps, func() error, error)
• type PackageOverview
• type Server
  • func (s *Server) Serve(ctx context.Context) error

Constants

const ProtocolVersion = "2025-06-18"

ProtocolVersion is the MCP protocol revision this server speaks.

const ServerName = "codesamplex"

ServerName is the serverInfo.name reported by initialize.

Functions

func SetUpdateNotice

func SetUpdateNotice(text string)

SetUpdateNotice records that a verified replacement is on disk. The stdio process remains client-owned and deliberately never terminates itself.

Types

type Deps

type Deps struct {
	// Search runs the C7 pipeline over the local store. offerID is an opaque
	// local-only capability for the recorded top result; it is empty on a
	// miss or when local recording failed.
	Search func(ctx context.Context, req domain.SearchRequest) (resp domain.SearchResponse, offerID string)
	// GetSample returns a cached sample's manifest and its files
	// (path → content, ≤64KB per file, binaries skipped).
	GetSample func(ctx context.Context, id string) (domain.SampleManifest, map[string]string, error)
	// Explain renders a compatibility explanation for one package/symbol
	// from locally cached shards, with observation and verification
	// evidence kept separate. snapshot is the underlying JSON (may be null).
	Explain func(ctx context.Context, purl, symbol string, env domain.EnvironmentFingerprint) (text string, snapshot json.RawMessage, err error)
	// Overview summarizes cached evidence for several packages at once. It
	// turns a search miss into a useful answer instead of an empty one; nil
	// simply falls back to the bare NO_SAFE_MATCH text.
	Overview func(ctx context.Context, purls []string, env domain.EnvironmentFingerprint) ([]PackageOverview, error)
	// LocalReadiness reports the install mode and how many compatibility
	// shards are cached. An agent launched straight from a registry — with
	// the binary but no `csx init` — would otherwise see every search miss
	// with no way to tell an empty cache from an empty network.
	LocalReadiness func(ctx context.Context) (mode string, shards int, err error)
	// RunObserved wraps one command in the evidence loop (scan → run →
	// record). sanitized carries only sanitizer output — never raw stderr.
	RunObserved func(ctx context.Context, argv []string, cwd string) (exitCode int, stage, result string, sanitized []string, err error)
	// ReportAdoption records what happened to a returned sample. The outcome
	// can call a failure "avoided" only when the local correlation proves all
	// four stages; the upload remains the existing anonymous adoption event.
	ReportAdoption func(ctx context.Context, offerID, sampleID string, applied bool, buildPass *bool) (localdb.InterventionOutcome, error)
	// Propose builds a sanitized clean-room spec + prompt and creates an
	// empty workspace. It NEVER publishes (goal.md §12.4).
	Propose func(ctx context.Context, goal string, pkgs, symbols []string) (spec samples.SanitizedSpec, prompt string, workdir string, err error)
	// LocalHits lists recent local search hits.
	LocalHits func(ctx context.Context) ([]localdb.HitRow, error)
	// LocalStats returns the local dashboard stats.
	LocalStats func(ctx context.Context) (map[string]any, error)
	// MachineEnv reports this host's environment. nil means collect it.
	MachineEnv func(ctx context.Context) domain.EnvironmentFingerprint
	// Mode reports the configured mode ("community", "local-only", or "").
	// Tools consult it before telling a caller that anything will be sent.
	Mode func() string
}

Deps injects tool behavior into the transport so tests fake it and the real wiring (NewDeps) stays daemon-free. Every function takes the request context; none may retain it.

func NewDeps

func NewDeps(home string) (*Deps, func() error, error)

NewDeps wires the real tool implementations over one CSX home, the same stores the daemon uses but constructed in-process — the MCP server keeps working with no daemon running (goal.md §3.9). The returned close func releases the database handle.

type PackageOverview

type PackageOverview struct {
	PURL         string  `json:"purl"`
	Cached       bool    `json:"cached"`
	Observations int64   `json:"observations"`
	PeerBuckets  int64   `json:"peerBuckets"`
	PassRate     float64 `json:"passRate"`
	Samples      int     `json:"samples"`
	TopFailure   string  `json:"topFailure,omitempty"`
}

PackageOverview is the compact "what does the network know about this package" summary attached to a miss. Counts are observation evidence: projects that compiled with the package present, never proof that a specific symbol executed (goal.md §3.5).

type Server

type Server struct {
	In      io.Reader
	Out     io.Writer
	Deps    *Deps
	Version string
	// contains filtered or unexported fields
}

Server serves MCP over In/Out. Deps supplies tool behavior; Version is the build stamp reported in serverInfo (default "dev").

func (*Server) Serve

func (s *Server) Serve(ctx context.Context) error

Serve reads newline-delimited JSON-RPC requests until In reaches EOF. Requests are handled serially (permitted by C8: arrival may be concurrent, serial handling is fine). Handler panics never kill the transport; they surface as -32603 responses.