Servidor MCP de reconocimiento de documentos

Servidor MCP en TypeScript/Node.js para agentes en IDE (VSCode). Proporciona 4 herramientas: reconocimiento de PDF electrónicos, Word (DOCX), Excel (XLSX) y búsqueda en PostgreSQL. Cada herramienta devuelve al agente un JSON estructurado.

Características

Contrato de resultado de cada herramienta: ver docs/contract.md.

Related MCP server: Document Search MCP Server

Principios de MCP

El agente (IDE) se conecta al servidor MCP mediante el transporte stdio: el IDE ejecuta el servidor como proceso hijo (en nuestro caso, contenedor Docker, ver opencode.json) e intercambia mensajes JSON-RPC 2.0. El ciclo de vida de la conexión consta de tres fases: initialize → tools/list → tools/call. En la fase tools/list, el agente obtiene las descripciones de las herramientas (nombre, descripción, esquema de parámetros de entrada) y las añade al contexto del modelo; en la fase tools/call, el agente envía los argumentos al servidor, el servidor realiza el trabajo real y devuelve un resultado JSON estructurado que vuelve al contexto del modelo para formar la respuesta.

Tool es una función declarada por el servidor: tiene un nombre, una descripción legible por humanos y un esquema JSON de parámetros. El modelo no ejecuta nada por sí mismo — solo decide qué tool llamar y con qué argumentos; la ejecución siempre ocurre en el lado del servidor MCP. En este proyecto, las tools son extract_pdf, extract_word, extract_excel y postgres_search. Una explicación visual de este esquema con diagramas Mermaid está en docs/mcp-explained.html.

Requisitos

• Node.js 20.11+ (se usa import.meta.dirname)

• PostgreSQL (solo para la tool postgres_search)

Instalación y ejecución

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

Las variables de entorno están en el archivo .env (copie .env.example, indique DATABASE_URL). El .env real no se commitea.

Ejecución en Docker

Todo el entorno se levanta con contenedores: el servidor MCP (compilado desde Dockerfile) y PostgreSQL con datos de prueba.

# 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

Esquema: db vive en la red ot5_default; el contenedor MCP de VSCode se conecta a la misma red y accede a la BD por el nombre de servicio db. Los datos de Postgres están en el volumen nombrado pgdata.

Conexión al agente en VSCode (opencode)

En el proyecto se usa la extensión opencode para VSCode (sst-dev.opencode). opencode conecta los servidores MCP a través de su configuración opencode.json (no mediante .vscode/mcp.json, que solo se necesita para el gateway MCP integrado de GitHub Copilot).

1. Instale las dependencias y compile el proyecto: npm install && npm run build.

2. Levante el entorno en Docker:

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

3. En la raíz del proyecto ya está opencode.json — inicia docs-server como contenedor:

   {
     "$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 debe estar en ejecución, la imagen ot5-mcp-server:latest compilada, la red ot5_default creada. La ruta a docker.exe es completa, ya que Docker no está en PATH.

4. Reinicie opencode (cierre/abra la ventana de VSCode o reinicie la sesión del agente) — la configuración se lee al iniciar.

5. En el chat del agente, envíe una solicitud que nombre explícitamente la herramienta, por ejemplo: «Llama a la herramienta MCP extract_pdf para samples/sample.pdf».

6. Confirmación de la llamada: la respuesta del agente llegará como JSON, y los registros del servidor aparecerán en la terminal/Docker.

Secretos: la cadena de BD para el modo docker es la cuenta de desarrollo local dev:dev, solo para pruebas.

Verificación sin IDE (smoke test)

npm run smoke-test

El script scripts/smoke-test.mjs levanta el servidor compilado por stdio mediante un cliente MCP y llama a todas las tools. Salida de la última ejecución: docs/evidence/smoke-test.log.

Ejemplo de línea de registro en el lado del servidor (nombre de la tool, parámetros, estado):

{"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"}

El registro está implementado en src/logger.ts:20–34 (limpia claves como password/token).

Seguridad y limitaciones

• Acceso a archivos — solo rutas relativas dentro de la raíz del proyecto; el acceso mediante ../ está prohibido (src/security.ts:6–22).

• PostgreSQL — solo lectura: sesión BEGIN READ ONLY, solo SELECT, sin multi-sentencias, tiempo de espera de consulta 10 s (src/tools/postgres.ts:43–86). La cadena de conexión solo proviene de .env, no aparece en los registros.

• Secretos — en el repositorio solo está .env.example; el registro limpia claves como password/token, etc. (src/logger.ts:20–34).

• PDF — solo PDF electrónicos (de texto). Los documentos escaneados (imágenes) no se reconocen — el OCR no está en el alcance.

Enlaces al código (según los requisitos de la tarea)

1. Servidor y registro de herramientas — src/index.ts:35–106 (tools) y src/index.ts:107–108 (transporte stdio).

2. Implementación de las herramientas:

   • extract_pdf — src/tools/pdf.ts:14–33 (implementación), registro en src/index.ts:36–49;

   • extract_word — src/tools/word.ts:17–71, registro en src/index.ts:52–65;

   • extract_excel — src/tools/excel.ts:15–36, registro en src/index.ts:68–81;

   • postgres_search — src/tools/postgres.ts:43–86, registro en src/index.ts:84–104.

3. Registro de llamadas — src/logger.ts:20–34; ejemplo de salida: docs/evidence/smoke-test.log.

4. Contrato de resultado — docs/contract.md.

Solicitudes de verificación al agente (criterio «llamadas desde IDE»)

Las solicitudes se realizaron en el chat del agente opencode dentro de VSCode. Transcripción del diálogo: mcp_ans.md (no se commitea, contiene contenido extraído de documentos personales). Tabla resumen: docs/evidence/verification.md.

Resultado según el criterio: 8 solicitudes de verificación, de las cuales 7 conducen a una llamada a la tool MCP (el requisito «≥5 solicitudes, ≥3 llamadas reales» se cumple con margen), además 2 solicitudes negativas confirman los límites de seguridad.

Estructura del proyecto

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)