---
schema_version: 1
id: RAC-KTW0M84VTFP3
type: roadmap
---
# RAC v0.10.0 — Guide Foundation

## Status

Planned

## Context

The Agent Context Guide requirement defines an MCP server that serves RAC
repository knowledge to coding agents, so that recorded decisions are
respected instead of silently violated.

The platform is ready. The v0.7.x series delivered the service layer,
canonical identity, lookup and resolution, and stable JSON contracts; the
v0.8.x series proved the consumer pattern with Explorer. ADR-008 prepared
this exact consumer; ADR-029 through ADR-034 pin Guide's delivery,
surface, and boundaries.

This milestone supersedes the earlier `v1.2-mcp-server` future stub, whose
broad tool-per-command sketch was rejected by ADR-030 in favour of a
four-tool wedge.

v0.10.0 stands up the server and the four tools with pinned contracts. It
deliberately excludes onboarding documentation (v0.10.1) and the grounding
demo (v0.10.2).

## Outcomes

- `rac mcp` serves a working stdio MCP server from any RAC repository root.
- Any MCP client can call four read-only tools — `get_artifact`,
  `search_artifacts`, `get_related`, `get_summary` — and receive
  deterministic, budgeted, contract-pinned responses.
- The server consumes RAC Core in-process with zero duplicated intelligence,
  verified by an isolation battery.

## Initiatives

### Initiative 1 — MCP Server Package

Introduce the Guide server as a new consumer package:

```text
RAC Core  →  rac.mcp (server layer)  →  MCP client
```

A FastMCP application factory builds the server for a repository root; the
CLI subcommand runs it over stdio. Only the server layer imports the MCP
SDK.

### Initiative 2 — The Four Tools

Implement the four tools exactly as pinned by the `guide-tool-surface`
design: signatures, verbatim descriptions, response shapes, and resolver
semantics. Tools call existing services — resolution, search, relationships,
portfolio — and serialize through the same `to_dict` shapes the CLI emits.
`get_related` filters the repository relationship report for one artifact at
the server boundary; filtering is presentation-only (ADR-031).

### Initiative 3 — Response Budget and Truncation

One shared budget implementation enforces the per-response character cap
(default 10,000, configurable at startup) with whole-item truncation and the
pinned marker fields (ADR-033).

### Initiative 4 — Structured Errors

Failed lookups return the resolver's structured outcomes — not-found,
duplicate — as data, never as protocol exceptions, in the shapes pinned by
the design.

### Initiative 5 — Contract Test Battery

Pin every tool's output shape, truncation behaviour, and error shape with
tests against the fixture corpora, following the golden-output practice.
An isolation battery asserts the dependency direction by construction.

## Constraints

- Guide consumes Core services only; no repository intelligence exists in
  the server layer (ADR-015, ADR-031).
- Every tool call re-reads the repository; no caching, no session state
  (ADR-032).
- The server is read-only by construction: no write-capable API is
  importable from the server layer (ADR-031).
- Tool names, signatures, and description text ship verbatim from the
  `guide-tool-surface` design; deviation is a contract change.
- No existing CLI behaviour or JSON contract changes (ADR-007).

## Non-Goals

- MCP resources, prompts, or HTTP/SSE transport (ADR-030, ADR-029)
- Conflict detection or any judgment-shaped tool (ADR-034)
- Client configuration documentation and examples corpus (v0.10.1)
- The grounding demo and launch assets (v0.10.2)
- New repository intelligence in Core

## Implementation Contract

The following decisions are pinned for v0.10.0.

### Module Locations

- The server lives in `src/rac/mcp/`: `server.py` (FastMCP application
  factory and tool registration), `budget.py` (response budget and
  truncation), `errors.py` (structured error shapes), `__init__.py`.
- Only `src/rac/mcp/` may import the `mcp` SDK — the mirror of the rule
  that only Explorer's `app.py`, `screens/`, and `widgets/` import Textual.
- The server layer imports only read services; nothing under `rac.core` or
  `rac.services` imports `rac.mcp` or the `mcp` SDK.

### Public APIs

- `rac.mcp.server`: `build_server(root: str) -> FastMCP`,
  `run_server(root: str) -> int`.
- Tools consume `rac.services.resolve` (`resolve_artifact`,
  `find_artifacts`), `rac.services.relationships`
  (`build_relationship_report`), `rac.services.portfolio`
  (`build_portfolio_summary`), and `rac.services.index`
  (`build_repository_index`) — extending Core first if a capability gap
  appears, never implementing server-side.

### Dependencies

- `mcp>=1.0` joins `[project] dependencies` in `pyproject.toml` as a
  standard dependency (ADR-029). No other base dependency changes.

### CLI and Exit Codes

`rac mcp [--root PATH]` defaults to the current directory.

| Outcome | Exit code |
| --- | --- |
| Clean server shutdown (client disconnect) | `0` |
| Usage error (`--root` is not a directory) | `2` |

- Diagnostics go to stderr only; stdout belongs to the MCP protocol.
- Tool-level failures surface as structured tool results, never exit codes.

### Testing

- New CI battery `mcp`; every new test file joins exactly one battery
  (ADR-027).
- `tests/test_mcp_server.py`: factory construction, CLI registration,
  `--root` handling, exit codes.
- `tests/test_mcp_tools.py`: contract tests pinning all four tool output
  shapes, truncation boundaries, and error shapes against `tests/fixtures/`
  corpora; equivalence assertions that tool payloads match the
  corresponding CLI JSON output for the same fixture state; a freshness
  test that edits the fixture between calls and observes the change
  (ADR-032).
- `tests/test_mcp_isolation.py`: AST battery asserting `rac.core` and
  `rac.services` never import `mcp` or `rac.mcp`, and that `rac.mcp`
  imports no write-capable service.

## Success Measures

- An MCP client connects to `rac mcp` and exercises all four tools against
  the dogfood corpus.
- Tool output for the dogfood corpus matches the equivalent CLI JSON output
  for equivalent queries.
- Contract tests fail on any unannounced change to tool output shapes,
  descriptions, truncation, or error shapes.
- All existing CLI behaviour and JSON contracts remain unchanged (ADR-007).

## Risks

- MCP SDK API churn between planning and implementation. Mitigated by
  pinning a floor version and keeping all SDK contact inside `rac.mcp`.
- Tool descriptions that read well but trigger poorly. Mitigated by the
  v0.10.2 measurement protocol; description text is a design contract that
  can be revised and re-measured without code changes elsewhere.

## Assumptions

- Core service functions suffice for all four tools; gaps are closed in
  Core with thin, tested additions.
- stdio is sufficient for every target client (ADR-029).

## Related Decisions

- ADR-029
- ADR-030
- ADR-031
- ADR-032
- ADR-033
- ADR-034
- ADR-007
- ADR-008
- ADR-015
- ADR-027

## Related Designs

- guide-tool-surface

## Related Requirements

- rac-agent-context-guide

## Dependencies

- v0.7.11 hybrid metadata and system-assigned identity
- v0.7.12 artifact lookup and resolution
- v0.7.x service layer and repository index
- v0.8.x consumer-boundary precedent (adapter and isolation patterns)
