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）通过stdio传输连接到MCP服务器：IDE将服务器作为子进程启动 （在本项目中为Docker容器，参见 opencode.json）并通过JSON-RPC 2.0交换消息。 连接生命周期包含三个阶段：initialize → tools/list → tools/call。 在tools/list阶段，代理获取工具描述（名称、说明、输入参数模式）并将其 添加到模型上下文中；在tools/call阶段，代理向服务器传递参数，服务器执行 实际工作并返回结构化JSON结果，该结果回到模型上下文中用于生成回复。

工具是服务器声明的函数：它有名称、人类可读的说明和JSON参数模式。 模型本身不执行任何操作——它只决定调用哪个工具以及使用哪些参数； 执行始终发生在MCP服务器端。在本项目中，工具为 extract_pdf、 extract_word、extract_excel 和 postgres_search。该模式的直观说明（含Mermaid图表）—— 见 docs/mcp-explained.html。

要求

• Node.js 20.11+（使用 import.meta.dirname）

• PostgreSQL（仅用于 postgres_search 工具）

安装与启动

1. 安装依赖并构建项目：npm install && npm run build。

2. 在Docker中启动环境：

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

3. 环境变量位于 .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容器连接到同一网络并通过服务名 db 访问数据库。Postgres数据存放在命名卷 pgdata 中。

连接到VSCode（opencode）中的代理

项目使用VSCode的 opencode 扩展（sst-dev.opencode）。 opencode通过其配置文件 opencode.json 连接MCP服务器（而非 .vscode/mcp.json， 后者仅用于内置的GitHub Copilot MCP网关）。

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. 在代理聊天中发送明确指定工具的请求，例如：「对 samples/sample.pdf 调用MCP工具 extract_pdf」。

6. 调用确认：代理的回复将以JSON形式返回，服务器日志显示在终端/Docker中。

密钥：docker模式的数据库连接串为本地开发账号 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内调用」标准）

请求在VSCode内的opencode代理聊天中执行。对话转录：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)