[RFC] Local MCP server (astryx mcp) so agents in consumer projects can use the CLI's capabilities directly

### Problem Statement

AI coding assistants working inside a consumer project can only use Astryx's tooling if two fragile things are both true: someone ran astryx init, and the model remembers to shell out to the CLI at the right moments. When either fails, the assistant falls back on training data and writes stale or invented APIs.

The hosted MCP server helps but has a narrow surface. It exposes search and get against the latest published docs, and because it runs on the docsite it cannot see anything about the project it is serving: not the installed @astryxdesign/core version, not the active theme, not any third-party integration packages. An agent working in a project pinned to an older version gets answers about a version it does not have.

Meanwhile the CLI already contains the capabilities agents actually need during a build: composition kits (build), layout skeletons (template --skeleton), the XLE layout language (layout expand), setup diagnostics (doctor), and pending migrations (upgrade --list). None of that is reachable over MCP. The gap shows up whenever an assistant scaffolds a page: it either knows to run the text CLI, or it guesses.

### Evidence of Demand

- The project's own research names this problem. The AI and Design Systems wiki page concludes that prose rules are suggestions rather than constraints, and internal/vibe-tests/cli-discovery-test/PLAN.md is a designed but unimplemented study of the cold-start question: does an agent ever find the CLI when nobody ran init? An MCP server attacks the same problem from the tool side, since MCP tools appear in the assistant's tool list on every request instead of depending on the agent recalling a terminal command.

- The working-with-ai doc topic includes a three-question setup probe and reports a 0% pass rate for agents without the docs installed, which is a direct measure of how badly agents do when discovery fails.

- The llms.txt route already deflects crawlers to the CLI, so the project has committed to "tooling, not scraped docs" as the delivery mechanism. MCP is the standard packaging for that commitment.

- Other design-system tooling has moved this way: shadcn ships a registry MCP server and Figma ships a Dev Mode MCP server, so assistants and their users increasingly expect component systems to be reachable this way.

### Why Existing Components Don't Cover This

- The hosted MCP route (apps/docsite/src/app/mcp/route.ts) is the closest thing, but it is remote by design. It reads build-time registries generated from the repo at deploy time, so it cannot answer version-, theme-, or integration-aware questions, and it has no path to side-effecting or project-local commands like doctor.

- The generated AGENTS.md/CLAUDE.md block teaches the workflow, but it is prose in a crowded context window, and it only exists after init. It also cannot make a tool show up in the assistant's tool list.

- The CLI's --json mode plus the manifest command give a machine-readable contract, but the agent still has to discover the binary, and manifest is in effect the tool schema an MCP bridge would serve. The metadata exists but the connector does not

### Rough Approaches Considered

Option A (preferred): a stdio MCP server as a new thin client. The CLI's architecture already separates a reusable api/ layer (pure functions returning {type, data} envelopes) from thin clients under clients/. An astryx mcp command would be a new clients/mcp/ binding: each tool wraps one api/ function, with tool schemas derived from the existing CommandDoc metadata that powers manifest.

`astryx mcp # stdio MCP server for the current project`

Suggested v1 tool set, all read-only and all backed by already-extracted API functions: search, component, docs, build (composition kit), template_skeleton, doctor. Project-aware and side-effecting tools (upgrade, init) would wait for their pending extraction into api/, per the thin-CLI roadmap in packages/cli/CONTRIBUTING.md, so this proposal sequences behind that work rather than cutting across it.

Option B (complementary, not alternative): init writes the client config. astryx init --agent claude already writes managed doc blocks; it could also write the MCP server entry (.mcp.json for Claude Code, the equivalent for Cursor) so a freshly initialized project exposes the tools with no extra step. The existing managed-block and staleness machinery (inspectAgentDocs) extends to this file.

A likely PR sequence: (1) clients/mcp/ with the read-only v1 tools plus a CommandDoc and tests, (2) init integration and working-with-ai doc updates, (3) project-aware tools when their API extractions land.

### Accessibility Considerations

Not applicable in the ARIA sense; this is developer tooling with no rendered UI

### Performance Considerations

_No response_

### Pre-submission Checklist

- [x] I have read the [Contributing guide](https://github.com/facebook/astryx/wiki/Contributing)
- [x] I have read the [API Conventions](https://github.com/facebook/astryx/wiki/API-Conventions)
- [x] I have checked that existing Astryx components cannot compose to solve this
- [x] This is a general-purpose UI pattern (not specific to one product)

Start by reading the reusable api/ layer, clients/ conventions, and packages/cli/CONTRIBUTING.md, then inspect apps/docsite/src/app/mcp/route.ts and the manifest CommandDoc metadata. The proposed first stage is clients/mcp/ with read-only tools backed by existing API functions; done means the v1 tools, schemas, and tests are in place without adding project-aware or side-effecting commands.

Written by the indexing model from the issue text.