academia-mcp 1.9.0__tar.gz → 1.9.2__tar.gz

academia_mcp-1.9.2/PKG-INFO

@@ -0,0 +1,170 @@
+Metadata-Version: 2.4
+Name: academia-mcp
+Version: 1.9.2
+Summary: MCP server that provides different tools to search for scientific publications
+Author-email: Ilya Gusev <phoenixilya@gmail.com>
+Project-URL: Homepage, https://github.com/IlyaGusev/academia_mcp
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: mcp>=1.10.1
+Requires-Dist: xmltodict>=0.14.0
+Requires-Dist: types-xmltodict>=0.14.0
+Requires-Dist: requests>=2.32.0
+Requires-Dist: types-requests>=2.32.0
+Requires-Dist: pypdf>=5.1.0
+Requires-Dist: beautifulsoup4>=4.12.0
+Requires-Dist: types-beautifulsoup4>=4.12.0
+Requires-Dist: markdownify==0.14.1
+Requires-Dist: acl-anthology==0.5.2
+Requires-Dist: markdown==3.7.0
+Requires-Dist: types-markdown==3.7.0.20250322
+Requires-Dist: huggingface-hub>=0.32.4
+Requires-Dist: fire>=0.7.0
+Requires-Dist: openai>=1.97.1
+Requires-Dist: jinja2>=3.1.6
+Requires-Dist: datasets>=4.0.0
+Requires-Dist: pymupdf>=1.26.4
+Requires-Dist: pillow>=11.3.0
+Requires-Dist: pydantic-settings>=2.6.0
+Dynamic: license-file
+
+# Academia MCP
+
+[![PyPI](https://img.shields.io/pypi/v/academia-mcp?label=PyPI%20package)](https://pypi.org/project/academia-mcp/)
+[![CI](https://github.com/IlyaGusev/academia_mcp/actions/workflows/python.yml/badge.svg)](https://github.com/IlyaGusev/academia_mcp/actions/workflows/python.yml)
+[![License](https://img.shields.io/github/license/IlyaGusev/academia_mcp)](LICENSE)
+[![smithery badge](https://smithery.ai/badge/@IlyaGusev/academia_mcp)](https://smithery.ai/server/@IlyaGusev/academia_mcp)
+[![Verified on MseeP](https://mseep.ai/badge.svg)](https://mseep.ai/app/e818878b-c3a6-4b3d-a5b4-e54dcd1f1fed)
+
+MCP server with tools to search, fetch, analyze, and report on scientific papers and datasets.
+
+### Features
+- ArXiv search and download
+- ACL Anthology search
+- Hugging Face datasets search
+- Semantic Scholar citations and references
+- Web search via Exa, Brave, or Tavily
+- Web page crawler, LaTeX compilation, PDF reading
+- Optional LLM-powered tools for document QA and research proposal workflows
+
+### Requirements
+- Python 3.12+
+
+### Install
+- Using pip (end users):
+```bash
+pip3 install academia-mcp
+```
+
+- For development (uv + Makefile):
+```bash
+uv venv .venv
+make install
+```
+
+### Quickstart
+- Run over HTTP (default transport):
+```bash
+uv run -m academia_mcp --transport streamable-http
+```
+
+- Run over stdio (for local MCP clients like Claude Desktop):
+```bash
+python -m academia_mcp --transport stdio
+```
+
+Notes:
+- Transports: `stdio`, `sse`, `streamable-http`.
+- `host`/`port` are used for HTTP transports; ignored for `stdio`. Default port is `5056` (or `PORT`).
+
+### Claude Desktop config
+```json
+{
+  "mcpServers": {
+    "academia": {
+      "command": "python3",
+      "args": [
+        "-m",
+        "academia_mcp",
+        "--transport",
+        "stdio"
+      ]
+    }
+  }
+}
+```
+
+### Available tools (one-liners)
+- `arxiv_search`: Query arXiv with field-specific queries and filters.
+- `arxiv_download`: Fetch a paper by ID and convert to structured text (HTML/PDF modes).
+- `anthology_search`: Search ACL Anthology with fielded queries and optional date filtering.
+- `hf_datasets_search`: Find Hugging Face datasets with filters and sorting.
+- `s2_get_citations`: List papers citing a given arXiv paper (Semantic Scholar Graph).
+- `s2_get_references`: List papers referenced by a given arXiv paper.
+- `visit_webpage`: Fetch and normalize a web page.
+- `web_search`: Unified search wrapper; available when at least one of Exa/Brave/Tavily keys is set.
+- `exa_web_search`, `brave_web_search`, `tavily_web_search`: Provider-specific search.
+- `get_latex_templates_list`, `get_latex_template`: Enumerate and fetch built-in LaTeX templates.
+- `compile_latex`: Compile LaTeX to PDF in `WORKSPACE_DIR`.
+- `read_pdf`: Extract text per page from a PDF.
+- `download_pdf_paper`, `review_pdf_paper`: Download and optionally review PDFs (requires LLM + workspace).
+- `document_qa`: Answer questions over provided document chunks (requires LLM).
+- `extract_bitflip_info`, `generate_research_proposals`, `score_research_proposals`: Research proposal helpers (requires LLM).
+
+Availability notes:
+- Set `WORKSPACE_DIR` to enable `compile_latex`, `read_pdf`, `download_pdf_paper`, and `review_pdf_paper`.
+- Set `OPENROUTER_API_KEY` to enable LLM tools (`document_qa`, `review_pdf_paper`, and bitflip tools).
+- Set one or more of `EXA_API_KEY`, `BRAVE_API_KEY`, `TAVILY_API_KEY` to enable `web_search` and provider tools.
+
+### Environment variables
+Set as needed depending on which tools you use:
+
+- `OPENROUTER_API_KEY`: required for LLM-related tools.
+- `BASE_URL`: override OpenRouter base URL.
+- `DOCUMENT_QA_MODEL_NAME`: override default model for `document_qa`.
+- `BITFLIP_MODEL_NAME`: override default model for bitflip tools.
+- `TAVILY_API_KEY`: enables Tavily in `web_search`.
+- `EXA_API_KEY`: enables Exa in `web_search` and `visit_webpage`.
+- `BRAVE_API_KEY`: enables Brave in `web_search`.
+- `WORKSPACE_DIR`: directory for generated files (PDFs, temp artifacts).
+- `PORT`: HTTP port (default `5056`).
+
+You can put these in a `.env` file in the project root.
+
+### Docker
+Build the image:
+```bash
+docker build -t academia_mcp .
+```
+
+Run the server (HTTP):
+```bash
+docker run --rm -p 5056:5056 \
+  -e PORT=5056 \
+  -e OPENROUTER_API_KEY=your_key_here \
+  -e WORKSPACE_DIR=/workspace \
+  -v "$PWD/workdir:/workspace" \
+  academia_mcp
+```
+
+Or use existing image: `phoenix120/academia_mcp`
+
+### Examples
+- [Comprehensive report screencast (YouTube)](https://www.youtube.com/watch?v=4bweqQcN6w8)
+- [Single paper screencast (YouTube)](https://www.youtube.com/watch?v=IAAPMptJ5k8)
+
+### Makefile targets
+- `make install`: install the package in editable mode with uv
+- `make validate`: run black, flake8, and mypy (strict)
+- `make test`: run the test suite with pytest
+- `make publish`: build and publish using uv
+
+### LaTeX/PDF requirements
+Only needed for LaTeX/PDF tools. Ensure a LaTeX distribution is installed and `pdflatex` is on PATH, as well as `latexmk`. On Debian/Ubuntu:
+```bash
+sudo apt install texlive-latex-base texlive-fonts-recommended texlive-latex-extra texlive-science latexmk
+```

academia_mcp-1.9.2/README.md

@@ -0,0 +1,136 @@
+# Academia MCP
+
+[![PyPI](https://img.shields.io/pypi/v/academia-mcp?label=PyPI%20package)](https://pypi.org/project/academia-mcp/)
+[![CI](https://github.com/IlyaGusev/academia_mcp/actions/workflows/python.yml/badge.svg)](https://github.com/IlyaGusev/academia_mcp/actions/workflows/python.yml)
+[![License](https://img.shields.io/github/license/IlyaGusev/academia_mcp)](LICENSE)
+[![smithery badge](https://smithery.ai/badge/@IlyaGusev/academia_mcp)](https://smithery.ai/server/@IlyaGusev/academia_mcp)
+[![Verified on MseeP](https://mseep.ai/badge.svg)](https://mseep.ai/app/e818878b-c3a6-4b3d-a5b4-e54dcd1f1fed)
+
+MCP server with tools to search, fetch, analyze, and report on scientific papers and datasets.
+
+### Features
+- ArXiv search and download
+- ACL Anthology search
+- Hugging Face datasets search
+- Semantic Scholar citations and references
+- Web search via Exa, Brave, or Tavily
+- Web page crawler, LaTeX compilation, PDF reading
+- Optional LLM-powered tools for document QA and research proposal workflows
+
+### Requirements
+- Python 3.12+
+
+### Install
+- Using pip (end users):
+```bash
+pip3 install academia-mcp
+```
+
+- For development (uv + Makefile):
+```bash
+uv venv .venv
+make install
+```
+
+### Quickstart
+- Run over HTTP (default transport):
+```bash
+uv run -m academia_mcp --transport streamable-http
+```
+
+- Run over stdio (for local MCP clients like Claude Desktop):
+```bash
+python -m academia_mcp --transport stdio
+```
+
+Notes:
+- Transports: `stdio`, `sse`, `streamable-http`.
+- `host`/`port` are used for HTTP transports; ignored for `stdio`. Default port is `5056` (or `PORT`).
+
+### Claude Desktop config
+```json
+{
+  "mcpServers": {
+    "academia": {
+      "command": "python3",
+      "args": [
+        "-m",
+        "academia_mcp",
+        "--transport",
+        "stdio"
+      ]
+    }
+  }
+}
+```
+
+### Available tools (one-liners)
+- `arxiv_search`: Query arXiv with field-specific queries and filters.
+- `arxiv_download`: Fetch a paper by ID and convert to structured text (HTML/PDF modes).
+- `anthology_search`: Search ACL Anthology with fielded queries and optional date filtering.
+- `hf_datasets_search`: Find Hugging Face datasets with filters and sorting.
+- `s2_get_citations`: List papers citing a given arXiv paper (Semantic Scholar Graph).
+- `s2_get_references`: List papers referenced by a given arXiv paper.
+- `visit_webpage`: Fetch and normalize a web page.
+- `web_search`: Unified search wrapper; available when at least one of Exa/Brave/Tavily keys is set.
+- `exa_web_search`, `brave_web_search`, `tavily_web_search`: Provider-specific search.
+- `get_latex_templates_list`, `get_latex_template`: Enumerate and fetch built-in LaTeX templates.
+- `compile_latex`: Compile LaTeX to PDF in `WORKSPACE_DIR`.
+- `read_pdf`: Extract text per page from a PDF.
+- `download_pdf_paper`, `review_pdf_paper`: Download and optionally review PDFs (requires LLM + workspace).
+- `document_qa`: Answer questions over provided document chunks (requires LLM).
+- `extract_bitflip_info`, `generate_research_proposals`, `score_research_proposals`: Research proposal helpers (requires LLM).
+
+Availability notes:
+- Set `WORKSPACE_DIR` to enable `compile_latex`, `read_pdf`, `download_pdf_paper`, and `review_pdf_paper`.
+- Set `OPENROUTER_API_KEY` to enable LLM tools (`document_qa`, `review_pdf_paper`, and bitflip tools).
+- Set one or more of `EXA_API_KEY`, `BRAVE_API_KEY`, `TAVILY_API_KEY` to enable `web_search` and provider tools.
+
+### Environment variables
+Set as needed depending on which tools you use:
+
+- `OPENROUTER_API_KEY`: required for LLM-related tools.
+- `BASE_URL`: override OpenRouter base URL.
+- `DOCUMENT_QA_MODEL_NAME`: override default model for `document_qa`.
+- `BITFLIP_MODEL_NAME`: override default model for bitflip tools.
+- `TAVILY_API_KEY`: enables Tavily in `web_search`.
+- `EXA_API_KEY`: enables Exa in `web_search` and `visit_webpage`.
+- `BRAVE_API_KEY`: enables Brave in `web_search`.
+- `WORKSPACE_DIR`: directory for generated files (PDFs, temp artifacts).
+- `PORT`: HTTP port (default `5056`).
+
+You can put these in a `.env` file in the project root.
+
+### Docker
+Build the image:
+```bash
+docker build -t academia_mcp .
+```
+
+Run the server (HTTP):
+```bash
+docker run --rm -p 5056:5056 \
+  -e PORT=5056 \
+  -e OPENROUTER_API_KEY=your_key_here \
+  -e WORKSPACE_DIR=/workspace \
+  -v "$PWD/workdir:/workspace" \
+  academia_mcp
+```
+
+Or use existing image: `phoenix120/academia_mcp`
+
+### Examples
+- [Comprehensive report screencast (YouTube)](https://www.youtube.com/watch?v=4bweqQcN6w8)
+- [Single paper screencast (YouTube)](https://www.youtube.com/watch?v=IAAPMptJ5k8)
+
+### Makefile targets
+- `make install`: install the package in editable mode with uv
+- `make validate`: run black, flake8, and mypy (strict)
+- `make test`: run the test suite with pytest
+- `make publish`: build and publish using uv
+
+### LaTeX/PDF requirements
+Only needed for LaTeX/PDF tools. Ensure a LaTeX distribution is installed and `pdflatex` is on PATH, as well as `latexmk`. On Debian/Ubuntu:
+```bash
+sudo apt install texlive-latex-base texlive-fonts-recommended texlive-latex-extra texlive-science latexmk
+```

{academia_mcp-1.9.0 → academia_mcp-1.9.2}/academia_mcp/server.py

@@ -10,7 +10,12 @@ from uvicorn.config import LOGGING_CONFIG as UVICORN_LOGGING_CONFIG
 from academia_mcp.settings import settings
 from academia_mcp.tools.arxiv_search import arxiv_search
 from academia_mcp.tools.arxiv_download import arxiv_download
-from academia_mcp.tools.s2_citations import s2_get_citations, s2_get_references
+from academia_mcp.tools.s2 import (
+    s2_get_citations,
+    s2_get_references,
+    s2_corpus_id_from_arxiv_id,
+    s2_get_info,
+)
 from academia_mcp.tools.hf_datasets_search import hf_datasets_search
 from academia_mcp.tools.anthology_search import anthology_search
 from academia_mcp.tools.document_qa import document_qa
@@ -33,6 +38,7 @@ from academia_mcp.tools.bitflip import (
     score_research_proposals,
 )
 from academia_mcp.tools.review import review_pdf_paper, download_pdf_paper
+from academia_mcp.tools.show_image import show_image
 
 
 def configure_uvicorn_style_logging(level: int = logging.INFO) -> None:
@@ -75,11 +81,14 @@ def run(
     server.add_tool(arxiv_download)
     server.add_tool(s2_get_citations)
     server.add_tool(s2_get_references)
+    server.add_tool(s2_corpus_id_from_arxiv_id)
+    server.add_tool(s2_get_info)
     server.add_tool(hf_datasets_search)
     server.add_tool(anthology_search)
     server.add_tool(get_latex_template)
     server.add_tool(get_latex_templates_list)
     server.add_tool(visit_webpage)
+    server.add_tool(show_image)
 
     if settings.WORKSPACE_DIR:
         server.add_tool(compile_latex)

{academia_mcp-1.9.0 → academia_mcp-1.9.2}/academia_mcp/tools/__init__.py

@@ -2,7 +2,7 @@ from .arxiv_search import arxiv_search
 from .anthology_search import anthology_search
 from .arxiv_download import arxiv_download
 from .hf_datasets_search import hf_datasets_search
-from .s2_citations import s2_get_references, s2_get_citations
+from .s2 import s2_get_references, s2_get_citations, s2_corpus_id_from_arxiv_id, s2_get_info
 from .document_qa import document_qa
 from .latex import (
     compile_latex,
@@ -14,6 +14,7 @@ from .web_search import web_search, tavily_web_search, exa_web_search, brave_web
 from .visit_webpage import visit_webpage
 from .bitflip import extract_bitflip_info, generate_research_proposals, score_research_proposals
 from .review import review_pdf_paper, download_pdf_paper, review_pdf_paper_by_url
+from .show_image import show_image
 
 __all__ = [
     "arxiv_search",
@@ -21,6 +22,8 @@ __all__ = [
     "anthology_search",
     "s2_get_references",
     "s2_get_citations",
+    "s2_corpus_id_from_arxiv_id",
+    "s2_get_info",
     "hf_datasets_search",
     "document_qa",
     "compile_latex",
@@ -38,4 +41,5 @@ __all__ = [
     "review_pdf_paper_by_url",
     "download_pdf_paper",
     "read_pdf",
+    "show_image",
 ]

academia_mcp-1.9.0/academia_mcp/tools/s2_citations.py → academia_mcp-1.9.2/academia_mcp/tools/s2.py

@@ -126,3 +126,38 @@ def s2_get_references(
     entries = result["data"]
     total_count = len(result["data"]) + result["offset"]
     return _format_entries(entries, offset if offset else 0, total_count)
+
+
+def s2_corpus_id_from_arxiv_id(arxiv_id: str) -> int:
+    """
+    Get the S2 Corpus ID for a given arXiv ID.
+
+    Args:
+        arxiv_id: The ID of a given arXiv paper.
+    """
+    assert isinstance(arxiv_id, str), "Error: Your arxiv_id must be a string"
+    if "v" in arxiv_id:
+        arxiv_id = arxiv_id.split("v")[0]
+    paper_url = PAPER_URL_TEMPLATE.format(paper_id=f"arxiv:{arxiv_id}", fields="externalIds")
+    response = get_with_retries(paper_url)
+    result = response.json()
+    return int(result["externalIds"]["CorpusId"])
+
+
+def s2_get_info(arxiv_id: str) -> str:
+    """
+    Get the S2 info for a given arXiv ID.
+
+    Returns a JSON object serialized to a string. The structure is:
+    {"title": ..., "authors": ..., "externalIds": ..., "venue": ..., "citationCount": ..., "publicationDate": ...}
+    Use `json.loads` to deserialize the result if you want to get specific fields.
+
+    Args:
+        arxiv_id: The ID of a given arXiv paper.
+    """
+    assert isinstance(arxiv_id, str), "Error: Your arxiv_id must be a string"
+    if "v" in arxiv_id:
+        arxiv_id = arxiv_id.split("v")[0]
+    paper_url = PAPER_URL_TEMPLATE.format(paper_id=f"arxiv:{arxiv_id}", fields=FIELDS)
+    response = get_with_retries(paper_url)
+    return json.dumps(response.json(), ensure_ascii=False)

academia_mcp-1.9.2/academia_mcp/tools/show_image.py

@@ -0,0 +1,41 @@
+import base64
+from pathlib import Path
+from io import BytesIO
+from typing import Dict
+
+import httpx
+from PIL import Image
+
+from academia_mcp.files import get_workspace_dir
+from academia_mcp.settings import settings
+
+
+def show_image(path: str) -> Dict[str, str]:
+    """
+    Reads an image from the specified URL or from the current work directory.
+    Always call this function at the end of the code block.
+    For instance:
+    ```python
+    show_image("https://example.com/image.png")
+    ```
+    Do not print it ever, just return as the last expression.
+
+    Returns an dictionary with a single "image" key.
+    Args:
+        url: Path to file inside current work directory or web URL
+    """
+    if path.startswith("http"):
+        response = httpx.get(path, timeout=10)
+        response.raise_for_status()
+        image = Image.open(BytesIO(response.content))
+    else:
+        assert settings.WORKSPACE_DIR is not None, "WORKSPACE_DIR is not set"
+        full_path = Path(path)
+        if not full_path.exists():
+            full_path = Path(get_workspace_dir()) / path
+            assert full_path.exists(), f"Image file {path} does not exist"
+        image = Image.open(str(full_path))
+    buffer_io = BytesIO()
+    image.save(buffer_io, format="PNG")
+    img_bytes = buffer_io.getvalue()
+    return {"image_base64": base64.b64encode(img_bytes).decode("utf-8")}

academia_mcp-1.9.2/academia_mcp.egg-info/PKG-INFO

@@ -0,0 +1,170 @@
+Metadata-Version: 2.4
+Name: academia-mcp
+Version: 1.9.2
+Summary: MCP server that provides different tools to search for scientific publications
+Author-email: Ilya Gusev <phoenixilya@gmail.com>
+Project-URL: Homepage, https://github.com/IlyaGusev/academia_mcp
+Classifier: Programming Language :: Python :: 3
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Operating System :: OS Independent
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: mcp>=1.10.1
+Requires-Dist: xmltodict>=0.14.0
+Requires-Dist: types-xmltodict>=0.14.0
+Requires-Dist: requests>=2.32.0
+Requires-Dist: types-requests>=2.32.0
+Requires-Dist: pypdf>=5.1.0
+Requires-Dist: beautifulsoup4>=4.12.0
+Requires-Dist: types-beautifulsoup4>=4.12.0
+Requires-Dist: markdownify==0.14.1
+Requires-Dist: acl-anthology==0.5.2
+Requires-Dist: markdown==3.7.0
+Requires-Dist: types-markdown==3.7.0.20250322
+Requires-Dist: huggingface-hub>=0.32.4
+Requires-Dist: fire>=0.7.0
+Requires-Dist: openai>=1.97.1
+Requires-Dist: jinja2>=3.1.6
+Requires-Dist: datasets>=4.0.0
+Requires-Dist: pymupdf>=1.26.4
+Requires-Dist: pillow>=11.3.0
+Requires-Dist: pydantic-settings>=2.6.0
+Dynamic: license-file
+
+# Academia MCP
+
+[![PyPI](https://img.shields.io/pypi/v/academia-mcp?label=PyPI%20package)](https://pypi.org/project/academia-mcp/)
+[![CI](https://github.com/IlyaGusev/academia_mcp/actions/workflows/python.yml/badge.svg)](https://github.com/IlyaGusev/academia_mcp/actions/workflows/python.yml)
+[![License](https://img.shields.io/github/license/IlyaGusev/academia_mcp)](LICENSE)
+[![smithery badge](https://smithery.ai/badge/@IlyaGusev/academia_mcp)](https://smithery.ai/server/@IlyaGusev/academia_mcp)
+[![Verified on MseeP](https://mseep.ai/badge.svg)](https://mseep.ai/app/e818878b-c3a6-4b3d-a5b4-e54dcd1f1fed)
+
+MCP server with tools to search, fetch, analyze, and report on scientific papers and datasets.
+
+### Features
+- ArXiv search and download
+- ACL Anthology search
+- Hugging Face datasets search
+- Semantic Scholar citations and references
+- Web search via Exa, Brave, or Tavily
+- Web page crawler, LaTeX compilation, PDF reading
+- Optional LLM-powered tools for document QA and research proposal workflows
+
+### Requirements
+- Python 3.12+
+
+### Install
+- Using pip (end users):
+```bash
+pip3 install academia-mcp
+```
+
+- For development (uv + Makefile):
+```bash
+uv venv .venv
+make install
+```
+
+### Quickstart
+- Run over HTTP (default transport):
+```bash
+uv run -m academia_mcp --transport streamable-http
+```
+
+- Run over stdio (for local MCP clients like Claude Desktop):
+```bash
+python -m academia_mcp --transport stdio
+```
+
+Notes:
+- Transports: `stdio`, `sse`, `streamable-http`.
+- `host`/`port` are used for HTTP transports; ignored for `stdio`. Default port is `5056` (or `PORT`).
+
+### Claude Desktop config
+```json
+{
+  "mcpServers": {
+    "academia": {
+      "command": "python3",
+      "args": [
+        "-m",
+        "academia_mcp",
+        "--transport",
+        "stdio"
+      ]
+    }
+  }
+}
+```
+
+### Available tools (one-liners)
+- `arxiv_search`: Query arXiv with field-specific queries and filters.
+- `arxiv_download`: Fetch a paper by ID and convert to structured text (HTML/PDF modes).
+- `anthology_search`: Search ACL Anthology with fielded queries and optional date filtering.
+- `hf_datasets_search`: Find Hugging Face datasets with filters and sorting.
+- `s2_get_citations`: List papers citing a given arXiv paper (Semantic Scholar Graph).
+- `s2_get_references`: List papers referenced by a given arXiv paper.
+- `visit_webpage`: Fetch and normalize a web page.
+- `web_search`: Unified search wrapper; available when at least one of Exa/Brave/Tavily keys is set.
+- `exa_web_search`, `brave_web_search`, `tavily_web_search`: Provider-specific search.
+- `get_latex_templates_list`, `get_latex_template`: Enumerate and fetch built-in LaTeX templates.
+- `compile_latex`: Compile LaTeX to PDF in `WORKSPACE_DIR`.
+- `read_pdf`: Extract text per page from a PDF.
+- `download_pdf_paper`, `review_pdf_paper`: Download and optionally review PDFs (requires LLM + workspace).
+- `document_qa`: Answer questions over provided document chunks (requires LLM).
+- `extract_bitflip_info`, `generate_research_proposals`, `score_research_proposals`: Research proposal helpers (requires LLM).
+
+Availability notes:
+- Set `WORKSPACE_DIR` to enable `compile_latex`, `read_pdf`, `download_pdf_paper`, and `review_pdf_paper`.
+- Set `OPENROUTER_API_KEY` to enable LLM tools (`document_qa`, `review_pdf_paper`, and bitflip tools).
+- Set one or more of `EXA_API_KEY`, `BRAVE_API_KEY`, `TAVILY_API_KEY` to enable `web_search` and provider tools.
+
+### Environment variables
+Set as needed depending on which tools you use:
+
+- `OPENROUTER_API_KEY`: required for LLM-related tools.
+- `BASE_URL`: override OpenRouter base URL.
+- `DOCUMENT_QA_MODEL_NAME`: override default model for `document_qa`.
+- `BITFLIP_MODEL_NAME`: override default model for bitflip tools.
+- `TAVILY_API_KEY`: enables Tavily in `web_search`.
+- `EXA_API_KEY`: enables Exa in `web_search` and `visit_webpage`.
+- `BRAVE_API_KEY`: enables Brave in `web_search`.
+- `WORKSPACE_DIR`: directory for generated files (PDFs, temp artifacts).
+- `PORT`: HTTP port (default `5056`).
+
+You can put these in a `.env` file in the project root.
+
+### Docker
+Build the image:
+```bash
+docker build -t academia_mcp .
+```
+
+Run the server (HTTP):
+```bash
+docker run --rm -p 5056:5056 \
+  -e PORT=5056 \
+  -e OPENROUTER_API_KEY=your_key_here \
+  -e WORKSPACE_DIR=/workspace \
+  -v "$PWD/workdir:/workspace" \
+  academia_mcp
+```
+
+Or use existing image: `phoenix120/academia_mcp`
+
+### Examples
+- [Comprehensive report screencast (YouTube)](https://www.youtube.com/watch?v=4bweqQcN6w8)
+- [Single paper screencast (YouTube)](https://www.youtube.com/watch?v=IAAPMptJ5k8)
+
+### Makefile targets
+- `make install`: install the package in editable mode with uv
+- `make validate`: run black, flake8, and mypy (strict)
+- `make test`: run the test suite with pytest
+- `make publish`: build and publish using uv
+
+### LaTeX/PDF requirements
+Only needed for LaTeX/PDF tools. Ensure a LaTeX distribution is installed and `pdflatex` is on PATH, as well as `latexmk`. On Debian/Ubuntu:
+```bash
+sudo apt install texlive-latex-base texlive-fonts-recommended texlive-latex-extra texlive-science latexmk
+```

{academia_mcp-1.9.0 → academia_mcp-1.9.2}/academia_mcp.egg-info/SOURCES.txt

@@ -28,7 +28,8 @@ academia_mcp/tools/hf_datasets_search.py
 academia_mcp/tools/latex.py
 academia_mcp/tools/py.typed
 academia_mcp/tools/review.py
-academia_mcp/tools/s2_citations.py
+academia_mcp/tools/s2.py
+academia_mcp/tools/show_image.py
 academia_mcp/tools/visit_webpage.py
 academia_mcp/tools/web_search.py
 tests/test_anthology_search.py
@@ -40,6 +41,7 @@ tests/test_extract_json.py
 tests/test_hf_dataset_search.py
 tests/test_latex.py
 tests/test_review.py
-tests/test_s2_citations.py
+tests/test_s2.py
+tests/test_show_image.py
 tests/test_visit_webpage.py
 tests/test_web_search.py

{academia_mcp-1.9.0 → academia_mcp-1.9.2}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "academia-mcp"
-version = "1.9.0"
+version = "1.9.2"
 description = "MCP server that provides different tools to search for scientific publications"
 readme = "README.md"
 authors = [

academia_mcp-1.9.0/tests/test_s2_citations.py → academia_mcp-1.9.2/tests/test_s2.py

@@ -1,6 +1,11 @@
 import json
 
-from academia_mcp.tools import s2_get_citations, s2_get_references
+from academia_mcp.tools import (
+    s2_get_citations,
+    s2_get_references,
+    s2_corpus_id_from_arxiv_id,
+    s2_get_info,
+)
 
 
 def test_s2_citations_pingpong() -> None:
@@ -22,3 +27,18 @@ def test_s2_citations_reversed() -> None:
 def test_s2_citations_versions() -> None:
     citations = json.loads(s2_get_citations("2409.06820v4"))
     assert citations["total_count"] >= 1
+
+
+def test_s2_corpus_id_from_arxiv_id() -> None:
+    assert s2_corpus_id_from_arxiv_id("2409.06820") == 272593138
+
+
+def test_s2_get_info() -> None:
+    info = json.loads(s2_get_info("2409.06820"))
+    assert info["title"] is not None
+    assert info["authors"] is not None
+    assert info["externalIds"] is not None
+    assert info["venue"] is not None
+    assert info["citationCount"] is not None
+    assert info["publicationDate"] is not None
+    assert info["externalIds"]["CorpusId"] == 272593138

academia_mcp-1.9.2/tests/test_show_image.py

@@ -0,0 +1,25 @@
+from io import BytesIO
+
+import httpx
+from PIL import Image
+
+from academia_mcp.tools import show_image
+from academia_mcp.files import get_workspace_dir
+
+
+def test_show_image_base(test_image_url: str) -> None:
+    result = show_image(test_image_url)
+    assert result is not None
+    assert "image_base64" in result
+    assert result["image_base64"] is not None
+
+
+def test_show_image_local(test_image_url: str) -> None:
+    response = httpx.get(test_image_url, timeout=10)
+    response.raise_for_status()
+    image = Image.open(BytesIO(response.content))
+    image.save(get_workspace_dir() / "test_image.png")
+    result = show_image("test_image.png")
+    assert result is not None
+    assert "image_base64" in result
+    assert result["image_base64"] is not None

academia_mcp-1.9.0/PKG-INFO

@@ -1,122 +0,0 @@
-Metadata-Version: 2.4
-Name: academia-mcp
-Version: 1.9.0
-Summary: MCP server that provides different tools to search for scientific publications
-Author-email: Ilya Gusev <phoenixilya@gmail.com>
-Project-URL: Homepage, https://github.com/IlyaGusev/academia_mcp
-Classifier: Programming Language :: Python :: 3
-Classifier: License :: OSI Approved :: MIT License
-Classifier: Operating System :: OS Independent
-Requires-Python: >=3.12
-Description-Content-Type: text/markdown
-License-File: LICENSE
-Requires-Dist: mcp>=1.10.1
-Requires-Dist: xmltodict>=0.14.0
-Requires-Dist: types-xmltodict>=0.14.0
-Requires-Dist: requests>=2.32.0
-Requires-Dist: types-requests>=2.32.0
-Requires-Dist: pypdf>=5.1.0
-Requires-Dist: beautifulsoup4>=4.12.0
-Requires-Dist: types-beautifulsoup4>=4.12.0
-Requires-Dist: markdownify==0.14.1
-Requires-Dist: acl-anthology==0.5.2
-Requires-Dist: markdown==3.7.0
-Requires-Dist: types-markdown==3.7.0.20250322
-Requires-Dist: huggingface-hub>=0.32.4
-Requires-Dist: fire>=0.7.0
-Requires-Dist: openai>=1.97.1
-Requires-Dist: jinja2>=3.1.6
-Requires-Dist: datasets>=4.0.0
-Requires-Dist: pymupdf>=1.26.4
-Requires-Dist: pillow>=11.3.0
-Requires-Dist: pydantic-settings>=2.6.0
-Dynamic: license-file
-
-# Academia MCP
-
-[![PyPI](https://img.shields.io/pypi/v/codearkt?label=PyPI%20package)](https://pypi.org/project/academia-mcp/)
-[![CI](https://github.com/IlyaGusev/academia_mcp/actions/workflows/python.yml/badge.svg)](https://github.com/IlyaGusev/academia_mcp/actions/workflows/python.yml)
-[![License](https://img.shields.io/github/license/IlyaGusev/academia_mcp)](LICENSE)
-[![smithery badge](https://smithery.ai/badge/@IlyaGusev/academia_mcp)](https://smithery.ai/server/@IlyaGusev/academia_mcp)
-
-A collection of MCP tools related to the search of scientific papers:
-- ArXiv search and download
-- ACL Anthology search
-- HuggingFact datasets search
-- Semantic Scholar citation graphs
-- Web search: Exa/Brave/Tavily
-- Page crawler
-
-## Install
-
-- Using pip (end users):
-```
-pip3 install academia-mcp
-```
-
-- For development (uv + Makefile):
-```
-uv venv .venv
-make install
-```
-
-## Examples
-Comprehensive report screencast: https://www.youtube.com/watch?v=4bweqQcN6w8
-
-Single paper screencast: https://www.youtube.com/watch?v=IAAPMptJ5k8
-
-
-## Claude Desktop config
-```
-{
-  "mcpServers": {
-    "academia": {
-      "command": "python3",
-      "args": [
-        "-m",
-        "academia_mcp",
-        "--transport",
-        "stdio"
-      ]
-    }
-  }
-}
-```
-
-## Running the server (CLI)
-
-```
-uv run -m academia_mcp --transport streamable-http
-```
-
-Notes:
-- Transports supported: `stdio`, `sse`, `streamable-http`.
-- Host/port are used for HTTP transports; for `stdio` they are ignored.
-
-## Makefile targets
-
-- `make install`: install the package in editable mode with uv.
-- `make validate`: run black, flake8, and mypy (strict).
-- `make test`: run the test suite with pytest.
-- `make publish`: build and publish using uv.
-
-## Environment variables
-
-Set as needed depending on which tools you use:
-
-- `TAVILY_API_KEY`: enables Tavily in `web_search`.
-- `EXA_API_KEY`: enables Exa in `web_search` and `visit_webpage`.
-- `BRAVE_API_KEY`: enables Brave in `web_search`.
-- `OPENROUTER_API_KEY`: required for `document_qa`.
-- `BASE_URL`: override OpenRouter base URL for `document_qa` and bitflip tools.
-- `DOCUMENT_QA_MODEL_NAME`: override default model for `document_qa`.
-- `BITFLIP_MODEL_NAME`: override default model for bitflip tools.
-- `WORKSPACE_DIR`: directory for generated files (PDFs, temp artifacts).
-
-## md_to_pdf requirements
-
-The `md_to_pdf` tool invokes `pdflatex`. Ensure a LaTeX distribution is installed and `pdflatex` is on PATH. On Debian/Ubuntu:
-
-```
-sudo apt install texlive-latex-base texlive-fonts-recommended texlive-latex-extra texlive-science
-```

academia_mcp-1.9.0/README.md

@@ -1,88 +0,0 @@
-# Academia MCP
-
-[![PyPI](https://img.shields.io/pypi/v/codearkt?label=PyPI%20package)](https://pypi.org/project/academia-mcp/)
-[![CI](https://github.com/IlyaGusev/academia_mcp/actions/workflows/python.yml/badge.svg)](https://github.com/IlyaGusev/academia_mcp/actions/workflows/python.yml)
-[![License](https://img.shields.io/github/license/IlyaGusev/academia_mcp)](LICENSE)
-[![smithery badge](https://smithery.ai/badge/@IlyaGusev/academia_mcp)](https://smithery.ai/server/@IlyaGusev/academia_mcp)
-
-A collection of MCP tools related to the search of scientific papers:
-- ArXiv search and download
-- ACL Anthology search
-- HuggingFact datasets search
-- Semantic Scholar citation graphs
-- Web search: Exa/Brave/Tavily
-- Page crawler
-
-## Install
-
-- Using pip (end users):
-```
-pip3 install academia-mcp
-```
-
-- For development (uv + Makefile):
-```
-uv venv .venv
-make install
-```
-
-## Examples
-Comprehensive report screencast: https://www.youtube.com/watch?v=4bweqQcN6w8
-
-Single paper screencast: https://www.youtube.com/watch?v=IAAPMptJ5k8
-
-
-## Claude Desktop config
-```
-{
-  "mcpServers": {
-    "academia": {
-      "command": "python3",
-      "args": [
-        "-m",
-        "academia_mcp",
-        "--transport",
-        "stdio"
-      ]
-    }
-  }
-}
-```
-
-## Running the server (CLI)
-
-```
-uv run -m academia_mcp --transport streamable-http
-```
-
-Notes:
-- Transports supported: `stdio`, `sse`, `streamable-http`.
-- Host/port are used for HTTP transports; for `stdio` they are ignored.
-
-## Makefile targets
-
-- `make install`: install the package in editable mode with uv.
-- `make validate`: run black, flake8, and mypy (strict).
-- `make test`: run the test suite with pytest.
-- `make publish`: build and publish using uv.
-
-## Environment variables
-
-Set as needed depending on which tools you use:
-
-- `TAVILY_API_KEY`: enables Tavily in `web_search`.
-- `EXA_API_KEY`: enables Exa in `web_search` and `visit_webpage`.
-- `BRAVE_API_KEY`: enables Brave in `web_search`.
-- `OPENROUTER_API_KEY`: required for `document_qa`.
-- `BASE_URL`: override OpenRouter base URL for `document_qa` and bitflip tools.
-- `DOCUMENT_QA_MODEL_NAME`: override default model for `document_qa`.
-- `BITFLIP_MODEL_NAME`: override default model for bitflip tools.
-- `WORKSPACE_DIR`: directory for generated files (PDFs, temp artifacts).
-
-## md_to_pdf requirements
-
-The `md_to_pdf` tool invokes `pdflatex`. Ensure a LaTeX distribution is installed and `pdflatex` is on PATH. On Debian/Ubuntu:
-
-```
-sudo apt install texlive-latex-base texlive-fonts-recommended texlive-latex-extra texlive-science
-```

academia_mcp-1.9.0/academia_mcp.egg-info/PKG-INFO

@@ -1,122 +0,0 @@
-Metadata-Version: 2.4
-Name: academia-mcp
-Version: 1.9.0
-Summary: MCP server that provides different tools to search for scientific publications
-Author-email: Ilya Gusev <phoenixilya@gmail.com>
-Project-URL: Homepage, https://github.com/IlyaGusev/academia_mcp
-Classifier: Programming Language :: Python :: 3
-Classifier: License :: OSI Approved :: MIT License
-Classifier: Operating System :: OS Independent
-Requires-Python: >=3.12
-Description-Content-Type: text/markdown
-License-File: LICENSE
-Requires-Dist: mcp>=1.10.1
-Requires-Dist: xmltodict>=0.14.0
-Requires-Dist: types-xmltodict>=0.14.0
-Requires-Dist: requests>=2.32.0
-Requires-Dist: types-requests>=2.32.0
-Requires-Dist: pypdf>=5.1.0
-Requires-Dist: beautifulsoup4>=4.12.0
-Requires-Dist: types-beautifulsoup4>=4.12.0
-Requires-Dist: markdownify==0.14.1
-Requires-Dist: acl-anthology==0.5.2
-Requires-Dist: markdown==3.7.0
-Requires-Dist: types-markdown==3.7.0.20250322
-Requires-Dist: huggingface-hub>=0.32.4
-Requires-Dist: fire>=0.7.0
-Requires-Dist: openai>=1.97.1
-Requires-Dist: jinja2>=3.1.6
-Requires-Dist: datasets>=4.0.0
-Requires-Dist: pymupdf>=1.26.4
-Requires-Dist: pillow>=11.3.0
-Requires-Dist: pydantic-settings>=2.6.0
-Dynamic: license-file
-
-# Academia MCP
-
-[![PyPI](https://img.shields.io/pypi/v/codearkt?label=PyPI%20package)](https://pypi.org/project/academia-mcp/)
-[![CI](https://github.com/IlyaGusev/academia_mcp/actions/workflows/python.yml/badge.svg)](https://github.com/IlyaGusev/academia_mcp/actions/workflows/python.yml)
-[![License](https://img.shields.io/github/license/IlyaGusev/academia_mcp)](LICENSE)
-[![smithery badge](https://smithery.ai/badge/@IlyaGusev/academia_mcp)](https://smithery.ai/server/@IlyaGusev/academia_mcp)
-
-A collection of MCP tools related to the search of scientific papers:
-- ArXiv search and download
-- ACL Anthology search
-- HuggingFact datasets search
-- Semantic Scholar citation graphs
-- Web search: Exa/Brave/Tavily
-- Page crawler
-
-## Install
-
-- Using pip (end users):
-```
-pip3 install academia-mcp
-```
-
-- For development (uv + Makefile):
-```
-uv venv .venv
-make install
-```
-
-## Examples
-Comprehensive report screencast: https://www.youtube.com/watch?v=4bweqQcN6w8
-
-Single paper screencast: https://www.youtube.com/watch?v=IAAPMptJ5k8
-
-
-## Claude Desktop config
-```
-{
-  "mcpServers": {
-    "academia": {
-      "command": "python3",
-      "args": [
-        "-m",
-        "academia_mcp",
-        "--transport",
-        "stdio"
-      ]
-    }
-  }
-}
-```
-
-## Running the server (CLI)
-
-```
-uv run -m academia_mcp --transport streamable-http
-```
-
-Notes:
-- Transports supported: `stdio`, `sse`, `streamable-http`.
-- Host/port are used for HTTP transports; for `stdio` they are ignored.
-
-## Makefile targets
-
-- `make install`: install the package in editable mode with uv.
-- `make validate`: run black, flake8, and mypy (strict).
-- `make test`: run the test suite with pytest.
-- `make publish`: build and publish using uv.
-
-## Environment variables
-
-Set as needed depending on which tools you use:
-
-- `TAVILY_API_KEY`: enables Tavily in `web_search`.
-- `EXA_API_KEY`: enables Exa in `web_search` and `visit_webpage`.
-- `BRAVE_API_KEY`: enables Brave in `web_search`.
-- `OPENROUTER_API_KEY`: required for `document_qa`.
-- `BASE_URL`: override OpenRouter base URL for `document_qa` and bitflip tools.
-- `DOCUMENT_QA_MODEL_NAME`: override default model for `document_qa`.
-- `BITFLIP_MODEL_NAME`: override default model for bitflip tools.
-- `WORKSPACE_DIR`: directory for generated files (PDFs, temp artifacts).
-
-## md_to_pdf requirements
-
-The `md_to_pdf` tool invokes `pdflatex`. Ensure a LaTeX distribution is installed and `pdflatex` is on PATH. On Debian/Ubuntu:
-
-```
-sudo apt install texlive-latex-base texlive-fonts-recommended texlive-latex-extra texlive-science
-```