q1-reviewer-mcp

<p align="center"> <img src="logo-q1-reviewer-mcp.png" alt="Q1-Reviewer-MCP Logo" width="200"/> </p>

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

<p align="center"> <em>"Get rejected by us before you get rejected by them."</em> </p>

<p align="center"> <a href="https://pypi.org/project/q1-reviewer-mcp/"><img src="https://img.shields.io/pypi/v/q1-reviewer-mcp?style=for-the-badge&color=1F3864&label=PyPI" alt="PyPI Version"></a> <a href="https://python.org"><img src="https://img.shields.io/pypi/pyversions/q1-reviewer-mcp?style=for-the-badge&color=375623" alt="Python"></a> <a href="https://opensource.org/licenses/MIT"><img src="https://img.shields.io/badge/License-MIT-red.svg?style=for-the-badge" alt="License"></a> <a href="https://modelcontextprotocol.io"><img src="https://img.shields.io/badge/MCP-Compatible-blue?style=for-the-badge&logo=data:image/svg+xml;base64,PHN2ZyB4bWxucz0iaHR0cDovL3d3dy53My5vcmcvMjAwMC9zdmciIHZpZXdCb3g9IjAgMCAyNCAyNCI+PHBhdGggZmlsbD0id2hpdGUiIGQ9Ik0xMiAyQzYuNDggMiAyIDYuNDggMiAxMnM0LjQ4IDEwIDEwIDEwIDEwLTQuNDggMTAtMTBTMTcuNTIgMiAxMiAyem0tMiAxNWwtNS01IDEuNDEtMS40MUwxMCAxNC4xN2w3LjU5LTcuNTlMMTkgOGwtOSA5eiIvPjwvc3ZnPg==" alt="MCP"></a> </p>

<p align="center"> <strong>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.</strong> </p>

---

🎯 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

<table> <tr> <td width="50%">

🔬 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

1. Open Claude Desktop
2. 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.

1. 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><strong>🔴 Overclaiming Rules</strong> (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><strong>📝 Introduction Audit Rules</strong></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><strong>🔬 Methodology Audit Rules</strong></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><strong>💬 Discussion Audit Rules</strong></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:

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Run the tests (python -m pytest tests/ -v)
4. Commit your changes (git commit -m 'Add amazing feature')
5. Push to the branch (git push origin feature/amazing-feature)
6. 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)

---

<p align="center"> <em>Because every manuscript deserves a Reviewer #2 before it meets the real one.</em> </p>

<p align="center"> _{Built with ❤️ for the academic community} </p>