Skip to main content
Glama
file-analyzer-mcp

file-analyzer-mcp

file-analyzer-mcp

Python Protocol Scope Tests

ローカルフォルダの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)

ツール

説明

list_directory(subpath=".", recursive=True)

フォルダツリー、拡張子別ファイル数/容量

read_document(relative_path)

テキスト/構造抽出 — .pdf .docx .pptx .svg .png

get_file_metadata(relative_path)

サイズ、更新時刻、ページ/スライド数、画像解像度など

プロジェクト構成

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)를 위한 운영 지침

セキュリティ & 制約

項目

ポリシー

パス分離

FILE_ANALYZER_ROOT配下のみアクセス可能 — ../、絶対パス注入、symlink逸脱をすべてブロック

ファイルサイズ

50MB超の場合は読み取らずエラーを返す

タイムアウト

抽出/メタデータ解析が30秒を超えるとエラーで中断して返す

対応拡張子

.pdf .docx .pptx .svg .png — .ppt(旧形式)、.jpgなどは非対応

画像解釈

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 -q

tests/はパス逸脱・絶対パス注入のブロック、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

    Related MCP Servers

    • A
      license
      Not graded
      quality
      B
      maintenance
      MCP 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
    • A
      license
      B
      quality
      D
      maintenance
      An MCP server that lets AI assistants read and visually analyze local documents — PDFs, Excel spreadsheets, CSV files, Word documents, PowerPoint presentations, and images.
      4
      49 npm
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      Local 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
    • A
      license
      Not graded
      quality
      C
      maintenance
      MCP 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