file-analyzer-mcp
file-analyzer-mcp
ローカルフォルダのPDF・DOCX・PPTX・SVG・PNGからテキスト/構造のみを抽出する個人用stdio MCP サーバーです。要約・解釈は行いません — 抽出された結果を読んで要約するのは、このツールを呼び出す ホストLLM(Claude Codeなど)の役割です。
行うこと / 行わないこと
行うこと | 行わないこと |
指定ルートフォルダ配下のドキュメントのテキスト/構造抽出 | 要約・解釈(ホストLLMが担当) |
フォルダツリー・拡張子別ファイル数/容量の集計 | ファイルの書き込み・削除・移動(読み取り専用) |
PNGのOCRテキスト抽出 | 画像の視覚的な意味(図・チャート)の把握 |
大容量/破損ファイルに対するタイムアウト処理 | サーバー実行中の分析対象フォルダの変更 |
Related MCP server: Docalyze
実行例
> read_document("quarterly-report.pdf")
{
"type": "pdf",
"num_pages": 12,
"text": "Q3 Revenue Summary\n..."
}
> read_document("../../etc/passwd")
{ "error": "'../../etc/passwd' resolves outside the allowed root folder" }クイックスタート
git clone https://github.com/asuramama-hue/fileanalyzer_mcp_testmonial.git
cd fileanalyzer_mcp_testmonial
python3 -m venv .venv && source .venv/bin/activate
pip install -e .
brew install tesseract # PNG OCR용 (한국어는 brew install tesseract-lang 추가)Claude Codeに登録:
claude mcp add file-analyzer --env FILE_ANALYZER_ROOT=/분석할/폴더 -- \
"$(pwd)/.venv/bin/python" "$(pwd)/server.py"
claude mcp list # ✔ Connected 확인登録後、新しいセッションで「このフォルダのドキュメントを要約して」と依頼すると、以下の3つのツールをClaudeが 直接呼び出します。
ツール(Tools)
ツール | 説明 |
| フォルダツリー、拡張子別ファイル数/容量 |
| テキスト/構造抽出 — |
| サイズ、更新時刻、ページ/スライド数、画像解像度など |
プロジェクト構成
server.py # FastMCP 앱 진입점, 툴 등록, 루트 폴더 검증
file_analyzer/
security.py # 경로 격리(resolve_safe_path), 크기 제한
timeout.py # 추출 작업 하드 타임아웃
audit.py # 로컬 감사 로그(logs/audit.jsonl)
tree.py, metadata.py # list_directory / get_file_metadata 로직
extractors/ # pdf · docx · pptx · svg · image(OCR) 추출기
tests/ # pytest 회귀 스위트
AGENTS.md # 호출 에이전트(Claude Code)를 위한 운영 지침セキュリティ & 制約
項目 | ポリシー |
パス分離 |
|
ファイルサイズ | 50MB超の場合は読み取らずエラーを返す |
タイムアウト | 抽出/メタデータ解析が30秒を超えるとエラーで中断して返す |
対応拡張子 |
|
画像解釈 | OCRテキストのみ抽出、図/チャートの視覚的な意味は把握できない |
分析対象フォルダ | サーバー起動時に1回固定、実行中は変更不可 |
可観測性 — 監査ログ
すべてのツール呼び出しはlogs/audit.jsonlにローカルのみ1行ずつ記録されます(外部送信なし)。
{"timestamp": "2026-08-26T06:03:35Z", "tool": "read_document", "params": {"relative_path": "report.pdf"}, "status": "ok", "duration_ms": 251.3}ログを空にするにはlogs/audit.jsonlを削除すればOKです。
開発
pip install -e ".[dev]"
pytest -qtests/はパス逸脱・絶対パス注入のブロック、5種類の抽出器、タイムアウト、監査ログ、サーバー統合を
扱います。このプロジェクト規模ではCIパイプラインなしでローカルpytest実行のみで回帰検証が
十分と判断し、そのように維持しています。
なぜこのように設計したか
要約機能なし — 別途LLM APIキーなしでも動作するよう、抽出はサーバーが/要約はホストが 分担する最小構成を選びました。
PNGはOCR、vision渡しではない — ホストに画像をbase64で渡す代わりにテキストだけを抽出して 返却量と実装の複雑さを下げました(図の視覚的な意味は見えない)。
git/CIなしでローカルpytestのみ — 1人用ローカルツール規模ではCIインフラは過剰と判断しました。
既知の制限
タイムアウトはスレッドベースのため、超過した呼び出し自体のバックグラウンドスレッドは返却後も最後まで 実行される可能性があります。
.pptはサポートしていません —.pptxに変換してから使用してください。
ライセンス
別途ライセンスファイルのない個人プロジェクトです。
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
Related MCP Connectors
Document-to-Markdown MCP server — convert PDF, Office and HTML into LLM-ready Markdown.
Document conversion MCP server: PDF to Markdown, image OCR, spreadsheet parsing.
Agent-native MCP server over the public saagarpatel.dev corpus. Read-only, stateless.
Hosted MCP server: convert PDFs to clean, LLM-ready Markdown with tables, formulas and OCR.
Related MCP Servers
- AlicenseNot gradedqualityBmaintenanceMCP server that reads PDFs and exposes them as structured Markdown, metadata, outlines, images, and tables to LLM consumers via tools like pdf_read_markdown and pdf_info.Apache 2.0
- AlicenseBqualityDmaintenanceAn MCP server that lets AI assistants read and visually analyze local documents — PDFs, Excel spreadsheets, CSV files, Word documents, PowerPoint presentations, and images.449 npmMIT
- AlicenseNot gradedqualityDmaintenanceLocal MCP server that indexes folders of documents into a hybrid vector + keyword search index for Claude Desktop, with support for PDFs, Office files, and images via OCR.MIT
- AlicenseNot gradedqualityCmaintenanceMCP server for indexing, semantic search, and generation of multi-format documents. Exposes 13 tools over JSON-RPC 2.0 so an LLM can search your local PDF, Excel, and Word files, and create or edit Excel and Word documents.AGPL 3.0