<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)](https://modelcontextprotocol.io) 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

```bash
pip install q1-reviewer-mcp
```

### Install from Source

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

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

3. 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

```bash
# 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](LICENSE) file for details.

---

## 👤 Author

**ZaEyAsa** — [GitHub](https://github.com/ZaEyAsa)

---

## 🌟 Related Projects

- [**Q1-Crafter-MCP**](https://github.com/ZaEyAsa/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">
  <sub>Built with ❤️ for the academic community</sub>
</p>