archetech / archon / 29528958821

90%

push

github

feat: type MCP tool handlers and declare selective output schemas (#720) (#728)

* feat: type MCP tool handlers and declare selective output schemas (#720)

Reduced scope of #720. The full proposal was ~41 output schemas over 145
tools; measuring first showed 87 of 139 keymaster methods return a scalar or
array, which MCP forbids in structuredContent, and the 52 object returns use 41
distinct types -- the shape reuse the issue assumed sits almost entirely in the
ineligible group. So schemas go only where they pay for themselves.

Typed handlers (the part with no wire cost):
- tool() is generic, so each handler's args are inferred from its own input
  schema. The generic is erased in the exported registry, where a homogeneous
  list can't carry it.
- requireKeymaster() no longer casts to any, so tsc checks all 145 handler
  bodies against the real Keymaster type. This found six latent gaps: five
  tools declaring a loose JSON object input for a method needing a specific
  shape, and get_property indexing an untyped didDocumentData. Marked with
  unvalidatedShape() and tracked in #727 -- behavior is unchanged here, since
  tightening inputs would change what the tools accept.

Output schemas on 6 tools: resolve_did, resolve_did_version, check_wallet,
fix_wallet, view_poll, view_ballot. Each always returns an object whose nesting
a caller must navigate to chain a further call. Cost is ~655 tokens on
listTools against an ~11k baseline; schemas for all eligible tools would have
run 5-15k, charged to every client on every session.

Schemas must be .passthrough(): a plain zod object serializes to
additionalProperties:false, which would make clients reject any field not
enumerated -- '@context' alone would have broken every resolve_did call.
Fields typed unknown at the source stay unknown; didDocumentData is often not
an object.

Tested via a real McpServer and Client over InMemoryTransport, which is the
only way to exercise the SDK's actual two-sided validat... (continued)

2941 of 3486 branches covered (84.37%)

Branch coverage included in aggregate %.

26 of 26 new or added lines in 1 file covered. (100.0%)

6112 of 6536 relevant lines covered (93.51%)

835.91 hits per line