mcp

func BuildServer ¶

func BuildServer(hasIndex bool, companions map[string]bool, repoPath, startPath string, opts ...Option) *mcp.Server

BuildServer constructs the stdio MCP server with startup-time conditional tool registration (D-08a, Pattern 3): hasIndex gates whether ANY tool is registered at all (MCP-03 — zero tools when no .codegraph/ resolves, though MCP init still completes successfully), companions names which of the 7 companion tools register beyond the always-visible codegraph_explore.

companions is a RESOLVED set, never a raw environment value: this function has no opinion about defaults, and in particular does not treat an empty map as "the caller didn't say, so give them everything." ResolveCompanions owns that decision, and an empty map here means exactly what it says — register codegraph_explore and nothing else.

repoPath and startPath are DELIBERATELY DISTINCT (CR-01, the Phase-1 CR-02 recurrence this parameter split fixes): repoPath is the confinement root — the RESOLVED index root every handler's confineToRepoRoot check anchors against, rejecting any client-supplied "path" argument that resolves outside it (CR-02/tools.go's trust boundary) — while startPath is the CALLER'S actual starting directory (serve.go's `start`, before ResolveCodegraphDir's upward walk), the value every handler falls back to when the caller omits "path" and the value that must reach query.OpenAt for WorktreeMismatch to have anything to compare. Because repoPath is always startPath itself or an ANCESTOR of it (it is ResolveCodegraphDir(startPath)'s own return value), confining the default startPath to repoPath always succeeds structurally — only an explicit, client-supplied "path" redirecting elsewhere can ever be rejected.

opts is variadic (SDK-02/VRFY-03) specifically so every pre-existing positional call site (17 of them, all in tests, as of this change) keeps compiling unchanged — only NewStdioServer, this file's one production caller, passes WithSessionLog.

func ParseToolFilter ¶ added in v0.6.0

func ParseToolFilter(value string) (selected map[string]bool, unknown []string)

ParseToolFilter splits a SET CODEGRAPH_MCP_TOOLS value on commas, trims whitespace around each entry, and classifies each non-empty name against companionNames. Recognized names are returned in selected (selected[name] == true); unrecognized names are returned in unknown, in the order they were seen, for the caller to warn about via WarnToolFilterTo — ParseToolFilter itself never writes output or aborts, so an unknown name can never fail startup (MCP-02: "unknown names ignored with a stderr warning").

Callers should not reach for this directly: ResolveCompanions is the seam that knows an UNSET variable means something entirely different from an empty one. This function only ever sees the set case.

func ResolveCompanions ¶ added in v0.6.0

func ResolveCompanions(value string, present bool) (companions map[string]bool, unknown []string)

ResolveCompanions decides which of the 7 companion tools register, from the raw CODEGRAPH_MCP_TOOLS value and whether that variable was SET AT ALL. It is the ONE place the default lives; BuildServer knows only "here is the companion set", never how it was derived.

present is load-bearing and MUST come from os.LookupEnv — never from a `value != ""` test. Under narrowing semantics "unset" and "set to the empty string" are two DIFFERENT answers (all 7 companions vs none), and os.Getenv collapses them into the same empty string. That collapse is the single most fragile point of this inversion, which is why the distinction is a parameter rather than an inference.

Semantics (superseding the pre-inversion opt-in allowlist, which made codegraph_explore the only default-visible tool and required the operator to name every companion they wanted):

• unset => all 7 companions register (8 tools total)
• "node,status" => only those 2 register (3 tools total)
• "" => no companion registers (explore only) — the pre-inversion default, still reachable, now by explicit operator action rather than by accident

An index must still resolve for ANY tool to register; nothing here overrides MCP-03's zero-tools-without-.codegraph/ rule, which BuildServer enforces via hasIndex.

func WarnToolFilterTo ¶ added in v0.6.0

func WarnToolFilterTo(w io.Writer, unknown []string, companions map[string]bool)

WarnToolFilterTo writes one stderr-style warning line per unrecognized filter name to w, followed by ONE line stating the resulting surface. Diagnostics never go to stdout — stdout is reserved for the MCP JSON-RPC transport (T-03-07-Leak) — so callers must pass os.Stderr, never os.Stdout, in production.

The consequence line is not decoration. Under the pre-inversion opt-in allowlist a typo cost exactly the mistyped tool: the operator was ADDING, so the loss showed up as "the thing I asked for is missing", blast radius one. Under narrowing semantics a value whose names are ALL typos narrows the surface to codegraph_explore alone — blast radius seven, presenting as the exact "the MCP server is only showing one tool" symptom this contract was rewritten to eliminate. Naming what was ignored without naming what survived leaves the operator to work that out themselves.

Deliberately NOT fatal: MCP-02 requires unknown names be ignored with a warning, and failing startup over one typo would take down a working server. Equally deliberately NOT a silent fallback to the default set — that would make a fully-typo'd value indistinguishable from a considered choice to narrow.