105 lines
4.5 KiB
Markdown
105 lines
4.5 KiB
Markdown
# 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](REFERENCE_ADAPTERS.md), then start:
|
|
|
|
```bash
|
|
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](MCP_CONTRACT.md#read-tools). It has no proposal or canonical-application surface.
|
|
|
|
## Generate a reference client fragment
|
|
|
|
The public launcher and generator APIs are:
|
|
|
|
```python
|
|
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](MCP_CONTRACT.md) for synchronization, pagination,
|
|
retrieval, proposal, and application rules, and
|
|
[Legacy Adapters and No-AST Policy](LEGACY_AND_NO_AST.md) before selecting `no_ast=True`.
|