File Analysis MCP (file-insight-mcp)

A personal local MCP server that reads unstructured documents in a specified folder, analyzes their structure, and writes per-document summaries and a folder-wide summary report.

All documents in this package's data/sample_docs/ are synthetic data created for demo purposes.

References

• Server structure (FastMCP, stdio, multi-MCP server composition): https://github.com/kyopark2014/mcp

• Harness conventions (step-by-step stage/next_actions, grounding anchors, approval boundaries): reuses the approach established in the related personal-meeting-mcp-training project

• Harness engineering principles list: https://github.com/walkinglabs/awesome-harness-engineering (context budget, pre-approval hooks, deterministic eval, and static safety scanner items selectively applied at this project's scale)

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

Related MCP server: file-analyzer

What this server does

1. Scans the structure of a fixed target folder (data/sample_docs/).

2. Reads only documents with allowed extensions (.txt .md .csv .log).

3. Extracts table of contents (heading structure), dates, numbers, and key term candidates from documents using rule-based logic.

4. Builds a combined summary prompt from all documents. The summary itself is written by the host LLM (Claude/Codex); this MCP does not call any LLM API.

5. Validates the structure of the written summary report and cross-checks that mentioned filenames actually exist.

6. Saves the report to a file only after the user explicitly approves.

Quick start

Required environment: Python 3.11 or later, uv

uv sync --extra dev

After installation, verify that all four commands in the Verification section below pass.

To visually inspect the tools with MCP Inspector:

uv run mcp dev src/file_insight_mcp/server.py

Project structure

Domain logic and tool conventions are separated so that changing validation rules does not require touching the tool layer.

Recommended flow

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

Resources and prompts

Harness design

This server treats not only functionality but also the way the model uses tools as a design target.

• Every response includes stage and next_actions, so the model can choose the next tool from the response alone. blocking: true is a guidance hint meaning "do not skip this step." What actually blocks saving is structure validation and the approval token; the hint does not take over that role.

• Errors are returned as ToolFailure with a cause code, recovery method, and selectable values. The goal is to let the model recover on its own without asking again.

• Argument schemas are kept flat ({"relative_path": "..."}). Using Pydantic models as argument types would nest them as {"params": {...}} and change the call shape.

• Return values are Pydantic models, so outputSchema is generated automatically.

• Every tool has readOnlyHint / destructiveHint so the host can show a different approval UI for write tools.

• Only certain checks (structure) block saving; heuristic checks (filename cross-check) are reported as warnings only.

Context budget

Following the principle that "the context window is not a dumping ground but a working-memory budget," every tool has an explicit cap on response size.

• scan_folder_structure: If MAX_SCAN_ENTRIES (500) is exceeded, it reports truncated: true and truncates.

• read_document: Files larger than MAX_FILE_BYTES (200KB) are not read in full; instead, an error guides the caller to read only part of the file via read_document_chunk.

• extract_key_terms: Limits the number of items per category with max_terms.

• preview_save_report: include_preview=False is the default, so a draft the model already has is not included in the response again. When it must be included, max_preview_chars limits the length.

• harness.truncate() / harness.number_lines(): Always makes truncation status and citation anchors (line numbers) explicit so the model does not have to guess whether "this is the whole thing or part of it."

Safety boundaries

• The server only handles security.TARGET_DIR (data/sample_docs/). It cannot access anything outside that directory via .., absolute paths, drive letters, or symbolic links (security.safe_relative_path).

• Files outside the extension allowlist (.txt .md .csv .log) are not read. Executable/script extensions are always excluded from targets.

• If a file exceeds MAX_FILE_BYTES (200KB), it is not read in full; an error guides the caller instead.

• Hidden files and folders whose names start with . are excluded from scanning.

• The only write tool is save_approved_report, which works only when the (report_id, body) hash token issued by preview_save_report matches.

• This server only reads documents. If code or shell execution calls such as eval/exec/subprocess appear in the source, scripts/validate_package.py fails.

Verification

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

The four commands each check different things, so all of them must pass.

run_evals.py includes the full save flow, covering whether saving succeeds or is rejected when the approval token is correct or incorrect. Whenever you fix a bug, add one line to evals/cases.jsonl with a case that reproduces that bug. See evals/README.md for the case syntax.

If you want to analyze a different folder

For safety, this project fixes the target folder to TARGET_DIR in src/file_insight_mcp/security.py (the data/sample_docs/ inside the package). To analyze a real work folder:

1. Change TARGET_DIR to the desired absolute path, or modify it to be injected via an environment variable.

2. Reflect the extensions that actually exist in that folder in ALLOWED_EXTENSIONS.

3. First check that there are no sensitive subfolders (credentials, personal information, etc.).

Claude Desktop connection

Replace ABSOLUTE_PROJECT_PATH in config/claude_desktop_config.example.json with the absolute path of this folder, then apply it to the Claude Desktop configuration. You must fully quit the app and relaunch it.

Design principles

• The MCP does not call any separate LLM API. Claude or Codex writes the summary sentences; this MCP handles the source text, structure, validation, and saving.

• It never fabricates filenames, numbers, or dates not confirmed in the documents; the grounding checker mechanically cross-checks them.

• Final saving requires both the approval token issued at preview and the user's explicit approval.

• Domain logic (core, outline, grounding) is separated from tool conventions (server, harness, security).