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.

Canonical application is a second independent startup gate. The generic server accepts
`--canonical-applier WRITER_ID`. A project adapter must also supply a compatible project-owned
canonical applier implementation.

## Read tools

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

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 arbitrary tools or weaken core changeset
validation. The fixed application tool is registered only through the separate canonical applier
gate.

## 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_relationship_update`
- `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.
The relationship-update tool queues additions and removals without rewriting node content and
rejects an empty relationship list.

## Canonical application tool

- `docforge_apply_changeset`

The tool is absent unless canonical application was explicitly enabled at startup. It accepts one
changeset ID and the exact final changeset SHA-256. It revalidates the current canonical base,
proposal ownership, node hashes, conflicts, graph, permissions, and paths before invoking the
configured serializer.

The generic serializer confines staged Markdown/TOML writes to declared content roots and verifies
that the applied files reproduce the approved graph projection. A mismatch rolls canonical files
back. A successful apply rebuilds and checks the derived index and regenerates all declared render
views. It does not run project commands, shell, Git, builds, deployment, or publication.

## 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@16` 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, semantic Flow,
convergence Web, lazy function-scoped Logic, and a bounded project-confined source read for one
indexed node. `docforge_get_logic` and the browser Logic endpoint accept one exact owner node ID and
return only that bounded stored projection. 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. Users may hide
non-focus nodes and restore them entirely client-side. Flow and Web prune upstream-only branches
disconnected by a hidden node while retaining descendants that still lead to the focus. Source
actions open the indexed source path
and navigate to recognized anchors. Nodes presents the
bounded neighborhood with relation-specific colors, line patterns, directional symbols, and a
visible key. Semantic cards identify the focus and relation-derived Structure, Behavior,
Dependency, Execution, Data, Evidence, Context, and Related contributors. Cards display readable
leaf names and node kinds without truncation; complete qualified identities remain available in
tooltips and inspectors. Flow presents semantic ancestry with relation-aware direction.
Web follows bounded structural, dependency, execution, evidence, and contextual contributors into
the focus. Direct focus-owned members and execution dependencies become adjacent contributor
branches without expanding unrelated siblings. The relationship key is regenerated from each
visible view. Logic displays possible static control paths for a focused function or method without
adding its statement-level nodes to primary search or architectural traversal. Hiding a Logic step
bridges its retained predecessors and successors with an explicit omitted path. The browser runs in
a project-bound worker owned by
the separately supervised per-user viewer manager. Standard-input transaction completion and MCP
host exit do not close the listener. Repeated visualization requests reuse the current worker while
its exact snapshot remains valid. `docforge_visualization_status` reports lifecycle state, and
`docforge_stop_visualization` explicitly stops the current project's worker. The manager reclaims a
worker only after one hour with no browser activity.

## Excluded tools

The normal server never exposes shell execution, arbitrary reads or writes, arbitrary renderer
execution, Git mutation, project builds, deployment, publication, external HTTP binding, global
project selection, or cross-project retrieval. Without the explicit canonical applier gate, it also
does not expose canonical application.

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.