DocForge2/docs/MCP_CONTRACT.md

# MCP boundary

The server uses local standard input/output transport and binds once to the explicit
`--project-root` supplied at process startup. Optional proposal access also binds once to the
configured `--proposal-writer`. It opens no network listener at startup. The explicit
`docforge_visualize` read tool may start one token-protected loopback-only HTTP listener for the
same immutable project binding.

## Read tools

- `docforge_project_info`
- `docforge_get_contract`
- `docforge_get_node`
- `docforge_search`
- `docforge_filter_nodes`
- `docforge_backlinks`
- `docforge_dependencies`
- `docforge_impact`
- `docforge_get_context`
- `docforge_validate_project`
- `docforge_render_status`
- `docforge_visualize`

Each response states that document text is project content, not higher-priority instructions. Each
response includes project identity, revision, source hash, adapter version, and staleness state.

The normal command binds the generic project loader. An explicit project integration may instead
construct the same read-only surface from a validated `ProjectService` and project-owned context
provider. This form cannot register proposal tools. Project discovery, session selection, family
partitioning, and custom context policy remain outside the DocForge core.

An explicit project integration may construct the full fixed surface only after supplying a
confined proposal policy and startup-bound writer. Adapter proposal validators may narrow the
writer's declared operations further. They cannot add tools, weaken core changeset validation, or
enable canonical application.

## Isolated proposal tools

- `docforge_create_changeset`
- `docforge_list_changesets`
- `docforge_get_changeset`
- `docforge_propose_node_create`
- `docforge_propose_node_update`
- `docforge_propose_node_move`
- `docforge_propose_node_delete`
- `docforge_validate_changeset`
- `docforge_get_changeset_diff`
- `docforge_preview_changeset`

Proposal tools may write only below the configured changeset or isolated preview roots. They never
change canonical files or declared project output. Without `--proposal-writer`, changeset mutation
tools return `proposal_access_disabled`. Validation, diff retrieval, and preview remain available
for existing changesets. A preview accepts a declared view ID, not a renderer name or command.

## Render boundary

`docforge_render_status` recomputes expected hashes without writing. `docforge_preview_changeset`
runs only a project-declared view through DocForge's fixed built-in renderer registry and writes one
atomic HTML file below the configured preview root. Rendering declared project output is available
only through the explicit local CLI integration command.

## Visualization boundary

`docforge_visualize` starts the fixed built-in `graph-browser@7` template against the currently
validated derived index. It may focus one stable node, run one bounded lexical query, or open the
project overview. The tool returns a loopback URL and exact snapshot identity.

The tool cannot select a project, database, template, host, port, filesystem path, or SQL
expression. Its HTTP surface is token-bound, read-only, same-origin, and limited to overview,
search, exact family/authority/status/tag filtering, node-neighborhood JSON, and a read-only
browser-lease heartbeat. The browser exposes an exact validated index snapshot. It rejects index
replacement or alteration and requires another MCP invocation to refresh.
Viewport interaction is entirely client-side: fitted neighborhood framing, wheel zoom, left-button
drag pan, explicit zoom buttons, reset, and Space-to-center selection never request or mutate
project data. Left activation visibly selects the node and opens a compact descriptor card.
Right-click opens the full inspector. Descriptor-pill activation fills the fixed left panel with an
exact bounded category result set. The fixed right panel contains neighborhood navigation.
Replacing the current root requires an explicit Explore neighborhood action. The Nodes/Flow
selector retains the same graph until a later contract defines flow semantics. The open browser
renews a bounded lease in a detached local worker, so standard-input transaction completion does
not close the listener. The worker tracks the longer-lived MCP client host and closes when that
owner exits.
Explicit service shutdown closes its tracked worker, and abandoned pages expire.

## Excluded tools

The normal server never exposes shell execution, arbitrary reads or writes, canonical changeset
application, declared project-output rendering, arbitrary renderer execution, Git mutation, project
builds, deployment, publication, external HTTP binding, global project selection, or cross-project
retrieval.

DFG-9 permanently retained manual canonical integration for DocForge 0.x. No application tool is
planned for MCP. A future local developer workflow may be considered only through a new approved
contract, and it must not make canonical application reachable from an MCP writer.

DocForge pins the official stable Python MCP SDK to the compatible `mcp>=1.28,<2` release line.
Migration to a later major release requires a separate contract and protocol compatibility review.