105 lines
5.7 KiB
Markdown
105 lines
5.7 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`
|
|
- `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@11` 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.
|