docs(atlas): plan the @kolu/surface/mcp adapter scope (#982) - #1266
Merged
Conversation
A plan-of-record note for #982 — the generic surface→MCP adapter. Argues for scoping it to the lifecycle spine (subscribe/teardown, zod→JSON-Schema, stdout discipline) + a default-deny selection/authz gate, not the auto-map; grounded in odu's hand-built mcp face as validated-but- partial prior art. Cross-linked from the odu note.
…lo-world + 2nd-surface cut - Diagram: grid-columns single-column stack (was scaled-down/unreadable when wide); vertical spine→gate flow, fixing the prose's 'above' claim. - Package: recommend packages/surface-mcp/ (@kolu/surface-mcp) sibling over the issue's @kolu/surface/mcp subpath — keeps @modelcontextprotocol/sdk out of core. - Worked example grounded in odu (not the notes demo): bridge the live coordinator via serveSurfaceAsMcp + an expose allowlist; ~1550 LoC → a projection surface. - New section: curation as a second surface (oduAgentSurface) so the adapter subsumes the compositions/guards too; refined the electricity verdict. - (zod→JSON-Schema paragraph still pending prior-art research workflow.)
…o tag in TS - zod→JSON-Schema: rewrite to BUY zod 4's native z.toJSONSchema (empirically verified vs pinned zod@4.3.6; old zod-to-json-schema sunset Nov 2025), naming the thin glue the package still owns (io:input, unrepresentable override, the mandatory dereference pass for cross-client compat, top-level object, one toInputSchema() + snapshot test for the zod-version-default seam). - New '### How the developer tags it' subsection: three default-deny mechanisms (structural membership · typed expose allowlist · co-located wrapper helpers); notes that decorators don't fit plain-object specs. Answers the @mcp-tool ask.
…-tools escape hatch, total graduation Per review: don't defer the framework work, and don't force everything through surface. - Curation section rewritten: projectSurface is scoped INTO #982 (combinator + surfaceClientRef server-as-client enabler + a derive helper), grounded in the framework (sibling composition + handler source shapes already exist; the projected-stream teardown is the SAME lifecycle the spine builds — solved once). New topology diagram. Drops the '~90% / maybe later' hedge. - Two paths, no gap: surface-mcp also takes bespoke 'tools' (hand-authored, compose over the live client, share the spine) for genuinely call-shaped capabilities — run is now a bespoke tool, not a forced primitive. - Verdict ③ → total graduation; recommendation → one PR, three parts (adapter + projectSurface in core + odu's full migration). - Intro reframed as 'right-scoping' (smaller on zod/stdio, bigger on projection).
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.
Plan-of-record Atlas note for #982 — the generic
@kolu/surface/mcpadapter (expose any stdio-served surface as an MCP server).The issue's framing is right: the framework is one adapter away from "every Kolu surface is also an MCP server." This note argues for scoping it to the part that's actually a framework primitive, because we already shipped the rest by hand (odu's
odu mcpface, juspay/odu#3 / #1258) and learned exactly where the seam falls.Thesis
rerun_node) is a procedure mapped 1:1; the four useful ones (get_nodes,tail_log,wait_for_settle,run) are hand-authored projections/compositions — and the surface's other procedure (run.configure, dangerous) is deliberately not a tool. "Every procedure → tool" ships the dangerous verb and misses the good ones.src/mcp/(~1550 lines, not "one file") isResourcePusher— theresources/subscribeteardown done right (the generation-token / detach-without-abort dance that dodges theERR_STREAM_DESTROYEDrace). That, plus the missing zod→JSON-Schema bridge and composition with the already-shippedserveOverStdiostdout discipline, is the genuinely generic spine worth extracting..ci/odu.sock). Pick bridge-a-live-surface as primary.Files
docs/atlas/src/content/atlas/surface-mcp.mdx— the new plan note (kind: feature,status: proposed), with a D2 architecture diagram of the seam.docs/atlas/src/content/atlas/mini-ci-vs-justci.mdx— forward-reference from odu's MCP-face section to the generic package (and dropped the now-inaccurate "~one file" claim).docs/atlas/dist/— rebuilt + staged (ci::atlas-syncgreen, host-independent).Rendered preview: https://htmlpreview.github.io/?https://github.com/juspay/kolu/blob/atlas-surface-mcp/docs/atlas/dist/surface-mcp.html
Proposed plan —
status: proposed, for review. Not merged.🤖 Generated with Claude Code