academia-mcp 1.9.2__py3-none-any.whl → 1.10.1__py3-none-any.whl

academia_mcp/server.py

@@ -38,7 +38,8 @@ 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
+from academia_mcp.tools.show_image import show_image, describe_image
+from academia_mcp.tools.speech_to_text import speech_to_text
 
 
 def configure_uvicorn_style_logging(level: int = logging.INFO) -> None:
@@ -116,11 +117,17 @@ def run(
         server.add_tool(generate_research_proposals)
         server.add_tool(score_research_proposals)
         server.add_tool(document_qa)
+        server.add_tool(describe_image)
         if settings.WORKSPACE_DIR:
             server.add_tool(review_pdf_paper)
     else:
         logger.warning("No OpenRouter API key is set, LLM-related tools will not be available!")
 
+    if settings.OPENAI_API_KEY:
+        server.add_tool(speech_to_text)
+    else:
+        logger.warning("No OpenAI API key is set, speech_to_text will not be available!")
+
     if port is None:
         if settings.PORT is not None:
             port = int(settings.PORT)

academia_mcp/settings.py

@@ -11,6 +11,7 @@ class Settings(BaseSettings):
     TAVILY_API_KEY: Optional[str] = None
     EXA_API_KEY: Optional[str] = None
     BRAVE_API_KEY: Optional[str] = None
+    OPENAI_API_KEY: Optional[str] = None
 
     REVIEW_MODEL_NAME: str = "gpt-5"
     BITFLIP_MODEL_NAME: str = "deepseek/deepseek-chat-v3-0324"
@@ -18,6 +19,7 @@ class Settings(BaseSettings):
     DOCUMENT_QA_MODEL_NAME: str = "deepseek/deepseek-chat-v3-0324"
     DOCUMENT_QA_QUESTION_MAX_LENGTH: int = 10000
     DOCUMENT_QA_DOCUMENT_MAX_LENGTH: int = 200000
+    DESCRIBE_IMAGE_MODEL_NAME: str = "gpt-4.1"
 
     PORT: int = 5056
     WORKSPACE_DIR: Optional[Path] = None

academia_mcp/tools/__init__.py

@@ -14,7 +14,8 @@ 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
+from .show_image import show_image, describe_image
+from .speech_to_text import speech_to_text
 
 __all__ = [
     "arxiv_search",
@@ -42,4 +43,6 @@ __all__ = [
     "download_pdf_paper",
     "read_pdf",
     "show_image",
+    "describe_image",
+    "speech_to_text",
 ]

academia_mcp/tools/show_image.py

@@ -1,13 +1,37 @@
 import base64
 from pathlib import Path
 from io import BytesIO
-from typing import Dict
+from typing import Dict, Optional
+from textwrap import dedent
 
 import httpx
 from PIL import Image
 
 from academia_mcp.files import get_workspace_dir
 from academia_mcp.settings import settings
+from academia_mcp.llm import llm_acall, ChatMessage
+
+
+DESCRIBE_PROMPTS = {
+    "general": "Provide a general description of this image. Focus on the main subjects, colors, and overall scene.",
+    "detailed": dedent(
+        """Analyze this image in detail. Include:
+        1. Main subjects and their relationships
+        2. Colors, lighting, and composition
+        3. Any text or symbols present
+        4. Context or possible meaning
+        5. Notable details or interesting elements"""
+    ),
+    "chess": dedent(
+        """Analyze this chess position and provide a detailed description including:
+        1. List of pieces on the board for both white and black
+        2. Whose turn it is to move
+        3. Basic evaluation of the position
+        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.",
+}
 
 
 def show_image(path: str) -> Dict[str, str]:
@@ -21,6 +45,7 @@ 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
     """
@@ -39,3 +64,41 @@ def show_image(path: str) -> Dict[str, str]:
     image.save(buffer_io, format="PNG")
     img_bytes = buffer_io.getvalue()
     return {"image_base64": base64.b64encode(img_bytes).decode("utf-8")}
+
+
+async def describe_image(
+    path: str, description_type: str = "general", custom_prompt: Optional[str] = None
+) -> str:
+    """
+    Tool to analyze and describe any image using GPT-4 Vision API.
+
+    Returns a description of the image based on the requested type.
+
+    Args:
+        image_path (str): Path to the image file.
+        description_type (str): Type of description to generate. Options:
+            - "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
+            - "custom": Custom description based on user prompt
+    """
+    image_base64 = show_image(path)["image_base64"]
+    assert (
+        description_type in DESCRIBE_PROMPTS or description_type == "custom"
+    ), f"Invalid description type: {description_type}"
+    prompt = DESCRIBE_PROMPTS.get(description_type, custom_prompt)
+    assert prompt and prompt.strip(), "Please provide a non-empty prompt"
+    content = [
+        {"type": "text", "text": prompt},
+        {
+            "type": "image_url",
+            "image_url": {"url": f"data:image/jpeg;base64,{image_base64}"},
+        },
+    ]
+    model_name = settings.DESCRIBE_IMAGE_MODEL_NAME
+    response = await llm_acall(
+        model_name=model_name,
+        messages=[ChatMessage(role="user", content=content)],
+    )
+    return response

academia_mcp/tools/speech_to_text.py

@@ -0,0 +1,48 @@
+from pathlib import Path
+from io import BytesIO
+
+import httpx
+from openai import AsyncOpenAI
+from academia_mcp.files import get_workspace_dir
+
+from academia_mcp.settings import settings
+
+
+async def speech_to_text(audio_path: str, provider: str = "openai") -> str:
+    """
+    Tool to convert speech to text using OpenAI's Whisper model.
+
+    Returns transcribed text from the audio file.
+
+    Args:
+        audio_path (str): Path to the audio file.
+        provider (str): Provider to use. Currently only "openai" is supported.
+    """
+
+    AVAILABLE_PROVIDERS = ("openai",)
+    assert (
+        provider in AVAILABLE_PROVIDERS
+    ), f"Invalid provider: {provider}. Available providers: {AVAILABLE_PROVIDERS}"
+
+    if audio_path.startswith("http"):
+        response = httpx.get(audio_path, timeout=10)
+        response.raise_for_status()
+        ext = audio_path.split(".")[-1]
+        audio_file = BytesIO(response.content)
+        audio_file.name = f"audio_file.{ext}"
+    else:
+        full_audio_path = Path(audio_path)
+        if not full_audio_path.exists():
+            full_audio_path = Path(get_workspace_dir()) / audio_path
+            assert full_audio_path.exists(), f"Audio file {audio_path} does not exist"
+        audio_file = BytesIO(open(full_audio_path, "rb").read())
+        audio_file.name = audio_path.split("/")[-1]
+
+    assert provider == "openai"
+    client = AsyncOpenAI(api_key=settings.OPENAI_API_KEY)
+    result = await client.audio.transcriptions.create(
+        model="gpt-4o-transcribe",
+        file=audio_file,
+        response_format="text",
+    )
+    return result

academia_mcp/tools/visit_webpage.py

@@ -8,7 +8,8 @@ from academia_mcp.utils import get_with_retries, post_with_retries
 from academia_mcp.settings import settings
 
 EXA_CONTENTS_URL = "https://api.exa.ai/contents"
-AVAILABLE_PROVIDERS = ("basic", "exa")
+TAVILY_EXTRACT_URL = "https://api.tavily.com/extract"
+AVAILABLE_PROVIDERS = ("basic", "exa", "tavily")
 
 
 def _exa_visit_webpage(url: str) -> str:
@@ -22,17 +23,27 @@ def _exa_visit_webpage(url: str) -> str:
     return json.dumps(response.json()["results"][0])
 
 
-def visit_webpage(url: str, provider: Optional[str] = "basic") -> str:
+def _tavily_visit_webpage(url: str) -> str:
+    key = settings.TAVILY_API_KEY or ""
+    assert key, "Error: TAVILY_API_KEY is not set and no api_key was provided"
+    payload = {
+        "urls": [url],
+    }
+    response = post_with_retries(TAVILY_EXTRACT_URL, payload=payload, api_key=key)
+    return json.dumps(response.json()["results"][0]["raw_content"])
+
+
+def visit_webpage(url: str, provider: Optional[str] = "tavily") -> str:
     """
     Visit a webpage and return the content.
 
     Returns a JSON object serialized to a string. The structure is: {"url": "...", "text": "..."}
     Use `json.loads` to deserialize the result if you want to get specific fields.
-    Use "exa" provider in case "basic" fails.
+    Try to use both "tavily" and "basic" providers. They might work differently for the same URL.
 
     Args:
         url: The URL of the webpage to visit.
-        provider: The provider to use. Available providers: "basic" (default) or "exa".
+        provider: The provider to use. Available providers: "tavily" (default), "exa", or "basic".
     """
     assert (
         provider in AVAILABLE_PROVIDERS
@@ -40,6 +51,10 @@ def visit_webpage(url: str, provider: Optional[str] = "basic") -> str:
 
     if provider == "exa" and settings.EXA_API_KEY:
         return _exa_visit_webpage(url)
+    elif provider == "tavily" and settings.TAVILY_API_KEY:
+        return _tavily_visit_webpage(url)
+    else:
+        provider = "basic"
 
     assert provider == "basic"
     response = get_with_retries(url)

{academia_mcp-1.9.2.dist-info → academia_mcp-1.10.1.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: academia-mcp
-Version: 1.9.2
+Version: 1.10.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.9.2.dist-info → academia_mcp-1.10.1.dist-info}/RECORD

@@ -4,12 +4,12 @@ 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=k6o-hxkeowHAgKGXUTWhZ6EI4u1RcSIfA-EFyoRmWZ8,4416
-academia_mcp/settings.py,sha256=vkhCrglL_OI1W0Me_1vS0WoQwDhpzj_XTfcuOylweYA,907
+academia_mcp/server.py,sha256=B29AeCWYYk3mj8eZP-it0i_SgbMUzzWQBfZ0DO3HvgQ,4706
+academia_mcp/settings.py,sha256=MSQYjmhZ3NDalTzu4z3ey1Aw60TrhkDcPWUTE4-iOaU,995
 academia_mcp/utils.py,sha256=P9U3RjYzcztE0KxXvJSy5wSBaUg2CM9tpByljYrsrl4,4607
 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=ns0n9MC-TarV-nbkFGCkGptI2Jg-dmb4FU_7l-T_ET8,1390
+academia_mcp/tools/__init__.py,sha256=lGUy5C4IymplHOXqOiwDD7CT4Z8aPHJqSxXo2g9qkks,1493
 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
@@ -20,12 +20,13 @@ academia_mcp/tools/latex.py,sha256=B1Leqt1FHY6H3DlUgeYse4LMFpf4-K1FQViXl5MKk8A,6
 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=mbzWpgaZrGjSgUqnfiiPoWLbyAjUS27F04mjOUqb_S8,1371
-academia_mcp/tools/visit_webpage.py,sha256=uEqZIkMqscZG58Rx2wd6L_OQkGxo5SrzCkoUB55HhC0,2018
+academia_mcp/tools/show_image.py,sha256=jiJlQ53dbZ0T61OBhCT3IKVvBl9NHc6jHgWLfg5BxiE,3856
+academia_mcp/tools/speech_to_text.py,sha256=YZzMqdvunzXkpcadP_mYhm6cs4qH1Y_42SfY-7eX4O4,1601
+academia_mcp/tools/visit_webpage.py,sha256=oKy8CFwTYyIPD73IOcfrUsokING8jpIyosAQ9WraO9E,2645
 academia_mcp/tools/web_search.py,sha256=kj3BrPdTVfyTjZ_9Jl2n3YUGzcRZk8diQs6cVSVmPrQ,6293
-academia_mcp-1.9.2.dist-info/licenses/LICENSE,sha256=xx0jnfkXJvxRnG63LTGOxlggYnIysveWIZ6H3PNdCrQ,11357
-academia_mcp-1.9.2.dist-info/METADATA,sha256=c4NsjDhKqpgL-RKN58OXWdEzAj7Ip1RDAvOJovT0wmI,6310
-academia_mcp-1.9.2.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
-academia_mcp-1.9.2.dist-info/entry_points.txt,sha256=gxkiKJ74w2FwJpSECpjA3XtCfI5ZfrM6N8cqnwsq4yY,51
-academia_mcp-1.9.2.dist-info/top_level.txt,sha256=CzGpRFsRRJRqWEb1e3SUlcfGqRzOxevZGaJWrtGF8W0,13
-academia_mcp-1.9.2.dist-info/RECORD,,
+academia_mcp-1.10.1.dist-info/licenses/LICENSE,sha256=xx0jnfkXJvxRnG63LTGOxlggYnIysveWIZ6H3PNdCrQ,11357
+academia_mcp-1.10.1.dist-info/METADATA,sha256=3Vuyr7l05zOUPVWTnWY_2p6cS1XSHt26oZLtkB47tVw,6311
+academia_mcp-1.10.1.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+academia_mcp-1.10.1.dist-info/entry_points.txt,sha256=gxkiKJ74w2FwJpSECpjA3XtCfI5ZfrM6N8cqnwsq4yY,51
+academia_mcp-1.10.1.dist-info/top_level.txt,sha256=CzGpRFsRRJRqWEb1e3SUlcfGqRzOxevZGaJWrtGF8W0,13
+academia_mcp-1.10.1.dist-info/RECORD,,