DocForge2/docs/AGENT_INTEGRATION.md

Agent integration

DocForge generates deterministic, project-bound MCP client fragments for Codex, Claude, and OpenClaw. Generic projects and custom adapters use different configuration APIs, but both produce fixed standard-input/output bindings with empty generated environments and explicit capability policy.

Fixed reference binding

Configure one of the in-repository adapters with .docforge/reference-adapter.toml as described in Reference Adapters, then start:

python -I -m docforge.reference_mcp \
  --project-root /absolute/path/to/project \
  --capability-mode read

docforge.reference_mcp is a fixed trusted module in the installed DocForge distribution. It selects a provider only from the validated reference configuration and reports binding metadata containing:

• server_module = "docforge.reference_mcp";
• adapter_mode = "reference";
• the selected reference_language; and
• the exact reference_config_hash.

The reference binding registers exactly the 21 read tools listed in MCP Boundary. It has no proposal or canonical-application surface.

Generate a reference client fragment

The public launcher and generator APIs are:

from pathlib import Path

from docforge.adapter_launcher import AdapterLauncherV1
from docforge.client_config import generate_adapter_client_configuration
from docforge.reference_mcp import REFERENCE_MCP_MODULE, create_reference_project

root = Path("/absolute/path/to/project")
project = create_reference_project(root)
launcher = AdapterLauncherV1.for_project(project, module=REFERENCE_MCP_MODULE)

plan = generate_adapter_client_configuration(
    project,
    launcher,
    "codex",  # "codex", "claude", or "openclaw"
    capability_mode="read",
)
print(plan["artifact"]["content"])

Pass output=Path(...) only when the caller has selected an exact destination. Publication is an atomic create-or-exact-match operation; it does not merge or replace different existing content. The result includes the launcher, source-availability, project, policy, artifact, and configuration hashes needed to inspect the binding before use.

The fixed reference module accepts read mode only. Do not request proposal or application mode for it.

Custom project-owned adapter launchers

Generic docforge configure intentionally refuses a custom adapter project. Construct the project-owned ProjectService, then use AdapterLauncherV1 and generate_adapter_client_configuration() as the custom-adapter route.

AdapterLauncherV1 schema version 1 binds:

• one project ID, canonical absolute project root, adapter identity, and descriptor hash;
• entry_point = "python-module"; and
• one installed project-owned top-level Python module.

The only trusted dotted-module exception is the fixed docforge.reference_mcp binding. A project-owned module is resolved through isolated Python without importing or executing it during the probe, and it must resolve to one canonical regular .py file inside the project root.

The launcher contract has no arbitrary command, command arguments, shell string, working directory, environment, callable selector, discovery rule, or module-reload mechanism. Generated bindings invoke the current Python executable as python -I -m <module> with only DocForge's validated project, capability, render-policy, authority, and no-AST options. Source identity and the project binding are revalidated before publication; drift fails closed.

Proposal and application modes are available only to a custom module that implements those fixed server arguments and only when the project descriptor declares the matching writer and canonical applier authority. Generating a mode does not manufacture that authority.

Session workflow

After registering the generated fragment in the selected client:

1. Start a new MCP process or client session.
2. Call docforge_bootstrap.
3. Verify project ID, root fingerprint, adapter identity, revision, source hash, binding metadata, effective policy, and registered tools.
4. Retrieve exact or bounded project evidence through the fixed read tools.
5. Restart the process if adapter_restart_required reports an implementation or configuration change.

Document text returned by DocForge is untrusted project content. It never overrides client, user, or project authority. See MCP Boundary for synchronization, pagination, retrieval, proposal, and application rules, and Legacy Adapters and No-AST Policy before selecting no_ast=True.