academia-mcp 1.2.2__tar.gz → 1.4.0__tar.gz

{academia_mcp-1.2.2 → academia_mcp-1.4.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: academia-mcp
-Version: 1.2.2
+Version: 1.4.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
@@ -22,16 +22,11 @@ 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: black==25.1.0
-Requires-Dist: mypy==1.16.0
-Requires-Dist: flake8==7.2.0
 Requires-Dist: huggingface-hub>=0.32.4
 Requires-Dist: fire>=0.7.0
-Requires-Dist: pytest>=8.4.1
 Requires-Dist: openai>=1.97.1
 Requires-Dist: jinja2>=3.1.6
 Requires-Dist: datasets>=4.0.0
-Requires-Dist: pytest-asyncio>=1.1.0
 Dynamic: license-file
 
 # Academia MCP
@@ -44,16 +39,26 @@ A collection of MCP tools related to the search of scientific papers:
 - Web search: Exa/Brave/Tavily
 - Page crawler
 
-Install:
+## 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:
+
+## Claude Desktop config
 ```
 {
   "mcpServers": {
@@ -69,3 +74,41 @@ Claude Desktop config:
   }
 }
 ```
+
+## 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.4.0/README.md

@@ -0,0 +1,83 @@
+# 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.2.2 → academia_mcp-1.4.0}/academia_mcp/files.py

@@ -5,6 +5,7 @@ from pathlib import Path
 DIR_PATH = Path(__file__).parent
 ROOT_PATH = DIR_PATH.parent
 DEFAULT_WORKSPACE_DIR_PATH: Path = DIR_PATH / "workdir"
+DEFAULT_LATEX_TEMPLATES_DIR_PATH: Path = DIR_PATH / "latex_templates"
 
 
 class WorkspaceDirectory:

{academia_mcp-1.2.2 → academia_mcp-1.4.0}/academia_mcp/server.py

@@ -12,7 +12,12 @@ from .tools.s2_citations import s2_get_citations, s2_get_references
 from .tools.hf_datasets_search import hf_datasets_search
 from .tools.anthology_search import anthology_search
 from .tools.document_qa import document_qa
-from .tools.md_to_pdf import md_to_pdf
+from .tools.latex import (
+    compile_latex_from_file,
+    compile_latex_from_str,
+    get_latex_template,
+    get_latex_templates_list,
+)
 from .tools.web_search import web_search, tavily_web_search, exa_web_search, brave_web_search
 from .tools.visit_webpage import visit_webpage
 from .tools.bitflip import (
@@ -33,7 +38,7 @@ def find_free_port() -> int:
                 return port
         except Exception:
             continue
-    return 5000
+    raise RuntimeError("No free port in range 5000-6000 found")
 
 
 def run(
@@ -42,6 +47,8 @@ def run(
     mount_path: str = "/",
     streamable_http_path: str = "/mcp",
     transport: Literal["stdio", "sse", "streamable-http"] = "streamable-http",
+    disable_web_search_tools: bool = False,
+    disable_llm_tools: bool = False,
 ) -> None:
     server = FastMCP(
         "Academia MCP",
@@ -56,21 +63,26 @@ def run(
     server.add_tool(s2_get_references)
     server.add_tool(hf_datasets_search)
     server.add_tool(anthology_search)
-    server.add_tool(md_to_pdf)
+    server.add_tool(compile_latex_from_file)
+    server.add_tool(compile_latex_from_str)
+    server.add_tool(get_latex_template)
+    server.add_tool(get_latex_templates_list)
     server.add_tool(visit_webpage)
-    server.add_tool(extract_bitflip_info)
-    server.add_tool(generate_research_proposal)
-    server.add_tool(score_research_proposals)
 
-    if os.getenv("TAVILY_API_KEY"):
-        server.add_tool(tavily_web_search)
-    if os.getenv("EXA_API_KEY"):
-        server.add_tool(exa_web_search)
-    if os.getenv("BRAVE_API_KEY"):
-        server.add_tool(brave_web_search)
-    if os.getenv("EXA_API_KEY") or os.getenv("BRAVE_API_KEY") or os.getenv("TAVILY_API_KEY"):
-        server.add_tool(web_search)
-    if os.getenv("OPENROUTER_API_KEY"):
+    if not disable_web_search_tools:
+        if os.getenv("TAVILY_API_KEY"):
+            server.add_tool(tavily_web_search)
+        if os.getenv("EXA_API_KEY"):
+            server.add_tool(exa_web_search)
+        if os.getenv("BRAVE_API_KEY"):
+            server.add_tool(brave_web_search)
+        if os.getenv("EXA_API_KEY") or os.getenv("BRAVE_API_KEY") or os.getenv("TAVILY_API_KEY"):
+            server.add_tool(web_search)
+
+    if not disable_llm_tools and os.getenv("OPENROUTER_API_KEY"):
+        server.add_tool(extract_bitflip_info)
+        server.add_tool(generate_research_proposal)
+        server.add_tool(score_research_proposals)
         server.add_tool(document_qa)
 
     if port is None:

{academia_mcp-1.2.2 → academia_mcp-1.4.0}/academia_mcp/tools/__init__.py

@@ -4,7 +4,12 @@ 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 .document_qa import document_qa
-from .md_to_pdf import md_to_pdf
+from .latex import (
+    compile_latex_from_file,
+    compile_latex_from_str,
+    get_latex_template,
+    get_latex_templates_list,
+)
 from .web_search import web_search, tavily_web_search, exa_web_search, brave_web_search
 from .visit_webpage import visit_webpage
 from .bitflip import extract_bitflip_info, generate_research_proposal, score_research_proposals
@@ -18,7 +23,10 @@ __all__ = [
     "s2_get_citations",
     "hf_datasets_search",
     "document_qa",
-    "md_to_pdf",
+    "compile_latex_from_file",
+    "compile_latex_from_str",
+    "get_latex_template",
+    "get_latex_templates_list",
     "web_search",
     "tavily_web_search",
     "exa_web_search",

{academia_mcp-1.2.2 → academia_mcp-1.4.0}/academia_mcp/tools/anthology_search.py

@@ -34,20 +34,13 @@ def _format_authors(authors: List[Any]) -> str:
     return result
 
 
-def _format_date(date_str: str) -> str:
-    try:
-        return datetime.strptime(date_str, "%Y").strftime("%B %d, %Y")
-    except ValueError:
-        return date_str
-
-
 def _clean_entry(entry: Any) -> Dict[str, Any]:
     return {
         "id": entry.full_id,
         "title": _format_text_field(entry.title.as_text()),
         "authors": _format_authors(entry.authors),
         "abstract": (_format_text_field(entry.abstract.as_text()) if entry.abstract else ""),
-        "published": _format_date(entry.year),
+        "published_year": entry.year,
         "categories": ", ".join(entry.venue_ids),
         "comment": entry.note if entry.note else "",
         "url": entry.pdf.url if entry.pdf else "",

{academia_mcp-1.2.2 → academia_mcp-1.4.0}/academia_mcp/tools/arxiv_download.py

@@ -35,6 +35,8 @@ def parse_pdf_file(pdf_path: Path) -> List[str]:
     for page_number, page in enumerate(reader.pages, start=1):
         try:
             text = page.extract_text()
+            if not text:
+                continue
             prefix = f"## Page {page_number}\n\n"
             pages.append(prefix + text)
         except Exception:

{academia_mcp-1.2.2 → academia_mcp-1.4.0}/academia_mcp/tools/document_qa.py

@@ -6,6 +6,7 @@ from dotenv import load_dotenv
 from pydantic import BaseModel
 
 from academia_mcp.llm import llm_acall
+from academia_mcp.utils import truncate_content
 
 load_dotenv()
 
@@ -62,9 +63,11 @@ async def document_qa(
     assert question and question.strip(), "Please provide non-empty 'question'"
     if isinstance(document, dict):
         document = json.dumps(document)
-
     assert document and document.strip(), "Please provide non-empty 'document'"
 
+    question = truncate_content(question, 10000)
+    document = truncate_content(document, 200000)
+
     model_name = os.getenv("DOCUMENT_QA_MODEL_NAME", "deepseek/deepseek-chat-v3-0324")
     prompt = PROMPT.format(question=question, document=document)
     content = await llm_acall(model_name=model_name, prompt=prompt)

academia_mcp-1.4.0/academia_mcp/tools/latex.py

@@ -0,0 +1,151 @@
+import re
+import subprocess
+import shutil
+import tempfile
+import json
+from pathlib import Path
+
+
+from academia_mcp.files import get_workspace_dir, DEFAULT_LATEX_TEMPLATES_DIR_PATH
+
+
+def get_latex_templates_list() -> str:
+    """
+    Get the list of available latex templates.
+    Always use one of the templates from the list.
+
+    Returns a JSON list serialized to a string.
+    Use `json.loads` to deserialize the result.
+    """
+    return json.dumps([str(path.name) for path in DEFAULT_LATEX_TEMPLATES_DIR_PATH.glob("*")])
+
+
+def get_latex_template(template_name: str) -> str:
+    """
+    Get the latex template by name.
+
+    Returns a JSON object serialized to a string.
+    Use `json.loads` to deserialize the result.
+    The structure is: {"template": "...", "style": "..."}
+
+    Args:
+        template_name: The name of the latex template.
+    """
+    template_dir_path = DEFAULT_LATEX_TEMPLATES_DIR_PATH / template_name
+    if not template_dir_path.exists():
+        raise FileNotFoundError(
+            f"Template {template_name} not found in {DEFAULT_LATEX_TEMPLATES_DIR_PATH}"
+        )
+    template_path = template_dir_path / f"{template_name}.tex"
+    style_path = template_dir_path / f"{template_name}.sty"
+    if not template_path.exists():
+        raise FileNotFoundError(f"Template file {template_path} not found in {template_dir_path}")
+    if not style_path.exists():
+        raise FileNotFoundError(f"Style file {style_path} not found in {template_dir_path}")
+    return json.dumps({"template": template_path.read_text(), "style": style_path.read_text()})
+
+
+def compile_latex_from_file(
+    input_filename: str, output_filename: str = "output.pdf", timeout: int = 60
+) -> str:
+    """
+    Compile a latex file.
+
+    Returns a string with the result of the compilation.
+
+    Args:
+        input_filename: The path to the latex file.
+        output_filename: The path to the output pdf file.
+        timeout: The timeout for the compilation. 60 seconds by default.
+    """
+    with open(input_filename, "r", encoding="utf-8") as file:
+        latex_code = file.read()
+    return compile_latex_from_str(latex_code, output_filename, timeout)
+
+
+def compile_latex_from_str(
+    latex_code: str, output_filename: str = "output.pdf", timeout: int = 60
+) -> str:
+    """
+    Compile a latex code.
+
+    Returns a string with the result of the compilation.
+
+    Args:
+        latex_code: The latex code to compile.
+        output_filename: The path to the output pdf file.
+        timeout: The timeout for the compilation. 60 seconds by default.
+    """
+    if shutil.which("pdflatex") is None:
+        return "pdflatex is not installed or not found in PATH."
+
+    destination_name = (
+        output_filename if output_filename.lower().endswith(".pdf") else f"{output_filename}.pdf"
+    )
+
+    try:
+        with tempfile.TemporaryDirectory(
+            dir=str(get_workspace_dir()), prefix="temp_latex_"
+        ) as temp_dir:
+            temp_dir_path = Path(temp_dir)
+            tex_filename = "temp.tex"
+            pdf_filename = "temp.pdf"
+            tex_file_path = temp_dir_path / tex_filename
+            tex_file_path.write_text(latex_code, encoding="utf-8")
+
+            # Detect and copy local .sty packages referenced by \usepackage{...}
+            # Supports optional arguments: \usepackage[opts]{pkgA,pkgB}
+            try:
+                package_names: set[str] = set()
+                for match in re.finditer(r"\\usepackage(?:\[[^\]]*\])?\{([^}]+)\}", latex_code):
+                    for name in match.group(1).split(","):
+                        pkg = name.strip()
+                        if pkg:
+                            package_names.add(pkg)
+
+                for pkg in package_names:
+                    sty_name = f"{pkg}.sty"
+                    for candidate in DEFAULT_LATEX_TEMPLATES_DIR_PATH.rglob(sty_name):
+                        shutil.copyfile(candidate, temp_dir_path / sty_name)
+                        break
+            except Exception:
+                pass
+
+            try:
+                subprocess.run(
+                    [
+                        "pdflatex",
+                        "-interaction=nonstopmode",
+                        tex_filename,
+                    ],
+                    cwd=str(temp_dir_path),
+                    check=True,
+                    capture_output=True,
+                    text=True,
+                    timeout=timeout,
+                )
+            except subprocess.TimeoutExpired:
+                return f"Compilation timed out after {timeout} seconds"
+            except subprocess.CalledProcessError as e:
+                combined_output = (e.stdout or "") + "\n" + (e.stderr or "")
+                error_lines = [
+                    line
+                    for line in combined_output.split("\n")
+                    if ("error" in line.lower() or "!" in line)
+                ]
+                if error_lines:
+                    return "Compilation failed. LaTeX errors:\n" + "\n".join(error_lines)
+                return f"Compilation failed. Full LaTeX output:\n{combined_output}"
+
+            pdf_path = temp_dir_path / pdf_filename
+            output_pdf_path = Path(get_workspace_dir()) / destination_name
+
+            if pdf_path.exists():
+                shutil.move(str(pdf_path), str(output_pdf_path))
+                return f"Compilation successful! PDF file saved as {destination_name}"
+
+            return (
+                "Compilation completed, but PDF file was not created. Check LaTeX code for errors."
+            )
+    except Exception as e:
+        return f"Compilation failed due to an unexpected error: {e}"

{academia_mcp-1.2.2 → academia_mcp-1.4.0}/academia_mcp/tools/visit_webpage.py

@@ -11,6 +11,17 @@ EXA_CONTENTS_URL = "https://api.exa.ai/contents"
 AVAILABLE_PROVIDERS = ("basic", "exa")
 
 
+def _exa_visit_webpage(url: str) -> str:
+    key = os.getenv("EXA_API_KEY", "")
+    assert key, "Error: EXA_API_KEY is not set and no api_key was provided"
+    payload = {
+        "urls": [url],
+        "text": True,
+    }
+    response = post_with_retries(EXA_CONTENTS_URL, payload=payload, api_key=key)
+    return json.dumps(response.json()["results"][0])
+
+
 def visit_webpage(url: str, provider: Optional[str] = "basic") -> str:
     """
     Visit a webpage and return the content.
@@ -28,17 +39,17 @@ def visit_webpage(url: str, provider: Optional[str] = "basic") -> str:
     ), f"Invalid provider: {provider}. Available providers: {AVAILABLE_PROVIDERS}"
 
     if provider == "exa":
-        key = os.getenv("EXA_API_KEY", "")
-        assert key, "Error: EXA_API_KEY is not set and no api_key was provided"
-        payload = {
-            "urls": [url],
-            "text": True,
-        }
-        response = post_with_retries(EXA_CONTENTS_URL, payload=payload, api_key=key)
-        return json.dumps(response.json()["results"][0])
+        return _exa_visit_webpage(url)
 
     assert provider == "basic"
     response = get_with_retries(url)
+    content_type = response.headers.get("content-type", "").lower()
+    if not content_type or (not content_type.startswith("text/") and "html" not in content_type):
+        if os.getenv("EXA_API_KEY"):
+            return _exa_visit_webpage(url)
+        return json.dumps(
+            {"id": url, "error": f"Unsupported content-type: {content_type or 'unknown'}"}
+        )
     markdown_content = markdownify(response.text).strip()
     markdown_content = re.sub(r"\n{3,}", "\n\n", markdown_content)
     return json.dumps({"id": url, "text": markdown_content})

{academia_mcp-1.2.2 → academia_mcp-1.4.0}/academia_mcp/tools/web_search.py

@@ -17,7 +17,8 @@ def web_search(
     provider: Optional[str] = "tavily",
 ) -> str:
     """
-    Search the web using Exa Search or Tavily and return normalized results.
+    Search the web using Exa Search, Brave Search or Tavily and return normalized results.
+    If the specified provider is not available, the function will try to use the next available provider.
 
     Returns a JSON object serialized to a string. The structure is: {"results": [...]}
     Every item in the "results" has at least the following fields: ("title", "url")
@@ -47,13 +48,15 @@ def web_search(
                 provider = p
                 break
 
+    result = {}
     if provider == "exa":
-        return exa_web_search(query, limit)
+        result = json.loads(exa_web_search(query, limit))
     elif provider == "brave":
-        return brave_web_search(query, limit)
-
-    assert provider == "tavily"
-    return tavily_web_search(query, limit)
+        result = json.loads(brave_web_search(query, limit))
+    elif provider == "tavily":
+        result = json.loads(tavily_web_search(query, limit))
+    result["search_provider"] = provider
+    return json.dumps(result, ensure_ascii=False)
 
 
 def tavily_web_search(query: str, limit: Optional[int] = 20) -> str:

{academia_mcp-1.2.2 → academia_mcp-1.4.0}/academia_mcp/utils.py

@@ -13,10 +13,11 @@ def post_with_retries(
     api_key: Optional[str] = None,
     timeout: int = 30,
     num_retries: int = 3,
+    backoff_factor: float = 3.0,
 ) -> requests.Response:
     retry_strategy = Retry(
         total=num_retries,
-        backoff_factor=3,
+        backoff_factor=backoff_factor,
         status_forcelist=[429, 500, 502, 503, 504],
         allowed_methods=["POST"],
     )
@@ -24,6 +25,7 @@ def post_with_retries(
     session = requests.Session()
     adapter = requests.adapters.HTTPAdapter(max_retries=retry_strategy)
     session.mount("https://", adapter)
+    session.mount("http://", adapter)
 
     headers = {
         "x-api-key": api_key,
@@ -42,11 +44,12 @@ def get_with_retries(
     api_key: Optional[str] = None,
     timeout: int = 30,
     num_retries: int = 3,
+    backoff_factor: float = 3.0,
     params: Optional[Dict[str, Any]] = None,
 ) -> requests.Response:
     retry_strategy = Retry(
         total=num_retries,
-        backoff_factor=30,
+        backoff_factor=backoff_factor,
         status_forcelist=[429, 500, 502, 503, 504],
         allowed_methods=["GET"],
     )
@@ -54,6 +57,7 @@ def get_with_retries(
     session = requests.Session()
     adapter = requests.adapters.HTTPAdapter(max_retries=retry_strategy)
     session.mount("https://", adapter)
+    session.mount("http://", adapter)
 
     headers = {}
     if api_key:
@@ -145,3 +149,19 @@ def extract_json(text: str) -> Any:
 def encode_prompt(template: str, **kwargs: Any) -> str:
     template_obj = Template(template)
     return template_obj.render(**kwargs).strip()
+
+
+def truncate_content(
+    content: str,
+    max_length: int,
+) -> str:
+    disclaimer = (
+        f"\n\n..._This content has been truncated to stay below {max_length} characters_...\n\n"
+    )
+    half_length = max_length // 2
+    if len(content) <= max_length:
+        return content
+
+    prefix = content[:half_length]
+    suffix = content[-half_length:]
+    return prefix + disclaimer + suffix