design: define initial MCP transport and ASP tool boundary

[vycdev2]

Summary

Define the first independently implementable jett mcp boundary: choose the local MCP transport, map the existing ASP command/query surface into stable tools and resources, and specify how project roots, compiler failures, and TOON payloads cross the transport.

Source documentation

• docs/progress.md — Phase H: Agent Tooling
• docs/design.md — MCP Server — Agents Connect Directly
• docs/architecture.md — MCP Server (jett_mcp)

Current state

The workspace has no jett_mcp crate, MCP dependency, or jett mcp subcommand. Agent-facing compiler operations currently run as one-shot CLI commands with --agent; build, format, run, test, bundle, and the implemented namespace/symbol/type/definition/reference/completion/signature queries already emit TOON-oriented output through CLI and driver paths.

The design docs describe jett mcp as a local server that exposes ASP commands as tools and documentation/project facts as resources, but they do not yet pin the initial MCP protocol version, stdio versus local HTTP transport, lifecycle, project-root selection, request concurrency, error mapping, or the exact first tool/resource inventory. The architecture currently says HTTP on localhost, while the implementation has no server boundary to preserve that choice.

Scope

This issue includes:

• choosing and documenting the initial MCP protocol/transport and local-only security boundary;
• defining server lifecycle, project-root selection, path validation, and request-concurrency behavior;
• mapping the implemented ASP operations to an initial tool inventory with deterministic names, input schemas, exit/error behavior, and TOON result payloads;
• defining the first documentation and project resources, including how shipped/generated content is located and refreshed;
• deciding whether MCP belongs in a dedicated jett_mcp crate or a smaller first slice behind jett_cli;
• adding transport-level tests for initialization, tool/resource discovery, representative success and compiler-failure calls, and shutdown.

It does not include inventing new compiler queries, completing the ASP diagnostic schema, implementing remote authentication or non-local deployment, or adding HIR/MIR/native backend behavior.

Acceptance criteria

• The supported MCP protocol version and initial transport are explicit, including why stdio or a localhost transport is the canonical first spelling.
• Server lifecycle, project-root selection, path containment, concurrency, cancellation, and local security expectations are documented.
• The initial tool and resource inventory has stable names, input schemas, TOON result rules, and structured protocol-error behavior.
• MCP delegates to shared driver/ASP operations rather than shelling out to recursively invoke jett or maintaining a second compiler-output implementation.
• Focused tests cover protocol initialization, discovery, at least one query tool, one compiler/test tool, one resource, compiler failure propagation, invalid paths/inputs, and clean shutdown.
• docs/design.md, docs/architecture.md, and the Phase H status in docs/progress.md reflect the accepted transport and implementation boundary.

Dependencies / open questions

#35 owns the complete ASP diagnostic context and cross-command failure envelope. The MCP design can choose transport, lifecycle, tool/resource inventory, and shared-operation boundaries independently, but its stable compiler-failure mapping should consume the accepted #35 envelope rather than define a competing schema.

The current docs promise TOON tool results even though MCP request/response envelopes use protocol-native structured data. The accepted design should state whether TOON is returned as text content, embedded structured content, or both without changing ASP's canonical payload.

This was generated by an AI agent (vycdev2). Please verify any changes before merging or applying.