registry

Overview ¶

Package registry — always-load annotation + deterministic sort for tools/list responses.

Two MCP-spec-compliance hooks live here:

1. SortToolsByName — emits each tool in name-sorted order at the MCP boundary. Post-SEP-2133 the spec calls out deterministic order so prompt-cache hits and client-side caching stay stable across runs. mcp-go's handleListTools already sorts in the base case, but session-tool merges, filters, and other AfterListTools hooks can disturb the order; pinning the sort here as the LAST hook guarantees the wire output stays deterministic regardless.

2. AnnotateAlwaysLoad — injects `_meta["anthropic/alwaysLoad"]: true` on the eight hot tools (Bash / Read / Edit / Glob / Grep / WebFetch / WebSearch / ToolSearch). Anthropic's "Code execution with MCP" engineering recipe lets Claude Code respect this hint to keep specific tools eager while deferring the long tail. Tools without AlwaysLoad=true are left untouched — the resulting JSON simply lacks the annotation, preserving backward compatibility for clients that don't read the namespace.

Both functions mutate the result in place; they're wired into the AfterListTools hook chain in internal/server/server.go.

Package registry — OpenTelemetry W3C Trace Context propagation over MCP `_meta`, per SEP-414.

MCP request `_meta` and response `_meta` carry W3C Trace Context (https://www.w3.org/TR/trace-context/) so a client and a server can stitch a single tool call into one distributed trace. The two fields are:

• `traceparent` — `00-<32-hex-trace>-<16-hex-span>-<2-hex-flags>`
• `tracestate` — vendor-specific key-value list, optional

Direction of flow:

1. Client serialises the active span as `_meta.traceparent` (and optionally `_meta.tracestate`) on the CallToolRequest.
2. Server middleware extracts those keys and parents the handler's ctx via the W3C TraceContext propagator. With the observability subsystem off, the remote span context is still attached but no live span is recorded — Inject on the way out simply re-emits the same trace_id/span_id so the client's reply correlates against its own active span. With observability on, agents.NewSupervisor / handler-side `obs.StartSpan` open a child span on top, and the response meta carries that child span's id so the client sees the whole subtree.
3. Server middleware Inject()s the (possibly child-of-remote) span context back onto the response's `_meta` envelope.

Fallback: when the request carries no `_meta.traceparent`, the middleware honours the `TRACEPARENT` (and `TRACESTATE`) process env vars. This keeps the v0.22 env-driven shim working for hosts that don't speak SEP-414 yet — they just set the env on the spawned MCP child and clawtool stitches them in.

Backwards compatibility: requests with NO trace context (no `_meta.traceparent` and no env var) are passed through unchanged; the response carries no `traceparent` either, so older clients that weren't reading these keys see exactly the pre-SEP-414 wire shape.

Package registry — typed manifest of every clawtool MCP tool. Codex's #1 ROI architectural recommendation (BIAM task a3ef5af9): collapse server.go's hand-maintained list of RegisterX calls + CoreToolDocs's parallel description list + the slash-command + skill routing-map cross-references into ONE typed source of truth.

Step 1 (this commit): ship the package + types + an empty Manifest. server.go is unchanged. Subsequent commits migrate tool registration through the registry, one cohesive group at a time, with the surface_drift_test guarding each step.

Why type-driven, not config-driven: a TOML manifest would need a runtime registry of register funcs anyway. Putting the register-fn pointer ON the typed ToolSpec keeps the type system honest — a misspelled tool name fails to compile, not at boot.

Why a separate package, not a method on core: core/ already owns ~30 RegisterX functions. Importing core to build the manifest, then having core import registry to look up specs, would be a cycle. registry stays a leaf — core (and any future tool source) imports it; server.go calls registry.Apply.

Package registry — TypeScript stub export for code-mode hosts.

Anthropic's "Code execution with MCP" recipe (and Cloudflare's earlier "Code Mode" pattern) presents the MCP tool catalog as a TypeScript file tree the agent imports from. Quoted reduction from that recipe: 150 K → 2 K tokens (98.7%) on heavy tool-call loops. The agent writes code instead of round-tripping each `tools/call`.

`clawtool tools export-typescript --output <dir>` walks the manifest and emits one `.ts` file per registered tool, plus a barrel `index.ts`. The MVP shape is minimal: tool name, description (docstring), and a typed function signature whose input + output are `any` for now. Full JSON-Schema → TypeScript translation lands in a follow-up cut once we decide how to represent oneOf / $ref / nested objects without bringing in a full schema-codegen dependency.

The point of the MVP: operators using a code-mode host (Codex 0.125+ rollout-tracing now records "code-mode edges"; Anthropic blog endorses the pattern) can already adopt clawtool's tool catalog as a TypeScript module today, with the agent reading the docstring to learn what each tool does. Type fidelity arrives incrementally.

Package registry — usage-hint enrichment for tools/list responses.

MCP's tools/list result carries each tool's Description, but Description answers WHAT the tool does. Calling agents (Claude Code, Codex, OpenCode) frequently need a HOW pointer too: "when do I pick this over the similar one", "what's a common mistake", "one concrete example". We curate that as a separate `UsageHint` field on the ToolSpec and surface it via the MCP-spec-defined `_meta` extension envelope:

{
  "name": "Glob",
  "description": "List files matching a glob pattern...",
  "_meta": {
    "clawtool": { "usage_hint": "Use when you need a file LIST..." }
  }
}

`_meta` is the canonical extension surface in the MCP spec — strict clients ignore unknown sub-keys gracefully, so adding the `clawtool` namespace under it is non-breaking. (We considered hanging the hint off `annotations.clawtool` per ADR-008's extension-namespace pattern, but mcp-go's typed `ToolAnnotation` struct has no extension map and re-shaping its MarshalJSON would force a vendored fork. `_meta.AdditionalFields` is the supported path.)

Wiring: server.go installs an `AddAfterListTools` hook that calls `EnrichListToolsResult` with the manifest's UsageHints map. The hook mutates the result in place before mcp-go serializes it.