MCP-Server zur Dokumentenerkennung

MCP-Server auf TypeScript/Node.js für Agenten in IDEs (VSCode). Stellt 4 Tools bereit: Erkennung von elektronischen PDFs, Word (DOCX), Excel (XLSX) und Suche in PostgreSQL. Jedes Tool gibt dem Agenten strukturiertes JSON zurück.

Funktionen

Ergebnisvertrag jedes Tools: siehe docs/contract.md.

Related MCP server: Document Search MCP Server

MCP-Prinzipien

Der Agent (IDE) verbindet sich mit dem MCP-Server über den stdio-Transport: Die IDE startet den Server als untergeordneten Prozess (in unserem Fall – Docker-Container, siehe opencode.json) und tauscht mit ihm JSON-RPC-2.0-Nachrichten aus. Der Verbindungslebenszyklus besteht aus drei Phasen: initialize → tools/list → tools/call. In der Phase tools/list erhält der Agent die Tool-Beschreibungen (Name, Beschreibung, Schema der Eingabeparameter) und fügt sie in den Modellkontext ein; in der Phase tools/call übergibt der Agent dem Server Argumente, der Server führt die eigentliche Arbeit aus und gibt ein strukturiertes JSON-Ergebnis zurück, das wieder in den Modellkontext gelangt, um die Antwort zu bilden.

Tool – eine vom Server deklarierte Funktion: Sie hat einen Namen, eine menschenlesbare Beschreibung und ein JSON-Schema der Parameter. Das Modell führt selbst nichts aus – es entscheidet nur, welches Tool mit welchen Argumenten aufgerufen wird; die Ausführung erfolgt immer auf der Seite des MCP-Servers. In diesem Projekt sind die Tools extract_pdf, extract_word, extract_excel und postgres_search. Eine anschauliche Erklärung dieses Schemas mit Mermaid-Diagrammen finden Sie in docs/mcp-explained.html.

Anforderungen

• Node.js 20.11+ (verwendet import.meta.dirname)

• PostgreSQL (nur für das Tool postgres_search)

Installation und Start

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

Umgebungsvariablen – in der Datei .env (kopieren Sie .env.example, geben Sie DATABASE_URL an). Die echte .env wird nicht committet.

Start in Docker

Die gesamte Umgebung wird mit Containern hochgefahren: MCP-Server (Build aus Dockerfile) und PostgreSQL mit Testdaten.

# 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 lebt im Netzwerk ot5_default; der MCP-Container von VSCode verbindet sich mit demselben Netzwerk und greift auf die Datenbank über den Dienstnamen db zu. Die Postgres-Daten liegen im named volume pgdata.

Verbindung zum Agenten in VSCode (opencode)

Im Projekt wird die Erweiterung opencode für VSCode verwendet (sst-dev.opencode). opencode verbindet MCP-Server über seine Konfiguration opencode.json (nicht über .vscode/mcp.json, das nur für den integrierten MCP-Gateway von GitHub Copilot benötigt wird).

1. Installieren Sie die Abhängigkeiten und bauen Sie das Projekt: npm install && npm run build.

2. Starten Sie die Umgebung in Docker:

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

3. Im Projektstamm liegt bereits opencode.json – es startet docs-server als 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 muss gestartet sein, das Image ot5-mcp-server:latest gebaut, das Netzwerk ot5_default erstellt. Der Pfad zu docker.exe ist vollständig, da Docker nicht im PATH ist.

4. Starten Sie opencode neu (schließen/öffnen Sie das VSCode-Fenster oder starten Sie die Agentensitzung neu) – die Konfiguration wird beim Start gelesen.

5. Senden Sie im Agenten-Chat eine Anfrage, die das Tool explizit nennt, z. B.: „Rufe das MCP-Tool extract_pdf für samples/sample.pdf auf“.

6. Bestätigung des Aufrufs: Die Antwort des Agenten kommt als JSON, und die Server-Logs erscheinen im Terminal/Docker.

Geheimnisse: Die Datenbankverbindung für den Docker-Modus ist ein lokales Dev-Konto dev:dev, nur für Tests.

Überprüfung ohne IDE (Smoke-Test)

npm run smoke-test

Das Skript scripts/smoke-test.mjs startet den gebauten Server über stdio mit einem MCP-Client und ruft alle Tools auf. Ausgabe des letzten Laufs: docs/evidence/smoke-test.log.

Beispiel einer Log-Zeile auf der Serverseite (Tool-Name, Parameter, 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"}

Die Protokollierung ist in src/logger.ts:20–34 implementiert (bereinigt Schlüssel wie password/token).

Sicherheit und Einschränkungen

• Dateizugriff – nur relative Pfade innerhalb des Projektstamms; Umgehung über ../ ist verboten (src/security.ts:6–22).

• PostgreSQL – nur Lesen: Sitzung BEGIN READ ONLY, nur SELECT, keine Multistatements, Abfragetimeout 10 s (src/tools/postgres.ts:43–86). Die Verbindungszeichenfolge kommt nur aus .env und gelangt nicht in die Logs.

• Geheimnisse – im Repository nur .env.example; die Protokollierung bereinigt Schlüssel wie password/token usw. (src/logger.ts:20–34).

• PDF – nur elektronische (textbasierte) PDFs. Gescannte Dokumente (Bilder) werden nicht erkannt – OCR ist nicht im Umfang enthalten.

Code-Verweise (gemäß Aufgabenanforderungen)

1. Server und Tool-Registrierung – src/index.ts:35–106 (Tools) und src/index.ts:107–108 (stdio-Transport).

2. Tool-Implementierungen:

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

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

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

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

3. Aufrufprotokollierung – src/logger.ts:20–34; Beispielausgabe: docs/evidence/smoke-test.log.

4. Ergebnisvertrag – docs/contract.md.

Testanfragen an den Agenten (Kriterium „Aufrufe aus der IDE“)

Die Anfragen wurden im Chat des opencode-Agenten innerhalb von VSCode ausgeführt. Transkript des Dialogs: mcp_ans.md (wird nicht committet, enthält extrahierten Inhalt persönlicher Dokumente). Übersichtstabelle: docs/evidence/verification.md.

Ergebnis zum Kriterium: 8 Testanfragen, davon führen 7 zu einem MCP-Tool-Aufruf (Anforderung „≥5 Anfragen, ≥3 echte Aufrufe“ mit Reserve erfüllt), plus 2 negative Anfragen bestätigen die Sicherheitsgrenzen.

Projektstruktur

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)