MCP 服务器

Q1-Reviewer-MCP

An MCP server that simulates a ruthless Q1 journal reviewer to analyze academic manuscripts for red flags and generate a formatted .docx decision letter.

README

<h1 align="center">Q1-Reviewer-MCP</h1>

"Get rejected by us before you get rejected by them."

An AI-powered MCP server that simulates a ruthless Q1 journal Reviewer #2 — so your manuscript gets torn apart before it ever reaches the real one.

🎯 What Is This?

Q1-Reviewer-MCP is a Model Context Protocol (MCP) server that turns Claude into a merciless academic peer reviewer. It reads your .docx manuscript, applies a battle-tested Q1 Red Flag Matrix, and produces a professionally formatted .docx decision letter — complete with color-coded severity ratings.

Think of it as having a permanently angry Reviewer #2 living inside your AI assistant, catching the exact issues that get manuscripts rejected from Nature, Cell, Plant Physiology, and other Q1 journals.

The Problem It Solves

Academic authors routinely receive "Major Revision" or "Reject" decisions due to preventable issues:

🔴 Overclaiming in the Discussion ("We proved that...")
🔴 Causal language without mechanistic evidence
🟠 Weak knowledge-gap framing in the Introduction
🟠 Insufficient biological replicates (n < 3)
🟡 Missing statistical test justification
🟡 No limitations paragraph

These issues are invisible to the author but predictable to an experienced reviewer. Q1-Reviewer catches them before submission.

✨ Features

🔬 Q1 Red Flag Matrix

Embedded review criteria covering:

Overclaiming detection — flags "prove", "perfectly", "definitively" in biological contexts
Causal language audit — catches "X causes Y" when only correlation data exists
Introduction analysis — detects missing knowledge gap statements
Methodology audit — flags n<3 replicates, missing normality tests, absent controls
Discussion audit — catches new data, excessive speculation, missing limitations
Results verification — ensures claims reference figures/tables

</td> <td width="50%">

📄 Professional Output

Decision letters that look like real journal reviews:

Color-coded severity — 🔴 Critical (red), 🟠 Major (orange), 🟢 Positive (green)
Structured format — Editor Decision → Concerns → Revisions → Strengths
Times New Roman, justified — academic standard formatting
Issue-level guidance — THE FLAW → THE Q1 STANDARD → THE DIRECTION
Saved as .docx — ready to share with co-authors

</td> </tr> <tr> <td>

🧠 3-Tier Section Detection

Handles any manuscript format:

Tier 1: Word Heading styles (most reliable)
Tier 2: Bold/uppercase keyword matching (no styles? no problem)
Tier 3: Full-text fallback (unstructured? we'll still review it)

</td> <td>

🌍 Smart Language Detection

Designed for scientific manuscripts:

Multi-section sampling for accuracy
Filters Latin taxonomic names (Arabidopsis thaliana, E. coli)
Won't mistake in vitro or et al. for non-English text

</td> </tr> </table>

🏗️ Architecture

Q1-Reviewer-MCP follows the Tool-as-Data-Fetcher pattern — the MCP server is purely a filesystem operator. All analytical intelligence lives in the host LLM (Claude), guided by the Q1 Red Flag Matrix embedded in tool descriptions.

┌─────────────────────────────────────────────────────────────┐
│                     HOST LLM (Claude)                        │
│   ┌─────────────────────────────────────────────────────┐   │
│   │              Q1 Red Flag Matrix                      │   │
│   │   (Embedded in tool descriptions — auto-injected)    │   │
│   └─────────────────────────────────────────────────────┘   │
│              Reasons, analyzes, generates critique           │
└──────────────────────────┬──────────────────────────────────┘
                           │ MCP Protocol (stdio)
┌──────────────────────────┼──────────────────────────────────┐
│            Q1-Reviewer-MCP Server (Python)                   │
│   ┌──────────────────┐   ┌───────────────────────────────┐  │
│   │ parse_manuscript_ │   │ generate_docx_report()        │  │
│   │ sections()        │   │ Writes formatted .docx        │  │
│   │ Reads .docx       │   │ decision letter to disk       │  │
│   └──────────────────┘   └───────────────────────────────┘  │
│                                                              │
│   📁 manuscript_v1.docx  →  📄 Q1_Review_Report.docx       │
└──────────────────────────────────────────────────────────────┘

Why this design?

🧠 All intelligence upgrades automatically — when Claude improves, reviews improve
💰 Zero server-side LLM costs — no API calls from the server
🧪 Easy to test — server only does file I/O
🔒 Secure — no ports, no HTTP, no authentication (stdio only)

📦 Installation

Prerequisites

Python 3.10+
Claude Desktop or Cursor (any MCP-compatible host)

Install from PyPI

pip install q1-reviewer-mcp

Install from Source

git clone https://github.com/ZaEyAsa/Q1-reviewer-mcp.git
cd Q1-reviewer-mcp
pip install -e .

⚙️ Configuration

Claude Desktop

Add to your Claude Desktop config file:

Windows: %APPDATA%\Claude\claude_desktop_config.json
macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "q1-reviewer": {
      "command": "python",
      "args": ["-m", "q1_reviewer.server"]
    }
  }
}

Note: If python isn't in your PATH, use the full path (e.g., "C:\\Python313\\python.exe" on Windows).

Cursor

Add the same configuration in Cursor Settings → MCP Servers.

Verify Installation

After restarting Claude Desktop, you should see three tools available:

parse_manuscript_sections — reads your manuscript
generate_docx_report — writes the review report
compare_revisions — compares V1 review with V2 manuscript (Phase 3)

🚀 Usage

Quick Start

Open Claude Desktop
Provide your manuscript path:

Please review my manuscript at:
C:/Users/me/Desktop/my_paper_v1.docx

Save the review report to the same directory.

Claude will:
- 📖 Read and parse your manuscript sections
- 🔬 Apply the Q1 Red Flag Matrix
- 📝 Generate a detailed critique
- 💾 Save a formatted .docx decision letter

What You'll Get

A professional .docx report containing:

Section	Description
Editor Decision	Overall verdict (Accept / Minor Revision / Major Revision / Reject)
Critical Concerns	🔴 Issues that would likely cause immediate rejection
Major Concerns	🟠 Significant issues requiring substantial revision
Minor Concerns	Issues that should be addressed but aren't dealbreakers
Recommended Revisions	Numbered action items for the author
Positive Aspects	🟢 Strengths of the manuscript (yes, we're fair too)

Example Output

Each issue follows the structured format:

issue_1: Pervasive Overclaiming

THE FLAW: The manuscript uses "proved" and "definitively demonstrated" in the Discussion, which are absolute claims inappropriate for biological research.

THE Q1 STANDARD: Q1 journals expect hedged language that reflects the inherent uncertainty of experimental biology. Only mathematical proofs allow "prove."

THE DIRECTION: Replace absolute claims with "suggest", "indicate", or "support the hypothesis that."

🔍 Q1 Red Flag Matrix

The review engine applies these rule categories:

<details> <summary>🔴 Overclaiming Rules (click to expand)</summary>

Flags absolute language: "prove", "perfect", "completely", "definitively", "undoubtedly"
Context-aware: accepts in mathematical/structural biology proofs
Flags causal language ("X causes Y") when only correlation data is presented
Suggests appropriate alternatives: "indicate", "suggest", "demonstrate" </details>

<details> <summary>📝 Introduction Audit Rules</summary>

Detects missing knowledge gap statements
Flags overpromising scope (claims vs. actual methodology)
Checks for the critical sentence: "However, [specific gap] remains unknown" </details>

<details> <summary>🔬 Methodology Audit Rules</summary>

Statistical test justification required
Normality test reference for parametric tests
Biological replicates: n ≥ 3 or power analysis
Negative controls in functional assays
Units on all numerical measurements </details>

<details> <summary>💬 Discussion Audit Rules</summary>

New data in Discussion (must appear in Results first)
Speculation depth limit (max 2 inferential steps)
Mandatory limitations paragraph
Data-claim alignment check </details>

📁 Project Structure

q1-reviewer-mcp/
├── src/q1_reviewer/
│   ├── server.py                  # MCP server entry point
│   ├── tools/
│   │   ├── parse.py               # 📖 parse_manuscript_sections()
│   │   ├── report.py              # 📝 generate_docx_report()
│   │   └── compare.py             # 🔄 compare_revisions() [Phase 3]
│   ├── formatting/
│   │   └── docx_builder.py        # .docx formatting engine
│   └── utils/
│       ├── section_splitter.py    # 3-tier section detection
│       └── lang_check.py          # Language detection
├── tests/
│   ├── test_parse.py              # 34 unit tests
│   ├── test_report.py             # 15 unit tests
│   ├── test_e2e.py                # End-to-end pipeline test
│   └── fixtures/                  # Test manuscripts
├── config/
│   └── claude_desktop_config.json # Example config
├── logo-q1-reviewer-mcp.png       # Project logo
├── pyproject.toml
├── requirements.txt
├── LICENSE
└── CHANGELOG.md

🧪 Testing

# Run all tests (49 tests)
python -m pytest tests/ -v

# Run specific modules
python -m pytest tests/test_parse.py -v    # Section parsing tests
python -m pytest tests/test_report.py -v   # Report generation tests

# Run end-to-end pipeline test
python tests/test_e2e.py

🗺️ Roadmap

Phase	Name	Status	Description
1	The Overclaim Detector	✅ Complete	MVP: parse `.docx`, apply Red Flag Matrix, generate `.docx` report
2	The Full Reviewer	🔜 Planned	Full-section analysis (Intro, Methods, Results) with per-issue severity scoring
3	The Editor	📋 Designed	V1↔V2 revision comparison with LLM-as-a-Judge scoring

🔧 Tech Stack

Component	Technology
Language	Python 3.10+
MCP Framework	Official MCP Python SDK (`FastMCP`)
Document I/O	`python-docx`
Language Detection	`langdetect`
Transport	`stdio`
Host Client	Claude Desktop / Cursor

🤝 Contributing

Contributions are welcome! Please:

Fork the repository
Create a feature branch (git checkout -b feature/amazing-feature)
Run the tests (python -m pytest tests/ -v)
Commit your changes (git commit -m 'Add amazing feature')
Push to the branch (git push origin feature/amazing-feature)
Open a Pull Request

📄 License

This project is licensed under the MIT License — see the LICENSE file for details.

👤 Author

ZaEyAsa — GitHub

🌟 Related Projects

Q1-Crafter-MCP — AI-powered academic writing assistant (the writing companion to Q1-Reviewer)

Because every manuscript deserves a Reviewer #2 before it meets the real one.

Built with ❤️ for the academic community