Metadata-Version: 2.4
Name: q1-crafter-mcp
Version: 0.1.0
Summary: Academic Research MCP Server for Claude Desktop — automates the full research cycle from source discovery to Q1-quality .docx output
Project-URL: Homepage, https://github.com/ZaEyAsa/q1-crafter-mcp
Project-URL: Repository, https://github.com/ZaEyAsa/q1-crafter-mcp
Project-URL: Issues, https://github.com/ZaEyAsa/q1-crafter-mcp/issues
Author: ZaEyAsa
License: MIT
License-File: LICENSE
Keywords: academic,apa7,citations,claude,docx,literature-review,mcp,research
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Scientific/Engineering
Classifier: Topic :: Text Processing :: Markup
Requires-Python: >=3.10
Requires-Dist: aiohttp>=3.9.0
Requires-Dist: beautifulsoup4>=4.12.0
Requires-Dist: feedparser>=6.0.11
Requires-Dist: httpx>=0.27.0
Requires-Dist: loguru>=0.7.2
Requires-Dist: matplotlib>=3.8.0
Requires-Dist: mcp>=1.0.0
Requires-Dist: networkx>=3.2.0
Requires-Dist: numpy>=1.26.0
Requires-Dist: pandas>=2.1.0
Requires-Dist: pydantic-settings>=2.1.0
Requires-Dist: pydantic>=2.5.0
Requires-Dist: python-docx>=1.1.0
Requires-Dist: python-dotenv>=1.0.0
Requires-Dist: rapidfuzz>=3.5.0
Requires-Dist: sickle>=0.7.0
Requires-Dist: tenacity>=8.2.0
Provides-Extra: dev
Requires-Dist: pytest-asyncio>=0.23.0; extra == 'dev'
Requires-Dist: pytest-cov>=4.1.0; extra == 'dev'
Requires-Dist: pytest>=7.4.0; extra == 'dev'
Requires-Dist: ruff>=0.3.0; extra == 'dev'
Description-Content-Type: text/markdown

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