uniarticles-mcp 0.1.0__tar.gz

uniarticles_mcp-0.1.0/.env.example

@@ -0,0 +1,2 @@
+SCOPUS_API_KEY=your_scopus_api_key_here
+SEMANTIC_SCHOLAR_API_KEY=your_semantic_scholar_api_key_here

uniarticles_mcp-0.1.0/PKG-INFO

@@ -0,0 +1,181 @@
+Metadata-Version: 2.4
+Name: uniarticles-mcp
+Version: 0.1.0
+Summary: Unified MCP server for multi-source academic literature retrieval
+Project-URL: Homepage, https://github.com/yourusername/uniarticles-mcp
+Project-URL: Repository, https://github.com/yourusername/uniarticles-mcp
+Project-URL: Issues, https://github.com/yourusername/uniarticles-mcp/issues
+Author-email: Your Name <your.email@example.com>
+License: MIT
+Keywords: academic,arxiv,chemrxiv,mcp,research,scopus,semanticscholar
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Science/Research
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Topic :: Scientific/Engineering
+Requires-Python: >=3.10
+Requires-Dist: arxiv>=2.1.0
+Requires-Dist: httpx>=0.27.0
+Requires-Dist: mcp>=1.0.0
+Requires-Dist: python-dotenv>=1.0.0
+Requires-Dist: semanticscholar>=0.8.4
+Provides-Extra: dev
+Requires-Dist: pytest>=8.0.0; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# UniArticles MCP Server
+
+A unified Model Context Protocol (MCP) server for retrieving academic literature from multiple sources.
+
+## 🌟 Features
+
+- **Unified Interface**: Consistent return structure across all data sources.
+- **Multi-Source Support**:
+  - **Scopus**: Extensive abstract and citation database.
+  - **Semantic Scholar**: AI-driven research tool.
+  - **ArXiv**: Open access archive for scholarly articles.
+  - **ChemRxiv**: Open access preprint archive for chemistry.
+- **MCP Standard**: Built on the FastMCP framework for easy integration with Claude and other MCP clients.
+
+## 🚀 Installation
+
+### Prerequisites
+- Python 3.10 or higher
+- `uv` (recommended) or `pip`
+
+### Using uv (Recommended)
+
+```bash
+# Clone the repository
+git clone <repository-url>
+cd UniArticles_MCPserver
+
+# Install dependencies
+uv sync
+```
+
+### Using pip
+
+```bash
+pip install -e .
+```
+
+## ⚙️ Configuration
+
+Create a `.env` file in the project root or set environment variables:
+
+```env
+# Required for Scopus
+SCOPUS_API_KEY=your_scopus_api_key
+
+# Optional (Recommended for higher limits)
+SEMANTICSCHOLAR_API_KEY=your_semanticscholar_api_key
+```
+
+### ⚠️ Important Notes
+- **API Key Handling**: If you do not have an API key for a service (e.g., Semantic Scholar), **you must delete the corresponding line** from the configuration. Do not leave it as `your_key_here`, otherwise the service will try to authenticate with that invalid string and fail (e.g., returning 403 Forbidden).
+- **Scopus**: If `SCOPUS_API_KEY` is missing, Scopus search will return errors, but other tools will work.
+- **Semantic Scholar**: If `SEMANTICSCHOLAR_API_KEY` is missing (i.e., the line is deleted), the service will automatically fallback to the public API (lower rate limits but functional).
+
+## 🏃 Usage
+
+### Running Locally
+
+```bash
+# Using uv
+uv run uniarticles-mcp
+
+# Using python directly
+python -m uniarticles
+```
+
+### With Claude Desktop
+
+#### Option 1: Via PyPI (Recommended if published)
+If you have published the package to PyPI (or are installing from a git URL), use `uvx`:
+
+> **Note**: In the example below, `SEMANTICSCHOLAR_API_KEY` is omitted. Remove it if you don't have a key.
+
+```json
+{
+  "mcpServers": {
+    "uniarticles": {
+      "command": "uvx",
+      "args": [
+        "uniarticles-mcp"
+      ],
+      "env": {
+        "SCOPUS_API_KEY": "your_scopus_key_here"
+      }
+    }
+  }
+}
+```
+
+#### Option 2: Full Configuration (With all keys)
+```json
+{
+  "mcpServers": {
+    "uniarticles": {
+      "command": "uvx",
+      "args": [
+        "uniarticles-mcp"
+      ],
+      "env": {
+        "SCOPUS_API_KEY": "your_scopus_key_here",
+        "SEMANTICSCHOLAR_API_KEY": "your_semanticscholar_key_here"
+      }
+    }
+  }
+}
+```
+
+#### Option 3: Local Development
+If you are running from source code locally:
+
+```json
+{
+  "mcpServers": {
+    "uniarticles": {
+      "command": "uv",
+      "args": [
+        "--directory",
+        "C:/absolute/path/to/UniArticles_MCPserver/UniArticles_MCPserver",
+        "run",
+        "uniarticles-mcp"
+      ],
+      "env": {
+        "SCOPUS_API_KEY": "your_scopus_key_here",
+        "SEMANTICSCHOLAR_API_KEY": "your_semanticscholar_key_here"
+      }
+    }
+  }
+}
+```
+
+## 🛠️ Development
+
+### Running Tests
+
+```bash
+# Run integration tests
+python -m unittest tests/test_integration.py
+```
+
+### Project Structure
+
+```text
+src/uniarticles/
+├── sources/           # Individual data source modules
+│   ├── arxiv.py
+│   ├── scopus.py
+│   ├── ...
+├── server.py          # Main server entry point
+└── config.py          # Configuration management
+```
+
+## 📄 License
+
+[MIT License](LICENSE)

uniarticles_mcp-0.1.0/README.md

@@ -0,0 +1,154 @@
+# UniArticles MCP Server
+
+A unified Model Context Protocol (MCP) server for retrieving academic literature from multiple sources.
+
+## 🌟 Features
+
+- **Unified Interface**: Consistent return structure across all data sources.
+- **Multi-Source Support**:
+  - **Scopus**: Extensive abstract and citation database.
+  - **Semantic Scholar**: AI-driven research tool.
+  - **ArXiv**: Open access archive for scholarly articles.
+  - **ChemRxiv**: Open access preprint archive for chemistry.
+- **MCP Standard**: Built on the FastMCP framework for easy integration with Claude and other MCP clients.
+
+## 🚀 Installation
+
+### Prerequisites
+- Python 3.10 or higher
+- `uv` (recommended) or `pip`
+
+### Using uv (Recommended)
+
+```bash
+# Clone the repository
+git clone <repository-url>
+cd UniArticles_MCPserver
+
+# Install dependencies
+uv sync
+```
+
+### Using pip
+
+```bash
+pip install -e .
+```
+
+## ⚙️ Configuration
+
+Create a `.env` file in the project root or set environment variables:
+
+```env
+# Required for Scopus
+SCOPUS_API_KEY=your_scopus_api_key
+
+# Optional (Recommended for higher limits)
+SEMANTICSCHOLAR_API_KEY=your_semanticscholar_api_key
+```
+
+### ⚠️ Important Notes
+- **API Key Handling**: If you do not have an API key for a service (e.g., Semantic Scholar), **you must delete the corresponding line** from the configuration. Do not leave it as `your_key_here`, otherwise the service will try to authenticate with that invalid string and fail (e.g., returning 403 Forbidden).
+- **Scopus**: If `SCOPUS_API_KEY` is missing, Scopus search will return errors, but other tools will work.
+- **Semantic Scholar**: If `SEMANTICSCHOLAR_API_KEY` is missing (i.e., the line is deleted), the service will automatically fallback to the public API (lower rate limits but functional).
+
+## 🏃 Usage
+
+### Running Locally
+
+```bash
+# Using uv
+uv run uniarticles-mcp
+
+# Using python directly
+python -m uniarticles
+```
+
+### With Claude Desktop
+
+#### Option 1: Via PyPI (Recommended if published)
+If you have published the package to PyPI (or are installing from a git URL), use `uvx`:
+
+> **Note**: In the example below, `SEMANTICSCHOLAR_API_KEY` is omitted. Remove it if you don't have a key.
+
+```json
+{
+  "mcpServers": {
+    "uniarticles": {
+      "command": "uvx",
+      "args": [
+        "uniarticles-mcp"
+      ],
+      "env": {
+        "SCOPUS_API_KEY": "your_scopus_key_here"
+      }
+    }
+  }
+}
+```
+
+#### Option 2: Full Configuration (With all keys)
+```json
+{
+  "mcpServers": {
+    "uniarticles": {
+      "command": "uvx",
+      "args": [
+        "uniarticles-mcp"
+      ],
+      "env": {
+        "SCOPUS_API_KEY": "your_scopus_key_here",
+        "SEMANTICSCHOLAR_API_KEY": "your_semanticscholar_key_here"
+      }
+    }
+  }
+}
+```
+
+#### Option 3: Local Development
+If you are running from source code locally:
+
+```json
+{
+  "mcpServers": {
+    "uniarticles": {
+      "command": "uv",
+      "args": [
+        "--directory",
+        "C:/absolute/path/to/UniArticles_MCPserver/UniArticles_MCPserver",
+        "run",
+        "uniarticles-mcp"
+      ],
+      "env": {
+        "SCOPUS_API_KEY": "your_scopus_key_here",
+        "SEMANTICSCHOLAR_API_KEY": "your_semanticscholar_key_here"
+      }
+    }
+  }
+}
+```
+
+## 🛠️ Development
+
+### Running Tests
+
+```bash
+# Run integration tests
+python -m unittest tests/test_integration.py
+```
+
+### Project Structure
+
+```text
+src/uniarticles/
+├── sources/           # Individual data source modules
+│   ├── arxiv.py
+│   ├── scopus.py
+│   ├── ...
+├── server.py          # Main server entry point
+└── config.py          # Configuration management
+```
+
+## 📄 License
+
+[MIT License](LICENSE)

uniarticles_mcp-0.1.0/claude_desktop_config.example.json

@@ -0,0 +1,13 @@
+{
+  "mcpServers": {
+    "uniarticles-mcp-server": {
+      "command": "uvx",
+      "args": [
+        "uniarticles-mcp"
+      ],
+      "env": {
+        "SCOPUS_API_KEY": "4d32cadb485f8b9854988ffc06770cbc"
+      }
+    }
+  }
+}

uniarticles_mcp-0.1.0/pyproject.toml

@@ -0,0 +1,47 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "uniarticles-mcp"
+version = "0.1.0"
+description = "Unified MCP server for multi-source academic literature retrieval"
+readme = "README.md"
+license = { text = "MIT" }
+authors = [
+    { name = "Your Name", email = "your.email@example.com" }
+]
+keywords = ["mcp", "academic", "research", "scopus", "arxiv", "semanticscholar", "chemrxiv"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Science/Research",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3.10",
+    "Programming Language :: Python :: 3.11",
+    "Programming Language :: Python :: 3.12",
+    "Topic :: Scientific/Engineering",
+]
+requires-python = ">=3.10"
+dependencies = [
+    "arxiv>=2.1.0",
+    "mcp>=1.0.0",
+    "httpx>=0.27.0",
+    "python-dotenv>=1.0.0",
+    "semanticscholar>=0.8.4",
+]
+
+[project.urls]
+Homepage = "https://github.com/yourusername/uniarticles-mcp"
+Repository = "https://github.com/yourusername/uniarticles-mcp"
+Issues = "https://github.com/yourusername/uniarticles-mcp/issues"
+
+[project.optional-dependencies]
+dev = [
+    "pytest>=8.0.0",
+]
+
+[project.scripts]
+uniarticles-mcp = "uniarticles.__main__:main"
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/uniarticles"]

uniarticles_mcp-0.1.0/src/uniarticles/__init__.py

@@ -0,0 +1,3 @@
+from .server import create_server
+
+__all__ = ["create_server"]

uniarticles_mcp-0.1.0/src/uniarticles/__main__.py

@@ -0,0 +1,10 @@
+from .server import create_server
+
+
+def main() -> None:
+    server = create_server()
+    server.run()
+
+
+if __name__ == "__main__":
+    main()

uniarticles_mcp-0.1.0/src/uniarticles/config.py

@@ -0,0 +1,16 @@
+import os
+from dataclasses import dataclass
+
+from dotenv import load_dotenv
+
+
+load_dotenv()
+
+
+@dataclass(frozen=True)
+class Settings:
+    scopus_api_key: str | None = os.getenv("SCOPUS_API_KEY")
+    semanticscholar_api_key: str | None = os.getenv("SEMANTICSCHOLAR_API_KEY")
+
+
+settings = Settings()

uniarticles_mcp-0.1.0/src/uniarticles/server.py

@@ -0,0 +1,9 @@
+from mcp.server.fastmcp import FastMCP
+
+from .sources import register_all_sources
+
+
+def create_server() -> FastMCP:
+    server = FastMCP("uniarticles-mcp")
+    register_all_sources(server)
+    return server

uniarticles_mcp-0.1.0/src/uniarticles/sources/__init__.py

@@ -0,0 +1,13 @@
+from mcp.server.fastmcp import FastMCP
+
+from .arxiv import register as register_arxiv_source
+from .chemrxiv import register as register_chemrxiv_source
+from .scopus import register as register_scopus_source
+from .semanticscholar import register as register_semanticscholar_source
+
+
+def register_all_sources(server: FastMCP) -> None:
+    register_arxiv_source(server)
+    register_chemrxiv_source(server)
+    register_semanticscholar_source(server)
+    register_scopus_source(server)

uniarticles_mcp-0.1.0/src/uniarticles/sources/arxiv.py

@@ -0,0 +1,62 @@
+import asyncio
+
+import arxiv
+from mcp.server.fastmcp import FastMCP
+
+
+def _ok(query: str, items: list[dict]) -> dict:
+    return {
+        "ok": True,
+        "source": "arxiv",
+        "query": query,
+        "count": len(items),
+        "items": items,
+        "error": None,
+    }
+
+
+def _err(query: str, message: str) -> dict:
+    return {
+        "ok": False,
+        "source": "arxiv",
+        "query": query,
+        "count": 0,
+        "items": [],
+        "error": message,
+    }
+
+
+def _run_arxiv_search(query: str, max_results: int) -> dict:
+    client = arxiv.Client()
+    search = arxiv.Search(
+        query=query,
+        max_results=max_results,
+        sort_by=arxiv.SortCriterion.SubmittedDate,
+    )
+    papers = []
+    for paper in client.results(search):
+        papers.append(
+            {
+                "id": paper.get_short_id(),
+                "title": paper.title,
+                "authors": [author.name for author in paper.authors],
+                "abstract": paper.summary,
+                "published": paper.published.isoformat(),
+                "categories": paper.categories,
+                "pdf_url": paper.pdf_url,
+            }
+        )
+    return _ok(query=query, items=papers)
+
+
+def register(server: FastMCP) -> None:
+    @server.tool()
+    async def search_arxiv(query: str, max_results: int = 10) -> dict:
+        normalized_query = query.strip()
+        bounded = max(1, min(max_results, 25))
+        if not normalized_query:
+            return _err(query=query, message="query must not be empty")
+        try:
+            return await asyncio.to_thread(_run_arxiv_search, normalized_query, bounded)
+        except Exception as exc:
+            return _err(query=normalized_query, message=str(exc))

uniarticles_mcp-0.1.0/src/uniarticles/sources/chemrxiv.py

@@ -0,0 +1,73 @@
+import httpx
+from mcp.server.fastmcp import FastMCP
+
+
+BASE_URL = "https://chemrxiv.org/engage/chemrxiv/public-api/v1"
+
+
+def _ok(term: str, items: list[dict]) -> dict:
+    return {
+        "ok": True,
+        "source": "chemrxiv",
+        "query": term,
+        "count": len(items),
+        "items": items,
+        "error": None,
+    }
+
+
+def _err(term: str, message: str) -> dict:
+    return {
+        "ok": False,
+        "source": "chemrxiv",
+        "query": term,
+        "count": 0,
+        "items": [],
+        "error": message,
+    }
+
+
+def _normalize_item(item: dict) -> dict:
+    return {
+        "itemId": item.get("itemId") or item.get("id"),
+        "doi": item.get("doi"),
+        "title": item.get("title"),
+        "abstract": item.get("abstract"),
+        "authors": item.get("authors"),
+        "publishedDate": item.get("publishedDate") or item.get("published"),
+        "url": item.get("url"),
+        "license": item.get("license"),
+    }
+
+
+async def _search_items(term: str, limit: int, page: int | None, sort: str | None) -> dict:
+    params = {"term": term, "limit": limit}
+    if page is not None:
+        params["page"] = page
+    if sort:
+        params["sort"] = sort
+    async with httpx.AsyncClient(timeout=20.0) as client:
+        response = await client.get(f"{BASE_URL}/items", params=params)
+        response.raise_for_status()
+        payload = response.json()
+    items = payload.get("items") or payload.get("results") or []
+    normalized = [_normalize_item(item) for item in items]
+    return _ok(term=term, items=normalized)
+
+
+def register(server: FastMCP) -> None:
+    @server.tool()
+    async def search_chemrxiv(
+        term: str,
+        limit: int = 10,
+        page: int | None = None,
+        sort: str | None = None,
+    ) -> dict:
+        normalized_term = term.strip()
+        bounded = max(1, min(limit, 50))
+        if not normalized_term:
+            return _err(term=term, message="term must not be empty")
+        try:
+            return await _search_items(term=normalized_term, limit=bounded, page=page, sort=sort)
+        except Exception as exc:
+            return _err(term=normalized_term, message=str(exc))

uniarticles_mcp-0.1.0/src/uniarticles/sources/scopus.py

@@ -0,0 +1,77 @@
+import httpx
+from mcp.server.fastmcp import FastMCP
+
+from ..config import settings
+
+
+BASE_URL = "https://api.elsevier.com/"
+
+
+def _ok(query: str, items: list[dict]) -> dict:
+    return {
+        "ok": True,
+        "source": "scopus",
+        "query": query,
+        "count": len(items),
+        "items": items,
+        "error": None,
+    }
+
+
+def _err(query: str, message: str) -> dict:
+    return {
+        "ok": False,
+        "source": "scopus",
+        "query": query,
+        "count": 0,
+        "items": [],
+        "error": message,
+    }
+
+
+async def _search_scopus(query: str, count: int, sort: str) -> dict:
+    api_key = settings.scopus_api_key
+    if not api_key:
+        raise ValueError("SCOPUS_API_KEY is required")
+    headers = {
+        "X-ELS-APIKey": api_key,
+        "Accept": "application/json",
+        "User-Agent": "UniArticlesMCP/0.1.0",
+    }
+    params = {
+        "query": query,
+        "count": count,
+        "sort": sort,
+        "view": "STANDARD",
+    }
+    async with httpx.AsyncClient(timeout=30.0, headers=headers) as client:
+        response = await client.get(f"{BASE_URL}content/search/scopus", params=params)
+        response.raise_for_status()
+        payload = response.json()
+    entries = payload.get("search-results", {}).get("entry", [])
+    normalized = []
+    for entry in entries:
+        normalized.append(
+            {
+                "title": entry.get("dc:title"),
+                "eid": entry.get("eid"),
+                "doi": entry.get("prism:doi"),
+                "coverDate": entry.get("prism:coverDate"),
+                "publicationName": entry.get("prism:publicationName"),
+                "creator": entry.get("dc:creator"),
+            }
+        )
+    return _ok(query=query, items=normalized)
+
+
+def register(server: FastMCP) -> None:
+    @server.tool()
+    async def search_scopus(query: str, count: int = 5, sort: str = "coverDate") -> dict:
+        normalized_query = query.strip()
+        bounded = max(1, min(count, 25))
+        if not normalized_query:
+            return _err(query=query, message="query must not be empty")
+        try:
+            return await _search_scopus(query=normalized_query, count=bounded, sort=sort)
+        except Exception as exc:
+            return _err(query=normalized_query, message=str(exc))