# q1-crafter-mcp

> Use this tool when you need to automate the academic research cycle, from source discovery to formatted manuscript output. It solves problems such as searching multiple databases, deduplicating results, and formatting citations in APA 7 style, with inputs including search queries and API keys, and outputs including formatted manuscripts and visualization charts. Use it in contexts where efficient and accurate research workflows are crucial, such as academic writing and literature reviews.

Canonical page: https://skillsregistry.net/skills/zaeyasa-q1-crafter-mcp  
JSON: https://api.skillsregistry.net/v1/skills/zaeyasa-q1-crafter-mcp

## Description

<p align="center">
  <img src="https://img.shields.io/badge/MCP-Server-blueviolet?style=for-the-badge&logo=anthropic" alt="MCP Server" />
  <img src="https://img.shields.io/badge/Python-3.10+-3776AB?style=for-the-badge&logo=python&logoColor=white" alt="Python" />
  <img src="https://img.shields.io/badge/APA_7-Compliant-success?style=for-the-badge" alt="APA 7" />
  <img src="https://img.shields.io/badge/License-MIT-yellow?style=for-the-badge" alt="License" />
</p>

<h1 align="center">🎓 Q1 Crafter MCP</h1>

<p align="center">
  <strong>Academic Research MCP Server for Claude Desktop</strong><br/>
  Automates the full research cycle — from source discovery across 18 databases<br/>
  to Q1-quality, APA 7-formatted <code>.docx</code> output.
</p>

<p align="center">
  <a href="#-features">Features</a> •
  <a href="#-quick-start">Quick Start</a> •
  <a href="#%EF%B8%8F-claude-desktop-setup">Claude Desktop</a> •
  <a href="#-available-tools">Tools</a> •
  <a href="#-supported-sources">Sources</a> •
  <a href="#-contributing">Contributing</a>
</p>

---

## ✨ Features

| Category | Highlights |
|----------|-----------|
| 🔍 **Multi-Source Search** | Query **18 academic APIs** in parallel with smart field-based routing |
| 🔄 **Intelligent Dedup** | Two-phase deduplication: exact DOI match → fuzzy title (92% Levenshtein) |
| 🇹🇷 **Turkish Sources** | Native support for TR Dizin, DergiPark (OAI-PMH), YÖK Tez Merkezi |
| 📊 **Literature Analysis** | Gap detection, keyword extraction (TF-IDF), citation validation |
| 📈 **Visualizations** | Publication trends, source distribution, citation network (Mermaid) |
| 📝 **APA 7 Engine** | Full citation formatter — handles 1/2/3+/20+ author rules, DOI formatting |
| 📄 **DOCX Generator** | One-click manuscript generation with title page, sections, references |
| ⚡ **Zero Config** | Free sources work instantly; paid APIs activate when keys are provided |

---

## 🚀 Quick Start

### Installation

```bash
pip install q1-crafter-mcp
```

### Configuration

```bash
# Copy the example env file
cp .env.example .env

# Add your API keys (optional — free sources work without any keys!)
# Edit .env and fill in the keys you have
```

### Run

```bash
q1-crafter-mcp
```

---

## 🖥️ Claude Desktop Setup

Add to your Claude Desktop configuration file:

<details>
<summary><strong>📋 Windows</strong> — <code>%APPDATA%\Claude\claude_desktop_config.json</code></summary>

```json
{
  "mcpServers": {
    "q1-crafter": {
      "command": "q1-crafter-mcp",
      "env": {
        "SCOPUS_API_KEY": "your-scopus-key",
        "IEEE_API_KEY": "your-ieee-key",
        "SPRINGER_API_KEY": "your-springer-key",
        "NCBI_API_KEY": "your-pubmed-key",
        "UNPAYWALL_EMAIL": "your-email@example.com"
      }
    }
  }
}
```

</details>

<details>
<summary><strong>📋 macOS</strong> — <code>~/Library/Application Support/Claude/claude_desktop_config.json</code></summary>

```json
{
  "mcpServers": {
    "q1-crafter": {
      "command": "q1-crafter-mcp",
      "env": {
        "SCOPUS_API_KEY": "your-scopus-key",
        "IEEE_API_KEY": "your-ieee-key",
        "SPRINGER_API_KEY": "your-springer-key"
      }
    }
  }
}
```

</details>

> **💡 Tip:** You don't need all API keys! Free sources (arXiv, CrossRef, OpenAlex, PubMed, etc.) work out of the box. Add paid keys to unlock more databases.

---

## 🛠 Available Tools

### 🔍 Search Tools

| Tool | Description |
|------|-------------|
| `search_academic` | Search up to 18 databases in parallel with smart routing |
| `search_by_doi` | Look up any paper by its DOI |
| `search_citations` | Find all papers that cite a given work |
| `search_references` | Get the reference list of a paper |

### 📊 Analysis Tools

| Tool | Description |
|------|-------------|
| `analyze_literature` | Identify research gaps, themes, trends, and top-cited papers |
| `validate_citations` | Bidirectional check: in-text citations ↔ reference list |
| `extract_keywords` | TF-IDF keyword extraction with bigram support |

### 📈 Visualization Tools

| Tool | Description |
|------|-------------|
| `generate_comparison_table` | Paper comparison tables (Markdown, CSV, APA format) |
| `generate_trend_chart` | Publication trend charts (base64 PNG, dark theme) |
| `generate_citation_network` | Citation network visualization (Mermaid diagram) |

### 📝 Output Tools

| Tool | Description |
|------|-------------|
| `write_section` | Academic section scaffolding with IMRaD templates |
| `format_references_apa7` | APA 7th edition reference list formatter |
| `build_docx` | Generate formatted `.docx` manuscript |
| `check_api_status` | Check which API sources are available |

---

## 🌐 Supported Sources

<table>
<tr>
<th>🆓 Free (No Key)</th>
<th>🔑 Free (Key Required)</th>
<th>🏛️ Institutional</th>
<th>🇹🇷 Turkish</th>
</tr>
<tr>
<td>

- arXiv
- CrossRef
- OpenAlex
- Europe PMC
- DOAJ
- BASE

</td>
<td>

- Semantic Scholar
- PubMed (NCBI)
- CORE
- Unpaywall

</td>
<td>

- Scopus (Elsevier)
- Web of Science
- IEEE Xplore
- Springer Nature
- ScienceDirect
- Dimensions

</td>
<td>

- TR Dizin
- DergiPark (OAI-PMH)
- YÖK Tez Merkezi

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

---

## 🏗 Architecture

```
q1-crafter-mcp/
├── src/q1_crafter_mcp/
│   ├── server.py            # MCP server + 14 tool registrations
│   ├── config.py            # Settings & API key management
│   ├── models.py            # Pydantic data models
│   └── tools/
│       ├── search/          # 18 API clients + aggregator + dedup
│       ├── analysis/        # Gap analyzer, keywords, summarizer
│       ├── visualization/   # Charts, tables, citation network
│       └── output/          # APA formatter, section writer, DOCX
├── tests/                   # 120 unit tests
├── pyproject.toml
└── .env.example
```

### How It Works

```mermaid
graph LR
    A[Claude Desktop] -->|MCP| B[Q1 Crafter Server]
    B --> C[🔍 Search 18 APIs]
    C --> D[🔄 Deduplicate]
    D --> E[📊 Analyze]
    E --> F[📈 Visualize]
    E --> G[📝 APA 7 Format]
    G --> H[📄 .docx Output]
```

1. **Search** — Queries up to 18 databases in parallel, routes by field (medicine → PubMed, CS → Semantic Scholar)
2. **Deduplicate** — Removes duplicates via exact DOI + fuzzy title matching (92% threshold)
3. **Analyze** — Identifies themes, gaps, trends, and extracts keywords
4. **Visualize** — Generates charts, tables, and citation networks
5. **Format** — Applies APA 7th edition rules for citations and references
6. **Output** — Assembles everything into a formatted `.docx` manuscript

---

## 📖 Usage Example

Just ask Claude naturally:

> 🗣 *"Search for papers about machine learning in drug discovery from 2020-2024, analyze the results, and generate a literature review section with APA 7 citations."*

Claude will automatically:
1. Search across available databases
2. Deduplicate and rank results
3. Analyze themes and identify gaps
4. Generate formatted citations
5. Write a structured section with proper references

---

## 🔑 API Key Setup

| Source | How to Get Key | Cost |
|--------|---------------|------|
| Semantic Scholar | [semanticscholar.org/product/api](https://www.semanticscholar.org/product/api) | Free |
| PubMed (NCBI) | [ncbi.nlm.nih.gov/account](https://www.ncbi.nlm.nih.gov/account/) | Free |
| CORE | [core.ac.uk/services/api](https://core.ac.uk/services/api) | Free |
| Scopus | [dev.elsevier.com](https://dev.elsevier.com/) | Institutional |
| IEEE Xplore | [developer.ieee.org](https://developer.ieee.org/) | Paid |
| Springer | [dev.springernature.com](https://dev.springernature.com/) | Free tier |
| Dimensions | [dimensions.ai](https://www.dimensions.ai/scientometric-research/) | Free for research |

---

## 🧪 Development

```bash
# Clone the repo
git clone https://github.com/ZaEyAsa/q1-crafter-mcp.git
cd q1-crafter-mcp

# Install with dev dependencies
pip install -e ".[dev]"

# Run tests
pytest

# Lint
ruff check src/
```

---

## 📊 Test Coverage

| Module | Tests | What's Covered |
|--------|-------|----------------|
| Models | 15 | Paper, Author, SearchConfig, serialization |
| APA Formatter | 18 | In-text, references, ordering, Turkish chars |
| Config | 10 | Source availability, key management |
| Dedup | 9 | DOI match, fuzzy title, metadata richness |
| Analysis | 18 | Gap analysis, keywords, summarizer, citations |
| Visualization | 17 | Charts, tables, citation networks |
| Output | 12 | Section writer, DOCX generator |
| Search Base | 7 | Client lifecycle, safe_search |
| **Total** | **120** | **All passing ✅** |

---

## 📄 License

MIT © [ZaEyAsa](https://github.com/ZaEyAsa)

---

<p align="center">
  <strong>Built with ❤️ for researchers who deserve better tools.</strong><br/>
  <sub>If this helps your research, give it a ⭐ on GitHub!</sub>
</p>

## Trust

- **Trust score (0–1):** 0.95
- **Verification tier:** verified
- **Last scanned:** 2026-09-28

## Facts

- **Version:** 1.0.0
- **Skill type:** atomic
- **Execution layer:** container
- **Runtime environment:** vm
- **Category:** database
- **Updated:** 2026-09-28

## Source

- **Source listing:** [Smithery](https://smithery.ai/server/zaeyasa/q1-crafter-mcp)
- **Repository:** <https://github.com/zaeyasa/q1-crafter-mcp>

## Use it

Resolve this record through the SkillsRegistry MCP server (no auth, read-only):

```
claude mcp add --transport http --scope user skillsregistry https://api.skillsregistry.net/mcp
```

```json
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "get_skill",
    "arguments": {
      "slug": "zaeyasa-q1-crafter-mcp"
    }
  }
}
```

REST: `GET https://api.skillsregistry.net/v1/skills/zaeyasa-q1-crafter-mcp` · pull for local use: `GET https://api.skillsregistry.net/v1/skills/zaeyasa-q1-crafter-mcp/pull`

---
SkillsRegistry indexes agent skills from public registries and GitHub. Skills we have analysed are scanned with Circle-IR and scored on six dimensions; each listing states its scan coverage. More: https://skillsregistry.net/llms.txt