MCP-сервер распознавания документов

MCP-сервер на TypeScript/Node.js для агентов в IDE (VSCode). Предоставляет 4 инструмента: распознавание электронных PDF, Word (DOCX), Excel (XLSX) и поиск по PostgreSQL. Каждый инструмент возвращает агенту структурированный JSON.

Возможности

Контракт результата каждого инструмента: см. docs/contract.md.

Related MCP server: Document Search MCP Server

Принципы MCP

Агент (IDE) подключается к MCP-серверу по транспорту stdio: IDE запускает сервер как дочерний процесс (в нашем случае — Docker-контейнер, см. opencode.json) и обменивается с ним сообщениями JSON-RPC 2.0. Жизненный цикл подключения состоит из трёх фаз: initialize → tools/list → tools/call. На фазе tools/list агент получает описания инструментов (имя, описание, схему входных параметров) и добавляет их в контекст модели; на фазе tools/call агент передаёт серверу аргументы, сервер выполняет реальную работу и возвращает структурированный JSON-результат, который попадает обратно в контекст модели для формирования ответа.

Tool — это функция, объявленная сервером: у неё есть имя, человекочитаемое описание и JSON-схема параметров. Модель сама ничего не выполняет — она лишь решает, какой tool вызвать и с какими аргументами; исполнение всегда происходит на стороне MCP-сервера. В этом проекте тулами являются extract_pdf, extract_word, extract_excel и postgres_search. Наглядное объяснение этой схемы со схемами Mermaid — в docs/mcp-explained.html.

Требования

• Node.js 20.11+ (используется import.meta.dirname)

• PostgreSQL (только для тула postgres_search)

Установка и запуск

npm install          # установка зависимостей
npm run build        # сборка в dist/
npm run make-samples # сгенерировать образцы в samples/ (для проверки)
npm start            # запуск сервера напрямую (stdio)

Переменные окружения — в файле .env (скопируйте .env.example, укажите DATABASE_URL). Реальный .env не коммитится.

Запуск в Docker

Всё окружение поднимается контейнерами: MCP-сервер (сборка из Dockerfile) и PostgreSQL с тестовыми данными.

# 1. Собрать образ MCP-сервера
docker build -t ot5-mcp-server .

# 2. Поднять PostgreSQL с тестовыми данными (db/init.sql)
docker compose up -d db

# 3. Проверка (опционально): тулы через stdio-контейнер
docker run -i --rm --network ot5_default -e PROJECT_ROOT=/project \
  -e DATABASE_URL=postgres://dev:dev@db:5432/docs \
  -v "%CD%:/project" ot5-mcp-server:latest

Схема: db живёт в сети ot5_default; MCP-контейнер VSCode подключается к той же сети и ходит к БД по имени сервиса db. Данные Postgres в named volume pgdata.

Подключение к агенту в VSCode (opencode)

В проекте используется расширение opencode для VSCode (sst-dev.opencode). opencode подключает MCP-серверы через свой конфиг opencode.json (а не через .vscode/mcp.json, который нужен только для встроенного MCP-шлюза GitHub Copilot).

1. Установите зависимости и соберите проект: npm install && npm run build.

2. Поднимите окружение в Docker:

   docker compose up -d db
   docker build -t ot5-mcp-server .

3. В корне проекта уже лежит opencode.json — он запускает docs-server как контейнер:

   {
     "$schema": "https://opencode.ai/config.json",
     "mcp": {
       "docs-server": {
         "type": "local",
         "command": [
           "C:\\Program Files\\Docker\\Docker\\resources\\bin\\docker.exe",
           "run", "-i", "--rm", "--network", "ot5_default",
           "-e", "PROJECT_ROOT=/project",
           "-e", "DATABASE_URL=postgres://dev:dev@db:5432/docs",
           "-v", "C:\\Users\\User\\Documents\\HW\\OT-5:/project",
           "ot5-mcp-server:latest"
         ],
         "enabled": true
       }
     }
   }

   Docker должен быть запущен, образ ot5-mcp-server:latest собран, сеть ot5_default создана. Путь к docker.exe — полный, т.к. Docker не в PATH.

4. Перезапустите opencode (закройте/откройте окно VSCode или перезапустите сессию агента) — конфиг читается при старте.

5. В чате агента отправьте запрос, явно называющий инструмент, например: «Вызови MCP-инструмент extract_pdf для samples/sample.pdf».

6. Подтверждение вызова: ответ агента придёт как JSON, а логи сервера появятся в терминале/Docker.

Секреты: строка БД для docker-режима — локальная dev-учётка dev:dev, только для тестов.

Проверка без IDE (смоук-тест)

npm run smoke-test

Скрипт scripts/smoke-test.mjs поднимает собранный сервер по stdio через MCP-клиент и вызывает все тулы. Вывод последнего прогона: docs/evidence/smoke-test.log.

Пример строки лога на стороне сервера (имя тула, параметры, статус):

{"ts":"2026-08-20T06:45:44.748Z","tool":"extract_pdf","params":{"path":"samples/sample.pdf"},"status":"success"}
{"ts":"2026-08-20T06:45:44.787Z","tool":"extract_word","params":{"path":"samples/sample.docx"},"status":"success"}
{"ts":"2026-08-20T06:45:44.798Z","tool":"extract_excel","params":{"path":"samples/sample.xlsx"},"status":"success"}
{"ts":"2026-08-20T06:45:44.811Z","tool":"postgres_search","params":{"operation":"list_tables"},"status":"success"}

Логирование реализовано в src/logger.ts:20–34 (вычищает ключи вида password/token).

Безопасность и ограничения

• Доступ к файлам — только относительные пути внутри корня проекта; обход через ../ запрещён (src/security.ts:6–22).

• PostgreSQL — только чтение: сессия BEGIN READ ONLY, только SELECT, без мультистейтментов, таймаут запроса 10 с (src/tools/postgres.ts:43–86). Строка подключения — только из .env, в логи не попадает.

• Секреты — в репозитории только .env.example; логирование вычищает ключи вида password/token и т.п. (src/logger.ts:20–34).

• PDF — только электронные (текстовые) PDF. Сканированные документы (изображения) не распознаются — OCR не входит в объём.

Ссылки на код (по требованиям задания)

1. Сервер и регистрация инструментов — src/index.ts:35–106 (тулы) и src/index.ts:107–108 (stdio-транспорт).

2. Реализация инструментов:

   • extract_pdf — src/tools/pdf.ts:14–33 (реализация), логирование в src/index.ts:36–49;

   • extract_word — src/tools/word.ts:17–71, логирование в src/index.ts:52–65;

   • extract_excel — src/tools/excel.ts:15–36, логирование в src/index.ts:68–81;

   • postgres_search — src/tools/postgres.ts:43–86, логирование в src/index.ts:84–104.

3. Логирование вызовов — src/logger.ts:20–34; пример вывода: docs/evidence/smoke-test.log.

4. Контракт результата — docs/contract.md.

Проверочные запросы к агенту (критерий «вызовы из IDE»)

Запросы выполнялись в чате агента opencode внутри VSCode. Транскрипт диалога: mcp_ans.md (не коммитится, содержит извлечённый контент личных документов). Сводная таблица: docs/evidence/verification.md.

Итог по критерию: 8 проверочных запросов, из них 7 приводят к вызову MCP-тула (требование «≥5 запросов, ≥3 реальных вызова» выполнено с запасом), плюс 2 негативных запроса подтверждают границы безопасности.

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

src/index.ts            # сервер, stdio-транспорт, регистрация тулов
src/logger.ts           # логирование вызовов (имя, параметры, статус)
src/security.ts         # проверка путей внутри корня проекта
src/tools/pdf.ts        # PDF (pdf-parse)
src/tools/word.ts       # DOCX (mammoth + cheerio)
src/tools/excel.ts      # XLSX (xlsx / SheetJS)
src/tools/postgres.ts   # PostgreSQL (pg, read-only)
scripts/make-samples.ts # генерация образцов
scripts/smoke-test.mjs  # смоук-тест через MCP-клиент
Dockerfile              # образ MCP-сервера
docker-compose.yml      # PostgreSQL с тестовыми данными
db/init.sql             # инициализация БД (таблицы + данные)
opencode.json          # MCP-конфиг для агента opencode
docs/contract.md        # контракт результатов
docs/evidence/          # логи подтверждений (smoke-test.log, verification.md)
docs/mcp-explained.html # наглядное объяснение принципов MCP (схемы Mermaid)