s2_mcp_server 1.0.0__py3-none-any.whl

s2_mcp_server-1.0.0.dist-info/METADATA

@@ -0,0 +1,476 @@
+Metadata-Version: 2.4
+Name: s2-mcp-server
+Version: 1.0.0
+Summary: MCP server for Semantic Scholar — 200M+ academic papers in Claude Desktop
+Project-URL: Homepage, https://topologica.ai
+Project-URL: Repository, https://github.com/smaniches/semantic-scholar-mcp
+Project-URL: Issues, https://github.com/smaniches/semantic-scholar-mcp/issues
+Project-URL: Changelog, https://github.com/smaniches/semantic-scholar-mcp/blob/main/CHANGELOG.md
+Project-URL: Semantic Scholar API, https://www.semanticscholar.org/product/api
+Author-email: Santiago Maniches <santiago@topologica.ai>
+Maintainer-email: TOPOLOGICA LLC <support@topologica.ai>
+License: MIT
+License-File: LICENSE
+Keywords: academic-research,claude,llm,mcp,model-context-protocol,python,research-tools,semantic-scholar
+Classifier: Development Status :: 5 - Production/Stable
+Classifier: Intended Audience :: Developers
+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 :: Software Development :: Libraries :: Python Modules
+Requires-Python: >=3.10
+Requires-Dist: httpx>=0.25.0
+Requires-Dist: mcp<2,>=1.25.0
+Requires-Dist: pydantic>=2.0.0
+Provides-Extra: dev
+Requires-Dist: hypothesis>=6.0.0; extra == 'dev'
+Requires-Dist: mypy>=1.0.0; extra == 'dev'
+Requires-Dist: pre-commit>=3.0.0; extra == 'dev'
+Requires-Dist: pytest-asyncio>=0.21.0; extra == 'dev'
+Requires-Dist: pytest-cov>=4.0.0; extra == 'dev'
+Requires-Dist: pytest>=7.0.0; extra == 'dev'
+Requires-Dist: respx>=0.20.0; extra == 'dev'
+Requires-Dist: ruff>=0.1.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# Semantic Scholar MCP Server
+
+[![CI](https://github.com/smaniches/semantic-scholar-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/smaniches/semantic-scholar-mcp/actions/workflows/ci.yml)
+[![codecov](https://codecov.io/gh/smaniches/semantic-scholar-mcp/graph/badge.svg)](https://codecov.io/gh/smaniches/semantic-scholar-mcp)
+[![PyPI version](https://img.shields.io/pypi/v/s2-mcp-server)](https://pypi.org/project/s2-mcp-server/)
+[![GitHub Release](https://img.shields.io/github/v/release/smaniches/semantic-scholar-mcp)](https://github.com/smaniches/semantic-scholar-mcp/releases)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+[![MCP](https://img.shields.io/badge/MCP-Compatible-blue)](https://modelcontextprotocol.io)
+[![Python 3.10+](https://img.shields.io/badge/python-3.10+-blue.svg)](https://www.python.org/downloads/)
+
+**The most comprehensive MCP server for academic research.** Direct access to 200M+ papers from [Semantic Scholar](https://www.semanticscholar.org/) within Claude Desktop.
+
+---
+
+## Installation
+
+### Option 1: One-Line Install (Recommended)
+```bash
+# No cloning needed — runs directly from PyPI
+uvx s2-mcp-server
+```
+
+### Option 2: Claude Code
+```bash
+claude mcp add semantic-scholar -- uvx s2-mcp-server
+```
+
+### Option 3: Claude Desktop (Windows)
+
+Add to `%APPDATA%\Claude\claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "semantic-scholar": {
+      "command": "uvx",
+      "args": ["s2-mcp-server"],
+      "env": {
+        "SEMANTIC_SCHOLAR_API_KEY": "your-key-here"
+      }
+    }
+  }
+}
+```
+
+### Option 4: Claude Desktop (macOS)
+
+Add to `~/Library/Application Support/Claude/claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "semantic-scholar": {
+      "command": "uvx",
+      "args": ["s2-mcp-server"],
+      "env": {
+        "SEMANTIC_SCHOLAR_API_KEY": "your-key-here"
+      }
+    }
+  }
+}
+```
+
+### Option 5: pip / From Source
+```bash
+pip install s2-mcp-server
+# or
+git clone https://github.com/smaniches/semantic-scholar-mcp.git
+cd semantic-scholar-mcp && pip install -e .
+```
+
+> **Note:** Get a free API key at [semanticscholar.org/product/api](https://www.semanticscholar.org/product/api). Without a key, you get rate-limited public access (1 req/sec).
+
+---
+
+## Configuration
+
+### API Key Options
+
+You can provide your API key in two ways:
+
+1. **Environment Variable** (recommended for persistent use):
+   ```bash
+   export SEMANTIC_SCHOLAR_API_KEY="your-api-key-here"
+   ```
+
+2. **Per-Request Parameter** (overrides env var):
+   ```json
+   {
+     "api_key": "your-api-key-here"
+   }
+   ```
+
+Get a free API key at: https://www.semanticscholar.org/product/api
+
+### Claude Desktop Setup
+
+Add to your Claude Desktop config file:
+
+**Windows:** `%APPDATA%\Claude\claude_desktop_config.json`
+**macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`
+**Linux:** `~/.config/Claude/claude_desktop_config.json`
+
+```json
+{
+  "mcpServers": {
+    "semantic-scholar": {
+      "command": "python",
+      "args": ["-m", "semantic_scholar_mcp"],
+      "env": {
+        "SEMANTIC_SCHOLAR_API_KEY": "your-api-key-here"
+      }
+    }
+  }
+}
+```
+
+Then **restart Claude Desktop**.
+
+---
+
+## Supported ID Formats
+
+The server accepts the following paper identifier formats:
+
+| Format | Pattern | Example |
+|--------|---------|---------|
+| Semantic Scholar ID | 40-character hex | `649def34f8be52c8b66281af98ae884c09aef38b` |
+| DOI | `DOI:xxx` | `DOI:10.1038/s41586-021-03819-2` |
+| ArXiv | `ARXIV:xxx` | `ARXIV:2106.15928` or `ARXIV:2106.15928v2` |
+| PubMed | `PMID:xxx` | `PMID:32908142` |
+| Corpus ID | `CorpusId:xxx` | `CorpusId:215416146` |
+| ACL | `ACL:xxx` | `ACL:P19-1285` |
+| URL | `URL:xxx` | `URL:https://arxiv.org/abs/2106.15928` |
+
+---
+
+## Tools Reference
+
+### 1. `semantic_scholar_search_papers`
+
+Search for academic papers with advanced filters.
+
+**Parameters:**
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `query` | string | Yes | Search query (supports AND, OR, NOT operators and "phrase search") |
+| `year` | string | No | Year filter: `"2024"`, `"2020-2024"`, or `"2020-"` |
+| `fields_of_study` | string[] | No | Filter by fields: `["Computer Science", "Biology"]` |
+| `publication_types` | string[] | No | Filter by type: `["Review", "JournalArticle"]` |
+| `open_access_only` | boolean | No | Only return open access papers (default: false) |
+| `min_citation_count` | integer | No | Minimum citation count |
+| `limit` | integer | No | Max results 1-100 (default: 10) |
+| `offset` | integer | No | Pagination offset (default: 0) |
+| `response_format` | string | No | `"markdown"` or `"json"` (default: markdown) |
+| `api_key` | string | No | Override environment API key |
+
+**Example:**
+```
+Search for "transformer attention mechanism" papers from 2023 with at least 100 citations
+```
+
+**JSON Example:**
+```json
+{
+  "query": "transformer attention mechanism",
+  "year": "2023",
+  "min_citation_count": 100,
+  "fields_of_study": ["Computer Science"],
+  "limit": 20
+}
+```
+
+---
+
+### 2. `semantic_scholar_get_paper`
+
+Get detailed information about a specific paper.
+
+**Parameters:**
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `paper_id` | string | Yes | Paper ID in any supported format |
+| `include_citations` | boolean | No | Include citing papers (default: false) |
+| `include_references` | boolean | No | Include referenced papers (default: false) |
+| `citations_limit` | integer | No | Max citations to return 1-100 (default: 10) |
+| `references_limit` | integer | No | Max references to return 1-100 (default: 10) |
+| `response_format` | string | No | `"markdown"` or `"json"` (default: markdown) |
+| `api_key` | string | No | Override environment API key |
+
+**Example:**
+```
+Get details for DOI:10.1038/s41586-021-03819-2 including its top 20 citations
+```
+
+**JSON Example:**
+```json
+{
+  "paper_id": "DOI:10.1038/s41586-021-03819-2",
+  "include_citations": true,
+  "citations_limit": 20
+}
+```
+
+---
+
+### 3. `semantic_scholar_search_authors`
+
+Search for academic authors by name.
+
+**Parameters:**
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `query` | string | Yes | Author name to search |
+| `limit` | integer | No | Max results 1-100 (default: 10) |
+| `offset` | integer | No | Pagination offset (default: 0) |
+| `response_format` | string | No | `"markdown"` or `"json"` (default: markdown) |
+| `api_key` | string | No | Override environment API key |
+
+**Example:**
+```
+Find author "Yoshua Bengio"
+```
+
+**JSON Example:**
+```json
+{
+  "query": "Yoshua Bengio",
+  "limit": 5
+}
+```
+
+---
+
+### 4. `semantic_scholar_get_author`
+
+Get author profile with publications.
+
+**Parameters:**
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `author_id` | string | Yes | Semantic Scholar author ID |
+| `include_papers` | boolean | No | Include publications (default: true) |
+| `papers_limit` | integer | No | Max papers to return 1-100 (default: 20) |
+| `response_format` | string | No | `"markdown"` or `"json"` (default: markdown) |
+| `api_key` | string | No | Override environment API key |
+
+**Example:**
+```
+Get author profile for author ID 1741101 with their top 50 publications
+```
+
+**JSON Example:**
+```json
+{
+  "author_id": "1741101",
+  "include_papers": true,
+  "papers_limit": 50
+}
+```
+
+---
+
+### 5. `semantic_scholar_recommendations`
+
+Get AI-powered paper recommendations based on a seed paper.
+
+**Parameters:**
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `paper_id` | string | Yes | Seed paper ID in any supported format |
+| `limit` | integer | No | Max recommendations 1-100 (default: 10) |
+| `response_format` | string | No | `"markdown"` or `"json"` (default: markdown) |
+| `api_key` | string | No | Override environment API key |
+
+**Example:**
+```
+Get recommendations based on paper 649def34f8be52c8b66281af98ae884c09aef38b
+```
+
+**JSON Example:**
+```json
+{
+  "paper_id": "ARXIV:1706.03762",
+  "limit": 15
+}
+```
+
+---
+
+### 6. `semantic_scholar_bulk_papers`
+
+Retrieve multiple papers in a single request (max 500).
+
+**Parameters:**
+| Parameter | Type | Required | Description |
+|-----------|------|----------|-------------|
+| `paper_ids` | string[] | Yes | List of paper IDs (max 500) |
+| `response_format` | string | No | `"markdown"` or `"json"` (default: json) |
+| `api_key` | string | No | Override environment API key |
+
+**Example:**
+```
+Retrieve these papers: DOI:10.1038/nature12373, ARXIV:2106.15928, PMID:32908142
+```
+
+**JSON Example:**
+```json
+{
+  "paper_ids": [
+    "DOI:10.1038/nature12373",
+    "ARXIV:2106.15928",
+    "PMID:32908142"
+  ]
+}
+```
+
+---
+
+### 7. `semantic_scholar_status`
+
+Check server health and API connectivity status.
+
+**Parameters:** None
+
+**Example:**
+```
+Check Semantic Scholar API status
+```
+
+**Response:**
+```json
+{
+  "server": "semantic-scholar-mcp",
+  "version": "1.0.0",
+  "api_key_configured": true,
+  "timestamp": "2025-01-15T12:00:00.000000+00:00",
+  "api_reachable": true
+}
+```
+
+---
+
+## Rate Limits
+
+| Tier | Requests/Second | How to Get |
+|------|-----------------|------------|
+| No API Key | 1 req/sec | Default |
+| Free API Key | 1 req/sec | [Sign up](https://www.semanticscholar.org/product/api) |
+| Academic Partner | 10-100 req/sec | Apply via S2 |
+
+The server automatically handles rate limiting with:
+- Request serialization to enforce minimum intervals
+- Exponential backoff retry for 429 (rate limit) and 503 (service unavailable) errors
+- Maximum 3 retries with jitter
+
+---
+
+## Architecture
+
+```
++-----------------+     +----------------------+     +-----------------+
+|  Claude Desktop |---->|  semantic-scholar-mcp |---->| Semantic Scholar|
+|   (MCP Client)  |<----|     (This Server)     |<----+      API        |
++-----------------+     +----------------------+     +-----------------+
+        |                         |                          |
+        | stdio (JSON-RPC)        | Your API Key             | HTTPS
+        | Local process           | Local machine            | 200M+ papers
+```
+
+**Your API key never leaves your machine.** The MCP server runs locally.
+
+---
+
+## Development
+
+```bash
+# Clone
+git clone https://github.com/smaniches/semantic-scholar-mcp.git
+cd semantic-scholar-mcp
+
+# Install dev dependencies
+pip install -e ".[dev]"
+
+# Run tests
+pytest
+
+# Run tests with coverage
+pytest --cov=src/semantic_scholar_mcp --cov-report=term-missing
+
+# Type checking
+mypy src/
+```
+
+---
+
+## Security
+
+API keys are never stored in code — environment variables only. See [SECURITY.md](.github/SECURITY.md) for vulnerability reporting. All API communication uses HTTPS.
+
+---
+
+## License
+
+MIT License - see [LICENSE](LICENSE) file.
+
+---
+
+## Author
+
+**Santiago Maniches**
+- Founder & CEO, [TOPOLOGICA LLC](https://topologica.ai)
+- ORCID: [0009-0005-6480-1987](https://orcid.org/0009-0005-6480-1987)
+- LinkedIn: [santiago-maniches](https://www.linkedin.com/in/santiagomaniches/)
+- Website: [topologica.ai](https://topologica.ai)
+
+---
+
+## Contributing
+
+Contributions welcome! Please read our [Contributing Guidelines](CONTRIBUTING.md).
+
+---
+
+## Support
+
+- Issues: [GitHub Issues](https://github.com/smaniches/semantic-scholar-mcp/issues)
+- Discussions: [GitHub Discussions](https://github.com/smaniches/semantic-scholar-mcp/discussions)
+- Contact: santiago@topologica.ai
+
+---
+
+<p align="center">
+  <b>Built by <a href="https://topologica.ai">TOPOLOGICA LLC</a></b><br>
+  <i>Advancing computational research through topological intelligence</i>
+</p>

s2_mcp_server-1.0.0.dist-info/RECORD

@@ -0,0 +1,9 @@
+semantic_scholar_mcp/__init__.py,sha256=W636-5kdM-_hMbrCFuNZ_rQ2sMSdrJMSgr9VHT6lPHo,934
+semantic_scholar_mcp/__main__.py,sha256=yHBntxuwGpoqMvEcgOXQqyen-OP49YWv-4qHWFCJPcg,248
+semantic_scholar_mcp/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+semantic_scholar_mcp/server.py,sha256=wnHAVc8VrUaNKvuG0guzuvvj0b5fHW3x7A4t-nfCtB4,40074
+s2_mcp_server-1.0.0.dist-info/METADATA,sha256=Lb56t2tjrT0y-S2q4Et6pFaNgAa9_1NUgM-mTFCznX4,13492
+s2_mcp_server-1.0.0.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+s2_mcp_server-1.0.0.dist-info/entry_points.txt,sha256=PaJwx6ElHSAmTGqEoXmbxXhylm6uksnNCfv8WNwbd-s,67
+s2_mcp_server-1.0.0.dist-info/licenses/LICENSE,sha256=qVrrCPTVNbhUJ7eh5mUX2LKX3HhQ1MoyBUCTEG0vXC0,1208
+s2_mcp_server-1.0.0.dist-info/RECORD,,

s2_mcp_server-1.0.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.29.0
+Root-Is-Purelib: true
+Tag: py3-none-any

s2_mcp_server-1.0.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+semantic-scholar-mcp = semantic_scholar_mcp:main

s2_mcp_server-1.0.0.dist-info/licenses/LICENSE

@@ -0,0 +1,28 @@
+MIT License
+
+Copyright (c) 2025 TOPOLOGICA LLC
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
+---
+
+Author: Santiago Maniches
+Organization: TOPOLOGICA LLC
+Website: https://topologica.ai
+ORCID: https://orcid.org/0009-0005-6480-1987

semantic_scholar_mcp/__init__.py

@@ -0,0 +1,43 @@
+"""
+Semantic Scholar MCP Server
+===========================
+
+MCP (Model Context Protocol) server for accessing Semantic Scholar's
+academic paper database directly within Claude Desktop.
+
+Author: Santiago Maniches (ORCID: 0009-0005-6480-1987)
+Organization: TOPOLOGICA LLC (https://topologica.ai)
+License: MIT
+
+For documentation: https://github.com/smaniches/semantic-scholar-mcp
+"""
+
+from .server import (
+    AuthenticationError,
+    NotFoundError,
+    RateLimitError,
+    SemanticScholarError,
+    ServerError,
+    ValidationError,
+    __version__,
+    main,
+    mcp,
+)
+
+__author__ = "Santiago Maniches"
+__email__ = "santiago@topologica.ai"
+__org__ = "TOPOLOGICA LLC"
+__url__ = "https://topologica.ai"
+__orcid__ = "0009-0005-6480-1987"
+
+__all__ = [
+    "mcp",
+    "main",
+    "__version__",
+    "SemanticScholarError",
+    "AuthenticationError",
+    "RateLimitError",
+    "NotFoundError",
+    "ValidationError",
+    "ServerError",
+]

semantic_scholar_mcp/__main__.py

@@ -0,0 +1,11 @@
+"""
+Entry point for running as module: python -m semantic_scholar_mcp
+
+Author: Santiago Maniches (ORCID: 0009-0005-6480-1987)
+Organization: TOPOLOGICA LLC (https://topologica.ai)
+"""
+
+from .server import main
+
+if __name__ == "__main__":
+    main()