# Research Guard MCP

> Check your research idea's novelty before investing months into it.

[![CI](https://github.com/Fengrru/research-guard/actions/workflows/ci.yml/badge.svg)](https://github.com/Fengrru/research-guard/actions)
[![Python 3.11+](https://img.shields.io/badge/python-3.11+-blue.svg)](https://www.python.org/downloads/)
[![License](https://img.shields.io/badge/license-Apache--2.0-green.svg)](LICENSE)
[![MCP](https://img.shields.io/badge/MCP-compatible-brightgreen.svg)](https://modelcontextprotocol.io)

## What it does

Research Guard is an MCP server that tells you if your research idea has already been explored. It decomposes your idea into (Problem, Method, Innovation), searches 200M+ academic papers across Semantic Scholar and OpenAlex, and gives you a **RED / YELLOW / GREEN** verdict with evidence.

**Not a search tool. A research decision guard.**

| Traditional tools | Research Guard |
|-------------------|----------------|
| "Here are 50 papers about X" | "3 papers overlap your core contribution — here's exactly where" |
| Keyword match results | Contribution-level alignment with evidence quotes |
| No answer | **proceed / differentiate / abandon_risk** + differentiation space |

---

## Quick start

### 1. Install

```bash
uvx research-guard-mcp
```

### 2. Get API keys

| Key | Free? | Where to get |
|-----|-------|-------------|
| Semantic Scholar API key | Yes (1 req/s free, 10 req/s with key) | [semanticscholar.org/product/api](https://www.semanticscholar.org/product/api) |
| OpenAI API key | Pay-per-use | [platform.openai.com](https://platform.openai.com) |

### 3. Configure your MCP client

<details>
<summary><strong>Claude Desktop</strong></summary>

Add to `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "research-guard": {
      "command": "uvx",
      "args": ["research-guard-mcp"],
      "env": {
        "S2_API_KEY": "your-semanticscholar-api-key",
        "OPENAI_API_KEY": "your-openai-api-key"
      }
    }
  }
}
```
</details>

<details>
<summary><strong>Claude Code</strong></summary>

```bash
claude mcp add research-guard -- uvx research-guard-mcp
```

Then set the environment variables in your shell profile.
</details>

<details>
<summary><strong>Cursor / Windsurf</strong></summary>

Add to your MCP config (`.cursor/mcp.json` or equivalent):

```json
{
  "mcpServers": {
    "research-guard": {
      "command": "uvx",
      "args": ["research-guard-mcp"],
      "env": {
        "S2_API_KEY": "your-semanticscholar-api-key",
        "OPENAI_API_KEY": "your-openai-api-key"
      }
    }
  }
}
```
</details>

---

## How it works

```
Your research idea
       |
   [Decompose]       →  (Problem, Method, Innovation) triple
       |
   [Expand]          →  5-dimension concept expansion
       |                  (synonyms, ancestors, alternatives, critiques, cross-domain)
       |
   [Retrieve]        →  Semantic Scholar + OpenAlex (parallel, deduplicated)
       |
   [Quick Rank]      →  Contribution-point scoring (text + semantic similarity)
       |
   [Deep Compare]    →  LLM pairwise comparison with evidence grounding
       |
   [Assess]          →  RED / YELLOW / GREEN  +  overlaps  +  blind spots
```

---

## Tools

| Tool | What it does | When to use |
|------|-------------|-------------|
| `check_novelty` | Full novelty assessment with RED/YELLOW/GREEN rating | Before starting any research direction |
| `expand_concepts` | Expand a term across 5 conceptual dimensions | Exploring terminology space before literature search |
| `smart_search` | Multi-source literature search with query expansion | Finding related work beyond keyword match |
| `explore_citation_network` | Forward/backward citation graph traversal | Understanding a paper's influence network |
| `find_blind_spots` | Detect unexplored areas and counter-evidence | When you want to challenge your own assumptions |
| `extract_contributions` | Extract problem/method/innovation from a paper | Analyzing a specific paper's contribution |

---

## Example

```
You: I'm thinking of using vision transformers with shifted windows
     for 3D medical image segmentation. Is this novel?

Claude: [calls check_novelty on Research Guard]

Research Guard result:
  Rating: YELLOW (partially overlapping)
  - Swin UNETR (2022) already uses Swin Transformer for brain tumor segmentation
  - TransUNet (2021) combines transformers with U-Net for medical images
  - Differentiation space: your 3D shifted window approach differs from their
    2D slice-based methods
  - Blind spot: no counter-evidence found for this combination

Claude: Your idea has significant overlap with existing work, but there's
        a clear differentiation path — the 3D shifted window mechanism is
        novel in this domain. I'd recommend proceeding with explicit
        positioning against Swin UNETR.
```

---

## Configuration

All settings are configured via environment variables (prefix `RESEARCH_GUARD_`):

| Variable | Default | Description |
|----------|---------|-------------|
| `S2_API_KEY` | — | Semantic Scholar API key (recommended) |
| `OPENAI_API_KEY` | — | OpenAI API key for LLM comparison |
| `OPENALEX_API_KEY` | — | OpenAlex API key (optional, higher rate limits) |
| `RESEARCH_GUARD_LLM_MODEL` | `gpt-4o-mini` | Model for deep comparison |
| `RESEARCH_GUARD_LOG_LEVEL` | `INFO` | Logging level |
| `RESEARCH_GUARD_LOG_FORMAT` | `console` | `console` or `json` |

---

## Architecture

```
research-guard/
├── packages/
│   ├── guard_core/          # Core engine (no MCP dependency)
│   │   ├── models.py        # Pydantic v2 type system
│   │   ├── decomposer.py    # LLM-based idea decomposition
│   │   ├── expander.py      # 5-dim concept expansion
│   │   ├── retriever.py     # Multi-source parallel retrieval
│   │   ├── novelty_checker.py # Main pipeline orchestrator
│   │   ├── similarity.py    # Text + semantic scoring
│   │   ├── blind_spot.py    # Counter-evidence detection
│   │   ├── contribution_comparator.py  # Contribution-level comparison
│   │   ├── cache.py         # SQLite async cache
│   │   ├── cost_tracker.py  # LLM cost monitoring
│   │   └── sources/         # API clients (S2, OpenAlex, arXiv)
│   ├── guard_mcp/           # FastMCP server (thin adapter)
│   └── guard_web/           # [Phase 2b] Web UI
├── plugins/                 # Extensible data source ABCs
├── datasets/                # Domain vocabularies + validators
├── tests/
│   ├── unit/                # Pure logic tests
│   └── integration/         # Real API tests (skippable)
└── docs/
```

---

## Development

```bash
git clone https://github.com/Fengrru/research-guard.git
cd research-guard
uv sync

# Run all tests
uv run pytest tests/unit -v

# Lint
uv run ruff check packages/ plugins/ datasets/ tests/

# Type check
uv run mypy packages/ --ignore-missing-imports
```

---

## Disclaimer

This tool only covers **indexed public literature** (Semantic Scholar, OpenAlex, arXiv). Unpublished work, gray literature, preprints not yet indexed, and non-English papers may not be fully captured. Always use this as a **decision-aid, not an absolute verdict**.

---

## License

[Apache-2.0](LICENSE) — commercial-friendly, patent grant included.

---

## Contributing

See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines. We welcome contributions for:

- New data source plugins (e.g., PubMed, DBLP, IEEE Xplore)
- Domain-specific expansion vocabularies
- Web UI (Phase 2b)