MCPサーバー文書認識

TypeScript/Node.js製のMCPサーバーで、IDE（VSCode）のエージェント向け。4つのツールを提供する： 電子PDF、Word（DOCX）、Excel（XLSX）の認識と、PostgreSQL検索。各ツールはエージェントに構造化JSONを返す。

機能

各ツールの結果コントラクト： docs/contract.md 参照。

Related MCP server: Document Search MCP Server

原則

エージェント（IDE）はMCPサーバーにstdioトランスポートで接続する：IDEがサーバーを子プロセスとして起動し （本プロジェクトではDockerコンテナ、opencode.json参照）、JSON-RPC 2.0でメッセージを交換する。 接続ライフサイクルは3フェーズ：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ツールのみ）

インストールと起動

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コンテナは同じネットワークに接続し、 サービス名 db でDBにアクセスする。PostgreSQLのデータは名前付きボリューム pgdata に保存される。

VSCodeのエージェントへの接続（opencode）

本プロジェクトではVSCode用拡張機能 opencode を使用（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. エージェントのチャットで、ツールを明示的に呼び出すリクエストを送信。例：「samples/sample.pdf に対して MCPツール extract_pdf を呼び出して」。

6. 呼び出しの確認：エージェントの応答はJSONとして返る。サーバーのログはターミナル/Dockerに表示される。

注意：DB接続文字列はDockerモードでは docker-compose.yml の環境変数から取得される。ローカル開発時は .env の DATABASE_URL を使用（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)