Skip to content

✨ Add serve mcp with tools declared by command annotations - #26

Merged
bdsoha merged 4 commits into
mainfrom
feature/mcp
Nov 15, 2026
Merged

bdsoha merged 4 commits into
mainfrom
feature/mcp

Conversation

@bdsoha

@bdsoha bdsoha commented Nov 15, 2026 •

Copy link
Copy Markdown
Member

What

ws-cli serve mcp runs a Model Context Protocol server over stdio for AI agents inside the workspace.

  • A command becomes a tool by carrying mcp annotations (cli.MCP): mcp (read or write), mcp.when (conditions on dotted env keys), mcp.flags (allow-list of exposed flags). The tool description is the command's long help.
  • The annotations are written to commands.yaml as an mcp: object per command.
  • The [!]<group>.<prop> condition lives in internals/config (Condition, Holds), so later features can gate on the same settings.
  • 22 tools: 19 read (info, show, logs, feature list|info|store, editor diagnostics|list|selection, template list|show, seed ls) and 3 write (editor open, editor reveal, template apply).
  • The list is read-only unless WS_AI_MCP_ALLOW_WRITE is set. WS_AI_MCP_TOOLS narrows it to groups or tool names (comma-delimited, * means all).
  • Each call runs the command as a subprocess: --flag=value args, -- before positionals, empty stdin, no colour, 60 s timeout, 64 KiB output cap keeping the tail. Arguments are validated against the tool's schema with jsonschema-go before anything is spawned.
  • serve mcp prints a start banner and one log line per tool call on stderr, in the style of serve current and serve metrics. Stdout carries only JSON-RPC.
  • show_env exposes the key only, so it runs the mode that redacts secret: true values. info env and secrets * are not tools.

Also in this PR

  • --port and --bind move from the serve group onto serve current and serve metrics, so serve mcp takes no flags. serve --port X current (flag before the subcommand) no longer parses; serve metrics --port --collectors is unchanged.
  • New module github.com/modelcontextprotocol/go-sdk v1.8.0. It serves both the 2025-11-25 and the stateless 2026-07-28 protocol, which is why it is preferred over a stdlib implementation.
  • Every other Go module is bumped to its latest release. No golden file changed.
  • New internals/proc: one bounded subprocess runner (timeout, wait delay, process group) and one self-exec seam, used by the MCP runner, tempfile.Detach, config.GetExtensions and the nvidia-smi call, which gains a 5 s timeout.
  • internals/server exports PrintStop and LogRequest, shared by the three serve commands.
  • The long help of show env, logs, feature info, editor diagnostics, editor open and template apply no longer names flags the tool does not expose; the hints moved to the flags' usage lines.

Behaviour to know

  • The ai env group is not in the workspace schema yet. Until it is, both variables are ignored with a warning and the server lists the read tools.
  • An unknown WS_AI_MCP_TOOLS entry is ignored with a warning and never widens the list. A value that cannot be resolved serves no tools.
  • mcp.when and WS_AI_MCP_ALLOW_WRITE shape the tool list. They are not a privilege boundary.
  • SIGTERM, SIGINT and SIGHUP cancel a running call and exit 0.

Verification

  • go vet ./... and go test ./... pass.
  • Tests run a real serve mcp process over stdio with 2025-11-25 and 2026-07-28 clients, call every listed tool with canary secrets planted, and pin the tool surface in a literal table.
  • Tried against Claude Code 2.1.325 and Codex CLI 0.167.2 from an installed build: both connect, list the tools and call them; a planted fake secret never appeared in a result; template_apply wrote a file with writes enabled. Not tried: the editor chat and opencode.

Follow-ups

  • workspace: add envs.ai to env.reference.yaml, bump the ws-cli digest, add an integration test.
  • Per-client MCP definitions and agent skills.

Run an MCP server over stdio whose tools are the commands that carry
`mcp` annotations. The list follows the run's `WS_*` settings and is
read-only unless `WS_AI_MCP_ALLOW_WRITE` is set; `WS_AI_MCP_TOOLS`
narrows it. Each call runs the command as a subprocess with a timeout
and an output cap. The annotations are written to `commands.yaml` as an
`mcp:` object.

Move `--port` and `--bind` from the `serve` group onto `serve current`
and `serve metrics`, so `serve mcp` takes no flags.

Add `github.com/modelcontextprotocol/go-sdk` v1.8.0 and bump every other
module to its latest release.
Drop the `mcp.description` annotation: a tool reads the command's long
help again, reworded where it named a flag the tool does not expose,
with the flag hints moved into the flags' own usage strings.

Move the `[!]<group>.<prop>` condition and its evaluation from
`internals/mcp` to `internals/config` as `Condition` and `Holds`.

`cli.MCP` returns the command, so a tool is declared where its command
is defined and the `init()` annotation blocks are gone.
Keep each behaviour of `serve mcp` asserted once, at the lowest layer
that proves it: the in-memory server keeps only what needs the recorder,
the literal tool table goes because `commands.yaml` already pins the
surface, and the real-process tests keep the lifecycle, the signals, the
warnings on stderr and one end-to-end settings check.
`serve mcp` prints a start banner and one log line per tool call on
stderr, through the same `server.PrintStop` and `server.LogRequest` that
`serve current` and `serve metrics` use. Stdout stays JSON-RPC only.

New `internals/proc` holds the bounded subprocess runner (timeout, wait
delay, process group) and the one self-exec seam. The MCP runner,
`tempfile.Detach`, `config.GetExtensions` and the `nvidia-smi` call use
it; `nvidia-smi` gains a 5 s timeout.

Tool arguments are validated against the generated schema with
`jsonschema-go`, and annotation lists are split by `config.ParseList`.
@bdsoha bdsoha self-assigned this Nov 15, 2026
@bdsoha
bdsoha merged commit 8aaa275 into main Nov 15, 2026
3 checks passed
@bdsoha
bdsoha deleted the feature/mcp branch November 15, 2026 12:43
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant