Consolidate DocForge setup and command reference
This commit is contained in:
parent
e405326334
commit
3c15e26283
4 changed files with 337 additions and 445 deletions
412
README.md
412
README.md
|
|
@ -1,108 +1,356 @@
|
|||
# DocForge
|
||||
|
||||
DocForge is a project-scoped documentation service for people and AI agents. It loads canonical
|
||||
Markdown and TOML from one repository, validates stable nodes and relationships, builds a disposable
|
||||
search index, and returns bounded context with source provenance.
|
||||
DocForge is a project-scoped documentation service for people and AI agents. It reads canonical
|
||||
Markdown and TOML from one repository, validates stable nodes and relationships, builds a
|
||||
disposable graph/search index, and returns bounded context with source provenance.
|
||||
|
||||
DocForge does not own project facts. It does not select project work, apply proposals, run project
|
||||
commands, or perform Git and deployment operations. It may write only configured derived output and
|
||||
isolated previews through the explicit render boundary.
|
||||
The canonical manual remains the project’s source of truth. DocForge does not apply canonical
|
||||
changes, select project work, run project commands, commit, push, deploy, or publish. It may write
|
||||
only configured derived output and isolated proposal previews through explicit boundaries.
|
||||
|
||||
## Current state
|
||||
This README is the complete setup and command reference. `docs/NEW_PROJECT_QUICKSTART.md` is kept
|
||||
only as a compatibility link for existing bookmarks.
|
||||
|
||||
DFG-0 through DFG-14 are complete. Worldforge uses separate read-only sessions and an optional
|
||||
AssetForge-only proposal process. OpenClaw can propose updates to existing AssetForge chapter prose
|
||||
through isolated, validated changesets and escaped previews. Canonical integration remains a
|
||||
developer review step through Worldforge's established builder. DFG-9 found no measured need for an
|
||||
application command, so manual canonical integration is the permanent DocForge 0.x policy.
|
||||
Canonical application remains external and closed to the library, CLI, and MCP server. See
|
||||
[`docs/APPLICATION_DECISION.md`](docs/APPLICATION_DECISION.md).
|
||||
## What DocForge provides
|
||||
|
||||
DFG-10 adds one generic `docforge_visualize` MCP tool. It validates the configured project and
|
||||
derived index, then starts a token-protected read-only graph browser on `127.0.0.1`. The browser
|
||||
supports project counts, family filtering, lexical search, exact node inspection, and bounded
|
||||
incoming-and-outgoing neighborhoods. It accepts no project path, database path, SQL, external bind
|
||||
address, or write operation.
|
||||
- A project-bound CLI for validation, indexing, graph queries, context, and declared renders.
|
||||
- A stdio MCP server with a fixed, project-scoped read surface.
|
||||
- Optional isolated documentation proposal changesets. Canonical application stays in the owning
|
||||
project’s normal editing and review workflow.
|
||||
- A loopback-only graph browser with a native per-user viewer manager.
|
||||
- A generic manual adapter and a contract for project-owned source-code adapters.
|
||||
|
||||
DFG-11 upgrades the fixed browser template with pointer-centered mouse-wheel zoom, left-button drag
|
||||
pan, zoom buttons, a reset control, and a live zoom percentage. These controls operate only on the
|
||||
client-side SVG viewport and do not broaden the read-only HTTP or project authority boundary.
|
||||
The generic adapter reads only declared Markdown and TOML nodes. It does not infer application
|
||||
modules, functions, calls, routes, tables, tests, or ownership. Projects that need those facts
|
||||
provide a deterministic, project-owned source adapter.
|
||||
|
||||
DFG-12 makes graph-node activation open a modal inspector without replacing the current
|
||||
neighborhood. The dialog exposes the node's complete validated content and offers a separate
|
||||
Explore neighborhood action when the user wants to recenter the graph.
|
||||
## Install and verify
|
||||
|
||||
DFG-13 makes pointer activation reliable by delaying SVG pointer capture until an actual drag
|
||||
crosses the movement threshold. It also ensures the empty-canvas instruction disappears whenever a
|
||||
neighborhood is rendered.
|
||||
|
||||
DFG-14 makes the viewer useful as a durable project-manual navigator. Resizable side panels and a
|
||||
draggable, resizable inspector support dense material. Neighborhoods are grouped generically by
|
||||
topology into the focus node, outgoing paths, and incoming or lateral context, with distinct
|
||||
palettes and progressive hop-distance shading.
|
||||
|
||||
DFG-17 makes relationship meaning visible without changing project graph facts. Nodes displays
|
||||
relation-specific colors, line patterns, directional symbols, and an exact visible key. Flow
|
||||
constructs a bounded upstream lineage with semantic direction for execution, data, and dependency
|
||||
relations while excluding structural and evidence context.
|
||||
|
||||
DFG-18 makes the viewer a managed project-bound local service. A native per-user supervisor owns
|
||||
the viewer manager, which survives MCP process turnover, reuses the current snapshot URL, exposes
|
||||
status and explicit stop tools, and reclaims only genuinely idle workers.
|
||||
|
||||
## Development
|
||||
|
||||
Install Pyright once with `npm install -g pyright`. DocForge configures it to use the repository
|
||||
virtual environment and treats a clean strict run as a required development gate.
|
||||
Requirements: Python 3.12+, [`uv`](https://docs.astral.sh/uv/), and Node/npm for browser-asset
|
||||
validation. Install Pyright once globally.
|
||||
|
||||
```bash
|
||||
git clone forgejo@repo.andraxion.net:administrator/DocForge.git /absolute/path/DocForge
|
||||
cd /absolute/path/DocForge
|
||||
uv sync
|
||||
npm ci
|
||||
pyright
|
||||
npm install -g pyright
|
||||
|
||||
pyright --pythonpath .venv/bin/python
|
||||
npm run lint:web
|
||||
uv run ruff check src tests tools
|
||||
uv run ruff format --check src tests tools
|
||||
uv run python -m unittest discover -s tests -v
|
||||
uv run docforge --project-root tests/fixtures/alpha validate
|
||||
uv run docforge --project-root tests/fixtures/alpha render-status manual
|
||||
uv run docforge --project-root tests/fixtures/alpha render manual
|
||||
uv run docforge-mcp --project-root tests/fixtures/alpha --proposal-writer alpha-editor
|
||||
```
|
||||
|
||||
The web gate validates the exact graph-browser HTML, CSS, and JavaScript served by DocForge. It also
|
||||
renders the fixture manual into a temporary project and validates that final HTML document.
|
||||
`npm run lint:web` validates the exact HTML, CSS, and JavaScript served by the graph browser, plus
|
||||
a freshly rendered fixture manual.
|
||||
|
||||
The command prints deterministic JSON. Derived indexes live under each project's configured cache
|
||||
directory and are never canonical input.
|
||||
## Connect a generic project
|
||||
|
||||
Proposal writers are declared by ID in `.docforge/project.toml`. Each writer receives explicit node
|
||||
families and operation types. The MCP process binds to one writer at startup; tools cannot select or
|
||||
impersonate another writer. Create, update, move, and delete tools write only isolated JSON
|
||||
changesets below the configured changeset root.
|
||||
### 1. Create the project descriptor
|
||||
|
||||
Projects may also declare render views with confined template, preview, and output paths. The first
|
||||
built-in renderer converts CommonMark to escaped HTML through strict template tokens. MCP may render
|
||||
validated changesets only into isolated preview paths. Declared project output is generated through
|
||||
the explicit local CLI command and is never an MCP operation.
|
||||
Create `/absolute/path/MyProject/.docforge/project.toml`:
|
||||
|
||||
Project adapters implement `AdapterLoader` and return one ordered, immutable `AdapterProjection`.
|
||||
`AdapterProject` validates the projection and exposes it through the same disposable index used by
|
||||
generic projects. Project-specific context, query ordering, and render-model policy remain in the
|
||||
adapter. Shadow adapters are local integration tools; the normal MCP server does not discover or
|
||||
execute them. An explicit integration may bind a validated adapter project to DocForge's read-only
|
||||
MCP surface without enabling proposal tools.
|
||||
```toml
|
||||
schema_version = 1
|
||||
project_id = "my-project"
|
||||
title = "My Project"
|
||||
adapter = "generic"
|
||||
|
||||
Proposal-enabled adapters supply confined project settings and a project-owned validator. The core
|
||||
still owns hashes, permissions, changeset storage, conflict checks, graph validation, diffs, and
|
||||
preview confinement. The adapter owns source-format rules and may only narrow the allowed proposal
|
||||
surface.
|
||||
[sources]
|
||||
content_roots = ["Docs/Manual"]
|
||||
authority_files = []
|
||||
|
||||
Both generic and explicit adapter MCP servers expose the same visualization tools because they read
|
||||
the validated `ProjectIndex` supplied by the project binding. `docforge_visualize` reuses its
|
||||
unguessable loopback URL when the current snapshot remains valid, or replaces the worker after a
|
||||
complete index check when it does not. The per-user viewer manager retains active workers across
|
||||
MCP process turnover, reports state through `docforge_visualization_status`, and reclaims idle
|
||||
workers after one hour. See [`docs/VIEWER_MANAGER.md`](docs/VIEWER_MANAGER.md) for installation.
|
||||
[derived]
|
||||
cache_root = ".docforge/cache"
|
||||
index = ".docforge/cache/index.sqlite3"
|
||||
|
||||
See [`docs/NEW_PROJECT_QUICKSTART.md`](docs/NEW_PROJECT_QUICKSTART.md) for a complete generic MCP
|
||||
setup, continuous-agent policy, visualization instructions, and a project-adapter checklist.
|
||||
[changesets]
|
||||
root = ".docforge/changesets"
|
||||
|
||||
[[changesets.writers]]
|
||||
id = "project-editor"
|
||||
families = ["architecture", "core", "system", "function", "operations", "roadmap"]
|
||||
operations = ["create", "update", "move", "delete"]
|
||||
|
||||
[graph]
|
||||
allowed_relations = ["depends_on", "owns", "calls", "reads", "writes", "tested_by", "relates_to"]
|
||||
|
||||
[limits]
|
||||
max_source_bytes = 500000
|
||||
max_nodes = 10000
|
||||
max_query_chars = 500
|
||||
max_results = 100
|
||||
max_traversal_depth = 6
|
||||
max_context_tokens = 12000
|
||||
max_changesets = 100
|
||||
max_changeset_operations = 100
|
||||
max_changeset_bytes = 1000000
|
||||
|
||||
[[profiles]]
|
||||
id = "development"
|
||||
families = ["architecture", "core", "system", "function", "operations", "roadmap"]
|
||||
statuses = ["current", "active", "open", "verified"]
|
||||
required_nodes = ["architecture.overview"]
|
||||
token_budget = 8000
|
||||
dependency_depth = 3
|
||||
```
|
||||
|
||||
Choose only family names, relations, limits, and required root nodes that the actual project can
|
||||
support truthfully.
|
||||
|
||||
### 2. Add canonical nodes
|
||||
|
||||
Create `/absolute/path/MyProject/Docs/Manual/architecture-overview.md`:
|
||||
|
||||
```markdown
|
||||
+++
|
||||
schema_version = 1
|
||||
id = "architecture.overview"
|
||||
title = "Architecture overview"
|
||||
family = "architecture"
|
||||
authority = "authoritative"
|
||||
status = "current"
|
||||
tags = ["architecture", "ownership"]
|
||||
summary = "Defines the top-level systems and ownership boundaries."
|
||||
+++
|
||||
|
||||
# Architecture overview
|
||||
|
||||
Describe the project’s core authorities, system boundaries, persistence owners, runtime flow,
|
||||
failure behavior, tests, and operational entry points.
|
||||
```
|
||||
|
||||
Every node needs a stable, unique `id`. Declare relationships in the same front matter:
|
||||
|
||||
```toml
|
||||
depends_on = ["core.database"]
|
||||
calls = ["system.metadata"]
|
||||
tested_by = ["function.test-metadata-publication"]
|
||||
```
|
||||
|
||||
Targets must already exist in the graph. Keep each node focused enough that an agent can retrieve
|
||||
relevant facts without loading the entire manual.
|
||||
|
||||
### 3. Build and check the derived graph
|
||||
|
||||
```bash
|
||||
DOCFORGE=/absolute/path/DocForge/.venv/bin/docforge
|
||||
PROJECT=/absolute/path/MyProject
|
||||
|
||||
"$DOCFORGE" --project-root "$PROJECT" validate
|
||||
"$DOCFORGE" --project-root "$PROJECT" build
|
||||
"$DOCFORGE" --project-root "$PROJECT" check
|
||||
"$DOCFORGE" --project-root "$PROJECT" context development
|
||||
```
|
||||
|
||||
`build` creates the disposable SQLite index in the configured cache path. Canonical Markdown and
|
||||
TOML remain authoritative. Rebuild after canonical documentation changes. A stale or altered index
|
||||
fails closed.
|
||||
|
||||
## CLI command reference
|
||||
|
||||
Every command emits deterministic JSON and begins with:
|
||||
|
||||
```bash
|
||||
docforge --project-root /absolute/path/MyProject <command>
|
||||
```
|
||||
|
||||
| Command | Purpose |
|
||||
| --- | --- |
|
||||
| `info` | Report the bound project and descriptor facts. |
|
||||
| `validate` | Validate the descriptor and canonical source graph. |
|
||||
| `build` | Build the disposable index. |
|
||||
| `check` | Validate source and confirm the index matches it. |
|
||||
| `validate-index` | Validate the existing derived index’s schema and identity. |
|
||||
| `show NODE_ID` | Return one complete node. |
|
||||
| `search QUERY [--limit N]` | Lexically search nodes. |
|
||||
| `filter [--family X] [--authority X] [--status X] [--tag X] [--limit N]` | Filter nodes by declared fields. |
|
||||
| `backlinks NODE_ID [--relation RELATION]` | Return incoming relationships. |
|
||||
| `dependencies NODE_ID [--depth N]` | Traverse declared dependencies. |
|
||||
| `impact NODE_ID [--depth N]` | Traverse likely downstream impact. |
|
||||
| `context PROFILE [--budget N]` | Return bounded, cited context for one configured profile. |
|
||||
| `render-status [VIEW_ID]` | Report declared render output state. |
|
||||
| `render VIEW_ID` | Generate one configured canonical render output. |
|
||||
| `preview CHANGESET_ID VIEW_ID` | Render one isolated changeset preview. |
|
||||
|
||||
Examples:
|
||||
|
||||
```bash
|
||||
docforge --project-root "$PROJECT" show architecture.overview
|
||||
docforge --project-root "$PROJECT" search metadata --limit 20
|
||||
docforge --project-root "$PROJECT" filter --family system --status current
|
||||
docforge --project-root "$PROJECT" backlinks system.metadata --relation calls
|
||||
docforge --project-root "$PROJECT" dependencies system.metadata --depth 3
|
||||
docforge --project-root "$PROJECT" impact system.metadata --depth 3
|
||||
docforge --project-root "$PROJECT" render-status manual
|
||||
docforge --project-root "$PROJECT" render manual
|
||||
```
|
||||
|
||||
## MCP server
|
||||
|
||||
Run one MCP server per project. Use absolute paths.
|
||||
|
||||
```bash
|
||||
docforge-mcp --project-root /absolute/path/MyProject --proposal-writer project-editor
|
||||
```
|
||||
|
||||
Omit `--proposal-writer` for a read-only integration. The writer value is a configured writer ID,
|
||||
not a shell command.
|
||||
|
||||
For an MCP client that uses JSON configuration:
|
||||
|
||||
```json
|
||||
{
|
||||
"mcpServers": {
|
||||
"my-project-docforge": {
|
||||
"command": "/absolute/path/DocForge/.venv/bin/docforge-mcp",
|
||||
"args": [
|
||||
"--project-root",
|
||||
"/absolute/path/MyProject",
|
||||
"--proposal-writer",
|
||||
"project-editor"
|
||||
]
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Fixed read tools
|
||||
|
||||
| MCP tool | Purpose |
|
||||
| --- | --- |
|
||||
| `docforge_project_info` | Project identity, index health, and capabilities. |
|
||||
| `docforge_get_contract` | Bound project contract and excluded operations. |
|
||||
| `docforge_get_node` | One exact node with full validated content. |
|
||||
| `docforge_search` | Lexical node search. |
|
||||
| `docforge_filter_nodes` | Filter by family, authority, status, or tag. |
|
||||
| `docforge_backlinks` | Incoming graph relationships. |
|
||||
| `docforge_dependencies` | Declared dependency traversal. |
|
||||
| `docforge_impact` | Downstream impact traversal. |
|
||||
| `docforge_get_context` | Bounded, cited context for a configured profile. |
|
||||
| `docforge_validate_project` | Validate source and derived index state. |
|
||||
| `docforge_render_status` | Declared render-output state. |
|
||||
| `docforge_visualize` | Start or reuse the project’s managed, read-only graph viewer. |
|
||||
| `docforge_visualization_status` | Viewer state, URL, and lifecycle information. |
|
||||
| `docforge_stop_visualization` | Explicitly stop the project viewer. |
|
||||
|
||||
When a proposal writer is configured, the server additionally exposes:
|
||||
|
||||
```text
|
||||
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
|
||||
```
|
||||
|
||||
MCP proposals write only isolated changesets. Review the diff, apply the approved text through the
|
||||
project’s normal workflow, then run `validate`, `build`, and `check`.
|
||||
|
||||
## Managed graph viewer
|
||||
|
||||
Install the per-user manager once:
|
||||
|
||||
```bash
|
||||
docforge-viewer-manager install-user-service
|
||||
```
|
||||
|
||||
Its lifecycle commands are:
|
||||
|
||||
```bash
|
||||
docforge-viewer-manager serve
|
||||
docforge-viewer-manager uninstall-user-service
|
||||
```
|
||||
|
||||
The native supervisor is systemd on Linux, a LaunchAgent on macOS, and Task Scheduler on Windows.
|
||||
The manager owns one loopback-only viewer worker per project snapshot. `docforge_visualize` starts
|
||||
or reuses it. Active browser requests renew its one-hour idle timeout. Stop it explicitly through
|
||||
`docforge_stop_visualization` when it is no longer wanted.
|
||||
|
||||
The viewer is read-only, token-protected, and bound to `127.0.0.1`. It shows both:
|
||||
|
||||
- **Nodes:** the bounded local graph with original stored relationship direction.
|
||||
- **Flow:** the complete bounded directed ancestry of the selected node. It follows every incoming
|
||||
stored edge recursively, preserving `source → target`; it does not infer or reverse arrows based
|
||||
on relationship names.
|
||||
|
||||
## Project-owned source adapters
|
||||
|
||||
Use the generic adapter when a declared manual graph is sufficient. Build a project-owned adapter
|
||||
when the graph must include source files, modules, functions, routes, tables, tests, or other
|
||||
code-derived facts.
|
||||
|
||||
An adapter must:
|
||||
|
||||
1. Read source as data. Never import or execute the application to discover facts.
|
||||
2. Use a deterministic, project-confined source set. For Git repositories, start with
|
||||
`git ls-files` and exclude generated output, caches, secrets, and binaries.
|
||||
3. Emit only evidence-backed nodes and edges with stable IDs, safe relative anchors, and hashes.
|
||||
4. Sort nodes, edges, and metadata deterministically.
|
||||
5. Return one immutable `AdapterProjection` through `AdapterLoader.load_projection()`.
|
||||
6. Keep its cache within the project and build/check through `ProjectIndex`.
|
||||
7. Bind the projection to `create_read_only_server()` unless an explicit proposal policy exists.
|
||||
8. Reject proposal operations against derived nodes and adapter-created edges.
|
||||
|
||||
The project owns its adapter and launches it rather than generic `docforge-mcp`:
|
||||
|
||||
```json
|
||||
{
|
||||
"mcpServers": {
|
||||
"my-project-docforge": {
|
||||
"command": "/absolute/path/MyProject/.venv/bin/python",
|
||||
"args": [
|
||||
"-m",
|
||||
"docforge_adapter.server",
|
||||
"serve",
|
||||
"--project-root",
|
||||
"/absolute/path/MyProject"
|
||||
]
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Require deterministic build, staleness, malformed-input, project-isolation, MCP-protocol, and
|
||||
project full-gate tests before relying on an adapter.
|
||||
|
||||
## Agent policy
|
||||
|
||||
Add a project-specific version of this to `AGENTS.md`:
|
||||
|
||||
```markdown
|
||||
## Canonical documentation and DocForge
|
||||
|
||||
- `/Docs/Manual/` is the canonical systems manual and architecture source of truth.
|
||||
- Before a systems-level, persistence, API, worker, plugin, operational, or mainline change, call
|
||||
`docforge_project_info` or `docforge_validate_project`, then retrieve relevant nodes with
|
||||
`docforge_search`, `docforge_get_context`, or `docforge_get_node`.
|
||||
- Inspect dependencies, backlinks, and impact at ownership boundaries. Read implementation and
|
||||
tests as well as the manual. Treat a code/manual disagreement as a defect.
|
||||
- After implementation, create and validate an isolated DocForge changeset. Review its diff.
|
||||
- Apply approved text through the normal editing workflow, then run `validate`, `build`, and
|
||||
`check`. Do not commit derived caches, changesets, or previews unless the project explicitly says
|
||||
otherwise.
|
||||
- When asked to visualize a project or node, call `docforge_visualize`.
|
||||
```
|
||||
|
||||
## Normal development loop
|
||||
|
||||
1. Validate the DocForge project.
|
||||
2. Retrieve relevant context, backlinks, dependencies, and impact.
|
||||
3. Inspect the corresponding implementation and tests.
|
||||
4. Implement and test the change.
|
||||
5. Create and validate a DocForge proposal when manual changes are needed.
|
||||
6. Review the proposal diff and apply approved text through the normal project workflow.
|
||||
7. Run `validate`, `build`, and `check`.
|
||||
8. Run the project’s complete test gate.
|
||||
9. Commit code, tests, and canonical manual updates together.
|
||||
|
||||
DocForge never applies, commits, pushes, builds, deploys, or publishes on the project’s behalf.
|
||||
|
|
|
|||
|
|
@ -106,7 +106,7 @@ incoming-and-outgoing neighborhoods. Descriptor filtering accepts only
|
|||
family, authority, status, or tag plus one exact value. There is no write endpoint, arbitrary query
|
||||
endpoint, static filesystem handler, external asset, or project-selection control.
|
||||
|
||||
The `graph-browser@8` template provides mouse-wheel zoom centered on the pointer, left-button drag
|
||||
The `graph-browser@11` template provides mouse-wheel zoom centered on the pointer, left-button drag
|
||||
pan, explicit zoom-in and zoom-out buttons, a reset-view button, and a live zoom percentage. A
|
||||
four-pixel drag threshold defers pointer capture and preserves node activation for ordinary clicks.
|
||||
Loading another root node fits the viewport to the returned neighborhood, including a useful
|
||||
|
|
|
|||
|
|
@ -63,7 +63,7 @@ only through the explicit local CLI integration command.
|
|||
|
||||
## Visualization boundary
|
||||
|
||||
`docforge_visualize` starts the fixed built-in `graph-browser@8` template against the currently
|
||||
`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.
|
||||
|
||||
|
|
|
|||
|
|
@ -1,363 +1,7 @@
|
|||
# DocForge: New Project Quickstart
|
||||
# DocForge setup moved to the README
|
||||
|
||||
This guide connects one project to DocForge so an AI agent can read its documentation graph before
|
||||
development work, propose documentation updates during development, inspect impact, and keep the
|
||||
canonical manual synchronized with the code.
|
||||
The complete installation, project setup, CLI, MCP, viewer-manager, adapter, and agent-policy
|
||||
reference now lives in the [DocForge README](../README.md).
|
||||
|
||||
DocForge is project-bound. Run one MCP server per project. Its MCP tools can read the validated
|
||||
graph and write isolated proposals, but they cannot directly edit canonical documentation, run
|
||||
builds, use Git, or deploy software. Canonical changes must be applied through the project's normal
|
||||
editing and review workflow.
|
||||
|
||||
## What this installs
|
||||
|
||||
The DocForge repository contains the complete generic CLI and stdio MCP server. Launching
|
||||
`docforge-mcp` as shown below exposes:
|
||||
|
||||
- Project identity, validation, exact-node retrieval, lexical search, and filtering.
|
||||
- Backlinks, dependency traversal, impact traversal, and bounded context profiles.
|
||||
- `docforge_visualize`, which starts the token-protected, loopback-only `graph-browser@8` viewer.
|
||||
The viewer supports search, family filtering, exact-node inspection, bounded neighborhoods,
|
||||
exact descriptor-pill filtering, compact left-click descriptors, full right-click inspection,
|
||||
fixed search and neighborhood side panels, explicit neighborhood exploration, fitted single- and
|
||||
multi-node framing, visible node selection, Space-to-center, mouse-wheel zoom, left-button drag
|
||||
panning, zoom controls, viewport reset, relationship color and symbol keys, and an upstream
|
||||
lineage Flow view.
|
||||
- `docforge_stop_visualization`, which explicitly stops the current project's persistent viewer.
|
||||
- `docforge_visualization_status`, which reports the manager-owned viewer state.
|
||||
- Isolated documentation changesets, proposal validation, diffs, and escaped HTML previews when a
|
||||
proposal writer and render view are configured.
|
||||
|
||||
The generic adapter graphs the Markdown and TOML nodes and relationships declared by the project.
|
||||
It does **not** inspect arbitrary source code or automatically infer modules, functions, calls,
|
||||
routes, database tables, tests, or ownership.
|
||||
|
||||
A project that needs automatic source-code graph extraction must provide a project-specific
|
||||
DocForge adapter. The adapter deterministically projects those code facts into DocForge nodes and
|
||||
edges, then binds that projection to DocForge's standard index and MCP tools. Ani-web's large code
|
||||
graph is an example of a custom adapter; it is not behavior supplied by the generic quickstart.
|
||||
|
||||
## 1. Install DocForge
|
||||
|
||||
Requirements:
|
||||
|
||||
- Python 3.12 or newer.
|
||||
- `uv`.
|
||||
- Access to the DocForge repository.
|
||||
|
||||
```bash
|
||||
git clone forgejo@repo.andraxion.net:administrator/DocForge.git /absolute/path/DocForge
|
||||
cd /absolute/path/DocForge
|
||||
uv sync
|
||||
uv run python -m unittest discover -s tests -v
|
||||
```
|
||||
|
||||
Use absolute paths in all MCP configuration.
|
||||
|
||||
## 2. Configure the project
|
||||
|
||||
Create `/absolute/path/MyProject/.docforge/project.toml`:
|
||||
|
||||
```toml
|
||||
schema_version = 1
|
||||
project_id = "my-project"
|
||||
title = "My Project"
|
||||
adapter = "generic"
|
||||
|
||||
[sources]
|
||||
content_roots = ["Docs/Manual"]
|
||||
authority_files = []
|
||||
|
||||
[derived]
|
||||
cache_root = ".docforge/cache"
|
||||
index = ".docforge/cache/index.sqlite3"
|
||||
|
||||
[changesets]
|
||||
root = ".docforge/changesets"
|
||||
|
||||
[[changesets.writers]]
|
||||
id = "project-editor"
|
||||
families = ["architecture", "core", "system", "function", "operations", "roadmap"]
|
||||
operations = ["create", "update", "move", "delete"]
|
||||
|
||||
[graph]
|
||||
allowed_relations = [
|
||||
"depends_on",
|
||||
"owns",
|
||||
"calls",
|
||||
"reads",
|
||||
"writes",
|
||||
"tested_by",
|
||||
"relates_to",
|
||||
]
|
||||
|
||||
[limits]
|
||||
max_source_bytes = 500000
|
||||
max_nodes = 10000
|
||||
max_query_chars = 500
|
||||
max_results = 100
|
||||
max_traversal_depth = 6
|
||||
max_context_tokens = 12000
|
||||
max_changesets = 100
|
||||
max_changeset_operations = 100
|
||||
max_changeset_bytes = 1000000
|
||||
|
||||
[[profiles]]
|
||||
id = "development"
|
||||
families = ["architecture", "core", "system", "function", "operations", "roadmap"]
|
||||
statuses = ["current", "active", "open", "verified"]
|
||||
required_nodes = ["architecture.overview"]
|
||||
token_budget = 8000
|
||||
dependency_depth = 3
|
||||
```
|
||||
|
||||
Choose family names, relationship names, limits, and the required root node for the actual project.
|
||||
Do not copy relationships that the project cannot support truthfully.
|
||||
|
||||
## 3. Create canonical nodes
|
||||
|
||||
Create `/absolute/path/MyProject/Docs/Manual/architecture-overview.md`:
|
||||
|
||||
```markdown
|
||||
+++
|
||||
schema_version = 1
|
||||
id = "architecture.overview"
|
||||
title = "Architecture overview"
|
||||
family = "architecture"
|
||||
authority = "authoritative"
|
||||
status = "current"
|
||||
tags = ["architecture", "ownership"]
|
||||
summary = "Defines the top-level systems and ownership boundaries."
|
||||
+++
|
||||
|
||||
# Architecture overview
|
||||
|
||||
Describe the project, its core authorities, system boundaries, persistence owners, runtime flow,
|
||||
failure behavior, tests, and operational entry points.
|
||||
```
|
||||
|
||||
Every node needs a stable, unique `id`. Relationships are declared in the same front matter:
|
||||
|
||||
```toml
|
||||
depends_on = ["core.database"]
|
||||
calls = ["system.metadata"]
|
||||
tested_by = ["function.test-metadata-publication"]
|
||||
```
|
||||
|
||||
The relationship target must already exist in the project graph. Keep nodes focused enough that an
|
||||
agent can retrieve the relevant facts without loading the whole manual.
|
||||
|
||||
## 4. Validate and build the graph
|
||||
|
||||
```bash
|
||||
DOCFORGE=/absolute/path/DocForge/.venv/bin/docforge
|
||||
PROJECT=/absolute/path/MyProject
|
||||
|
||||
"$DOCFORGE" --project-root "$PROJECT" validate
|
||||
"$DOCFORGE" --project-root "$PROJECT" build
|
||||
"$DOCFORGE" --project-root "$PROJECT" check
|
||||
"$DOCFORGE" --project-root "$PROJECT" context development
|
||||
```
|
||||
|
||||
`build` creates the disposable SQLite index under `.docforge/cache/`. Canonical Markdown remains the
|
||||
source of truth. Rebuild after canonical documentation changes. A stale or altered index fails
|
||||
closed.
|
||||
|
||||
## 5. Register the MCP server
|
||||
|
||||
Add a project-specific stdio MCP server to the agent host:
|
||||
|
||||
```json
|
||||
{
|
||||
"mcpServers": {
|
||||
"my-project-docforge": {
|
||||
"command": "/absolute/path/DocForge/.venv/bin/docforge-mcp",
|
||||
"args": [
|
||||
"--project-root",
|
||||
"/absolute/path/MyProject",
|
||||
"--proposal-writer",
|
||||
"project-editor"
|
||||
]
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
Restart or reload the agent host. Confirm that it exposes tools beginning with
|
||||
`docforge_project_info`, `docforge_get_node`, `docforge_search`, `docforge_dependencies`,
|
||||
`docforge_impact`, `docforge_get_context`, `docforge_visualize`, and
|
||||
`docforge_stop_visualization`, `docforge_visualization_status`, and `docforge_create_changeset`.
|
||||
|
||||
Omit `--proposal-writer` for a read-only integration.
|
||||
|
||||
## 5A. Optional source-code adapter
|
||||
|
||||
The generic setup above is complete when the project only needs a graph of its declared manual
|
||||
nodes. Build a project-specific adapter when the graph must also contain source files, modules,
|
||||
functions, routes, tables, tests, services, plugins, or other facts derived from the codebase.
|
||||
|
||||
Tell Codex to keep the adapter inside the owning project, for example:
|
||||
|
||||
```text
|
||||
MyProject/
|
||||
docforge_adapter/
|
||||
__init__.py
|
||||
graph.py # Parse tracked source as data and produce project facts.
|
||||
integration.py # Translate facts into DocForge nodes, edges, and policy.
|
||||
server.py # Build, check, report, and serve the bound MCP process.
|
||||
tests/
|
||||
test_docforge_adapter.py
|
||||
```
|
||||
|
||||
The adapter must:
|
||||
|
||||
1. Read source files as data. It must not import or execute the application to discover facts.
|
||||
2. Select a deterministic, project-confined source set. A Git project should normally begin with
|
||||
`git ls-files`; exclude generated manuals, caches, build output, secrets, and binary artifacts.
|
||||
3. Parse each supported language or format with deterministic parsers. Emit only relationships
|
||||
backed by direct evidence. Omit uncertain calls, ownership, or persistence edges instead of
|
||||
guessing.
|
||||
4. Give every node a stable ID, family, authority, status, summary, safe relative source path,
|
||||
optional source anchor, and SHA-256 content hash.
|
||||
5. Give every edge stable source and target IDs, a declared relation, and adapter metadata that
|
||||
records its evidence and origin.
|
||||
6. Sort nodes by node ID, edges by source/relation/target, and metadata by key.
|
||||
7. Implement `AdapterLoader.load_projection()` and return one immutable `AdapterProjection` with a
|
||||
resolved project root, revision, adapter ID/version, and lowercase SHA-256 source hash.
|
||||
8. Wrap the loader in `AdapterProject`, place its cache inside the project, and build/check it
|
||||
through `ProjectIndex`.
|
||||
9. Bind the project to `create_read_only_server()`. Use `create_project_server()` only after adding
|
||||
explicit `AdapterProjectSettings`, a startup-bound proposal writer, confined canonical sources,
|
||||
and a validator that prevents proposals from changing derived source nodes or adapter edges.
|
||||
10. Supply a project context provider if `docforge_get_context` needs project-specific profiles.
|
||||
Search, node retrieval, traversal, impact, and visualization work directly from the standard
|
||||
index.
|
||||
|
||||
The essential integration shape is:
|
||||
|
||||
```python
|
||||
from pathlib import Path
|
||||
|
||||
from docforge.adapter_contract import AdapterProject
|
||||
from docforge.index import ProjectIndex
|
||||
from docforge.mcp_server import create_read_only_server
|
||||
|
||||
from .graph import ProjectAdapterLoader
|
||||
|
||||
|
||||
def open_project(root: Path):
|
||||
loader = ProjectAdapterLoader(root.resolve(strict=True))
|
||||
project = AdapterProject(
|
||||
loader,
|
||||
cache_root=loader.root / ".docforge" / "cache" / "project-adapter",
|
||||
)
|
||||
return project, ProjectIndex(project)
|
||||
|
||||
|
||||
def serve(root: Path) -> None:
|
||||
project, index = open_project(root)
|
||||
index.check() # Build explicitly before serving; never hide stale state.
|
||||
create_read_only_server(project).run(transport="stdio")
|
||||
```
|
||||
|
||||
The project-owned `server.py` should provide explicit `build`, `check`, and `serve` operations. The
|
||||
MCP host then launches that module instead of the generic `docforge-mcp` command:
|
||||
|
||||
```json
|
||||
{
|
||||
"mcpServers": {
|
||||
"my-project-docforge": {
|
||||
"command": "/absolute/path/MyProject/.venv/bin/python",
|
||||
"args": [
|
||||
"-m",
|
||||
"docforge_adapter.server",
|
||||
"serve",
|
||||
"--project-root",
|
||||
"/absolute/path/MyProject"
|
||||
]
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
If the adapter combines canonical manual nodes with derived code nodes, load the generic manual
|
||||
through `Project.open(project_root)`, translate its canonical nodes and edges into `AdapterNode` and
|
||||
`AdapterEdge`, merge them with the derived projection, and reject proposal operations against all
|
||||
derived node IDs and adapter-created relationships.
|
||||
|
||||
Require these adapter acceptance checks:
|
||||
|
||||
- Two unchanged builds produce the same ordered nodes, edges, source hash, and projection identity.
|
||||
- A tracked source change changes the source hash and makes the old index stale.
|
||||
- Missing targets, duplicate IDs, unsafe paths, unsorted metadata, and invalid hashes fail closed.
|
||||
- Building the graph does not import the application or cause runtime, network, database, or
|
||||
filesystem side effects.
|
||||
- Read-only MCP exposes only the fixed DocForge read surface, including visualization start and
|
||||
explicit viewer shutdown.
|
||||
- Proposal-enabled MCP cannot modify derived source facts or write outside confined changeset and
|
||||
preview roots.
|
||||
- Build, check, MCP protocol tests, adapter tests, and the owning project's full test gate pass.
|
||||
|
||||
### Ready-to-give Codex setup request
|
||||
|
||||
```text
|
||||
Install and configure DocForge for this repository using the new-project quickstart. Use the
|
||||
generic adapter for the canonical manual, and create a project-owned source adapter if source-code
|
||||
graph extraction is required. Inspect the repository languages and formats before choosing
|
||||
parsers. Read tracked source as data; never import or execute the application for discovery.
|
||||
Produce deterministic, evidence-backed nodes and edges with stable IDs and safe source anchors.
|
||||
Omit relationships that cannot be proven. Bind one project-scoped MCP server with visualization,
|
||||
build and check the index explicitly, add adapter contract and staleness tests, and add the supplied
|
||||
DocForge policy to AGENTS.md. Keep canonical manual writes outside MCP: use isolated proposals,
|
||||
review their diffs, apply them through the normal project workflow, then rebuild and check the
|
||||
index. Do not report completion until DocForge validation, adapter tests, MCP protocol checks, and
|
||||
the project's complete test gate pass.
|
||||
```
|
||||
|
||||
## 6. Tell the agent to use DocForge automatically
|
||||
|
||||
Place this policy in the project's `AGENTS.md` and adjust the manual path and profile if needed:
|
||||
|
||||
```markdown
|
||||
## Canonical documentation and DocForge
|
||||
|
||||
- `/Docs/Manual/` is the canonical systems manual and architecture source of truth.
|
||||
- Use the project-bound DocForge MCP server for every systems-level, architectural, persistence,
|
||||
plugin, worker, API, operational, or mainline change.
|
||||
- Before editing, call `docforge_project_info` or `docforge_validate_project`. Retrieve the relevant
|
||||
nodes with `docforge_search`, `docforge_get_context`, or `docforge_get_node`. Inspect dependencies,
|
||||
backlinks, and impact when changing an owned boundary.
|
||||
- Read the implementation and tests as well as the manual. Treat a code/manual disagreement as a
|
||||
defect. Do not silently choose one side.
|
||||
- During implementation, preserve explicit ownership, inputs, outputs, state writes, failure
|
||||
behavior, callers, tests, and operational consequences.
|
||||
- After implementation, create an isolated DocForge changeset. Propose every required manual
|
||||
update, validate the changeset, and inspect its diff.
|
||||
- DocForge proposals do not edit canonical files. Apply the reviewed proposal through the project's
|
||||
normal file-editing workflow, then run DocForge `validate`, `build`, and `check`.
|
||||
- Commit code, tests, and canonical documentation together. Never commit `.docforge/cache/`,
|
||||
`.docforge/changesets/`, or previews unless the project explicitly declares otherwise.
|
||||
- If DocForge reports stale state, missing nodes, invalid edges, or an index mismatch, stop and
|
||||
repair or rebuild the graph before claiming the work complete.
|
||||
- When asked to “visualize” the project or a node, call `docforge_visualize`. The viewer is
|
||||
loopback-only and read-only. Its native per-user manager keeps active pages alive across MCP
|
||||
transactions, reports state through `docforge_visualization_status`, and reclaims only workers
|
||||
idle for an hour. See `docs/VIEWER_MANAGER.md` for one-time installation.
|
||||
```
|
||||
|
||||
The policy is what makes DocForge part of normal development rather than an optional lookup tool.
|
||||
|
||||
## 7. Normal development loop
|
||||
|
||||
1. Validate the DocForge project.
|
||||
2. Retrieve the relevant context and impact graph.
|
||||
3. Inspect the corresponding code and tests.
|
||||
4. Implement and test the change.
|
||||
5. Create and validate a DocForge proposal.
|
||||
6. Review the proposal diff.
|
||||
7. Apply the approved text through normal project editing.
|
||||
8. Run `validate`, `build`, and `check`.
|
||||
9. Run the project's complete test gate.
|
||||
10. Commit code, tests, and canonical manual updates together.
|
||||
|
||||
DocForge never applies, commits, pushes, builds, deploys, or publishes on the project's behalf.
|
||||
This file remains only so existing bookmarks and links continue to resolve. Update links to point
|
||||
to `README.md`.
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue