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
• 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 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@8 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, and node-neighborhood JSON. 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. Nodes presents the bounded neighborhood with relation-specific colors, line patterns, directional symbols, and a visible key. Its navigation groups the focus, nodes reachable through outgoing edges, and remaining incoming or lateral context. Flow presents the same bounded snapshot as an upstream lineage. Execution edges retain their declared direction; reads, imports, and dependencies reverse to show what feeds the focus; structural, evidence, and context edges are excluded. The same relationship key is regenerated from the visible Flow edges. 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, 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.