feat(mcp): publish json and code surfaces over MCP#142
Merged
Conversation
The `json` and `code` part kinds were publishable over the CLI and REST but never added to the MCP tool schemas, so MCP agents could not publish them and the tool descriptions claimed they did not exist. Add both kinds to the HTTP JSON-Schema and stdio zod `kind` enums and document their fields (`data`; `code`/`language`/`lineStart`). To prevent the part-kind list from drifting between tiers again, derive the `SurfaceKind` type and both MCP enums from one canonical `SURFACE_KINDS` list in server/types.ts, and add test/mcpSpec.test.ts, which asserts every kind round-trips through the MCP schema and the runtime validator. Co-Authored-By: Claude Opus 4.8 (1M context) <noreply@anthropic.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What
The
jsonandcodesurface kinds have been publishable over the CLI and REST since they were added, but they were never added to the MCP tool schemas — so MCP agents couldn't publish them and the tool descriptions claimed they didn't exist. This closes that tier-parity gap and adds a structural guard so it can't recur.Surfaced by a code review of
main; the fix was rebased onto #140's post/surface wire-vocabulary rename.Changes
mcpSpec.ts— addjsonandcodeto the HTTP JSON-Schema enum and the stdio zod enum (now derived, see below), add their field schemas (datafor json;code/language/lineStartfor code —titlealready existed), and refresh the prose inMCP_INSTRUCTIONS,MCP_SURFACES_DESCRIPTION, thepublish_post/deprecated-alias tool descriptions, and the surface schema's.describe().types.ts— introduce a canonicalSURFACE_KINDStuple as the single source of truth;SurfaceKindnow derives from it.How we avoid this regression again
The kind list previously lived in four hand-maintained places (the
SurfaceKindtype, the runtime validator, and two MCP enums) that drifted independently. Now:kindenums are derived fromSURFACE_KINDS([...SURFACE_KINDS]), so adding a kind to the type adds it to MCP automatically. This is the exact failure that happened, structurally eliminated.data, code needscode/language), sotest/mcpSpec.test.tspublishes a minimal example of everySURFACE_KINDSmember through the real stdio publish schema and the runtime validator, and asserts the advertised HTTP enum equalsSURFACE_KINDS. Verified the guard fails (2 failed) when json/code are removed.Validation
npm run typecheck✅ (node + workers + viewer)npm test✅ 261 passing (incl. 5 new guards)npm run lint✅ ·npm run format:check✅patch🤖 Generated with Claude Code