opencode-ppocr-mcp

Local OCR, no cloud. PP-OCRv6 Medium detection + recognition on ONNX Runtime (CPU), for images and multi-page PDFs.

本地 OCR:PP-OCRv6 Medium 检测+识别,ONNX Runtime CPU 推理,可识别图片与多页 PDF。

As a DeepSeek Harness plugin: the MCP server ships inside the bundle, so installing one plugin is the whole setup — no mcpServers file to hand-edit.

Install

DeepSeek Harness Desktop — open Plugins in the sidebar, choose Add plugin, and enter:

https://github.com/bauerelizabeth07139/opencode-ppocr-mcp

Then switch the new dsh-ppocr bundle on. The Desktop app boots the reserved desktop profile, so that is where it has to be enabled.

dsh CLI — install it into the profile you actually boot:

dsh plugin --profile web add bauerelizabeth07139/opencode-ppocr-mcp

No git on the machine? pnpm resolves a git shorthand with git ls-remote, which fails with 'git' is not recognized when git is missing. Use the tarball instead — that path is plain HTTPS:

dsh plugin --profile web add https://codeload.github.com/bauerelizabeth07139/opencode-ppocr-mcp/tar.gz/main

The same address works in the Desktop Add plugin dialog. Replace main with a commit SHA to pin an exact revision (/tar.gz/<sha>).

Uninstall with dsh plugin --profile web remove dsh-ppocr.

Requirements

• Python ≥ 3.8 on PATH, or pointed at with python.

• The OCR stack in that interpreter — this is the heavy part:

  pip install paddlepaddle==3.0.0 paddleocr==3.7.0 onnxruntime Pillow
  

  requirements.txt in this repository pins exactly those.

• Disk and network for the first run: the detection and recognition models (~170 MB) download into ~/.paddlex/official_models/ the first time a tool is called. CPU only; no GPU and no display.

Tools

The server registers 2 tool(s). DSH namespaces them automatically, so the model calls them as mcp__ppocr__<tool>:

Tool	What it does
ocr_image	Runs detection + recognition on one image and returns the text. Parameter: image_path (required).
ocr_pdf	Renders and recognises a PDF page by page. Parameters: pdf_path (required), start_page (default 1), end_page (optional).

Configuration

Key	Environment variable	Default	Meaning
python	—	discovered	interpreter that runs the server — must have the OCR stack
toolCallTimeoutMs	—	600000	DSH's per-call budget; the first call also downloads the models
env	—	{}	raw environment passthrough (the server reads none)

Every field is optional and lives in the loader row. For example, in cordis.patch.yml:

- id: dsh-ppocr
  name: 'dsh-ppocr'
  config:
    python: 'C:\ocr-venv\Scripts\python.exe'
    toolCallTimeoutMs: 900000

Notes

• The plugin mounts; the interpreter must carry the stack. The server imports PaddleOCR lazily, when a tool is called, so a missing dependency shows up as a tool error naming the import rather than a plugin that refuses to load. Point python at an interpreter that has paddlepaddle, paddleocr, onnxruntime and Pillow.
• The first call is slow. Detection and recognition models (~170 MB) download into ~/.paddlex/official_models/ on first use; the 600 s per-call budget covers it.
• end_page must be a number. The server does not coerce it, so passing a string makes its comparison fail — pass an integer.

How it is mounted

index.js resolves a Python interpreter (the configured python, then python3/python on PATH), hands the server its argv and working directory, and mounts it as a stdio MCP server through @deepseek-ai/dsh-mcp-client with failOnStartupError: true, so a server that cannot start is a visible error rather than a silently missing tool.

Credentials are forwarded explicitly. The harness scrubs credential-shaped variables (KEY, TOKEN, SECRET, PASSWORD) out of the environment a child process inherits, so config.apiKey — falling back to the variable the server documents — is written into the child's environment by the plugin itself. That means both of these work:

config:
  apiKey: '<your key>'

export the API key variable='<your key>'   # picked up at load time

Development

No build step and no runtime dependencies — @deepseek-ai/cordis and @deepseek-ai/dsh-mcp-client are peers supplied by the Harness.

npm test    # node >= 22: manifest checks + the stdio mount, both Harness-free

The mount test loads index.js with @deepseek-ai/dsh-mcp-client stubbed and asserts the exact stdio configuration the plugin produces, including the credential forwarding above.

Repository layout

Path	Purpose
index.js	the DSH plugin: resolves the interpreter and mounts the server
cordis.patch.yml	the loader row that activates the plugin
locale/{en,zh}.json	card title and description for the plugin lists
assets/icon.svg	card artwork
test/	npm test: manifest composition and the mount contract
server.py	the MCP server, unchanged
requirements.txt	the OCR stack, pinned

Other hosts (unchanged)

The server is a plain stdio MCP server and still works anywhere else. The repository's original README is kept verbatim as README.opencode.md, and the launch stanza from it keeps working:

{
  "mcp": {
    "ppocr": {
      "type": "local",
      "command": ["python", "path/to/server.py"],
      "enabled": true
    }
  }
}

License

MIT — the repository's README declared MIT but shipped no licence file; this plugin's release adds one.