corpus-mcp

Локальный MCP сервер, который предоставляет агенту чистый и эффективный доступ к локальному корпусу знаний из офлайн-ZIM-архивов — Википедия, медицинская вики (MDWiki), документация разработчика (DevDocs) и Stack Exchange — через единый интерфейс. Без интернета, без эмбеддингов, без векторной базы данных: полнотекстовый поиск libzim плюс детерминированная очистка контента на стороне сервера.

Публичный интерфейс MCP — ровно два инструмента:

search(query, limit?)
fetch(ref, sections?)

Настроенный корпус — это забота оператора, а не агента. Агент только:

discover  →  search()
select    →  fetch()

Семейства корпусов

Вся идентификация корпуса, маршрутизация, доступ к ZIM, интерпретация HTML, очистка, ранжирование, обработка редиректов и нормализация остаются обязанностями сервера. Агенту никогда не требуется разбирать HTML, обрабатывать редиректы, конструировать или разбирать ссылки, а также знать что-либо о libzim, пространства имён ZIM или внутреннем устройстве хранения корпуса.

Related MCP server: mcpzim

Ссылки

Результаты search() содержат непрозрачный ref (например, corpus://Wikipedia/Bell_test); fetch() использует его. Агент никогда не должен создавать, разбирать или изменять ref или выводить корпус из него:

search() produces ref      fetch() consumes ref

Архитектура

Local agent
    │  MCP / Streamable HTTP  →  http://127.0.0.1:8000/mcp
    ▼
┌──────────────────────────────────────────────┐
│ Corpus MCP Server                            │
│  search()  fetch()                           │
│  ├─ CorpusManager (routing, cache,          │
│  │   bounded-concurrency fan-out)           │
│  ├─ federated ranking (RRF + lexical title  │
│  │   reranking + diversity)                 │
│  ├─ adapters: mediawiki / devdocs /         │
│  │   stackexchange                           │
│  ├─ HTML cleaner → Markdown, section trees  │
│  └─ GlobalRef codec (opaque refs)           │
└─────────────┬────────────────────────────────┘
              ▼
      per-library ZIM service (only libzim touchpoint,
      one search lock per archive)
              ▼
      corpus/  (read-only volume, N .zim archives)
      corpus.toml  (manifest: name, adapter, path)

Слой MCP не раскрывает никаких концепций libzim: никаких пространств имён, идентификаторов кластеров, сырых записей, MIME-типов или сырого HTML.

Предварительные требования

• Docker + Docker Compose

• Архивы ZIM (см. ниже)

• Для запуска набора тестов локально: Python 3.12 и uv (или pip)

Расположение корпуса

Сервер никогда не скачивает архивы сам — сбор корпуса намеренно отделен от запуска приложения. Структура по умолчанию:

corpus/
  wikipedia/wikipedia_en_all_nopic_*.zim
  medical/mdwiki_en_all_maxi_*.zim
  devdocs/devdocs_en_cpp_*.zim
  devdocs/devdocs_en_cmake_*.zim
  devdocs/devdocs_en_python_*.zim
  stackexchange/stackoverflow.com_en_all_*.zim
  stackexchange/security.stackexchange.com_en_all_*.zim
  stackexchange/softwareengineering.stackexchange.com_en_all_*.zim
corpus.toml

corpus.toml описывает каждую библиотеку, ее адаптер и путь (относительно корня корпуса):

version = 1

[[library]]
name = "Wikipedia"
path = "wikipedia/wikipedia_en_all_nopic_2026-06.zim"
adapter = "mediawiki"

[[library]]
name = "CMake-Docs"
path = "devdocs/devdocs_en_cmake_2026-08.zim"
adapter = "devdocs"

Правила проверки: уникальные имена, известные адаптеры, пути должны оставаться внутри корня корпуса. Проверьте корпус перед запуском сервера:

make validate-corpus   # opens every archive, reports metadata
make corpus-list       # list configured libraries

Запуск / остановка

make start           # build + start (docker compose, detached)
make logs            # tail logs
make ps              # container status
make stop            # stop (keep containers)
make down            # stop + remove
make restart
make build

После этого конечная точка MCP доступна по адресу http://127.0.0.1:8000/mcp (Streamable HTTP). Порт хоста по умолчанию привязан только к loopback; контейнер слушает адрес 0.0.0.0:8000 внутри.

Если какой-либо указанный ZIM не может быть открыт, сервер не запускается и указывает проблемную библиотеку — частично работоспособного режима не существует.

Схемы инструментов

search(query: str, limit?: int)

Ищет полнотекстовый индекс каждой настроенной библиотеки (ограниченная параллельность, один рабочий процесс на архив), объединяет ранжированные списки с помощью Reciprocal Rank Fusion, упорядочивает конкурирующих кандидатов из разных корпусов по лексическому совпадению заголовков, применяет детерминированную логику разнообразия и возвращает чистые результаты. limit по умолчанию равен 5; сервер накладывает жёсткий максимум (SEARCH_MAX_LIMIT, по умолчанию 10).

{
  "results": [
    {
      "ref": "corpus://Wikipedia/Bell_test",
      "library": "Wikipedia",
      "kind": "article",
      "title": "Bell test",
      "snapshot": "2026-06",
      "snippet": "To close the detection loophole, an apparatus with a high detection efficiency is needed.",
      "relevant_sections": [
        { "id": "Notable_experiments", "title": "Notable experiments" },
        { "id": "Loopholes", "title": "Loopholes" }
      ]
    }
  ]
}

• ref — непрозрачный глобальный идентификатор; передайте его обратно в fetch().

• library / kind / snapshot — происхождение: какой архив, какой документ, и снимок корпуса (полученный из метаданных архива).

• relevant_sections — 0–3 детерминированных лексических подсказки (пусто, если ни одна секция явно не соответствует). Идентификаторы секций генерируются сервером; агент не должен их восстанавливать.

Одна неисправная библиотека ухудшает качество поиска (остальные по-прежнему отвечают), но никогда не останавливает его.

fetch(ref: str, sections?: list[str])

Возвращает очищенный документ в виде структурированного Markdown.

• Без параметра sections: весь документ (ограничен MAX_FETCH_CHARS; truncated: true, если обрезан на границе секции).

• С параметром sections: только указанные секции (включая вложенные). Идентификаторы секций берутся из search() подсказок или из available_sections. Вводная секция имеет идентификатор "". Для тем секции — question, accepted-answer и answer-<id>; их поле metadata содержит оценку, флаг «принято» и теги.

{
  "ref": "corpus://Wikipedia/Bell_test",
  "library": "Wikipedia",
  "kind": "article",
  "title": "Bell test",
  "snapshot": "2026-06",
  "sections": [
    { "id": "Loopholes", "title": "Loopholes", "content": "## Loopholes\n\n..." }
  ],
  "available_sections": [
    { "id": "", "title": "Bell test" },
    { "id": "Background", "title": "Background" },
    { "id": "Loopholes", "title": "Loopholes" }
  ],
  "truncated": false
}

Ошибки — краткие и конструктивные:

{ "error": "invalid_ref", "message": "invalid reference: ..." }
{ "error": "not_found", "message": "Document not found in Wikipedia: Foo_bar" }
{
  "error": "section_not_found",
  "missing_sections": ["Experiments"],
  "available_sections": [ { "id": "Loopholes", "title": "Loopholes" }, "..." ]
}

Пример рабочего процесса агента

search("Bell experiment loopholes")
    ↓
fetch("corpus://Wikipedia/Bell_test", ["Notable_experiments", "Loopholes"])

Конфигурация

Переменные окружения (показаны значения по умолчанию в контейнере):

Переменные Compose на стороне хоста: CORPUS_ROOT (по умолчанию ./corpus) и CORPUS_CONFIG (по умолчанию ./corpus.toml).

Сервер быстро завершится при недопустимой конфигурации.

Тесты

make test     # unit + integration + MCP surface tests (needs .venv)
make lint
make format

Настройка для локального запуска тестов:

uv venv .venv --python 3.12
uv pip install -e . --python .venv/bin/python
uv pip install --python .venv/bin/python pytest pytest-asyncio ruff
make test

Тесты создают небольшие самостоятельные ZIM-файлы с помощью writer из libzim (по одному на семейство корпусов); внешний корпус не требуется. Регрессионный тест поверхности MCP проверяет, что сервер предоставляет ровно два инструмента — search и fetch — и никаких prompts или resources.

Модель безопасности

Сервис локальен изначально: привязка к хосту по умолчанию только к loopback, тома корпуса только для чтения, контейнер запускается от непривилегированного пользователя, без привилегированного режима, без Docker-сокета, без произвольного файлового доступа, без извлечения URL, без выполнения команд оболочки. Ни один инструмент не принимает файловые пути, URL, команды или исполняемое содержимое — ref является лишь непрозрачным идентификатором корпоративной базы.