문서 인식 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

MCP 작동 원리

에이전트(IDE)는 stdio 전송 방식으로 MCP 서버에 연결합니다. IDE는 서버를 자식 프로세스로 실행하며(이 프로젝트에서는 Docker 컨테이너, opencode.json 참고) JSON-RPC 2.0 메시지로 통신합니다. 연결 수명 주기는 initialize → tools/list → tools/call의 세 단계로 구성됩니다. tools/list 단계에서 에이전트는 도구 설명(이름, 설명, 입력 파라미터 스키마)을 받아 모델 컨텍스트에 추가합니다. tools/call 단계에서는 에이전트가 서버에 인수를 전달하고, 서버가 실제 작업을 수행하여 구조화된 JSON 결과를 반환합니다. 이 결과는 다시 모델 컨텍스트로 들어가 응답을 만드는 데 사용됩니다.

Tool은 서버가 선언한 함수입니다. 이름, 사람이 읽을 수 있는 설명, 파라미터 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 네트워크에 있습니다. VSCode MCP 컨테이너는 같은 네트워크에 연결되어 서비스 이름 db로 DB에 접속합니다. Postgres 데이터는 named volume pgdata에 저장됩니다.

VSCode(opencode) 에이전트에 연결

이 프로젝트는 VSCode용 opencode 확장(sst-dev.opencode)을 사용합니다. opencode는 자체 설정인 opencode.json을 통해 MCP 서버를 연결합니다. .vscode/mcp.json을 통해서가 아닙니다. .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의 경로는 full path입니다. Docker가 PATH에 없기 때문입니다.

4. opencode를 재시작합니다(VSCode 창을 닫았다 열거나 에이전트 세션을 재시작) — 설정은 시작 시 읽힙니다.

5. 에이전트 채팅에 도구를 명시적으로 포함한 실행을 하나 보냅니다. 예: "Введите extract_pdf для samples/sample.pdf."

6. 호출 확인: 에이전트의 답변은 JSON으로 자격 저장되며, 서버 로그는 터미널/Docker에 표시됩니다.

비밀 정보: docker 모드의 DB 연결 문자열은 로컬 개발용 계정 dev:dev이며 테스트 전용입니다.

IDE 없이 검증 (스모크 테스트)

npm run smoke-test

scripts/smoke-test.mjs은 빌드된 서버를 MCP 클라이언트를 통해 stdio로 띄우고 모든 도구를 호출합니다. 가장 최근 실행 결과: 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:64–81;

   • postgres_search — src/tools/postgres.ts:43–86, 로깅은 src/index.ts:84–104.

3. 호출 로깅 — src/index.ts의 로그 출력 참고.

   • 로깅 구현: src/index.ts:20–34? 원문은 src/index.ts/logger.ts:20–34로 표기됨. 바로 src/tools/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)