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_bootstrap
• docforge_sync
• 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. Every normal tool call first checks current source identity and atomically rebuilds disposable index state when it is missing, stale, or invalid. docforge_bootstrap performs that synchronization and returns the complete fixed binding, active index path, proposal and application capabilities, and recommended workflow. docforge_sync exposes the same idempotent synchronization explicitly. Neither operation changes canonical sources.

Adapter-backed servers also validate their process-start implementation fingerprint before every tool. adapter_restart_required is stale but not synchronizable. Its remediation is restart_project_server; the current process does not reload project code, update Git staging, or continue with a newly changed validator.

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_register_changes
• docforge_list_changesets
• docforge_get_changeset
• docforge_rebase_changeset
• docforge_abandon_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.

docforge_register_changes is the preferred write entry point. It creates, populates, projects, conflict-checks, and validates one complete changeset in a single locked operation. Existing-node operations may omit expected_content_hash; the server captures the current synchronized node hash inside that transaction. The stored changeset remains fully hash-bound.

docforge_rebase_changeset moves a stale proposal to the current project base only when all touched nodes, sources, relationships, permissions, and graph invariants still validate. It never merges prose. docforge_abandon_changeset preserves an audit receipt without deleting the proposal. Changeset listing returns draft and ready work by default. Stale, applied, and abandoned proposals remain available through an explicit status or history request. Applied and abandoned proposals no longer participate in overlap conflict detection.

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. Canonical success records an applied lifecycle receipt bound to the reviewed changeset hash before refreshing derived state. Index or render refresh failures return a successful canonical application with a degraded derived-refresh report and explicit remediation; they never invite the caller to apply the same canonical change twice. DocForge 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@17 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, composable node-kind/language/capability 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, highlights its incident edges and direct neighbors, mutes unrelated visible paths, 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.

Preserved no-AST bindings

An owner may start the generic MCP server with --no-ast:

docforge-mcp --project-root /absolute/project --no-ast

Project-owned integrations select the same immutable process policy with create_project_server(..., no_ast=True) or create_read_only_server(..., no_ast=True).

The policy preserves the current adapter extraction strategy. It does not require an adapter API migration and does not disable complete-projection loading or non-AST incremental fingerprinting, invalidation, and caching.

Both docforge_bootstrap and docforge_get_contract report the exact policy. MCP server instructions tell clients not to add Python AST, Tree-sitter, compiler-AST, or function-Logic extraction. Under this binding:

• docforge_get_logic returns adapter_policy_forbids_logic;
• a nonempty Logic projection is rejected before index publication;
• a pre-existing index containing Logic is rejected before any read or live-viewer snapshot;
• hash-bound canonical application refresh uses the same policy-bound index;
• adapter_ast_upgrade and function_logic_extraction appear as excluded operations; and
• changing the policy requires changing the process configuration and starting a new MCP process.

The policy governs the DocForge binding and conforming MCP clients. DocForge can enforce published and indexed Logic, but it does not inspect arbitrary adapter source to prove which parser implementation the adapter uses. DocForge still exposes no filesystem sandbox and cannot prevent an unrelated process with direct repository write access from editing adapter files. Repository permissions and project instructions remain responsible for that broader boundary.