{
  "markdown": "# Scholar MCP Server\n\n[![Python Version](https://img.shields.io/badge/python-3.10%2B-blue)](https://www.python.org/)\n[![Model Context Protocol](https://img.shields.io/badge/MCP-FastMCP-brightgreen)](https://modelcontextprotocol.io/)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n[![Registry](https://img.shields.io/badge/Registry-Verified-blue)](https://registry.modelcontextprotocol.io/)\n\nA [Model Context Protocol](https://modelcontextprotocol.io/) (MCP) server providing structured access to scientific literature databases. It serves as a unified interface for **Scopus**, **OpenAlex**, **Semantic Scholar**, and **Unpaywall**, enabling AI agents to perform systematic paper discovery, author disambiguation, citation lineage tracking, and multimodal Content extraction.\n\n## Core Capabilities\n\n- **Unified Literature Search**\n  - **Semantic Scholar Integration** — High-relevance search and detailed metadata, including AI-generated **TLDRs** (requires API key).\n  - **Scopus Integration** — Targeted metadata retrieval via advanced Boolean syntax (requires API key).\n  - **OpenAlex Integration** — Broad search across 250M+ works with abstract reconstruction.\n  - **Unpaywall Resolution** — DOI-to-PDF cross-referencing across global Open Access repositories.\n  - **Sci-Hub Fallback (⚠️ Use with Caution)** — Automatic mirror resolution and parsing for paywall bypassing.\n\n- **Book Search & Extraction**\n  - **Google Books & Open Library** — Integrated search for book metadata, editions, and descriptions without API keys.\n  - **Library Genesis (Libgen)** — Search and extract full text from books directly using PyMuPDF. Features smart caching and token-saving strategies (TOC reading, targeted keyword searching, and page range extraction).\n\n- **Author Identification & Metrics**\n  - Instant author disambiguation and ID resolution via OpenAlex autocomplete.\n  - Comprehensive profiles: H-index, i10-index, institutional affiliation history, and ORCID linkage.\n  - Precision metrics from Elsevier (Scopus) for verified publication counts.\n\n- **Citation Lineage Tracking**\n  - Map research evolution through forward citations (citing works) and backward references (cited works).\n\n- **Structured & Multimodal Extraction**\n  - **Text Extraction** — Layout-aware parsing of OA PDFs using [PyMuPDF](https://pymupdf.readthedocs.io/).\n  - **Vision Rendering** — Page-by-page PNG rendering for LLM-based analysis of charts, tables, and equations.\n  - **HTML Fallbacks** — Extraction from web-based research resources via BeautifulSoup.\n\n- **Topic Mapping & Field Analysis**\n  - Concepts and domain hierarchy discovery to map research landscapes.\n  - Batch metadata retrieval for high-throughput literature processing (up to 50 DOIs/request).\n\n- **Access Management & Fallbacks**\n  - Automated detection of closed-access content with human-in-the-loop instructions for manual uploads.\n\n## Architecture\n\n```mermaid\ngraph TD\n    A[LLM Agent] -->|MCP Protocol| B(Scholar MCP Server)\n    B --> C{Database Router}\n    C -->|Primary| D[Scopus API]\n    C -->|Fallback| E[OpenAlex API]\n    C -->|DOI Resolver| F[Unpaywall API]\n    C -->|Citations| P[CrossRef API]\n    \n    D --> G{Access Check}\n    E --> G\n    F --> G\n    P --> G\n    \n    G -->|Open Access| H[PDF Buffer Download]\n    G -->|Closed Access| I[Human-in-the-Loop Prompt]\n    H --> J[PyMuPDF Text Extractor]\n    H --> K[PyMuPDF Vision Renderer]\n    J --> L[Return Context to LLM]\n    K --> L\n    I --> L\n    B --> M{Author Router}\n    M -->|Profile| N[OpenAlex Authors API]\n    M -->|Metrics| O[Scopus Author API]\n    N --> L\n    O --> L\n```\n\n## Installation\n\n### Quick Start (via PyPI)\n\nThe fastest way to use the server is directly via PyPI:\n\n```bash\npip install scholar-academic-mcp\n```\n\n### Manual Setup (for Development)\n\n```bash\n# Clone the repository\ngit clone https://github.com/mlintangmz2765/Scholar-MCP.git\ncd Scholar-MCP\n\n# Setup virtual environment\npython -m venv venv\n.\\venv\\Scripts\\activate  # Windows\nsource venv/bin/activate # Unix\n\n# Install in editable mode\npip install -e .\n```\n\n### Environment Variables\n\n| Variable            | Required | Description                                                       |\n|---------------------|----------|-------------------------------------------------------------------|\n| `SCOPUS_API_KEY`    | Yes      | Elsevier API key for Scopus search and author retrieval.          |\n| `S2_API_KEY`        | No       | Semantic Scholar API key for TLDRs and S2 graph access.           |\n| `SCIHUB_MIRRORS`    | No       | Comma-separated list of active Sci-Hub mirrors for PDF fallback.  |\n| `LIBGEN_MIRRORS`    | No       | Comma-separated list of active Library Genesis mirrors.           |\n| `SCOPUS_INST_TOKEN` | No       | Institutional token for full abstract access via Scopus.          |\n| `CONTACT_EMAIL`     | Yes      | Email for OpenAlex/Unpaywall polite-pool API routing.             |\n\n## Configuration\n\n### Claude Desktop / Cursor\n\nAdd the following to your configuration file (e.g., `claude_desktop_config.json`):\n\n```json\n{\n  \"mcpServers\": {\n    \"scholar-academic-mcp\": {\n      \"command\": \"scholar-academic-mcp\",\n      \"env\": {\n        \"SCOPUS_API_KEY\": \"your_scopus_api_key\",\n        \"S2_API_KEY\": \"your_s2_api_key\",\n        \"SCIHUB_MIRRORS\": \"https://sci-hub.ru,https://sci-hub.st\",\n        \"LIBGEN_MIRRORS\": \"https://libgen.la,http://libgen.li\",\n        \"SCOPUS_INST_TOKEN\": \"your_optional_inst_token\",\n        \"CONTACT_EMAIL\": \"your_email@domain.com\"\n      }\n    }\n  }\n}\n```\n\n## Quick Start & Examples\n\nOnce configured, your AI agent can perform complex research workflows. Below are representative examples of tool inputs and structured outputs.\n\n### 1. Literature Discovery (Scopus)\n**Prompt**: *\"Find recent papers about 'Transformer architectures' published after 2022 using Scopus.\"*\n\n**Tool Call**: `search_papers_tool(query=\"TITLE-ABS-KEY(Transformer architectures) AND PUBYEAR > 2022\", limit=3)`\n\n**Output**:\n```text\nFound 3 papers via Scopus:\n- [SCOPUS_ID:85184...] Attention is All You Need? A Survey of Transformer Variants\n  Authors: Smith, J., Doe, A.\n  Date: 2024-01-15 | DOI: 10.1016/j.artint.2023.104012\n```\n\n### 2. Multimodal Content Analysis\n**Prompt**: *\"I need to see the diagram for the neural network architecture on page 3 of this URL.\"*\n\n**Tool Call**: `get_full_text_visual_tool(url=\"https://arxiv.org/pdf/1706.03762.pdf\", max_pages=3)`\n\n**Output**:\n- `[Text]` \"Successfully rendered 3 pages visually...\"\n- `[Image]` (PNG data of page 1)\n- `[Image]` (PNG data of page 2)\n- `[Image]` (PNG data of page 3 - containing the architecture diagram)\n\n### 3. Research Topic Mapping\n**Prompt**: *\"Help me understand the subfields and domains related to 'Generative AI'.\"*\n\n**Tool Call**: `search_topics_tool(query=\"Generative AI\")`\n\n**Output**:\n```text\nFound 1 topics for 'Generative AI':\n- Artificial Intelligence\n  Hierarchy: Computer Science → Artificial Intelligence → Machine Learning\n  Works: 12,450 | Citations: 450,210\n  Description: A field of computer science that focuses on creating systems capable of generating...\n```\n\n## Tools\n\nThe server registers **23 tools** across 7 categories:\n\n### Paper Discovery\n\n| Tool                           | Signature                                                                | Description                                                                                                   |\n|--------------------------------|--------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------|\n| `search_papers_tool`           | `(query, limit=5, use_scopus=True, sort_by=\"relevance\")`                | Search papers via Scopus (Boolean syntax) or OpenAlex. Sort by `cited_by_count` or `publication_year`.        |\n| `search_papers_s2_tool`        | `(query, limit=5)`                                                       | Search papers via Semantic Scholar. Note: strictly rate-limited to 1 request/sec.                             |\n| `get_paper_details_tool`       | `(paper_id)`                                                             | Fetch full metadata and abstract by Scopus ID, DOI, or OpenAlex ID (with automatic routing).                  |\n| `get_paper_details_s2_tool`    | `(paper_id)`                                                             | Fetch full metadata from Semantic Scholar, including **AI-generated TLDRs**. Accepts S2 ID or DOI.              |\n| `search_titles_unpaywall_tool` | `(query, is_oa=None)`                                                    | Search Unpaywall's database directly by title. Set `is_oa=True` for strictly OA results.                      |\n| `get_related_works_tool`       | `(paper_id, limit=10)`                                                   | Find related/similar papers using OpenAlex's bibliographic coupling.                                          |\n\n### Book Discovery & Extraction\n\n| Tool                           | Signature                                                                | Description                                                                                                   |\n|--------------------------------|--------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------|\n| `search_books_tool`            | `(query, limit=5, source=\"googlebooks\")`                                 | Search for book metadata via Google Books or Open Library.                                                    |\n| `get_book_details_tool`        | `(book_id, source=\"googlebooks\")`                                        | Fetch complete book details, descriptions, and ISBNs.                                                         |\n| `search_libgen_tool`           | `(query, limit=5)`                                                       | Search Library Genesis for books to retrieve their download MD5 hashes.                                       |\n| `interact_with_book_tool`      | `(md5, action, keyword, start_page, end_page)`                           | Smart extraction from Libgen. Actions: `toc` (Table of Contents), `search` (keywords), `pages` (range).       |\n\n### Author Analytics\n\n| Tool                              | Signature                          | Description                                                                    |\n|-----------------------------------|------------------------------------|--------------------------------------------------------------------------------|\n| `autocomplete_authors_tool`       | `(name, limit=5)`                  | Rapidly disambiguate author names and resolve OpenAlex Author IDs.             |\n| `search_authors_tool`             | `(name, institution=None, limit=5)`| Detailed bibliometric profiles: H-index, i10-index, ORCID, and research concepts. |\n| `search_author_by_orcid_tool`     | `(orcid)`                          | Look up an author directly by ORCID (raw or URL format).                       |\n| `retrieve_author_works_tool`      | `(author_id, limit=15)`           | Chronologically sorted publications for a given OpenAlex author.               |\n| `get_author_profile_scopus_tool`  | `(author_id)`                      | Fetch precise Scopus-sourced h-index, citation counts, and affiliation.        |\n| `get_author_profile_s2_tool`      | `(author_id)`                      | Fetch Semantic Scholar author profile (H-index, paper count, citations).       |\n\n### Citation Tracking\n\n| Tool               | Signature                              | Description                                                              |\n|--------------------|----------------------------------------|--------------------------------------------------------------------------|\n| `get_citations_tool`| `(paper_id, direction=\"references\")`  | Retrieve forward citations or backward references via OpenAlex.          |\n\n### Full-Text & PDF\n\n| Tool                            | Signature                                 | Description                                                                              |\n|---------------------------------|-------------------------------------------|------------------------------------------------------------------------------------------|\n| `get_full_text_tool`            | `(url, start_page=None, end_page=None)`   | Extract text from an OA PDF or HTML page. Supports page range selection.                 |\n| `get_full_text_visual_tool`     | `(url, max_pages=3)`                      | Render PDF pages as images for Vision-capable LLMs.                                      |\n| `fetch_pdf_text_unpaywall_tool` | `(doi)`                                   | All-in-one: resolve DOI via Unpaywall → download PDF → extract text.                     |\n| `get_scihub_link_tool`          | `(doi)`                                   | Attempts to resolve a strict paywalled DOI to a free direct PDF link using Sci-Hub.      |\n| `fetch_pdf_text_scihub_tool`    | `(doi)`                                   | All-in-one bypass: resolve DOI via Sci-Hub → download PDF → extract text.                |\n\n### Citation & Writing\n\n| Tool                    | Signature                  | Description                                                                      |\n|-------------------------|----------------------------|----------------------------------------------------------------------------------|\n| `get_bibtex_tool`       | `(doi)`                    | Generate a BibTeX entry for LaTeX via CrossRef content negotiation.               |\n| `format_citation_tool`  | `(doi, style=\"apa\")`      | Format citation in APA, IEEE, Chicago, Harvard, Vancouver, MLA, or Turabian.     |\n\n### Open Access Resolution\n\n| Tool                    | Signature | Description                                                            |\n|-------------------------|-----------|------------------------------------------------------------------------|\n| `get_unpaywall_link_tool`| `(doi)`  | Resolve a DOI to all available OA locations via Unpaywall.             |\n\n### Topic Mapping & Batch Analysis\n\n| Tool                    | Signature                  | Description                                                                      |\n|-------------------------|----------------------------|----------------------------------------------------------------------------------|\n| `search_topics_tool`    | `(query, limit=10)`        | Browse research topics/concepts. Returns fields, domains, and publication volume. |\n| `batch_lookup_tool`        | `(dois: list[str])` | Batch-fetch metadata for multiple DOIs in a single call (max 50).                |\n\n\n## Technical Design & Reliability\n\nScholar MCP is engineered for precision and fault tolerance in high-stakes research environments, utilizing several layers of protection to ensure data integrity:\n\n- **Strict Data Contracts (Pydantic)**\n  - All upstream API responses are validated against **Pydantic** models before being returned to the agent.\n  - Ensures a predictable, type-safe interface even if upstream database schemas change.\n\n- **Fault-Tolerant Networking (Tenacity)**\n  - Integrated **Exponential Backoff** using `tenacity` for transient HTTP errors (429, 5xx).\n  - Configurable rate-limit awareness for Elsevier and OpenAlex \"polite pool\" routing.\n\n- **Resource Safety & Concurrency**\n  - **Context-Managed Extractors**: Automatic cleanup of PDF buffers and file descriptors.\n  - **Isolated Concurrency**: Batch operations utilize `asyncio.gather` with localized exception handling to prevent session-wide failures.\n\n- **System Observability**\n  - Structured standard-error (`stderr`) logging provides execution visibility during the tool lifecycle without interfering with the MCP JSON-RPC protocol.\n\n- **Automated Verification**\n  - Comprehensive test suite leveraging **respx** for deterministic API mocking, ensuring 100% coverage of edge cases without network externalites.\n\n## Project Structure\n\n```text\nScholar-MCP/\n├── .github/workflows/ # GitHub Actions (CI & Releases)\n├── scripts/           # Automation & Validation scripts\n├── tests/             # Pytest suite (respx mocked)\n├── server.py          # FastMCP tool entry point\n├── api.py             # API Clients (Scopus, OpenAlex, Unpaywall, CrossRef)\n├── extractor.py       # PDF/HTML Extraction & Rendering\n├── models.py          # Pydantic Data Validation\n├── server.json        # MCP Registry Manifest\n├── pyproject.toml     # Python packaging configuration\n├── requirements.txt   # Dependencies\n├── VERSION            # Version tracking (v1.0.0)\n├── LICENSE            # MIT License\n├── README.md          # Documentation\n├── .env.example       # Template for API keys\n└── .gitignore         # Git exclusion rules\n```\n\n## Troubleshooting\n\n| Symptom | Cause | Resolution |\n|---------|-------|------------|\n| `HTTP 401` from Scopus | Standard API keys lack `META_ABS` view access. | Set `SCOPUS_INST_TOKEN` or use OpenAlex as fallback. |\n| `HTTP 403` on PDF download | Publisher anti-bot protection (Cloudflare, DataDome). | Provide the PDF manually to the LLM. |\n| Empty Unpaywall results | Paper is behind a strict paywall with no OA copies. | Request the PDF from the author via ResearchGate or institutional access. |\n| `SCOPUS_API_KEY is not set` | Missing environment variable. | Ensure `.env` is configured or pass via MCP client `env` block. |\n\n## Contributing\n\n1. Fork the repository.\n2. Create a feature branch (`git checkout -b feature/my-feature`).\n3. Commit your changes (`git commit -m 'feat: add new capability'`).\n4. Push to the branch (`git push origin feature/my-feature`).\n5. Open a Pull Request.\n\nPlease ensure all code follows PEP 8 conventions.\n\n## License\n\nMIT License. See [LICENSE](LICENSE) for details.\n\n---\n\n> **Disclaimer:** Automated querying of publisher APIs must comply with the respective Terms of Service of Elsevier, OpenAlex, and Unpaywall. Do not distribute API keys. Adhere to all applicable rate limits.\n\nmcp-name: io.github.mlintangmz2765/scholar",
  "bytes": 18215,
  "sha": "54c38ad29c5cc4f55ce9340713b3c6fc6ef7a6d9cfb383465b0ef359e2b87e3d",
  "repo_slug": "mlintangmz2765/scholar-mcp",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_mlintangmz2765_scholar_35151078/readme"
}