ファイル分析MCP (file-insight-mcp)

指定されたフォルダ内の非構造化ドキュメントを読み取って構造を分析し、ドキュメント別の要約とフォルダ全体の要約レポートを作成する個人用ローカルMCPサーバーである。

このパッケージの data/sample_docs/ 内のドキュメントはすべてデモ用に作成された合成データである。

基盤となる参考

• サーバー構造(FastMCP、stdio、複数MCPサーバー構成): https://github.com/kyopark2014/mcp

• ハーネス規約(段階的なstage/next_actions、根拠アンカー、承認境界): 同系列の personal-meeting-mcp-training プロジェクトで確立した方式を再利用

• ハーネスエンジニアリング原則リスト: https://github.com/walkinglabs/awesome-harness-engineering (コンテキスト予算、事前承認フック、決定論的eval、静的セキュリティスキャナーの項目を このプロジェクトの規模に合わせて選別適用)

• MCP Python SDK: https://github.com/modelcontextprotocol/python-sdk

Related MCP server: file-analyzer

このサーバーが行うこと

1. 固定された対象フォルダ(data/sample_docs/)の構造をスキャンする。

2. 許可された拡張子(.txt .md .csv .log)のドキュメントのみを読み取る。

3. ドキュメントから目次(見出し構造)、日付・数値・主要用語の候補をルールベースで抽出する。

4. ドキュメント全体を結合した要約プロンプトを作成する。要約自体はホストLLM(Claude/Codex)が 作成し、このMCPはLLM APIを呼び出さない。

5. 作成された要約レポートの構造を検証し、言及されたファイル名が実際に存在するか照合する。

6. ユーザーが明示的に承認した後にのみレポートをファイルとして保存する。

クイックスタート

必須環境: Python 3.11以上、uv

uv sync --extra dev

インストール後、下記の検証節の4つのコマンドをすべてパスすることを確認する。

MCP Inspectorでツールを目視確認するには:

uv run mcp dev src/file_insight_mcp/server.py

プロジェクト構造

ドメインロジックとツール規約を分離し、検証ルールを変更するときにツール階層に触れないようにする。

推奨フロー

SCAN → LIST → READ → EXTRACT → DRAFT → CHECK → PREVIEW → [사용자 승인] → SAVED

リソースとプロンプト

ハーネス設計

このサーバーは機能だけでなく、モデルがツールを使う方法も設計対象としている。

• すべての応答に stage と next_actions があり、モデルが応答だけを見て次のツールを 選ぶ。blocking: true は「この段階をスキップしないでください」という案内ヒントである。実際に 保存を妨げるのは構造検証と承認トークンであり、ヒントがその役割を代行することはない。

• エラーは ToolFailure で原因コード・復旧方法・選択可能な値を一緒に返す。 モデルが再度問い合わせずに自分で回復できるようにすることが目的である。

• 引数スキーマはフラットに保つ({"relative_path": "..."})。Pydanticモデルを 引数型として使うと {"params": {...}} のようにネストされ、呼び出し形式が変わる。

• 戻り値はPydanticモデルなので outputSchema が自動的に生成される。

• すべてのツールに readOnlyHint / destructiveHint を付け、ホストが書き込みツールに 異なる承認UIを表示できるようにする。

• 確実なチェック(構造)のみ保存を妨げ、ヒューリスティックなチェック(ファイル名照合)は警告としてのみ通知する。

コンテキスト予算

「コンテキストウィンドウは捨てる場所ではなく作業メモリの予算」という原則に従い、 すべてのツールは応答サイズに明示的な上限を設けている。

• scan_folder_structure: MAX_SCAN_ENTRIES(500)を超えると truncated: true で 通知して切り詰める。

• read_document: MAX_FILE_BYTES(200KB)を超えるファイルは全体を読み取らず、 read_document_chunk で一部のみ読み取るようにエラーで案内する。

• extract_key_terms: max_terms で分類別の項目数を制限する。

• preview_save_report: include_preview=False がデフォルト値なので、すでに保持している ドラフトを再度応答に含めない。含める必要がある場合のみ max_preview_chars で長さを 制限する。

• harness.truncate() / harness.number_lines(): 切り詰めの有無と引用アンカー(行 番号)を常に明示し、モデルが「これが全体なのか一部なのか」を推測しないようにする。

安全境界

• サーバーは security.TARGET_DIR(data/sample_docs/)の1つだけを扱う。..、絶対パス、 ドライブ文字、シンボリックリンクでもその外側にアクセスできない (security.safe_relative_path)。

• 拡張子allowlist(.txt .md .csv .log)外のファイルは読み取らない。実行/スクリプト 拡張子は対象から常に除外される。

• ファイルサイズが MAX_FILE_BYTES(200KB)を超えると全体を読み取らず、エラーで案内する。

• 名前が . で始まる隠しファイル・フォルダはスキャンから除外する。

• 書き込みツールは save_approved_report の1つだけで、preview_save_report が発行した (report_id、本文)ハッシュトークンが一致する場合のみ動作する。

• このサーバーはドキュメントを読み取るだけである。eval/exec/subprocess のようなコード・シェル実行 呼び出しがソースに入ると scripts/validate_package.py が失敗する。

検証

uv run pytest -q
uv run python scripts/smoke_stdio.py
uv run python scripts/run_evals.py
uv run python scripts/validate_package.py

4つのコマンドの役割がそれぞれ異なるため、すべてパスさせる必要がある。

run_evals.py には、承認トークンが正しい場合と間違っている場合に保存がそれぞれ成功・拒否されるかまで 含めた全体の保存フローが入っている。バグを修正するたびに、そのバグを再現するケースを evals/cases.jsonl に1行追加する。ケースの文法は evals/README.md を参照。

他のフォルダを分析したい場合

このプロジェクトは安全性のため、対象フォルダを src/file_insight_mcp/security.py の TARGET_DIR(パッケージ内の data/sample_docs/)に固定している。実際の業務フォルダを 分析するには:

1. TARGET_DIR を任意の絶対パスに変更するか、環境変数で注入するように修正する。

2. そのフォルダに実際にある拡張子を ALLOWED_EXTENSIONS に反映する。

3. 機密性の高いサブフォルダ(認証情報、個人情報など)がないか先に確認する。

Claude Desktop接続

config/claude_desktop_config.example.json の ABSOLUTE_PROJECT_PATH をこのフォルダの 絶対パスに置き換えた後、Claude Desktop設定に反映する。アプリを完全に終了してから 再度実行する必要がある。

設計原則

• MCPは別のLLM APIを呼び出さない。ClaudeまたはCodexが要約文を作成し、 このMCPは原文・構造・検証・保存を担当する。

• ドキュメントで確認されていないファイル名・数値・日付を作り出さず、根拠チェッカーが 機械的に照合する。

• 最終保存はプレビューで発行された承認トークンとユーザーの明示的承認の両方が 必要である。

• ドメインロジック(core、outline、grounding)とツール規約(server、harness、 security)を分離する。