academia-mcp 1.10.9__py3-none-any.whl → 1.11.1__py3-none-any.whl

academia_mcp/server.py

@@ -63,35 +63,34 @@ def find_free_port() -> int:
     raise RuntimeError("No free port in range 5000-6000 found")
 
 
-def run(
-    host: str = "0.0.0.0",
-    port: Optional[int] = None,
-    mount_path: str = "/",
+def create_server(
     streamable_http_path: str = "/mcp",
-    transport: Literal["stdio", "sse", "streamable-http"] = "streamable-http",
+    mount_path: str = "/",
+    stateless_http: bool = True,
     disable_web_search_tools: bool = False,
     disable_llm_tools: bool = False,
-) -> None:
-    configure_uvicorn_style_logging()
+    port: Optional[int] = None,
+    host: str = "0.0.0.0",
+) -> FastMCP:
     server = FastMCP(
         "Academia MCP",
-        stateless_http=True,
+        stateless_http=stateless_http,
         streamable_http_path=streamable_http_path,
         mount_path=mount_path,
     )
     logger = logging.getLogger(__name__)
 
-    server.add_tool(arxiv_search)
-    server.add_tool(arxiv_download)
-    server.add_tool(s2_get_citations)
-    server.add_tool(s2_get_references)
+    server.add_tool(arxiv_search, structured_output=True)
+    server.add_tool(arxiv_download, structured_output=True)
+    server.add_tool(visit_webpage, structured_output=True)
+    server.add_tool(s2_get_citations, structured_output=True)
+    server.add_tool(s2_get_references, structured_output=True)
+    server.add_tool(s2_get_info, structured_output=True)
     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)
     server.add_tool(yt_transcript)
 
@@ -106,20 +105,20 @@ def run(
 
     if not disable_web_search_tools:
         if settings.TAVILY_API_KEY:
-            server.add_tool(tavily_web_search)
+            server.add_tool(tavily_web_search, structured_output=True)
         if settings.EXA_API_KEY:
-            server.add_tool(exa_web_search)
+            server.add_tool(exa_web_search, structured_output=True)
         if settings.BRAVE_API_KEY:
-            server.add_tool(brave_web_search)
+            server.add_tool(brave_web_search, structured_output=True)
         if settings.EXA_API_KEY or settings.BRAVE_API_KEY or settings.TAVILY_API_KEY:
-            server.add_tool(web_search)
+            server.add_tool(web_search, structured_output=True)
         else:
             logger.warning("No web search tools keys are set, web_search will not be available!")
 
     if not disable_llm_tools and settings.OPENROUTER_API_KEY:
-        server.add_tool(extract_bitflip_info)
-        server.add_tool(generate_research_proposals)
-        server.add_tool(score_research_proposals)
+        server.add_tool(extract_bitflip_info, structured_output=True)
+        server.add_tool(generate_research_proposals, structured_output=True)
+        server.add_tool(score_research_proposals, structured_output=True)
         server.add_tool(document_qa)
         server.add_tool(describe_image)
         if settings.WORKSPACE_DIR:
@@ -140,6 +139,27 @@ def run(
 
     server.settings.port = port
     server.settings.host = host
+    return server
+
+
+def run(
+    host: str = "0.0.0.0",
+    port: Optional[int] = None,
+    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:
+    configure_uvicorn_style_logging()
+    server = create_server(
+        streamable_http_path=streamable_http_path,
+        mount_path=mount_path,
+        disable_web_search_tools=disable_web_search_tools,
+        disable_llm_tools=disable_llm_tools,
+        port=port,
+        host=host,
+    )
 
     if transport == "streamable-http":
         # Enable CORS for browser-based clients

academia_mcp/tools/arxiv_download.py

@@ -3,19 +3,17 @@
 # https://github.com/bytedance/pasa/blob/main/utils.py
 
 import re
-import json
 import tempfile
 from pathlib import Path
-from typing import Any, List, Optional, Dict
-from dataclasses import dataclass, field
+from typing import Any, Dict, List, Optional
 
-import requests
 import bs4
+import requests
 from markdownify import MarkdownConverter  # type: ignore
+from pydantic import BaseModel, Field
 
+from academia_mcp.pdf import download_pdf, parse_pdf_file
 from academia_mcp.utils import get_with_retries
-from academia_mcp.pdf import parse_pdf_file, download_pdf
-
 
 HTML_URL = "https://arxiv.org/html/{paper_id}"
 ABS_URL = "https://arxiv.org/abs/{paper_id}"
@@ -28,12 +26,24 @@ SECTION_STOP_WORDS = (
 )
 
 
-@dataclass
-class TOCEntry:
+class DownloadResponse(BaseModel):  # type: ignore
+    title: str = Field(description="Title of the paper")
+    abstract: str = Field(description="Abstract of the paper")
+    toc: str = Field(description="Table of Contents", default="")
+    sections: Optional[List[str]] = Field(description="Sections of the paper", default=None)
+    references: Optional[List[Dict[str, Any]]] = Field(
+        description="Parsed references from the paper", default=None
+    )
+    original_format: str = Field(
+        description="Original format of the paper (pdf or html)", default="html"
+    )
+
+
+class TOCEntry(BaseModel):  # type: ignore
     level: int
     title: str
     html_id: Optional[str] = None
-    subsections: List["TOCEntry"] = field(default_factory=list)
+    subsections: List["TOCEntry"] = Field(default_factory=list)
 
     def linearize(self) -> List["TOCEntry"]:
         entries = [self]
@@ -196,7 +206,7 @@ def _parse_citation_metadata(metas: List[str]) -> Dict[str, Any]:
     return result
 
 
-def _extract_citations(soup_biblist: bs4.element.Tag) -> List[Dict[str, Any]]:
+def _extract_references(soup_biblist: bs4.element.Tag) -> List[Dict[str, Any]]:
     extracted = []
     for li in soup_biblist.find_all("li", recursive=False):
         metas = [x.text.strip() for x in li.find_all("span", class_="ltx_bibblock")]
@@ -214,17 +224,17 @@ def _parse_html(paper_id: str) -> Dict[str, Any]:
     article = soup.article
     assert article and isinstance(article, bs4.element.Tag)
 
-    citations = []
+    references = []
     biblist_tag = article.find(class_="ltx_biblist")
     if biblist_tag and isinstance(biblist_tag, bs4.element.Tag):
-        citations = _extract_citations(biblist_tag)
+        references = _extract_references(biblist_tag)
 
     toc = _generate_toc(article)
     sections = _build_by_toc(toc, article, url)
     return {
         "toc": toc.to_str(),
         "sections": sections,
-        "citations": citations,
+        "references": references,
         "original_format": "html",
     }
 
@@ -255,36 +265,24 @@ def _parse_pdf(paper_id: str) -> Dict[str, Any]:
     return {
         "toc": "\n".join([f"Page {page_number}" for page_number in range(1, len(pages) + 1)]),
         "sections": pages,
-        "citations": [],
+        "references": [],
         "original_format": "pdf",
     }
 
 
 def arxiv_download(
     paper_id: str,
-    include_citations: Optional[bool] = False,
+    include_references: Optional[bool] = False,
     mode: Optional[str] = "html",
-) -> str:
+) -> DownloadResponse:
     """
     Downloads a paper from Arxiv and converts it to text.
     Use mode = "html" by default.
     Fall back to mode = "pdf" if there are any problems with the HTML version.
 
-    Returns a JSON with a following structure:
-    {
-        "title": "...",
-        "abstract": "...",
-        "toc": "...",
-        "sections": ["...", ...],
-        "citations": [...]
-    }
-    Use `json.loads` to deserialize the result if you want to get specific fields.
-    For example, `abstract = json.loads(arxiv_download("2409.06820v1"))`
-    The "toc" key contains Table of Contents, that sometimes has indexing for sections.
-
     Args:
         paper_id: ID of the paper on Arxiv. For instance: 2409.06820v1
-        include_citations: include "citations" in the result or not. False by default.
+        include_references: include "references" in the result or not. False by default.
         mode: Which version of paper to use. Options: ["html", "pdf"]. "html" by default.
     """
 
@@ -297,7 +295,6 @@ def arxiv_download(
     else:
         content = _parse_pdf(paper_id)
 
-    if not include_citations and "citations" in content:
-        content.pop("citations")
-
-    return json.dumps({**abs_meta, **content}, ensure_ascii=False)
+    if not include_references and "references" in content:
+        content.pop("references")
+    return DownloadResponse(**{**abs_meta, **content})

academia_mcp/tools/arxiv_search.py

@@ -2,12 +2,12 @@
 # https://github.com/jonatasgrosman/findpapers/blob/master/findpapers/searchers/arxiv_searcher.py
 # https://info.arxiv.org/help/api/user-manual.html
 
-import json
 import re
-from typing import Optional, List, Dict, Any, Union
-from datetime import datetime, date
+from datetime import date, datetime
+from typing import Any, Dict, List, Optional, Union
 
 import xmltodict
+from pydantic import BaseModel, Field
 
 from academia_mcp.utils import get_with_retries
 
@@ -17,6 +17,25 @@ SORT_BY_OPTIONS = ("relevance", "lastUpdatedDate", "submittedDate")
 SORT_ORDER_OPTIONS = ("ascending", "descending")
 
 
+class ArxivSearchEntry(BaseModel):  # type: ignore
+    id: str = Field(description="Paper ID")
+    title: str = Field(description="Paper title")
+    authors: str = Field(description="Authors of the paper")
+    published: str = Field(description="Published date of the paper")
+    updated: str = Field(description="Updated date of the paper")
+    categories: str = Field(description="Categories of the paper")
+    comment: str = Field(description="Comment of the paper")
+    index: int = Field(description="Index of the paper", default=0)
+    abstract: Optional[str] = Field(description="Abstract of the paper", default=None)
+
+
+class ArxivSearchResponse(BaseModel):  # type: ignore
+    total_count: int = Field(description="Total number of results")
+    returned_count: int = Field(description="Number of results returned")
+    offset: int = Field(description="Offset for pagination")
+    results: List[ArxivSearchEntry] = Field(description="Search entries")
+
+
 def _format_text_field(text: str) -> str:
     return " ".join([line.strip() for line in text.split() if line.strip()])
 
@@ -48,17 +67,17 @@ def _format_date(date: str) -> str:
     return dt.strftime("%B %d, %Y")
 
 
-def _clean_entry(entry: Dict[str, Any]) -> Dict[str, Any]:
-    return {
-        "id": entry["id"].split("/")[-1],
-        "title": _format_text_field(entry["title"]),
-        "authors": _format_authors(entry["author"]),
-        "abstract": _format_text_field(entry["summary"]),
-        "published": _format_date(entry["published"]),
-        "updated": _format_date(entry["updated"]),
-        "categories": _format_categories(entry.get("category", {})),
-        "comment": _format_text_field(entry.get("arxiv:comment", {}).get("#text", "")),
-    }
+def _clean_entry(entry: Dict[str, Any]) -> ArxivSearchEntry:
+    return ArxivSearchEntry(
+        id=entry["id"].split("/")[-1],
+        title=_format_text_field(entry["title"]),
+        authors=_format_authors(entry["author"]),
+        abstract=_format_text_field(entry["summary"]),
+        published=_format_date(entry["published"]),
+        updated=_format_date(entry["updated"]),
+        categories=_format_categories(entry.get("category", {})),
+        comment=_format_text_field(entry.get("arxiv:comment", {}).get("#text", "")),
+    )
 
 
 def _convert_to_yyyymmddtttt(date_str: str) -> str:
@@ -105,22 +124,19 @@ def _format_entries(
     start_index: int,
     include_abstracts: bool,
     total_results: int,
-) -> str:
+) -> ArxivSearchResponse:
     clean_entries: List[Dict[str, Any]] = []
     for entry_num, entry in enumerate(entries):
         clean_entry = _clean_entry(entry)
         if not include_abstracts:
-            clean_entry.pop("abstract")
-        clean_entry["index"] = start_index + entry_num
+            clean_entry.abstract = None
+        clean_entry.index = start_index + entry_num
         clean_entries.append(clean_entry)
-    return json.dumps(
-        {
-            "total_count": total_results,
-            "returned_count": len(entries),
-            "offset": start_index,
-            "results": clean_entries,
-        },
-        ensure_ascii=False,
+    return ArxivSearchResponse(
+        total_count=total_results,
+        returned_count=len(entries),
+        offset=start_index,
+        results=clean_entries,
     )
 
 
@@ -133,7 +149,7 @@ def arxiv_search(
     sort_by: Optional[str] = "relevance",
     sort_order: Optional[str] = "descending",
     include_abstracts: Optional[bool] = False,
-) -> str:
+) -> ArxivSearchResponse:
     """
     Search arXiv papers with field-specific queries.
 
@@ -158,12 +174,6 @@ def arxiv_search(
         all:role OR all:playing OR all:"language model"
         (au:vaswani OR au:"del maestro") ANDNOT ti:attention
 
-    Returns a JSON object serialized to a string. The structure is:
-    {"total_count": ..., "returned_count": ..., "offset": ..., "results": [...]}
-    Every item in the "results" has the following fields:
-    ("index", "id", "title", "authors", "abstract", "published", "updated", "categories", "comment")
-    Use `json.loads` to deserialize the result if you want to get specific fields.
-
     Args:
         query: The search query, required.
         offset: The offset to scroll search results. 10 items will be skipped if offset=10. 0 by default.
@@ -211,10 +221,9 @@ def arxiv_search(
     entries = feed.get("entry", [])
     if isinstance(entries, dict):
         entries = [entries]
-    formatted_entries: str = _format_entries(
+    return _format_entries(
         entries,
         start_index=start_index,
         total_results=total_results,
         include_abstracts=include_abstracts,
     )
-    return formatted_entries

academia_mcp/tools/bitflip.py

@@ -1,17 +1,18 @@
+# Based on
 # https://arxiv.org/abs/2504.12976
 # https://web.stanford.edu/class/cs197c/slides/02-literature-search.pdf
 
 import json
 import random
-from typing import List, Optional, Any, Dict
+from typing import Any, Dict, List, Optional
 
-from pydantic import BaseModel
 from datasets import load_dataset  # type: ignore
+from pydantic import BaseModel, Field
 
-from academia_mcp.tools.arxiv_download import arxiv_download
-from academia_mcp.utils import extract_json, encode_prompt
-from academia_mcp.llm import llm_acall, ChatMessage
+from academia_mcp.llm import ChatMessage, llm_acall
 from academia_mcp.settings import settings
+from academia_mcp.tools.arxiv_download import arxiv_download
+from academia_mcp.utils import encode_prompt, extract_json
 
 
 class ProposalDataset:
@@ -128,7 +129,7 @@ Return only the JSON list of proposals in this exact format:
         "spark": "4-6 word summary",
         "abstract": "An abstract that summarizes the proposal in conference format (approximately 250 words).",
         "experiments": ["...", "..."],
-        "risks_and_limitations": "A list of potential risks and limitations of the proposal."
+        "risks_and_limitations": ["...", "..."]
     },
     ...
 ]
@@ -177,12 +178,12 @@ Return only scores for all proposals in this exact format (no extra text):
 
 
 class BitFlipInfo(BaseModel):  # type: ignore
-    bit: str
-    flip: str
-    spark: str
+    bit: str = Field(description="Technical limitation or conventional approach")
+    flip: str = Field(description="Innovative approach or solution")
+    spark: str = Field(description="4-6 word summary")
 
 
-async def extract_bitflip_info(arxiv_id: str) -> str:
+async def extract_bitflip_info(arxiv_id: str) -> BitFlipInfo:
     """
     Extracts the Bit-Flip information from the arXiv paper.
 
@@ -190,20 +191,12 @@ async def extract_bitflip_info(arxiv_id: str) -> str:
     questioning existing constraints or reapplying techniques to new domains/scales.
     The "Bit" is the prevailing belief, and the "Flip" is the counterargument.
 
-    Returns a JSON object in this format:
-    {
-        "bit": "Technical limitation or conventional approach, in at least two sentences",
-        "flip": "Innovative approach or solution, in at least two sentences",
-        "spark": "4-6 word summary of the core idea"
-    }
-    Use `json.loads` to deserialize the result if you want to get specific fields.
-
     Args:
         arxiv_id: The arXiv ID of the paper to extract the Bit-Flip information from.
     """
     model_name = settings.BITFLIP_MODEL_NAME
     paper = arxiv_download(arxiv_id)
-    abstract = json.loads(paper)["abstract"]
+    abstract = paper.abstract
     prompt = encode_prompt(EXTRACT_PROMPT, abstract=abstract)
     content = await llm_acall(
         model_name=model_name,
@@ -212,12 +205,31 @@ async def extract_bitflip_info(arxiv_id: str) -> str:
     )
     result = extract_json(content)
     bitflip_info: BitFlipInfo = BitFlipInfo.model_validate(result)
-    return str(bitflip_info.model_dump_json())
+    return bitflip_info
+
+
+class ResearchProposal(BaseModel):  # type: ignore
+    proposal_id: int = Field(default=0, description="ID of the proposal")
+    flip: str = Field(description="Innovative approach or solution, in at least two sentences")
+    spark: str = Field(description="4-6 word summary")
+    abstract: str = Field(
+        description="An abstract that summarizes the proposal in conference format."
+    )
+    experiments: List[str] = Field(
+        description="A list of experiments that would be conducted to validate the proposal."
+    )
+    risks_and_limitations: List[str] = Field(
+        description="A list of potential risks and limitations of the proposal."
+    )
+
+
+class GenerateResearchProposalResponse(BaseModel):  # type: ignore
+    proposals: List[ResearchProposal] = Field(description="A list of research proposals")
 
 
 async def generate_research_proposals(
     bit: str, num_proposals: int = 3, additional_context: str = ""
-) -> str:
+) -> GenerateResearchProposalResponse:
     """
     Proposes improvement ideas for the Bit.
 
@@ -225,20 +237,6 @@ async def generate_research_proposals(
         bit: The Bit to propose improvement ideas for. The bit is a technical limitation or conventional approach of some paper.
         num_proposals: The number of proposals to generate.
         additional_context: Additional context to use when proposing the improvement idea.
-
-    Returns a JSON string with a research proposal in this format:
-    [
-        {
-            "proposal_id": ...,
-            "flip": "Innovative approach or solution, in at least two sentences",
-            "spark": "4-6 word summary",
-            "abstract": "An abstract that summarizes the proposal in conference format (approximately 250 words).",
-            "experiments": ["...", "..."],
-            "risks_and_limitations": "A list of potential risks and limitations of the proposal."
-        },
-        ...
-    ]
-    Use `json.loads` to deserialize the result if you want to get specific items.
     """
     model_name = settings.BITFLIP_MODEL_NAME
     max_completion_tokens = int(settings.BITFLIP_MAX_COMPLETION_TOKENS)
@@ -262,46 +260,51 @@ async def generate_research_proposals(
         temperature=1.0,
     )
     result = extract_json(content)
-    for proposal in result:
-        proposal["proposal_id"] = random.randint(0, 1000000)
-    return json.dumps(result, ensure_ascii=False)
+    return GenerateResearchProposalResponse(
+        proposals=[ResearchProposal.model_validate(proposal) for proposal in result]
+    )
+
+
+class ScoredProposal(BaseModel):  # type: ignore
+    proposal_id: int = Field(default=0, description="ID of the proposal")
+    spark: str = Field(description="4-6 word summary")
+    strengths: List[str] = Field(description="A list of strengths of the proposal")
+    weaknesses: List[str] = Field(description="A list of weaknesses of the proposal")
+    novelty: int = Field(description="Novelty rating from 1 to 4")
+    clarity: int = Field(description="Clarity rating from 1 to 4")
+    significance: int = Field(description="Significance rating from 1 to 4")
+    feasibility: int = Field(description="Feasibility rating from 1 to 4")
+    soundness: int = Field(description="Soundness rating from 1 to 4")
+    overall: int = Field(description="Overall rating from 1 to 10")
 
 
-async def score_research_proposals(proposals: str | List[str | Dict[str, Any] | Any]) -> str:
+class ScoreResearchProposalsResponse(BaseModel):  # type: ignore
+    proposals: List[ScoredProposal] = Field(description="List of scored proposals")
+
+
+async def score_research_proposals(
+    proposals: str | List[str | Dict[str, Any] | Any],
+) -> ScoreResearchProposalsResponse:
     """
     Scores a list of research proposals.
     Use proposals obtained with the `generate_research_proposal` tool.
 
-    Returns a JSON string with a list of scores in this format:
-    [
-        {
-            "proposal_id": 0,
-            "spark": "...",
-            "strengths": ["...", "..."],
-            "weaknesses": ["...", "..."],
-            "novelty": 2,
-            "clarity": 2,
-            "significance": 2,
-            "feasibility": 2,
-            "soundness": 2,
-            "overall": 5
-        },
-        ...
-    ]
-    Use `json.loads` to deserialize the result if you want to get specific fields.
-
     Args:
         proposals: A list of JSON strings with research proposals.
     """
     model_name = settings.BITFLIP_MODEL_NAME
     if isinstance(proposals, str):
         proposals = json.loads(proposals)
-        assert isinstance(proposals, list), "Proposals should be a list of JSON strings"
-    prompt = encode_prompt(SCORE_PROMPT, proposals=[str(p) for p in proposals])
+        assert isinstance(proposals, list), "Proposals should be a list"
+    if isinstance(proposals, list):
+        proposals = [str(p) for p in proposals]
+    prompt = encode_prompt(SCORE_PROMPT, proposals=proposals)
     content = await llm_acall(
         model_name=model_name,
         messages=[ChatMessage(role="user", content=prompt)],
         temperature=0.0,
     )
     scores = extract_json(content)
-    return json.dumps(scores, ensure_ascii=False)
+    return ScoreResearchProposalsResponse(
+        proposals=[ScoredProposal.model_validate(score) for score in scores]
+    )

academia_mcp/tools/s2.py

@@ -1,9 +1,10 @@
 # Based on
 # https://api.semanticscholar.org/api-docs/graph#tag/Paper-Data/operation/get_graph_get_paper_citations
 
-import json
 from typing import Optional, List, Dict, Any
 
+from pydantic import BaseModel, Field
+
 from academia_mcp.utils import get_with_retries
 
 
@@ -13,42 +14,58 @@ REFERENCES_URL_TEMPLATE = "https://api.semanticscholar.org/graph/v1/paper/{paper
 FIELDS = "title,authors,externalIds,venue,citationCount,publicationDate"
 
 
+class S2PaperInfo(BaseModel):  # type: ignore
+    arxiv_id: Optional[str] = Field(description="ArXiv ID of the paper", default=None)
+    external_ids: Optional[Dict[str, Any]] = Field(
+        description="External IDs of the paper.", default=None
+    )
+    title: str = Field(description="Paper title")
+    authors: List[str] = Field(description="Authors of the paper")
+    venue: str = Field(description="Paper venue")
+    citation_count: Optional[int] = Field(description="Paper citation count", default=None)
+    publication_date: Optional[str] = Field(description="Paper publication date", default=None)
+
+
+class S2SearchResponse(BaseModel):  # type: ignore
+    total_count: int = Field(description="Total number of results.")
+    returned_count: int = Field(description="Number of results returned.")
+    offset: int = Field(description="Offset of the results.")
+    results: List[S2PaperInfo] = Field(description="Search entries")
+
+
 def _format_authors(authors: List[Dict[str, Any]]) -> List[str]:
     return [a["name"] for a in authors]
 
 
-def _clean_entry(entry: Dict[str, Any]) -> Dict[str, Any]:
+def _clean_entry(entry: Dict[str, Any]) -> S2PaperInfo:
     entry = entry["citingPaper"] if "citingPaper" in entry else entry["citedPaper"]
     external_ids = entry.get("externalIds")
     if not external_ids:
         external_ids = dict()
     external_ids.pop("CorpusId", None)
     arxiv_id = external_ids.pop("ArXiv", None)
-    return {
-        "arxiv_id": arxiv_id,
-        "external_ids": external_ids if external_ids else None,
-        "title": entry["title"],
-        "authors": _format_authors(entry["authors"]),
-        "venue": entry.get("venue", ""),
-        "citation_count": entry.get("citationCount", 0),
-        "publication_date": entry.get("publicationDate", ""),
-    }
+    return S2PaperInfo(
+        arxiv_id=arxiv_id,
+        external_ids=external_ids if external_ids else None,
+        title=entry["title"],
+        authors=_format_authors(entry["authors"]),
+        venue=entry.get("venue", ""),
+        citation_count=entry.get("citationCount"),
+        publication_date=entry.get("publicationDate"),
+    )
 
 
 def _format_entries(
     entries: List[Dict[str, Any]],
     start_index: int,
     total_results: int,
-) -> str:
+) -> S2SearchResponse:
     clean_entries = [_clean_entry(e) for e in entries]
-    return json.dumps(
-        {
-            "total_count": total_results,
-            "returned_count": len(entries),
-            "offset": start_index,
-            "results": clean_entries,
-        },
-        ensure_ascii=False,
+    return S2SearchResponse(
+        total_count=total_results,
+        returned_count=len(entries),
+        offset=start_index,
+        results=clean_entries,
     )
 
 
@@ -56,16 +73,10 @@ def s2_get_citations(
     arxiv_id: str,
     offset: Optional[int] = 0,
     limit: Optional[int] = 50,
-) -> str:
+) -> S2SearchResponse:
     """
     Get all papers that cited a given arXiv paper based on Semantic Scholar info.
 
-    Returns a JSON object serialized to a string. The structure is:
-    {"total_count": ..., "returned_count": ..., "offset": ..., "results": [...]}
-    Every item in the "results" has the following fields:
-    ("arxiv_id", "external_ids", "title", "authors", "venue", "citation_count", "publication_date")
-    Use `json.loads` to deserialize the result if you want to get specific fields.
-
     Args:
         arxiv_id: The ID of a given arXiv paper.
         offset: The offset to scroll through citations. 10 items will be skipped if offset=10. 0 by default.
@@ -98,16 +109,10 @@ def s2_get_references(
     arxiv_id: str,
     offset: Optional[int] = 0,
     limit: Optional[int] = 50,
-) -> str:
+) -> S2SearchResponse:
     """
     Get all papers that were cited by a given arXiv paper (references) based on Semantic Scholar info.
 
-    Returns a JSON object serialized to a string. The structure is:
-    {"total_count": ..., "returned_count": ..., "offset": ..., "results": [...]}
-    Every item in the "results" has the following fields:
-    ("arxiv_id", "external_ids", "title", "authors", "venue", "citation_count", "publication_date")
-    Use `json.loads` to deserialize the result if you want to get specific fields.
-
     Args:
         arxiv_id: The ID of a given arXiv paper.
         offset: The offset to scroll through citations. 10 items will be skipped if offset=10. 0 by default.
@@ -144,14 +149,10 @@ def s2_corpus_id_from_arxiv_id(arxiv_id: str) -> int:
     return int(result["externalIds"]["CorpusId"])
 
 
-def s2_get_info(arxiv_id: str) -> str:
+def s2_get_info(arxiv_id: str) -> S2PaperInfo:
     """
     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.
     """
@@ -160,4 +161,13 @@ def s2_get_info(arxiv_id: str) -> str:
         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)
+    json_data = response.json()
+    return S2PaperInfo(
+        arxiv_id=json_data.get("externalIds", {}).get("ArXiv"),
+        external_ids=json_data.get("externalIds", {}),
+        title=json_data["title"],
+        authors=_format_authors(json_data["authors"]),
+        venue=json_data.get("venue", ""),
+        citation_count=int(json_data.get("citationCount", 0)),
+        publication_date=str(json_data.get("publicationDate", "")),
+    )

academia_mcp/tools/show_image.py

@@ -30,7 +30,20 @@ DESCRIBE_PROMPTS = {
         4. Any immediate tactical opportunities or threats
         5. Suggested next moves with brief explanations"""
     ),
-    "text": "Extract and describe any text present in this image. If there are multiple pieces of text, organize them clearly.",
+    "text": dedent(
+        """You are performing OCR and transcription.
+        Extract ALL text and numbers from the image verbatim.
+        - Preserve original casing, punctuation, symbols, mathematical notation, and whitespace layout when possible.
+        - If layout is multi-column or tabular, reconstruct lines top-to-bottom, left-to-right; use line breaks between blocks.
+        - For any uncertain or low-confidence characters, mark with a '?' and include a note.
+        - After the raw extraction, provide a clean, normalized version (fixing obvious OCR artifacts) as a separate section.
+        Return two sections:
+        [RAW TRANSCRIPTION]
+        ...
+        [NORMALIZED]
+        ...
+        """
+    ),
 }
 
 
@@ -44,10 +57,8 @@ def show_image(path: str) -> Dict[str, str]:
     ```
     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
+        path: Path to file inside current work directory or web URL
     """
     if path.startswith("http"):
         response = httpx.get(path, timeout=10)
@@ -80,7 +91,7 @@ async def describe_image(
             - "general": General description of the image
             - "detailed": Detailed analysis of the image
             - "chess": Analysis of a chess position
-            - "text": Extract and describe text from the image
+            - "text": Extract and describe text or numbers from the image
             - "custom": Custom description based on user prompt
     """
     image_base64 = show_image(path)["image_base64"]
@@ -93,12 +104,16 @@ async def describe_image(
         {"type": "text", "text": prompt},
         {
             "type": "image_url",
-            "image_url": {"url": f"data:image/jpeg;base64,{image_base64}"},
+            "image_url": {"url": f"data:image/png;base64,{image_base64}"},
         },
     ]
     model_name = settings.DESCRIBE_IMAGE_MODEL_NAME
+    llm_kwargs = {}
+    if description_type in {"text", "chess"}:
+        llm_kwargs["temperature"] = 0.0
     response = await llm_acall(
         model_name=model_name,
         messages=[ChatMessage(role="user", content=content)],
+        **llm_kwargs,
     )
     return response

academia_mcp/tools/visit_webpage.py

@@ -1,12 +1,11 @@
 import re
-import json
-from typing import Optional, Dict, Any, cast
+from typing import Any, Dict, List, Optional
 
 from markdownify import markdownify  # type: ignore
+from pydantic import BaseModel, Field
 
-from academia_mcp.utils import get_with_retries, post_with_retries
 from academia_mcp.settings import settings
-from academia_mcp.utils import sanitize_output
+from academia_mcp.utils import get_with_retries, post_with_retries, sanitize_output
 
 EXA_CONTENTS_URL = "https://api.exa.ai/contents"
 TAVILY_EXTRACT_URL = "https://api.tavily.com/extract"
@@ -14,6 +13,16 @@ AVAILABLE_PROVIDERS = ("basic", "exa", "tavily")
 ERROR_MESSAGE = "Failed to get content from the page. Try to use another provider."
 
 
+class VisitWebpageResponse(BaseModel):  # type: ignore
+    id: str = Field(description="ID of the webpage, usually the URL")
+    provider: str = Field(description="Provider used to get the content")
+    text: Optional[str] = Field(description="Text content of the webpage", default=None)
+    images: List[str] = Field(description="Images of the webpage", default_factory=list)
+    error: Optional[str] = Field(
+        description="Error message if the webpage is not found", default=None
+    )
+
+
 def _exa_visit_webpage(url: str) -> Dict[str, Any]:
     key = settings.EXA_API_KEY or ""
     assert key, "Error: EXA_API_KEY is not set and no api_key was provided"
@@ -25,7 +34,7 @@ def _exa_visit_webpage(url: str) -> Dict[str, Any]:
     results = response.json()["results"]
     if not results:
         return {"error": ERROR_MESSAGE}
-    return cast(Dict[str, Any], results[0])
+    return {"text": results[0]["text"]}
 
 
 def _tavily_visit_webpage(url: str) -> Dict[str, Any]:
@@ -33,12 +42,15 @@ def _tavily_visit_webpage(url: str) -> Dict[str, Any]:
     assert key, "Error: TAVILY_API_KEY is not set and no api_key was provided"
     payload = {
         "urls": [url],
+        "extract_depth": "advanced",
+        "include_images": True,
     }
     response = post_with_retries(TAVILY_EXTRACT_URL, payload=payload, api_key=key)
     results = response.json()["results"]
     if not results:
         return {"error": ERROR_MESSAGE}
-    return {"text": results[0]["raw_content"]}
+    result = results[0]
+    return {"text": result["raw_content"], "images": result["images"]}
 
 
 def _basic_visit_webpage(url: str) -> Dict[str, Any]:
@@ -58,13 +70,9 @@ def _basic_visit_webpage(url: str) -> Dict[str, Any]:
         return {"error": str(e) + "\n" + ERROR_MESSAGE}
 
 
-def visit_webpage(url: str, provider: Optional[str] = "basic") -> str:
+def visit_webpage(url: str, provider: Optional[str] = "basic") -> VisitWebpageResponse:
     """
     Visit a webpage and return the content.
-
-    Returns a JSON object serialized to a string. The structure is: {"id": "...", "text": "..."}.
-    If there are errors, the structure is: {"id": "...", "error": "..."}.
-    Use `json.loads` to deserialize the result if you want to get specific fields.
     Try to use both "tavily" and "basic" providers. They might work differently for the same URL.
 
     Args:
@@ -82,6 +90,9 @@ def visit_webpage(url: str, provider: Optional[str] = "basic") -> str:
     else:
         result = _basic_visit_webpage(url)
 
-    result["id"] = url
-    result["provider"] = provider
-    return sanitize_output(json.dumps(result, ensure_ascii=False))
+    result = VisitWebpageResponse(id=url, provider=provider, **result)
+    if result.text:
+        result.text = sanitize_output(result.text)
+    if result.error:
+        result.error = sanitize_output(result.error)
+    return result

academia_mcp/tools/web_search.py

@@ -1,10 +1,9 @@
-import json
-from typing import Optional, List, Tuple
+from typing import List, Optional, Tuple
 
-from academia_mcp.utils import post_with_retries, get_with_retries
-from academia_mcp.settings import settings
-from academia_mcp.utils import sanitize_output
+from pydantic import BaseModel, Field
 
+from academia_mcp.settings import settings
+from academia_mcp.utils import get_with_retries, post_with_retries, sanitize_output
 
 EXA_SEARCH_URL = "https://api.exa.ai/search"
 TAVILY_SEARCH_URL = "https://api.tavily.com/search"
@@ -30,20 +29,27 @@ def _parse_domains(query: str) -> Tuple[str, List[str]]:
     return query, include_domains
 
 
+class WebSearchEntry(BaseModel):  # type: ignore
+    id: str = Field(description="ID of the search entry, usually the URL")
+    title: str = Field(description="Title of the web page")
+    content: str = Field(description="Content of the web page")
+
+
+class WebSearchResponse(BaseModel):  # type: ignore
+    results: List[WebSearchEntry] = Field(description="Results of the search")
+    search_provider: str = Field(description="Provider used to get the results")
+
+
 def web_search(
     query: str,
     limit: Optional[int] = 20,
     provider: Optional[str] = "tavily",
     include_domains: Optional[List[str]] = None,
-) -> str:
+) -> WebSearchResponse:
     """
     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")
-    Use `json.loads` to deserialize the result if you want to get specific fields.
-
     Args:
         query: The search query, required.
         limit: The maximum number of items to return. 20 by default, maximum 25.
@@ -81,27 +87,23 @@ def web_search(
                 provider = p
                 break
 
-    result = {}
+    result: Optional[WebSearchResponse] = None
     if provider == "exa":
-        result = json.loads(exa_web_search(query, limit, include_domains=include_domains))
+        result = exa_web_search(query, limit, include_domains=include_domains)
     elif provider == "brave":
-        result = json.loads(brave_web_search(query, limit))
+        result = brave_web_search(query, limit)
     elif provider == "tavily":
-        result = json.loads(tavily_web_search(query, limit, include_domains=include_domains))
-    result["search_provider"] = provider
-    return sanitize_output(json.dumps(result, ensure_ascii=False))
+        result = tavily_web_search(query, limit, include_domains=include_domains)
+    assert result is not None, "Error: No provider was available"
+    return result
 
 
 def tavily_web_search(
     query: str, limit: Optional[int] = 20, include_domains: Optional[List[str]] = None
-) -> str:
+) -> WebSearchResponse:
     """
     Search the web using Tavily and return results.
 
-    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")
-    Use `json.loads` to deserialize the result if you want to get specific fields.
-
     Args:
         query: The search query, required.
         limit: The maximum number of items to return. 20 by default, maximum 25.
@@ -131,23 +133,23 @@ def tavily_web_search(
     results = response.json()["results"]
     for result in results:
         content = " ".join(result["content"].split(" ")[:40])
-        content = content.strip("., ")
+        content = sanitize_output(content.strip("., "))
         result["content"] = content
         result.pop("raw_content", None)
         result.pop("score", None)
-    return sanitize_output(json.dumps({"results": results}, ensure_ascii=False))
+    entries = [
+        WebSearchEntry(id=result["url"], title=result["title"], content=result["content"])
+        for result in results
+    ]
+    return WebSearchResponse(results=entries, search_provider="tavily")
 
 
 def exa_web_search(
     query: str, limit: Optional[int] = 20, include_domains: Optional[List[str]] = None
-) -> str:
+) -> WebSearchResponse:
     """
     Search the web using Exa and return results.
 
-    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")
-    Use `json.loads` to deserialize the result if you want to get specific fields.
-
     Args:
         query: The search query, required.
         limit: The maximum number of items to return. 20 by default, maximum 25.
@@ -184,17 +186,18 @@ def exa_web_search(
 
     response = post_with_retries(EXA_SEARCH_URL, payload, key)
     results = response.json()["results"]
-    return sanitize_output(json.dumps({"results": results}, ensure_ascii=False))
+    entries = []
+    for result in results:
+        content = " || ".join(result["highlights"])
+        content = sanitize_output(content)
+        entries.append(WebSearchEntry(id=result["url"], title=result["title"], content=content))
+    return WebSearchResponse(results=entries, search_provider="exa")
 
 
-def brave_web_search(query: str, limit: Optional[int] = 20) -> str:
+def brave_web_search(query: str, limit: Optional[int] = 20) -> WebSearchResponse:
     """
     Search the web using Brave and return results.
 
-    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")
-    Use `json.loads` to deserialize the result if you want to get specific fields.
-
     Args:
         query: The search query, required.
         limit: The maximum number of items to return. 20 by default, maximum 20.
@@ -212,4 +215,8 @@ def brave_web_search(query: str, limit: Optional[int] = 20) -> str:
     }
     response = get_with_retries(BRAVE_SEARCH_URL, key, params=payload)
     results = response.json()["web"]["results"]
-    return sanitize_output(json.dumps({"results": results}, ensure_ascii=False))
+    entries = []
+    for result in results:
+        content = sanitize_output(result["description"])
+        entries.append(WebSearchEntry(id=result["url"], title=result["title"], content=content))
+    return WebSearchResponse(results=entries, search_provider="brave")

academia_mcp/utils.py

@@ -171,6 +171,8 @@ def sanitize_output(output: str) -> str:
     """
     See https://github.com/modelcontextprotocol/python-sdk/issues/1144#issuecomment-3076506124
     """
+    if not output:
+        return output
     output = output.replace("\x85", " ")
     output = output.replace("\u0085", " ")
     return output

{academia_mcp-1.10.9.dist-info → academia_mcp-1.11.1.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: academia-mcp
-Version: 1.10.9
+Version: 1.11.1
 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

{academia_mcp-1.10.9.dist-info → academia_mcp-1.11.1.dist-info}/RECORD

@@ -4,30 +4,30 @@ academia_mcp/files.py,sha256=ynIt0XbU1Z7EPWkv_hVX0pGKsLlmjYv-MVJLOfi6yzs,817
 academia_mcp/llm.py,sha256=zpGkuJFf58Ofgys_fi28-47_wJ1a7sIs_yZvI1Si6z0,993
 academia_mcp/pdf.py,sha256=9PlXzHGhb6ay3ldbTdxCcTWvH4TkET3bnb64mgoh9i0,1273
 academia_mcp/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-academia_mcp/server.py,sha256=tZ57YkW2EcW4DRIk87n2PFZkkTjAVsVQ5lphvc1AVA4,5517
+academia_mcp/server.py,sha256=uJNV5YStMJ3sEbx4waOclSw_hN0Gkz5PJ-q8VjX1kfA,6390
 academia_mcp/settings.py,sha256=c5s4dI8V_cWmMED-jKDmHjfdIaBcxwEK4HdHNQ3WUIg,1096
-academia_mcp/utils.py,sha256=lRlb615JJ_0d4gcFpMoBjB6w0xXcde9dFDw0LwYpSPQ,4863
+academia_mcp/utils.py,sha256=ixtYI7qidFJpc8Tzc5sokseCLx4r0yFFgbktKaY-Ixo,4904
 academia_mcp/latex_templates/agents4science_2025/agents4science_2025.sty,sha256=hGcEPCYBJS4vdhWvN_yEaJC4GvT_yDroI94CfY2Oguk,12268
 academia_mcp/latex_templates/agents4science_2025/agents4science_2025.tex,sha256=Tl1QkHXHRopw9VEfWrD3Layr5JP_0gIzVQjL4KXIWqc,15814
 academia_mcp/tools/__init__.py,sha256=Z30vULZwUeUX5nDz5wcv0znhAeBtZRa0dvz7vD8SUYE,1555
 academia_mcp/tools/anthology_search.py,sha256=rhFpJZqGLABgr0raDuH0CARBiAJNJtEI4dlMrKNHfDQ,7669
-academia_mcp/tools/arxiv_download.py,sha256=gBY0_Kz0yGtVkLMwn6GrAyfBjovZVgcSMuyy67p65Cw,10474
-academia_mcp/tools/arxiv_search.py,sha256=pzM18qrF3QL03A53w003kE7hQi3s3QKtjgw0m7K88UY,8355
-academia_mcp/tools/bitflip.py,sha256=1B-EEcDnJjB9YmvVWsGv_Un19Bkeud9SZDw2TpGTCSg,12184
+academia_mcp/tools/arxiv_download.py,sha256=4zl9QkWF7uU2BYz4XH7Fu_51htolSYtO7a2v4_ikhxg,10633
+academia_mcp/tools/arxiv_search.py,sha256=p4DeCvV3TUpj58etx0QOxm-GYKAWkP9AGjLv4HUUqUc,8857
+academia_mcp/tools/bitflip.py,sha256=0OPxQRU5VLWrcIlj4Ubjeq4gIq0pR5FDhXDHuLR0ppw,12759
 academia_mcp/tools/document_qa.py,sha256=Wb2nEEVu9UyPp8ktHWeT9wS2JBle8fb9zRjTNVIDdBE,2463
 academia_mcp/tools/hf_datasets_search.py,sha256=KiBkqT4rXjEN4oc1AWZOPnqN_Go90TQogY5-DUm3LQo,2854
 academia_mcp/tools/latex.py,sha256=B1Leqt1FHY6H3DlUgeYse4LMFpf4-K1FQViXl5MKk8A,6144
 academia_mcp/tools/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 academia_mcp/tools/review.py,sha256=Va0lFJJKuk-NvWhKS3UZ-Dnuk7CyuDQ4S1nd70D-ffE,11117
-academia_mcp/tools/s2.py,sha256=QX7-pbetab3Xt_1tvVPU6o5D_NAe9y6jcTGRBK1vwtY,6200
-academia_mcp/tools/show_image.py,sha256=jiJlQ53dbZ0T61OBhCT3IKVvBl9NHc6jHgWLfg5BxiE,3856
+academia_mcp/tools/s2.py,sha256=ykJOkpHnyZRlfyDnCIL9m-Rnu5dBecoKxg0SjlzdvLk,6457
+academia_mcp/tools/show_image.py,sha256=DWSnYMTn_dJpGTLL1r_sbX5XsB6p9z-vClApDANz84s,4534
 academia_mcp/tools/speech_to_text.py,sha256=YZzMqdvunzXkpcadP_mYhm6cs4qH1Y_42SfY-7eX4O4,1601
-academia_mcp/tools/visit_webpage.py,sha256=swlFwWRzWc7-AHP2ouRZJScSTA4dHZ32fuJnA2V0lUc,3311
-academia_mcp/tools/web_search.py,sha256=VphVztf2jZNT3bPJPJuTdMkKbe2-LIbSV7keKV47lac,8616
+academia_mcp/tools/visit_webpage.py,sha256=uJZx9vBGS8q-J-VH4Pr7T9lNtDsWU83gJhlotcd1ajg,3788
+academia_mcp/tools/web_search.py,sha256=CHgco8DufTFwtVecgDOOMylIY99iUmCdb0oZtpGntx0,8646
 academia_mcp/tools/yt_transcript.py,sha256=ilfOpX14moC1bKHbFmOVvZ8-_NxuQQUoQbV28e9FBaE,1217
-academia_mcp-1.10.9.dist-info/licenses/LICENSE,sha256=xx0jnfkXJvxRnG63LTGOxlggYnIysveWIZ6H3PNdCrQ,11357
-academia_mcp-1.10.9.dist-info/METADATA,sha256=GA4c2pahSKkxfT_UUV-DtwFiN7Qu4uR5FgRyW9tcn7o,6356
-academia_mcp-1.10.9.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
-academia_mcp-1.10.9.dist-info/entry_points.txt,sha256=gxkiKJ74w2FwJpSECpjA3XtCfI5ZfrM6N8cqnwsq4yY,51
-academia_mcp-1.10.9.dist-info/top_level.txt,sha256=CzGpRFsRRJRqWEb1e3SUlcfGqRzOxevZGaJWrtGF8W0,13
-academia_mcp-1.10.9.dist-info/RECORD,,
+academia_mcp-1.11.1.dist-info/licenses/LICENSE,sha256=xx0jnfkXJvxRnG63LTGOxlggYnIysveWIZ6H3PNdCrQ,11357
+academia_mcp-1.11.1.dist-info/METADATA,sha256=e8HbUnRcj5HSHxC7soI4yRFpO5-xyoL_4kMYTUNPwK0,6356
+academia_mcp-1.11.1.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+academia_mcp-1.11.1.dist-info/entry_points.txt,sha256=gxkiKJ74w2FwJpSECpjA3XtCfI5ZfrM6N8cqnwsq4yY,51
+academia_mcp-1.11.1.dist-info/top_level.txt,sha256=CzGpRFsRRJRqWEb1e3SUlcfGqRzOxevZGaJWrtGF8W0,13
+academia_mcp-1.11.1.dist-info/RECORD,,