docscanner-mcp

DocScanner MCP Server v1

DocScanner MCP Server v1 exposes a lightweight documentation review workflow through MCP tools.

It is designed for end users who want to review plain text documents from an MCP-compatible client such as Claude Desktop, Cursor, or VS Code MCP integrations.

What This Server Does

The server provides 4 tools:

1. review_document
2. readability_score
3. style_check
4. summarize_document

It also provides 2 read-only resources:

1. style-guide://main
2. rules://review

High-Level Flow

1. You send document text from an MCP client.
2. The client calls one of the DocScanner tools.
3. The tool returns structured JSON results.
4. You use the response directly, or ask the client to rework your text.

Project Layout

• server.py: MCP entry point and tool/resource registration.
• tools/review.py: Rule-based issue detection (passive voice, long sentences).
• tools/readability.py: Flesch score and grade level.
• tools/style.py: Style violations (future tense, sentence length).
• tools/summary.py: Basic extractive summary.
• resources/style_guide.md: Style guide text served as an MCP resource.
• resources/review_rules.md: Review rule categories served as an MCP resource.
• smoke_test.py: Local smoke test for all four tools.

Prerequisites

• Python 3.10 or newer
• pip

Installation

From the project root, install dependencies:

pip install -r requirements.txt

If needed, install directly:

pip install mcp textstat

Running The MCP Server

Start the server from the project root:

python server.py

The process stays active and waits for MCP client requests.

Connecting From An MCP Client

Configure your MCP client to launch this server with Python.

Command:

python

Arguments:

server.py

Working directory:

docscanner-mcp project root

After connecting, the client should discover:

• Tools: review_document, readability_score, style_check, summarize_document
• Resources: style-guide://main, rules://review

Tool Reference

1) review_document

Input:

{
  "document": "content here"
}

Output shape:

{
  "issues": [
    {
      "severity": "high",
      "message": "Avoid passive voice"
    }
  ]
}

Current behavior:

• Returns severity/message issues.
• Detects passive voice patterns.
• Flags sentences longer than 25 words.
• Returns one medium issue when the document is empty.

2) readability_score

Input:

{
  "document": "content here"
}

Output shape:

{
  "flesch_score": 62.5,
  "grade_level": 8
}

Current behavior:

• Computes Flesch Reading Ease using textstat.
• Computes Flesch-Kincaid grade level.
• Rounds score to one decimal.
• Returns zeros for empty input.

3) style_check

Input:

{
  "document": "content here"
}

Output shape:

{
  "violations": [
    "Future tense detected",
    "Sentence too long"
  ]
}

Current behavior:

• Detects future tense keywords: will, shall, going to.
• Flags sentences longer than 25 words.
• Returns an empty violations list for empty input.

4) summarize_document

Input:

{
  "document": "content here"
}

Output shape:

{
  "summary": "..."
}

Current behavior:

• Uses the first two sentences as a concise summary.
• Truncates long summary text to about 300 characters.
• Returns a fallback message for empty input.

Resource Reference

style-guide://main

Serves this guidance:

• Use active voice.
• Use sentence case.
• Avoid future tense.
• Keep sentences under 25 words.

rules://review

Serves rule categories:

• Passive Voice
• Readability
• Terminology
• Capitalization
• Formatting

Example End-User Prompts

Use prompts like these in your MCP client:

• Review this document using review_document and list high severity issues first.
• Run readability_score on this text and explain if grade_level is suitable for general users.
• Run style_check and rewrite only the violating sentences.
• Summarize this document in two concise sentences using summarize_document.
• Read style-guide://main first, then review my text against it.

Local Smoke Test

A small smoke test is included to verify all tools at once:

python smoke_test.py

Expected result:

• JSON output that includes keys for all 4 tools.
• Non-empty values for most fields when sample text is present.

Troubleshooting

ModuleNotFoundError for mcp or textstat

Install dependencies again:

pip install -r requirements.txt

Server starts but client cannot discover tools

Check:

1. The client command points to python.
2. Arguments include server.py.
3. Working directory is the project root.
4. The process starts without Python errors.

Empty or weak analysis results

Check document input quality:

1. Ensure the document field contains plain text.
2. Use multiple sentences for better summary/readability output.
3. Avoid sending only headings or very short snippets.

Notes On v1 Scope

This version intentionally stays small and deterministic.

• No file parsing (PDF, DOCX) yet
• No RAG retrieval pipeline yet
• No GitLab integration yet

This keeps setup simple and makes behavior easy to validate before expanding to later versions.