MCP Runbook Search Server

Сервер Model Context Protocol (MCP), который предоставляет семантический поиск по набору внутренних инженерных runbook'ов в виде инструментов — чтобы Claude Desktop, MCP-совместимая IDE или пользовательский агент могли спросить «как нам обработать отказ базы данных?» и получить нужный runbook, вместо того чтобы кто-то искал в вики.

Обзор

MCP стандартизирует то, как LLM-клиент обнаруживает и вызывает инструменты, предоставляемые отдельным серверным процессом, через stdio или HTTP. Этот сервер реализует эту сторону протокола для одного конкретного, реалистичного сценария использования: делая внутреннюю базу знаний (runbook'и, постмортемы, плейбуки) доступной для запросов любому MCP-клиенту без написания индивидуальной интеграции для каждого клиента.

Сервер предоставляет три инструмента:

• search_runbooks(query, top_k) — семантический поиск по корпусу runbook'ов, ранжированный по косинусной близости.

• get_runbook(doc_id) — получить полный текст одного runbook по идентификатору.

• list_runbooks() — перечислить идентификаторы и заголовки всех индексированных runbook'ов.

Ключевые особенности

• Реальный протокол MCP, а не имитация — построен на официальном mcp Python SDK с сервером FastMCP и проверен end-to-end с реальным ClientSession, подключающимся через stdio (см. пример запуска ниже) — а не только модульными тестами базовых функций.

• Семантический поиск без зависимостей — хэширующий эмбеддер превращает каждый документ в вектор фиксированного размера без внешней модели, API-ключа или сетевых вызовов, поэтому сервер работает полностью офлайн. Косинусная близость этих векторов ранжирует результаты по смыслу, а не только по совпадению ключевых слов.

• Логика инструментов отделена от транспорта — src/tools.py содержит простые функции над Corpus, независимо протестированные; src/server.py только подключает эти функции к декораторам инструментов MCP. Замена stdio на HTTP-транспорт или корпуса на реальное хранилище документов не затрагивает логику инструментов.

• Понятная обработка ошибок — get_runbook для неизвестного идентификатора возвращает структурированный ответ {"error": ...} вместо исключения, поэтому клиент в любом случае получает полезный ответ.

Архитектура

MCP client (Claude Desktop, IDE, custom agent)
        │  stdio / JSON-RPC
        ▼
 FastMCP server (src/server.py)
        │  registers tools
        ▼
 tools.py  ──▶  Corpus (src/corpus.py)
                  │
                  ▼
          hashing embedder + cosine similarity
                  │
                  ▼
          5 sample engineering runbooks

Технологический стек

Структура проекта

.
├── src/
│   ├── corpus.py    # Hashing embedder, Corpus, sample runbook documents
│   ├── tools.py      # Pure tool functions (search / get / list)
│   └── server.py     # FastMCP server wiring tools.py into MCP tool decorators
├── tests/
│   ├── test_corpus.py
│   └── test_tools.py
├── .github/workflows/ci.yml
├── Dockerfile
├── requirements.txt
└── README.md

Начало работы

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

• Python 3.10+

Установка

git clone https://github.com/deekshu05/mcp-document-search-server.git
cd mcp-document-search-server
pip install -r requirements.txt

Запуск сервера

python -m src.server

Это запускает сервер на stdio, ожидая подключения MCP-клиента.

Подключение из Claude Desktop

Добавьте это в ваш claude_desktop_config.json:

{
  "mcpServers": {
    "runbook-search": {
      "command": "python",
      "args": ["-m", "src.server"],
      "cwd": "/path/to/mcp-document-search-server"
    }
  }
}

Перезапустите Claude Desktop, и search_runbooks, get_runbook и list_runbooks станут инструментами, которые Claude может вызывать напрямую в разговоре.

Запуск с Docker

docker build -t mcp-runbook-server .
docker run -i mcp-runbook-server

Пример запуска

Реальный вывод Python MCP-клиента, подключающегося к этому серверу через stdio и вызывающего его инструменты — не симулированная стенограмма:

Tools exposed: ['search_runbooks', 'get_runbook', 'list_runbooks']

search_runbooks('the primary database node is not responding'):
{
  "doc_id": "rb-001",
  "title": "Database failover procedure",
  "snippet": "Database failover procedure. When the primary Postgres node becomes
  unresponsive, promote the standby replica using the orchestrator's promote
  command, update the connection endpoint in the service config map, and verify",
  "score": 0.439
}
{
  "doc_id": "rb-003",
  "title": "Deploy rollback procedure",
  "snippet": "Deploy rollback procedure. If error rates exceed the alert
  threshold within ten minutes of a deploy, trigger the automated rollback to
  the previous stable image tag, confirm the health checks pass on all
  replicas, and po",
  "score": 0.3208
}

get_runbook('rb-001'):
{
  "doc_id": "rb-001",
  "title": "Database failover procedure",
  "text": "Database failover procedure. When the primary Postgres node becomes
  unresponsive, promote the standby replica using the orchestrator's promote
  command, update the connection endpoint in the service config map, and
  verify replication lag has dropped to zero on the new primary before
  resuming writes. Page the on-call DBA if promotion does not complete within
  five minutes."
}

Запрос никогда не упоминает «Postgres» или «failover» по имени — это простое описание симптома — и поиск всё равно ранжирует правильный runbook первым по смыслу, а не по совпадению ключевых слов, с реальным вторым результатом (процедура отката), который действительно является следующим наиболее связанным runbook'ом.

Влияние

Подобный шаблон превращает внутреннюю базу знаний, которая раньше требовала от кого-то знания, какую страницу вики искать, в нечто, что любой MCP-совместимый ИИ-ассистент может напрямую запрашивать и цитировать, сокращая время между «началом инцидента» и «появлением нужного runbook'а перед реагирующим».

Дорожная карта

• Заменить хэширующий эмбеддер на настоящую модель эмбеддингов при работе с более крупным корпусом

• Потоковый HTTP-транспорт наряду со stdio для удалённых MCP-клиентов

• Сквозное индексирование, чтобы новые runbook'и можно было добавлять без перезапуска сервера

• Разграничение прав доступа, чтобы разные MCP-клиенты видели разные подмножества корпуса

Лицензия

MIT