Case Index MCP

A local Model Context Protocol server for incremental indexing of document folders, with offline Cyrillic OCR on CPU. It is independent of any particular MCP host and does not require Kimi, Claude, or another AI desktop application to be installed.

What it does

• Indexes PDF, DOCX, TXT, Markdown, RTF, ODT, PNG, JPEG, TIFF, and BMP files.

• Extracts existing PDF text where available; otherwise renders pages at 200 DPI and runs OCR.

• Uses bundled RapidOCR/OpenVINO models for the primary OCR pass.

• Optionally runs PaddleOCR as a second pass for uncertain OCR results.

• Reprocesses only new, changed, or previously failed documents; removes stale index entries when source files disappear.

• Writes a manifest, per-page text, combined transcripts, and a Russian СТАТУС_дела.md report.

• Supports foreground and background runs, progress inspection, cancellation, and transcript retrieval.

• Never changes supported source documents. It creates _work/ and СТАТУС_дела.md inside the indexed folder.

OCR transcripts are drafts. Always verify names, dates, numbers, and pages marked needs_review against the originals. This software indexes documents; it does not provide legal analysis or legal advice.

Related MCP server: bigos

Requirements

• Python 3.11 or newer (3.11–3.13 recommended).

• A CPython environment supported by the pinned OpenVINO and pypdfium2 wheels.

• Network access for Python package installation. The bundled primary OCR works offline afterward.

Install

git clone https://github.com/yasd810-beep/case-index-mcp.git
cd case-index-mcp
python -m venv .venv

Activate the environment and install the primary engine:

# Windows PowerShell
.venv\Scripts\Activate.ps1
pip install -r requirements.txt

# macOS / Linux
source .venv/bin/activate
pip install -r requirements.txt

Optional PaddleOCR fallback:

pip install -r requirements-fallback.txt

PaddleOCR models are downloaded by PaddleOCR on first use. Set CASE_INDEX_CACHE_DIR to override the default cache directory, ~/.case-index-mcp. Set use_paddle_fallback to false when indexing if you do not install or want the fallback.

Connect an MCP host

Add a stdio server using the absolute path to the virtual environment's Python and to server.py. A generic configuration looks like this:

{
  "mcpServers": {
    "case-index": {
      "command": "C:\\tools\\case-index-mcp\\.venv\\Scripts\\python.exe",
      "args": ["C:\\tools\\case-index-mcp\\server.py"]
    }
  }
}

On macOS or Linux, for example:

{
  "mcpServers": {
    "case-index": {
      "command": "/opt/case-index-mcp/.venv/bin/python",
      "args": ["/opt/case-index-mcp/server.py"]
    }
  }
}

Consult your MCP host's documentation for the location and schema of its configuration file. Restart the host after changing the configuration.

Tools

For a large folder, call index_project with background=true, then poll get_index_status. Do not delete lock files to stop a run; use cancel_index. If files are added while a run is active, start another run after it finishes.

Output layout

indexed-folder/
├── _work/
│   ├── case-index/
│   │   ├── manifest.json
│   │   └── run.json
│   ├── pages/
│   └── transcripts/
└── СТАТУС_дела.md

The manifest contains source paths, content hashes, extraction metadata, and OCR diagnostics. Treat index output as potentially sensitive because it contains text from the indexed documents. Do not publish an indexed project or its _work directory with this software.

Verify

The integration suite creates only synthetic documents under test-run/:

python tests/integration_test.py

An additional smoke test checks bundled-model hashes and primary OCR on a generated image:

python tests/ocr_smoke.py

License and models

Code is provided under Apache License 2.0. The bundled PaddleOCR model files and dictionary are also distributed under Apache License 2.0; see NOTICE. SHA-256 hashes in models/SHA256.json are verified before OCR starts.