Connecting RAGRAF to DeepSeek Harness

How it works

What was fixed in RAGRAF

The defect was not "inconvenient" but "does not work at all": the very first response containing Russian text killed the server. Measured by running it — three causes, each confirmed by a measurement.

UnicodeEncodeError: 'charmap' codec can't encode characters in position 97-105
  File "src/ragraf/mcp_server.py", line 551, in send
    sys.stdout.write(json.dumps(message, ensure_ascii=False) + "\n")

1. 1Stream encodingThe MCP SDK passes only 12 variables to the child process (APPDATA, PATH, TEMP, USERPROFILE and friends — DEFAULT_INHERITED_ENV_VARS), and HARNESS additionally scrubs names containing PASSWORD|SECRET|TOKEN|KEY plus every DSH_*. Neither PYTHONUTF8 nor PYTHONIOENCODING is in that set — the process locale stays cp1252. Fix: force_utf8_stdio() reconfigures stdin, stdout and stderr to UTF-8 without relying on the environment.
2. 2Dependenciesfastembed, PyYAML, sqlite_vec, tree_sitter and ijson were reachable to the PATH interpreter only through PYTHONUSERBASE — HARNESS scrubs it, and the server reports "PyYAML is not installed". Solution: the server is launched by the project's own .venv interpreter — measured to import every package even with all PYTHON* variables removed.
3. 3Mandatory --projectA client that starts the server without arguments could not start it at all. Fix: --project is no longer required — the corpus is resolved from the working directory through the registry (_resolve_default_project()), the ragraf_use_project tool was added for manual switching, and --agent is now also read from the RAGRAF_AGENT variable.

Compatibility with previous clients is preserved: AutoClaw and SagaAI pass --project explicitly and set PYTHONIOENCODING — nothing changed for them.

Installation — three steps

All three steps place files into the HARNESS home directory (%USERPROFILE%\.dsh or $DSH_HOME); the ready-made blocks ship in the harness/ directory of the RAGRAF repository. In the commands below, $repo is the path to the local RAGRAF clone and $dsh is the app's bundled CLI.

1. 1Connect the MCP serverThe ready block harness/ragraf-mcp.patch.yml is appended to the end of the profile patch layer cordis.patch.yml. The application stores patches as an array, so the block goes in as a separate "- insert:" line. Back it up first — the file belongs to the user.
   Appending the patch block (PowerShell)Copy

   $repo = 'C:\AutoClaw\RAGRAF'   # путь к локальному клону RAGRAF
   $src  = Join-Path $repo 'harness\ragraf-mcp.patch.yml'
   $dst  = Join-Path ([Environment]::GetFolderPath('UserProfile')) '.dsh\profiles\desktop\cordis.patch.yml'
   
   # 1. бэкап (обязательно: файл принадлежит пользователю)
   Copy-Item $dst "$dst.bak-$(Get-Date -Format yyyyMMdd-HHmmss)"
   
   # 2. проверить, что блока ещё нет
   Select-String -LiteralPath $dst -Pattern 'mcp-ragraf'
   
   # 3. дописать блок (слой патчей — массив; блок вставляется отдельной строкой "- insert:")
   Add-Content -LiteralPath $dst -Value (Get-Content -LiteralPath $src -Raw) -Encoding utf8NoBOM

   Check that the patch applies — without launching the app:

   Verification via dsh --dump-configCopy

   $dsh = Join-Path $env:LOCALAPPDATA 'Programs\DeepSeek Harness\resources\runtime\cli\bin\dsh.cmd'
   & $dsh --profile headless --patch $src --dump-config | Select-String 'serverName: ragraf' -Context 1,3

   The desktop profile is the app's working profile; headless is for one-off command-line tasks. For a profile other than desktop, place the block into its cordis.patch.yml the same way.

2. 2Install the skillThe skill root %USERPROFILE%\.dsh\skills is read by the @deepseek-ai/dsh-skill-filesystem provider: it looks for <name>/SKILL.md at the top level. A skill in this directory is discovered without a restart — the provider watches the root.
   Installing the ragraf-core skillCopy

   $skills = Join-Path ([Environment]::GetFolderPath('UserProfile')) '.dsh\skills\ragraf-core'
   New-Item -ItemType Directory -Path $skills -Force | Out-Null
   Copy-Item (Join-Path $repo 'harness\skills\ragraf-core\SKILL.md') "$skills\SKILL.md" -Force

3. 3Add the rule to the global instructionsHARNESS reads %USERPROFILE%\.dsh\AGENTS.md (the dsh-agent-instructions module; dshHome = $DSH_HOME or ~/.dsh). The section to insert is harness/agents-section.md; place it before the "Changelog" section, otherwise the rule ends up after the history (in the verified installation it is section 6). Expected behavior: asked "where does a code task start", the agent answers mcp__ragraf__ensure and refers to that section.

Verification — four levels

From narrow to broad: the server alone → a live run inside the app → the skill → the project checker. Every level is a command and an expected output measured in the live session.

cd $repo
Remove-Item Env:\PYTHONUTF8, Env:\PYTHONIOENCODING -ErrorAction SilentlyContinue
python tests\test_mcp_compat.py

ИТОГ: пройдено 13, провалено 0

& $dsh --profile headless --patch $src --json `
  "Вызови mcp__ragraf__index_status и приведи первую строку ответа"

{"type":"tool_call","tool":"mcp__ragraf__ragraf_index_status","input":{}}
{"type":"tool_result","status":"completed","result":"op=index_status rev=rev-0043 capability=full ..."}

& $dsh --profile headless --patch $src "Загрузи навык ragraf-core и назови первый шаг"

{"type":"tool_call","tool":"skill","input":{"name":"ragraf-core"}}

pwsh -NoLogo -NoProfile -NonInteractive -File tools\Invoke-ProjectDoctrine.ps1

checks: 16, errors: 0, warnings: 0, Result: PASS
[PASS] MCP server survives a scrubbed client environment
[PASS] operations outside the facade are recorded

Three limitations to know

Get-CimInstance Win32_Process -Filter "Name='java.exe'" |
  Select-Object ProcessId, @{n='MB';e={[int]($_.WorkingSetSize/1MB)}}
Get-NetTCPConnection -LocalPort 9500 -ErrorAction SilentlyContinue

# висящий сервер снимается вместе с родительским процессом:
taskkill /PID <PID родительского cmd.exe> /T /F

Rollback

HARNESS: restore the patch layer and AGENTS.md from the backups (the installation printed their names), remove the ragraf-core skill directory.

$home2 = [Environment]::GetFolderPath('UserProfile')
# 1. вернуть слой патчей из бэкапа (имя печатала установка)
Copy-Item "$home2\.dsh\profiles\desktop\cordis.patch.yml.bak-<метка>" `
          "$home2\.dsh\profiles\desktop\cordis.patch.yml" -Force
# 2. вернуть глобальные правила
Copy-Item "$home2\.dsh\AGENTS.md.bak-<метка>" "$home2\.dsh\AGENTS.md" -Force
# 3. убрать навык
Remove-Item "$home2\.dsh\skills\ragraf-core" -Recurse -Force

RAGRAF: the edits are additive — they do not touch the index, the storage schema, revision numbering or the registry, so rollback needs no reindexing. To restore the previous behavior, three changes suffice: remove the force_utf8_stdio() call, return required=True to --project, and delete the ragraf_use_project tool from TOOLS and _handlers.

HARNESS behavior: where things live

The home directory is controlled by DSH_HOME (an explicit path wins) and DSH_AGENTS_HOME (the shared agent-skills directory, default ~/.agents). HARNESS scrubs both from child-process environments — this does not affect the MCP server launch: it reads only --project and the working directory.

Skill root resolution order (rank): <project>/.dsh/skills (100), <project>/.agents/skills (200), user customSkillDirs (300), ~/.dsh/skills (400), ~/.agents/skills (500). The project root is the nearest directory containing .git.

HARNESS is developed in a private repository (github.com/deepseek-ai/deepseek-harness); no public API verification was done. The contract above is described from the facts of the current installation — lib/index.js and package READMEs inside app.asar — not from documentation.