file-analyzer-mcp

動作確認

フォルダを指定すると、推測ではなく実際のツリーを返します:

$ analyze_folder_structure({ "folder_path": "tests/fixtures" })

{
  "status": "OK",
  "file_count": 6,
  "supported_file_count": 6,
  "extension_stats": [
    { "extension": ".pdf",  "count": 2, "bytes": 723995 },
    { "extension": ".docx", "count": 1, "bytes": 35505 },
    { "extension": ".pptx", "count": 1, "bytes": 33067 },
    { "extension": ".svg",  "count": 1, "bytes": 319 },
    { "extension": ".png",  "count": 1, "bytes": 74 }
  ],
  "tree_text": "fixtures/\n├── sample.docx (34.7KB)\n├── sample.pdf (431B)\n├── sample.png (74B)\n├── sample.pptx (32.3KB)\n├── sample.svg (319B)\n└── sample_scanned.pdf (706.6KB)"
}

その中の1つを読むと、見出し・段落・表が構造化された形で返ってきます(平坦化されません):

$ read_docx({ "file_path": "tests/fixtures/sample.docx" })

{
  "status": "OK",
  "headings": ["테스트 문서"],
  "text": "테스트 문서\n본문 첫 문단입니다.",
  "tables": [{ "index": 0, "rows": [["A", "B"], ["1", "2"]] }]
}

どちらの呼び出しも再現可能です — このリポジトリをクローンし、uv sync --extra dev を実行して、tests/fixtures/ に対して自分で呼び出してみてください。

Related MCP server: Agent Helper

これは何か

フォルダ内のあらゆるファイル(PDF、Word、PowerPoint、SVG、PNG)を読み取り、構造と生のコンテンツを呼び出し元のエージェント(Claude Code、Claude Desktop、Codex)に返す個人用MCPサーバーです。それ自体は要約を行いません。

これが設計全体です:サーバーが抽出し、ホストが解釈します。このサーバーにはLLM APIキーは一切ありません。PNGはキャプションではなくbase64の画像コンテンツとして返され、ホスト自身のビジョンがそれを読み取ります。スキャンされたPDFは、要求した場合にのみOCR処理されます。

ツール

大きなドキュメントはページ分割されます:PDFはpage_start/page_end、PPTXはslide_start/slide_endです。デフォルトの上限は30ページ/60スライドで、それを超えるとレスポンスのnext_actionsが次に要求すべき範囲を教えてくれます。

インストール

uv sync --extra dev

Claude Codeに登録する:

claude mcp add -s user file-analyzer -- "<uv.exe path>" --directory "<this folder>" run python src/file_analyzer_mcp/server.py

Windowsでuvがpip経由でインストールされている場合、ClaudeのPATHには含まれません — uv.exeのフルパスを使用してください(確認はpip show uv)。Claude DesktopとCodexの例はconfig/にあります:claude_code.example.md、claude_desktop_config.example.json、codex-config.example.toml。

セキュリティ

機密パスは決定的に拒否されます — モデルが読まないと判断することに依存しません。paths.pyを参照してください。

すべての呼び出しは監査もされます — ツール名、引数、結果(成功またはブロック)がlogs/audit.jsonlに追記されます。audit.pyを参照してください。これらすべてに加えて50MBのファイルサイズ上限が適用されます。

このサーバーを拡張する人向けの規約はAGENTS.mdにあります。

エラー

すべての失敗はToolFailureを発生させ、コード、平易な理由、復旧方法を含みます — メッセージは人間だけでなく、呼び出し元のモデルが読んで行動できるように書かれています。

スキャンPDFのOCR

read_pdf(ocr=True)にはTesseractが必要です:

winget install UB-Mannheim.TesseractOCR
uv run python scripts/setup_ocr.py   # copies eng/osd, downloads kor.traineddata

ocr_langのデフォルトは"kor+eng"です。Tesseractのパスが間違っていますか?TESSERACT_CMDを設定してください。

テスト

uv run pytest -q                        # parser / path / audit unit tests
uv run python scripts/smoke_stdio.py    # real stdio round-trip against the server

変更が完了と見なされるには、両方がパスする必要があります — pytestはモジュールを個別にチェックし、スモークテストだけが実際のMCPプロトコルを実行してスキーマレベルの破損を検出します。

制限