file-analysis-mcp

指定したフォルダ内の非構造化文書(pdf、docx、pptx、txt、svg、png、csv、xlsx)を読み取り、 構造を把握し、承認なしには何も保存しない個人用ローカルMCPです。

実際の動作例

同梱の合成サンプルフォルダ(sample_docs/)に対して実行した実際の結果です。

list_folder_contents()
→ count: 8, entries: data.csv, diagram.svg, notes.docx, photo.png,
  readme.txt, report.pdf, sheet.xlsx, slides.pptx

describe_file(relative_path="slides.pptx")
→ {"slide_count": 3, "slide_titles": ["팀 소개", "구성원", "다음 스프린트"]}

これらのファイルを実際に読み込んで作成したレポートが data/outputs/onboarding-overview-report.mdに あります — 構造検証 VALID、ファイル名根拠検査 GROUNDED(100点)で合格しました。

実際の講義資料フォルダ(PPTX、9MB、16スライド)を指定して検証も行い、その過程で PowerPointを開いたまま生じるロックファイル(~$*.pptx)を読み込もうとして、フォーマット ライブラリの例外がそのまま出てしまうバグを発見し修正しました。現在は原因コードと復旧 方法を含むエラーとして処理されます。

[INVALID_REQUEST] '~$파일.pptx' 파일을 열지 못했습니다: Package not found ...
복구 방법: list_folder_contents로 파일 목록과 지원 형식을 다시 확인하세요.

Related MCP server: local-docs-mcp

これは何か

フォルダを1つ指定すると、中の文書を読み取り、ページ/スライド/シート数などの構造を まず把握し、要約レポートの作成まで支援します。8つの形式をそれぞれ専用 パーサー(pypdf/python-docx/python-pptx/openpyxl/Pillow)で扱います。

なぜ違うのか

• MCPはLLMを呼び出しません。 実際の要約文はHost(Claude/Codex)が 書きます。サーバーはデータ照会・構造分析・検証・保存のみを担当します。

• 保存前には承認トークンとユーザーの明示的な承認の両方が必要です。 書き込み ツールはsave_approved_reportの1つだけで、残り10個は読み取り専用です。

• PNGはOCRなしで実際の画像コンテンツとして渡されます。 Hostのビジョン能力が 直接見て解釈します。

• エラーは常に原因コード + 復旧方法 + 選択可能な値を一緒に返します (上記の例を参照)。

どのように動作するか

list_folder_contents → describe_file → read_file_text(또는 read_image_file)
  → build_summary_prompt → validate_report_draft → check_report_grounding
  → preview_save_report → [사용자 승인] → save_approved_report

はじめに

python -m venv .venv
.venv/Scripts/pip install -e ".[dev]"
.venv/Scripts/python scripts/generate_samples.py
.venv/Scripts/python -m pytest -q
.venv/Scripts/python scripts/smoke_stdio.py

実際のフォルダを分析する

デフォルト値はsample_docs/です。サーバー実行前に環境変数を1つ変更するだけです。

FILE_ANALYSIS_ROOT="D:\내 문서 폴더" .venv/Scripts/python src/file_analysis_mcp/server.py

Codex CLIに登録するには:

codex mcp add file-analysis --env FILE_ANALYSIS_ROOT="D:\내 문서 폴더" -- \
  "<프로젝트경로>\.venv\Scripts\python.exe" "<프로젝트경로>\src\file_analysis_mcp\server.py"

制限

• 画像はOCRを行いません。テキストを抽出するのではなく、画像コンテンツを そのままHostに渡します。

• 20MBを超えるファイルは構造確認のみ可能で、本文は読み取れません。

• check_report_groundingは正規表現ベースのヒューリスティックのため、誤検知が ある可能性があります(助言にすぎず、保存を妨げません)。

• 暗号化されているか、破損しているか、他のプログラムが使用中のファイルは、原因 コードとともにエラーとして報告されます — サーバーは停止しません。

基盤パターン

personal-meeting-mcp-trainingと同じ設計原則(階層分離、stage/ next_actions、承認境界)に従います。詳細なツール契約は src/file_analysis_mcp/の各モジュールのdocstringを参照してください。