Repository navigation
feat(mcp): add the MCP server on the official TypeScript SDK - #129
Open
oto-macenauer-absa wants to merge 1 commit into
Open
oto-macenauer-absa wants to merge 1 commit into
oto-macenauer-absa wants to merge 1 commit into
Conversation
protocol/ registers search_documents, list_documents, read_document and the kb:// resources on the SDK v2 McpServer with zod 4 schemas. transport/ is a stateless Streamable HTTP handler (Origin check, 64 KiB body cap, per-client and global rate limits, in-flight cap, timeout) with /healthz and designed browser error pages; config.ts is the only reader of argv and KB_MCP_*. Build step 3b also bundles the server into one minified dist/_mcp/server.mjs (~410 KB; English-only zod locales, the SDK's Workers validator instead of Ajv) and writes dist/_error/not-found.html. The fragment server serves the endpoint through the same handler. Golden byte-exact protocol tests (UPDATE_GOLDEN=1), bundle-vs-source equivalence and a size budget pin the behaviour. A Makefile fronts the npm scripts; CI lints with make lint. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This was referenced Oct 21, 2026
This branch has not been deployed
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
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
Second layer of the MCP server stack (#117): the MCP server itself, built on the official MCP TypeScript SDK v2 and bundled at build time. It is not deployed yet; #119 wires it into nginx and the image.
Stack: #128 (search index) ← this PR ← #119 (deployment and docs).
Changes
mcp/src/protocol/: one file per tool (search_documents,list_documents,read_document), thekb://resources and zod 4 schemas, all on the SDK v2McpServer. The SDK was chosen over FastMCP, mcp-framework, xmcp and a hand-rolled JSON-RPC server.mcp/src/transport/: a stateless Streamable HTTP handler with:Also a listener with
/healthz, and designed browser error pages.mcp/src/config.ts: the only reader of argv and the environment (KB_MCP_*).mcp/src/main.ts: the stdio and HTTP entry point.mcp/build/bundle.ts: esbuild produces one minifieddist/_mcp/server.mjsof about 410 KB, against a 450 KiB budget. Two substitutions make that possible: zod keeps English locales only, and the SDK's Ajv validator is swapped for its Workers validator (src/sdk-shims.ts).Build step 3b also writes the bundle and
dist/_error/not-found.html.Makefile: build, lint, test, dev, size, image and prod targets, all delegating to npm scripts. The CI lint job now runsmake lint.tests/fragment-server.mjsserves the MCP endpoint through the same handler, and keeps_mcpand missing routes on the designed 404.Tests:
UPDATE_GOLDEN=1regenerates them);Verification
make lint: greennpm audit --omit=dev --audit-level=high: greennpm test: all passednpm run test:mcp: all passednpx playwright test --config=playwright.config.ci.js: all passednpm run test:container: all passedPart of #117
🤖 Generated with Claude Code