# 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:

```bash
pip install -r requirements.txt
```

If needed, install directly:

```bash
pip install mcp textstat
```

## Running The MCP Server

Start the server from the project root:

```bash
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:

```text
python
```

Arguments:

```text
server.py
```

Working directory:

```text
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:

```json
{
  "document": "content here"
}
```

Output shape:

```json
{
  "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:

```json
{
  "document": "content here"
}
```

Output shape:

```json
{
  "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:

```json
{
  "document": "content here"
}
```

Output shape:

```json
{
  "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:

```json
{
  "document": "content here"
}
```

Output shape:

```json
{
  "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:

```bash
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:

```bash
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.