Q1 Crafter MCP

<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

pip install q1-crafter-mcp

Configuration

# 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

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>

{
  "mcpServers": {
    "q1-crafter": {
      "command": "python",
      "args": ["-m", "q1_crafter_mcp.server"],
      "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 / Linux</strong> — <code>~/Library/Application Support/Claude/claude_desktop_config.json</code></summary>

{
  "mcpServers": {
    "q1-crafter": {
      "command": "python3",
      "args": ["-m", "q1_crafter_mcp.server"],
      "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.

---

🔧 Troubleshooting

<details> <summary><strong>❌ ENOENT error: <code>spawn q1-crafter-mcp ENOENT</code></strong></summary>

This means Claude Desktop can't find the executable. This is common on Windows because pip install puts scripts in a user directory that isn't in Claude Desktop's PATH.

Fix: Use python -m instead of the direct command (already shown in the config above). Make sure you're using:

"command": "python",
"args": ["-m", "q1_crafter_mcp.server"]

Alternative fix: Use the full path to the executable:

# Find where it's installed:
pip show q1-crafter-mcp
# Look at the "Location" field, then the Scripts folder next to it

# Example: C:\Users\YourName\AppData\Roaming\Python\Python313\Scripts\q1-crafter-mcp.exe

Then use that full path in your config:

"command": "C:\\Users\\YourName\\AppData\\Roaming\\Python\\Python313\\Scripts\\q1-crafter-mcp.exe"

</details>

<details> <summary><strong>❌ Server disconnected immediately</strong></summary>

Check that the package is installed correctly:

python -m q1_crafter_mcp.server

If you get an import error, reinstall:

pip install --force-reinstall q1-crafter-mcp

</details>

<details> <summary><strong>❌ No search results returned</strong></summary>

• Free sources (arXiv, CrossRef, OpenAlex) work without API keys
• If you added API keys, verify they are correct in your Claude Desktop config
• Run check_api_status tool in Claude to see which sources are available

</details>

---

🛠 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

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	Free
PubMed (NCBI)	ncbi.nlm.nih.gov/account	Free
CORE	core.ac.uk/services/api	Free
Scopus	dev.elsevier.com	Institutional
IEEE Xplore	developer.ieee.org	Paid
Springer	dev.springernature.com	Free tier
Dimensions	dimensions.ai	Free for research

---

🧪 Development

# 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

---

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