Proposal: MCP server for AI-generated tours (agent-generated CodeTour content)

[maurice30120]

Problem

AI agents (Copilot, Claude, Cursor, etc.) increasingly write and modify code in repositories, and they are well positioned to explain that code too. CodeTour tours are the natural artifact for that: a checked-in, human-readable walkthrough of a codebase or a change. Today, however, tours can only be recorded manually by a human clicking through files — so the one artifact an agent could use to leave durable, reviewable explanations behind is the one it cannot produce.

Proposal

Add a local MCP server, bundled with the desktop extension, that exposes two tools so any MCP-capable agent can generate CodeTour content:

• create_project_tour — a tour explaining a codebase, with steps anchored to files, directories, lines, unique patterns, or selections.
• create_changes_tour — a tour explaining committed changes from the merge-base of a baseRef to the current HEAD (verified against the live HEAD to avoid stale explanations), optionally including uncommitted work.

The agent provides fully written content; the server only validates and persists it. This keeps the human in charge of the narrative while making the mechanical part (anchoring steps to the right lines, writing valid .tour files) deterministic.

Design

1. Two tools, one responsibility. The server never generates content itself; it validates proposals (strict input schema, anchor existence and bounds checked against actual file content) and writes deterministic .tour files under .tours/.
2. Stdio confinement. One server instance per workspace folder, spawned over stdio, confined to the --workspace-root argument, no network access.
3. Strict validation. Unknown fields rejected, active URI schemes (command:, file:, vscode:, javascript:) rejected in Markdown descriptions, anchor patterns capped in length and checked against catastrophic backtracking before being run against file contents, Git refs resolved to full SHAs via git rev-parse --verify before any Git invocation.
4. Atomic, deterministic writes. Temp file in the resolved real directory, then rename; an empty generation never replaces a useful existing tour.
5. Compatibility preserved. The vscode.lm MCP provider API is stable only since VS Code 1.101, but the extension's engine floor would stay at ^1.60.0: the API is declared locally and feature-detected at runtime. On hosts older than 1.101 the feature is simply inactive; no user is excluded by upgrading. The web extension is unaffected (all Node.js-only integrations are desktop-only).

Delivery plan

To keep review tractable, the work would come as independent PRs:

1. A small, unrelated crash fix I found along the way (comment threads without a source range crash step recording).
2. The self-contained packages/mcp-server with its own test suite (73 tests: unit validation, stdio integration, security, packaged-binary).
3. The extension integration: runtime-conditional provider registration, VSIX bundling, README section.

I have the implementation working and tested on a fork and would love feedback on the design — in particular the runtime-conditional vscode.lm registration approach and the PR split — before opening the PRs.