zaeyasa/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 ```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": "[email protected]" } } } } ``` </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>