MCP document recognition server

MCP server in TypeScript/Node.js for IDE agents (VSCode). Provides 4 tools: recognition of electronic PDF, Word (DOCX), Excel (XLSX), and PostgreSQL search. Each tool returns structured JSON to the agent.

Features

The result contract for each tool: see docs/contract.md.

Related MCP server: Document Search MCP Server

MCP principles

The agent (IDE) connects to the MCP server over stdio transport: the IDE launches the server as a child process (in our case, a Docker container, see opencode.json) and exchanges JSON-RPC 2.0 messages with it. The connection lifecycle consists of three phases: initialize → tools/list → tools/call. During the tools/list phase, the agent receives tool descriptions (name, description, input parameter schema) and adds them to the model context; during the tools/call phase, the agent passes arguments to the server, the server does the actual work, and returns a structured JSON result, which goes back into the model context to form a response.

Tool is a function declared by the server: it has a name, a human-readable description, and a JSON parameter schema. The model does not execute anything itself — it only decides which tool to call and with what arguments; execution always happens on the MCP server side. In this project the tools are extract_pdf, extract_word, extract_excel, and postgres_search. A visual explanation with Mermaid diagrams is in docs/mcp-explained.html.

Requirements

• Node.js 20.11+ (import.meta.dirname is used)

• PostgreSQL (only for the postgres_search tool)

Installation and startup

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

Environment variables are in the .env file (copy .env.example, specify DATABASE_URL). The actual .env is not committed.

Running in Docker

The entire environment is run with containers: the MCP server (built from Dockerfile) and PostgreSQL with test data.

# 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

Schema: db lives in the ot5_default network; the VSCode MCP container connects to the same network and accesses the DB via the service name db. Postgres data is in the named volume pgdata.

Connecting to the agent in VSCode (opencode)

The project uses the opencode extension for VSCode (sst-dev.opencode). opencode connects MCP servers through its own opencode.json config (not through .vscode/mcp.json, which is needed only for the built-in GitHub Copilot MCP gateway).

1. Install dependencies and build the project: npm install && npm run build.

2. Bring up the environment in Docker:

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

3. The project root already contains opencode.json — it starts docs-server as a container:

   {
     "$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 must be running, the ot5-mcp-server:latest image must be built, and the ot5_default network must exist. The path to docker.exe is full because Docker is not in PATH.

4. Restart opencode (close/reopen the VSCode window or restart the agent session) — the config is read at startup.

5. In the agent chat, send a request that explicitly names the tool, e.g. «Call the extract_pdf MCP tool for samples/sample.pdf».

6. Call confirmation: the agent's response will come as JSON, and the server logs will appear in the terminal/Docker.

Secrets: the database connection string for docker mode is the local dev account dev:dev, for tests only.

Verification without an IDE (smoke test)

npm run smoke-test

The script scripts/smoke-test.mjs starts the built server via stdio through the MCP client and calls all the tools. The output of the last run: docs/evidence/smoke-test.log.

Example of a server-side log line (tool name, parameters, status):

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

Logging is implemented in src/logger.ts:20–34 (it strips keys like password/token).

Security and limitations

• File access — only relative paths within the project root; traversal via ../ is prohibited (src/security.ts:6–22).

• PostgreSQL — read-only: session BEGIN READ ONLY, only SELECT, no multi-statements, request timeout 10 s (src/tools/postgres.ts:43–86). The connection string is taken only from .env and never enters the logs.

• Secrets — only .env.example is in the repository; logging strips keys like password/token, etc. (src/logger.ts:19–34).

• PDF — only electronic (text) PDFs. Scanned documents (images) are not recognized — OCR is out of scope.

Code references (as required by the task)

1. Server and tool registration — src/index.ts:35–106 (tools) and src/index.ts:107–108 (stdio transport).

2. Tool implementations:

   • extract_pdf — src/tools/pdf.ts:14–33 (implementation), logging in src/index.ts:36–49;

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

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

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

3. Call logging — src/logger.ts:19–34; output example: docs/evidence/smoke-test.log.

4. Result contract — docs/contract.md.

Verification prompts for the agent (criterion «calls from the IDE»)

The prompts were run in the opencode agent chat inside VSCode. Conversation transcript: mcp_ans.md (not committed; contains extracted content from personal documents). Summary table: docs/evidence/verification.md.

Summary by the criterion: 8 verification prompts, of which 7 lead to MCP tool calls (the requirement of «at least 5 requests, at least 3 real calls» is met with a margin), and 2 negative prompts additionally confirm the security boundaries.

Project structure

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)