Connecting RAGRAF to AutoClaw

Two channels: CLI and MCP

Do not mix them — what you verify depends on the channel. The CLI works always and does not depend on the application settings; MCP exposes the same operations as agent tools but requires registering the server.

What is already configured

A snapshot of the author machine from the integration-session measurements — a reference for how things should look after setup.

AutoClaw accounts on the machine (each has its own skill tree and runtime)

%APPDATA%\AutoClaw-oversea-official\accounts\<account-1>\   (основной)
%APPDATA%\AutoClaw-oversea-official\accounts\<account-2>\

The skill is deployed to both accounts — it stays visible when the account is switched. Copy freshness was confirmed by measurement: SKILL.md, reference/operations.md and reference/repair.md match the project revision by SHA-256 in both accounts.

The CLI channel: works without configuration

The primary path while MCP is not registered. Three rules.

1. 1First step — bring the corpus up to dateThe response carries status: actual — the index is current, reindexed — just rebuilt, created — there was no corpus and one was created, not_a_project — the directory does not look like a project, error — the reason is in the reason field.
   First step of a task (PowerShell)Copy

   python <repo>\tools\ragraf.py ensure <каталог проекта>

2. 2Then — an operation, not reading filesstale: true means the facts must not be trusted until reindexing: the code has moved ahead. This is not a "just in case" warning.
   Index operations (PowerShell)Copy

   python <repo>\tools\ragraf.py -p <repo>\config\<корпус>.yaml query symbol --name corpus_hash
   python <repo>\tools\ragraf.py -p <repo>\config\<корпус>.yaml check

3. 3The corpus list — a command that needs no configurationThe development registry is visible without -p: catalog prints every registered corpus with revisions and checksums.
   Corpus registry (PowerShell)Copy

   python <repo>\tools\ragraf.py catalog

Why the CLI is preferable here

Not for convenience. Every command prints text the agent reads directly, while an MCP response must be interpreted through a schema. The CLI also depends neither on restarting the app nor on server registration — it cannot "silently fall off". Polygon measurement: 14 tool calls versus 28 without the index; first-hit on the target file — 92%.

The MCP channel: mechanics and connection

The way MCP connection works in AutoClaw differs from familiar clients (Claude Desktop, Codex, DeepSeek Harness), and that matters. Four facts measured in the session:

1. 1There is no MCP config in the profileA search through ~/.pi, <account>\runtime and <account>\projects found neither mcp.json nor mcpServers in the settings. Registration does not live in a profile file.
2. 2ragraf is not registered by any application packageAll 106 tables of runtime.sqlite were checked — there is no MCP-server table; mentions of ragraf-mcp in the database turned out to be past-session history, not a registration.
3. 3The vertical pack declares MCP servers by declarationThe mcpServers field exists in the pack schema: dist\resources\vertical-packs\code\zwork-pack.json. Official packs have it empty ("mcpServers": []), and there are no user packs on disk at all (a search for zwork-pack.json outside the installation — 0 files).
4. 4The bundled agent does not serve MCP@earendil-works/pi-coding-agent contains not a single line about MCP (dist and docs checked); every mcpServers mention found in the bundle belongs to bundled vendor SDKs (Google/Gemini) and has nothing to do with AutoClaw.

How to connect and what to check

1. 1Find the MCP section in the product settingsOpen the project (or application) settings in AutoClaw and find the section about MCP / external tools — the server is registered there.
2. 2Enter the launch values (verified by running)--project is not needed: the server resolves the corpus from the working directory through the development registry, and for another project the corpus is selected with the ragraf_use_project tool (ragraf_catalog lists them).
3. 3Verify, do not assumeBefore connecting, call tool_search with the query ragraf — expect 0. After registration and a restart — 24 tools. That difference is the proof the connection worked.

команда:            <repo>\.venv\Scripts\python.exe
аргументы:          <repo>\tools\ragraf-mcp.py
                    --agent AutoClaw --agent-kind autoclaw
рабочий каталог:    <repo>

If there is no such settings section

Then the honest answer is: the MCP channel is unavailable in this build, and RAGRAF works through the CLI (previous section). Nothing is lost except that each call is a command rather than a tool. Inventing a registration by editing the database or substituting files is not allowed: runtime.sqlite is application state, and editing it behind the product back breaks the accounting of permissions and artifacts (governed_tool_* tables).

Four compatibility defects

Connecting the second client (DeepSeek Harness) exposed defects that also concerned AutoClaw. All four are closed, each with regression protection.

1. 1The server died on the first Russian response in a scrubbed environmentThe MCP client passes only 12 variables to the child process (APPDATA, HOMEDRIVE, HOMEPATH, LOCALAPPDATA, PATH, PROCESSOR_ARCHITECTURE, SYSTEMDRIVE, SYSTEMROOT, TEMP, USERNAME, USERPROFILE, PROGRAMFILES). Neither PYTHONUTF8 nor PYTHONIOENCODING is among them, the process locale stays cp1252 — and send() died with UnicodeEncodeError: charmap codec (src/ragraf/mcp_server.py). The AutoClaw shell sets both variables, so for AutoClaw the defect was invisible — it surfaced only on the second client. Fix: force_utf8_stdio() — the streams are forced to UTF-8 inside the server itself, not taken from the environment.
2. 2The mandatory --project blocked multi-project workFix: --project is optional, the corpus is looked up by working directory (development registry), the ragraf_use_project tool was added. One server serves all 18 corpora of the author machine.
3. 3The reindex command did not record the run in the registryMeasured on the RAGRAF own corpus: rev-0046 in the index, rev-0045 with the old checksum in the registry; because of that, check reindexed the corpus again, while catalog and the panel showed the past state. Fix: src/ragraf/cli.py — reindex records the run through the same shared entry point watch.record_index_run as index.
4. 4ensure and use_project were missing from the statisticsTelemetry is attached by a wrapper around the op_* facade methods, but these two operations live in the MCP server. The usage summary did not include them — meaning there was no way to answer whether agents follow the first-step rule. Fix: Facade.record_external_call (src/ragraf/facade.py) plus a record on the server side. Measurement after the fix: ensure 1, use_project 1 in the per-agent summary.

Dependencies: why the .venv interpreter

On the author machine, RAGRAF dependencies are reachable to the PATH interpreter only through PYTHONUSERBASE (%APPDATA%\AutoClaw-oversea-official\toolchain\python\Python313\site-packages). An external client scrubs it — and python from PATH fails with "PyYAML is not installed". Measured: the project .venv is self-sufficient — with all PYTHON* variables removed it imports yaml, fastembed, sqlite_vec, tree_sitter, ijson, tiktoken. This helps AutoClaw too: the CLI in the agent shell works anyway, but the .venv stops depending on environment settings.

Skill and rules

The ragraf-core skill

The skill lives in the tree of each account:

%APPDATA%\AutoClaw-oversea-official\accounts\<account>\runtime\zwork-agent\skills\ragraf-core\
    SKILL.md                 (вход: когда применять, порядок работы)
    reference/operations.md  (выбор операции и границы)
    reference/repair.md      (что делать, когда индекс сломан)

The source is the project directory: <repo>\docs\skills\ragraf-core. Edits go into the project first, then are copied to the account service directory. Otherwise, at the next deployment the account copy "falls behind" the project and the agent works from a stale revision. There are exactly two copies — one per account; the skill is present in both.

Verified by a freshness measurement (this session): both accounts hold three files — SKILL.md 9811 bytes, reference/operations.md 7546, reference/repair.md 11271 — and the SHA-256 of each matches the project revision. The account copies have not fallen behind the source.

$src = '<repo>\docs\skills\ragraf-core'
Get-ChildItem "$env:APPDATA\AutoClaw-oversea-official\accounts" -Directory | ForEach-Object {
    $dst = Join-Path $_.FullName 'runtime\zwork-agent\skills\ragraf-core'
    if (Test-Path -LiteralPath $dst) {
        Copy-Item -Recurse -Force "$src\*" $dst
        Write-Host "обновлено: $dst"
    }
}

Skill validation: the file starts with ---, the name and description fields parse line by line, the size is under 256 KiB, the encoding is UTF-8 without BOM, line endings are LF, and the account copy matches the project one byte for byte.

Rules: ~/.pi/agent/AGENTS.md

This is the AutoClaw user rules file — it is picked up in any project without its own AGENTS.md, and vice versa: a project AGENTS.md is stricter. AGENTS.md files from parent directories are also picked up, up to the .git boundary.

The section that forces working through the index is section 8, "Mandatory use of RAGRAF in code development". Three places to know:

Verification — four levels

From narrow to broad: CLI and registry → corpus freshness → the MCP channel → telemetry. Each level is a command and the expected result from the session.

python <repo>\tools\ragraf.py catalog
python <repo>\tools\ragraf.py ensure <repo>

18 projects in the registry; status: actual and matching checksums.

python <repo>\tools\ragraf.py -p <repo>\config\<корпус>.yaml check

"corpus checksum now" = "checksum at indexing", "changed after indexing: no".

tool_search("ragraf")                    → до подключения: 0 инструментов
                                           после регистрации и перезапуска: 24
ragraf_ensure()                          → status = actual | reindexed | created
ragraf_index_status()                    → index_rev, capability
ragraf_use_project(project="<имя>")      → ревизия ДРУГОГО корпуса

cd <repo>
Remove-Item Env:\PYTHONUTF8, Env:\PYTHONIOENCODING -ErrorAction SilentlyContinue
python tests\test_mcp_compat.py        # 15 проверок

python <repo>\tools\ragraf.py -p <repo>\config\<корпус>.yaml usage --agent AutoClaw

A per-agent line with the call count and operations, including ensure. If ensure is absent from the breakdown, the client never called it — telemetry did not "lose" it.

Rollback

MCP registration is the only reversible action in the interface: remove the server in the same settings section and restart the application. The index, registry and corpora are unaffected.

The RAGRAF edits themselves are additive; restoring the previous behavior takes three changes: remove the force_utf8_stdio() call, return required=True to --project, delete ragraf_use_project from TOOLS and _handlers. None of them touches the index, storage schema, revision numbering or the registry — no reindexing is needed on rollback.

The skill copies in the accounts are restored from the project:

Copy-Item -Recurse -Force <repo>\docs\skills\ragraf-core `
    "$env:APPDATA\AutoClaw-oversea-official\accounts\<account>\runtime\zwork-agent\skills\ragraf-core"

Where things live in AutoClaw

Installation peculiarity: the application code lies unpacked (resources\app\dist), not in app.asar. That is convenient for reconnaissance: files are readable by ordinary means and main.cjs can be searched line by line.

Invitation to AutoClaw