academia-mcp 1.2.1__py3-none-any.whl → 1.3.0__py3-none-any.whl

academia_mcp/server.py

@@ -33,7 +33,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 +42,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",
@@ -58,19 +60,21 @@ def run(
     server.add_tool(anthology_search)
     server.add_tool(md_to_pdf)
     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/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/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/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/tools/md_to_pdf.py

@@ -367,6 +367,10 @@ def md_to_pdf(markdown_text: str, output_filename: str = "output") -> str:
     with open(tex_file_path, "w", encoding="utf-8") as f:
         f.write(latex_code)
 
+    if shutil.which("pdflatex") is None:
+        shutil.rmtree(temp_dir, ignore_errors=True)
+        return "pdflatex is not installed or not found in PATH."
+
     try:
         subprocess.run(
             [
@@ -383,12 +387,14 @@ def md_to_pdf(markdown_text: str, output_filename: str = "output") -> str:
         )
 
     except subprocess.TimeoutExpired:
+        shutil.rmtree(temp_dir, ignore_errors=True)
         return "Compilation timed out after 30 seconds"
     except subprocess.CalledProcessError as e:
         error_msg = e.stdout.decode("utf-8")
         error_lines = [
             line for line in error_msg.split("\n") if "error" in line.lower() or "!" in line
         ]
+        shutil.rmtree(temp_dir, ignore_errors=True)
         if error_lines:
             return "Compilation failed. LaTeX errors:\n" + "\n".join(error_lines)
         return f"Compilation failed. Full LaTeX output:\n{error_msg}"
@@ -401,4 +407,5 @@ def md_to_pdf(markdown_text: str, output_filename: str = "output") -> str:
         shutil.rmtree(temp_dir, ignore_errors=True)
         return f"Compilation successful! PDF file saved as {output_filename}.pdf"
 
+    shutil.rmtree(temp_dir, ignore_errors=True)
     return "Compilation completed, but PDF file was not created. Check LaTeX code for errors."

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/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")
@@ -28,17 +29,34 @@ def web_search(
         limit: The maximum number of items to return. 20 by default, maximum 25.
         provider: The provider to use. "exa", "tavily" or "brave". "tavily" by default.
     """
-    assert provider in (
-        "exa",
-        "tavily",
-        "brave",
-    ), "Error: provider must be either 'exa', 'tavily' or 'brave'"
+    providers = ("tavily", "brave", "exa")
+    assert provider in providers, "Error: provider must be either 'exa', 'tavily' or 'brave'"
+
+    is_tavily_available = os.getenv("TAVILY_API_KEY") is not None
+    is_exa_available = os.getenv("EXA_API_KEY") is not None
+    is_brave_available = os.getenv("BRAVE_API_KEY") is not None
+    assert is_tavily_available or is_exa_available or is_brave_available
+    availability = {
+        "tavily": is_tavily_available,
+        "brave": is_brave_available,
+        "exa": is_exa_available,
+    }
+
+    if not availability[provider]:
+        for p in providers:
+            if availability[p]:
+                provider = p
+                break
 
+    result = {}
     if provider == "exa":
-        return exa_web_search(query, limit)
-    if provider == "brave":
-        return brave_web_search(query, limit)
-    return tavily_web_search(query, limit)
+        result = json.loads(exa_web_search(query, limit))
+    elif provider == "brave":
+        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/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

{academia_mcp-1.2.1.dist-info → academia_mcp-1.3.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: academia-mcp
-Version: 1.2.1
+Version: 1.3.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
@@ -44,16 +44,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 +79,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.3.0.dist-info/RECORD

@@ -0,0 +1,25 @@
+academia_mcp/__init__.py,sha256=2Ru2I5u4cE7DrkkAsibDUEF1K6sYtqppb9VyFrRoQKI,94
+academia_mcp/__main__.py,sha256=rcmsOtJd3SA82exjrcGBuxuptcoxF8AXI7jNjiVq2BY,59
+academia_mcp/files.py,sha256=hI5dj4h0fX8V3DXKI_C8vs1fte2uc9gsBXC6prLV4o4,745
+academia_mcp/llm.py,sha256=o84FQNSbjjVSk9DlvFXWsUDiz5IOaavYU6kOqnPEG7E,1071
+academia_mcp/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+academia_mcp/server.py,sha256=mMGKxL9u_EFEq4eTO0Xj6uknXUSW7X5dspxeexR1O8s,2729
+academia_mcp/utils.py,sha256=P9U3RjYzcztE0KxXvJSy5wSBaUg2CM9tpByljYrsrl4,4607
+academia_mcp/tools/__init__.py,sha256=8_8QWPRYmPiUjdiNrQilEEnCRR-UBU7g-56jT52V3VQ,934
+academia_mcp/tools/anthology_search.py,sha256=rhFpJZqGLABgr0raDuH0CARBiAJNJtEI4dlMrKNHfDQ,7669
+academia_mcp/tools/arxiv_download.py,sha256=soa9nPDHV1-ZgTLtqh-Fj69WkRsrb1hRKouWDa2ePng,11269
+academia_mcp/tools/arxiv_search.py,sha256=pzM18qrF3QL03A53w003kE7hQi3s3QKtjgw0m7K88UY,8355
+academia_mcp/tools/bitflip.py,sha256=u0hSOPWbnCDu2EbA_RkueX496SvTKz9QhZcXugshSfI,10949
+academia_mcp/tools/document_qa.py,sha256=04pJpiYCg27EFiZhfmTaMjeobu8SMT0Dls7OAFDoH00,2392
+academia_mcp/tools/hf_datasets_search.py,sha256=KiBkqT4rXjEN4oc1AWZOPnqN_Go90TQogY5-DUm3LQo,2854
+academia_mcp/tools/md_to_pdf.py,sha256=2fMZvUrffhPUa8CIk7q43ExfH-W-p9rvO2HpW3DIT54,13121
+academia_mcp/tools/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+academia_mcp/tools/s2_citations.py,sha256=dqrBp76RrX1zH2XzcMAoWBbvbtyhxLeF-xnqOKD_JiM,4852
+academia_mcp/tools/visit_webpage.py,sha256=OZdqDkVPIbANyFw5o5jIjU5Rr_dolxrGDs63Ud-GmRM,1966
+academia_mcp/tools/web_search.py,sha256=mobKm4iqKppn8pduZYMzWRo1MQBjkAqmMtrFLI5XY2Y,6296
+academia_mcp-1.3.0.dist-info/licenses/LICENSE,sha256=xx0jnfkXJvxRnG63LTGOxlggYnIysveWIZ6H3PNdCrQ,11357
+academia_mcp-1.3.0.dist-info/METADATA,sha256=Lx7zXo9Zx6Pi0bxLkaYciF3YU5DP6cB7LbYB_ko8kmk,3324
+academia_mcp-1.3.0.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+academia_mcp-1.3.0.dist-info/entry_points.txt,sha256=gxkiKJ74w2FwJpSECpjA3XtCfI5ZfrM6N8cqnwsq4yY,51
+academia_mcp-1.3.0.dist-info/top_level.txt,sha256=CzGpRFsRRJRqWEb1e3SUlcfGqRzOxevZGaJWrtGF8W0,13
+academia_mcp-1.3.0.dist-info/RECORD,,

academia_mcp-1.2.1.dist-info/RECORD

@@ -1,25 +0,0 @@
-academia_mcp/__init__.py,sha256=2Ru2I5u4cE7DrkkAsibDUEF1K6sYtqppb9VyFrRoQKI,94
-academia_mcp/__main__.py,sha256=rcmsOtJd3SA82exjrcGBuxuptcoxF8AXI7jNjiVq2BY,59
-academia_mcp/files.py,sha256=hI5dj4h0fX8V3DXKI_C8vs1fte2uc9gsBXC6prLV4o4,745
-academia_mcp/llm.py,sha256=o84FQNSbjjVSk9DlvFXWsUDiz5IOaavYU6kOqnPEG7E,1071
-academia_mcp/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-academia_mcp/server.py,sha256=q9bhacVm-8uuIMc_xSeymmVaIB8pQCqfTQx5GU8hhpM,2492
-academia_mcp/utils.py,sha256=tkHBho-NfzAR8rplFaiRYq4sBmQ9V3JPjDJTDrz58Xs,4041
-academia_mcp/tools/__init__.py,sha256=8_8QWPRYmPiUjdiNrQilEEnCRR-UBU7g-56jT52V3VQ,934
-academia_mcp/tools/anthology_search.py,sha256=_5s8EzdV7NQD_F3bjVH4XlKKHOJlFtWlQVrPbODuc3I,7847
-academia_mcp/tools/arxiv_download.py,sha256=xanzt77TZBQRngzGbKCRz4Hp-Mwfe_q-46eRW23TpVs,11219
-academia_mcp/tools/arxiv_search.py,sha256=pzM18qrF3QL03A53w003kE7hQi3s3QKtjgw0m7K88UY,8355
-academia_mcp/tools/bitflip.py,sha256=u0hSOPWbnCDu2EbA_RkueX496SvTKz9QhZcXugshSfI,10949
-academia_mcp/tools/document_qa.py,sha256=lWtzRNFKwQpQO8vPNvYYbNnGh3LsBmGl6f9vSRIuqaw,2245
-academia_mcp/tools/hf_datasets_search.py,sha256=KiBkqT4rXjEN4oc1AWZOPnqN_Go90TQogY5-DUm3LQo,2854
-academia_mcp/tools/md_to_pdf.py,sha256=Ovc_-8j7gIZNEM1d0ZDH-8qbtfZLSaNmCm5DQjrtM0k,12810
-academia_mcp/tools/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-academia_mcp/tools/s2_citations.py,sha256=dqrBp76RrX1zH2XzcMAoWBbvbtyhxLeF-xnqOKD_JiM,4852
-academia_mcp/tools/visit_webpage.py,sha256=0zAZYeQxPDu0OjgAAvbMLZh0ttaS5q-_4WhgsEPrbsI,1542
-academia_mcp/tools/web_search.py,sha256=NAkbXdD9mKxsIXhWN32dRd_EiaB3G6ENy-n-bc7HAaQ,5448
-academia_mcp-1.2.1.dist-info/licenses/LICENSE,sha256=xx0jnfkXJvxRnG63LTGOxlggYnIysveWIZ6H3PNdCrQ,11357
-academia_mcp-1.2.1.dist-info/METADATA,sha256=mLcD1By5dg9L8hNMlybFg5IUjS4S7uzXggGshnTESV8,1899
-academia_mcp-1.2.1.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
-academia_mcp-1.2.1.dist-info/entry_points.txt,sha256=gxkiKJ74w2FwJpSECpjA3XtCfI5ZfrM6N8cqnwsq4yY,51
-academia_mcp-1.2.1.dist-info/top_level.txt,sha256=CzGpRFsRRJRqWEb1e3SUlcfGqRzOxevZGaJWrtGF8W0,13
-academia_mcp-1.2.1.dist-info/RECORD,,