file-analysis-mcp

「このフォルダにある pdf/docx/pptx/svg/png ドキュメント、全部読んで要約して。」 Claude Code にこの一文を実行させるための個人用 MCP サーバーです。

フォルダを指定すると、中のドキュメントを開いてテキストだけをそのまま抽出して返します。 要約・解釈は このサーバーではなく、このサーバーを呼び出した Claude が会話の中で行います — そのため、別途 LLM API キーは不要で、ローカルで完全にプライベートに動作します。

目次

• 実際にはこう動作します

• クイックスタート

• ツール5つ

• Claude Code への登録

• プロジェクト構成

• 設計原則: ハーネスエンジニアリング

Related MCP server: file-analyzer

実際にはこう動作します

Claude Code で実際のフォルダ(社内 PRD ドキュメントが入ったフォルダ)を指定して質問した結果です。

私: docs フォルダにあるドキュメントを要約して、ファイル構造を分析して

Claude が analyze_folder_structure → analyze_folder を順に呼び出し、返ってきた 原文テキストをもとに次のように回答します。

[analyze_folder_structure] pdf 2개, 총 455KB, 최대 파일 prd.pdf(231KB)
[analyze_folder]           2개 파일 모두 추출 성공 (succeeded: 2, failed: 0)

→ Claude의 요약:
두 문서는 같은 프로젝트("ParameterCheck")의 서로 다른 산출물입니다.
- proposal.pdf: RF솔루션 파트의 CAB 파라미터 검증 자동화 기획서
- prd.pdf: 같은 아이디어의 정식 PRD. 목표는 검증 시간 10분→5분 단축,
  MVP는 "파라미터 엑셀 입력 시 집계시트 자동 생성 + 오류 빨강 표시"
공통점: 사람 검토·승인은 항상 최종 단계로 남겨둔다는 원칙이 두 문서 모두에 명시됨.

サーバーはテキストを渡しただけで、上記の要約文はすべて Claude が作成したものです — これが このプロジェクトが目指す役割分担です。

クイックスタート

# 1) 의존성 설치 (uv 사용)
uv sync --extra dev

# 2) 확인
uv run pytest                        # 유닛테스트
uv run python scripts/smoke_stdio.py # 실제 MCP 프로토콜로 서버를 띄워보는 스모크 테스트

OCR(PNG 分析)が必要な場合は Tesseract-OCR を 別途インストールしてください — 下記 Claude Code への登録 の前半に案内があります。 インストール前でも残り4つのツールは正常に動作します。

ツール5つ

すべてのツールは読み取り専用で、ファイルを変更・削除しません。上限(max_files)に達しても ファイルを黙って省略せず、何件を見られなかったかを応答にそのまま残し、status が PARTIAL になることでその事実をすぐに確認できます。

Claude Code への登録

OCR エンジンのインストール(PNG 分析にのみ必要)

pytesseract は Tesseract-OCR エンジンの Python バインディングに過ぎず、エンジン本体は別途 インストールする必要があります。

1. UB-Mannheim Tesseract インストール版 を ダウンロードして Windows にインストールします。(日本語認識が必要な場合は、インストール中に "Additional language data" で Japanese にチェックを入れてください。)

2. インストールパス(デフォルト C:\Program Files\Tesseract-OCR)をシステム PATH に追加します。

3. tesseract --version でインストールを確認します。

サーバー登録

このリポジトリにはすでに .mcp.json がルートに用意されています。Claude Code を file-analysis-mcp フォルダ(または上位フォルダ)で実行すると自動的に認識されます。再起動 後、/mcp コマンドまたはツール一覧で file-analysis の5つのツールが見えるか確認してください。

手動で登録する場合:

claude mcp add file-analysis -- uv --directory "C:\Users\20223\Desktop\file-analysis-mcp" run python src/file_analysis_mcp/server.py

推奨フロー: analyze_folder_structure で構造を先に把握 → analyze_folder で 全ドキュメントのテキストを一括抽出 → Claude が抽出されたテキストをもとに要約。

プロジェクト構成

file-analysis-mcp/
├── pyproject.toml
├── .mcp.json
├── src/file_analysis_mcp/
│   ├── server.py        # FastMCP 서버, 도구 5개
│   ├── harness.py        # 응답/오류 계약 (BaseResponse, ToolFailure 등)
│   ├── scanner.py         # 폴더 스캔/구조 분석
│   └── extractors/        # pdf/docx/pptx/svg/image 텍스트 추출기
├── scripts/smoke_stdio.py
├── tests/
│   ├── test_scanner.py           # 도메인 로직(순수 함수) 유닛테스트
│   ├── test_extractors.py        # 포맷별 추출기 유닛테스트
│   └── test_server_contract.py   # 하네스 규약(도구 계약) 테스트
└── data/sample_docs/       # 테스트용 샘플 문서

設計原則: ハーネスエンジニアリング

このサーバーは「機能を増やすこと」よりもモデルが応答だけを見て次に何をすべきか分かるように することを優先します。awesome-harness-engineering で 紹介されている原則のうち、ローカル・単一ユーザー・読み取り専用というこのプロジェクトの性質に 実際に合うものだけを選択的に適用しました。(OpenTelemetry による可観測性、プロンプトインジェクションの サンドボックス化、mcp-guardian 系のスコープ承認ゲーティングなどは、マルチユーザー・長期実行 エージェント向けのもので、この規模の個人用ツールには過剰なため適用していません。)

意図的に適用していないもの

• 要約/根拠検証(grounding)機能: このサーバーは「抽出のみ」を行う設計なので(要約は ホストモデルの役割)、該当しません。

• 行番号引用アンカー(L12 | ...): 引用根拠を検証する別途ツールがない限り、 テキストが汚くなるだけなので適用していません。必要になれば harness.number_lines() を 再利用して追加できます。

• 承認トークン方式の保存ワークフロー: このサーバーはファイルを書き込まないため、該当なし。