93 lines
4.8 KiB
Markdown
93 lines
4.8 KiB
Markdown
# 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@5` 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/filter, 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: wheel zoom, left-button drag pan, explicit zoom
|
|
buttons, and reset never request or mutate project data. Graph-node activation fetches exact node
|
|
data from the same bounded read endpoint and opens a client-side modal inspector. Replacing the
|
|
current root requires the modal's explicit Explore neighborhood action. 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.
|