scholarx 2.3.3__tar.gz → 2.3.4__tar.gz

{scholarx-2.3.3/scholarx.egg-info → scholarx-2.3.4}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: scholarx
-Version: 2.3.3
+Version: 2.3.4
 Summary: Universal Research Paper API — single entry point for arXiv, PMC, bioRxiv, medRxiv, PsyArXiv, OSF, and Semantic Scholar
 Author-email: Project Maintainers <maintainers@users.noreply.github.com>
 License: MIT
@@ -48,7 +48,7 @@ Dynamic: license-file
 ![PyPI - Wheel](https://img.shields.io/pypi/wheel/scholarx)
 ![PyPI - Implementation](https://img.shields.io/pypi/implementation/scholarx)
 
-*Version: 2.3.3*
+*Version: 2.3.4*
 
 > **Documentation** — Installation, deployment, usage across the API, CLI, MCP, and
 > agent interfaces are maintained in the
@@ -96,6 +96,9 @@ The table below is auto-generated from the MCP server — do not edit by hand.
 | `sx_info` | `DISCOVERYTOOL` | Get metadata about sources and categories. |
 | `sx_search` | `SEARCHTOOL` | Search for research papers across all configured sources. |
 | `sx_storage` | `STORAGETOOL` | Manage offline PDF storage and background downloads. |
+| `sx_enabled_sources` | `OPERATIONTOOL` | List the paper sources enabled on this server (read-only). |
+| `sx_download_papers` | `OPERATIONTOOL` | Download many papers in parallel. |
+| `sx_download_urls` | `OPERATIONTOOL` | Download arXiv PDFs directly by id or URL in parallel. |
 
 #### Verbose 1:1 API-mapped tools (`MCP_TOOL_MODE=verbose` or `both`)
 

{scholarx-2.3.3 → scholarx-2.3.4}/README.md

@@ -20,7 +20,7 @@
 ![PyPI - Wheel](https://img.shields.io/pypi/wheel/scholarx)
 ![PyPI - Implementation](https://img.shields.io/pypi/implementation/scholarx)
 
-*Version: 2.3.3*
+*Version: 2.3.4*
 
 > **Documentation** — Installation, deployment, usage across the API, CLI, MCP, and
 > agent interfaces are maintained in the
@@ -68,6 +68,9 @@ The table below is auto-generated from the MCP server — do not edit by hand.
 | `sx_info` | `DISCOVERYTOOL` | Get metadata about sources and categories. |
 | `sx_search` | `SEARCHTOOL` | Search for research papers across all configured sources. |
 | `sx_storage` | `STORAGETOOL` | Manage offline PDF storage and background downloads. |
+| `sx_enabled_sources` | `OPERATIONTOOL` | List the paper sources enabled on this server (read-only). |
+| `sx_download_papers` | `OPERATIONTOOL` | Download many papers in parallel. |
+| `sx_download_urls` | `OPERATIONTOOL` | Download arXiv PDFs directly by id or URL in parallel. |
 
 #### Verbose 1:1 API-mapped tools (`MCP_TOOL_MODE=verbose` or `both`)
 

{scholarx-2.3.3 → scholarx-2.3.4}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"
 
 [project]
 name = "scholarx"
-version = "2.3.3"
+version = "2.3.4"
 description = "Universal Research Paper API — single entry point for arXiv, PMC, bioRxiv, medRxiv, PsyArXiv, OSF, and Semantic Scholar"
 readme = "README.md"
 license = { text = "MIT" }

{scholarx-2.3.3 → scholarx-2.3.4}/scholarx/mcp_server.py

@@ -19,7 +19,7 @@ from pydantic import Field
 
 load_config()
 
-__version__ = "2.3.3"
+__version__ = "2.3.4"
 
 # Wall budget for an inline single-paper download before it is handed to the
 # background queue. Kept well under the MCP child-call timeout so a slow source
@@ -501,6 +501,66 @@ def register_storage_tools(mcp):
         return {"error": f"Unknown action: {action}"}  # pragma: no cover
 
 
+async def _sx_resolve_papers(client, paper_source, ids) -> list:
+    """Resolve each id to a Paper; ids that cannot be resolved are dropped."""
+    found = await asyncio.gather(*(client.get_paper(paper_source, pid) for pid in ids))
+    return [paper for paper in found if paper]
+
+
+def register_operation_tools(mcp):
+    """Register one tool per API-client operation not covered by the routed tools."""
+
+    @mcp.tool(tags={"discovery"}, annotations={"readOnlyHint": True})
+    async def sx_enabled_sources() -> dict:
+        """List the paper sources enabled on this server (``ScholarXClient.enabled_sources``)."""
+        client = _get_client()
+        return {"sources": [s.value for s in client.enabled_sources]}
+
+    @mcp.tool(
+        tags={"storage"},
+        annotations={"readOnlyHint": False, "destructiveHint": False, "idempotentHint": True},
+    )
+    async def sx_download_papers(
+        source: str = Field(description="Paper source (arxiv, pmc, etc.)"),
+        paper_ids: str = Field(description="Comma-separated paper IDs to download in parallel"),
+        concurrency: int = Field(default=0, description="Max simultaneous downloads; 0 auto-sizes"),
+    ) -> dict:
+        """Download many papers in parallel (``ScholarXClient.download_papers``)."""
+        from scholarx.models import PaperSource
+
+        error, paper_source, ids = _validate_bulk_download_request(source, paper_ids, PaperSource)
+        if error:
+            return error
+        client = _get_client()
+        papers = await _sx_resolve_papers(client, paper_source, ids)
+        try:
+            results = await client.download_papers(papers, concurrency=concurrency)
+        except ValueError:
+            return {"error": "Invalid download request"}
+        return {"results": results}
+
+    @mcp.tool(
+        tags={"storage"},
+        annotations={"readOnlyHint": False, "destructiveHint": False, "idempotentHint": True},
+    )
+    async def sx_download_urls(
+        paper_ids: str = Field(description="Comma-separated arXiv ids or abs/pdf URLs"),
+        concurrency: int = Field(default=0, description="Max simultaneous downloads; 0 auto-sizes"),
+    ) -> dict:
+        """Download arXiv PDFs directly by id or URL in parallel (``ScholarXClient.download_urls``)."""
+        if not paper_ids:
+            return {"error": "'paper_ids' required"}
+        if len(paper_ids) > _MAX_DIRECT_DOWNLOAD_INPUT_CHARS:
+            return {"error": "'paper_ids' input limit exceeded"}
+        raw_ids = [i.strip() for i in paper_ids.split(",") if i.strip()]
+        client = _get_client()
+        try:
+            results = await client.download_urls(raw_ids, concurrency=concurrency)
+        except ValueError:
+            return {"error": "Invalid download request"}
+        return {"results": results}
+
+
 def register_kg_tools(mcp):
     """Register native knowledge-graph ingestion tools (Wire-First)."""
 
@@ -600,6 +660,7 @@ def get_mcp_instance():
             register_search_tools,
             register_discovery_tools,
             register_storage_tools,
+            register_operation_tools,
             register_kg_tools,
         ],
     )

{scholarx-2.3.3 → scholarx-2.3.4/scholarx.egg-info}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: scholarx
-Version: 2.3.3
+Version: 2.3.4
 Summary: Universal Research Paper API — single entry point for arXiv, PMC, bioRxiv, medRxiv, PsyArXiv, OSF, and Semantic Scholar
 Author-email: Project Maintainers <maintainers@users.noreply.github.com>
 License: MIT
@@ -48,7 +48,7 @@ Dynamic: license-file
 ![PyPI - Wheel](https://img.shields.io/pypi/wheel/scholarx)
 ![PyPI - Implementation](https://img.shields.io/pypi/implementation/scholarx)
 
-*Version: 2.3.3*
+*Version: 2.3.4*
 
 > **Documentation** — Installation, deployment, usage across the API, CLI, MCP, and
 > agent interfaces are maintained in the
@@ -96,6 +96,9 @@ The table below is auto-generated from the MCP server — do not edit by hand.
 | `sx_info` | `DISCOVERYTOOL` | Get metadata about sources and categories. |
 | `sx_search` | `SEARCHTOOL` | Search for research papers across all configured sources. |
 | `sx_storage` | `STORAGETOOL` | Manage offline PDF storage and background downloads. |
+| `sx_enabled_sources` | `OPERATIONTOOL` | List the paper sources enabled on this server (read-only). |
+| `sx_download_papers` | `OPERATIONTOOL` | Download many papers in parallel. |
+| `sx_download_urls` | `OPERATIONTOOL` | Download arXiv PDFs directly by id or URL in parallel. |
 
 #### Verbose 1:1 API-mapped tools (`MCP_TOOL_MODE=verbose` or `both`)
 

{scholarx-2.3.3 → scholarx-2.3.4}/scholarx.egg-info/SOURCES.txt

@@ -57,6 +57,7 @@ tests/test_kg_ingest.py
 tests/test_kg_media.py
 tests/test_mcp_server.py
 tests/test_models.py
+tests/test_operation_tools.py
 tests/test_paper_storage.py
 tests/test_parallel_download.py
 tests/test_providers.py

scholarx-2.3.4/tests/test_operation_tools.py

@@ -0,0 +1,109 @@
+"""CONN-SCHOLARX-API-COVERAGE-R001: one MCP tool per remaining API operation, coverage at the 90 baseline."""
+
+import subprocess
+import sys
+from pathlib import Path
+from unittest.mock import AsyncMock, MagicMock, patch
+
+import pytest
+
+from scholarx.mcp_server import register_operation_tools
+from scholarx.models import PaperSource
+
+pytestmark = pytest.mark.spec("CONN-SCHOLARX-API-COVERAGE-R001")
+
+ROOT = Path(__file__).resolve().parents[1]
+
+
+class MockMCP:
+    def __init__(self):
+        self.tools = {}
+        self.kwargs = {}
+
+    def tool(self, *args, **kwargs):
+        def decorator(func):
+            self.tools[func.__name__] = func
+            self.kwargs[func.__name__] = kwargs
+            return func
+
+        return decorator
+
+
+@pytest.fixture
+def tools():
+    mcp = MockMCP()
+    register_operation_tools(mcp)
+    return mcp
+
+
+def test_tools_are_registered_with_hints(tools):
+    assert set(tools.tools) == {"sx_enabled_sources", "sx_download_papers", "sx_download_urls"}
+    assert tools.kwargs["sx_enabled_sources"]["annotations"]["readOnlyHint"] is True
+    assert tools.kwargs["sx_download_papers"]["annotations"]["readOnlyHint"] is False
+    assert tools.kwargs["sx_download_urls"]["annotations"]["readOnlyHint"] is False
+
+
+@pytest.mark.asyncio
+async def test_enabled_sources(tools):
+    client = MagicMock(enabled_sources=[PaperSource.ARXIV])
+    with patch("scholarx.mcp_server._get_client", return_value=client):
+        assert await tools.tools["sx_enabled_sources"]() == {"sources": ["arxiv"]}
+
+
+@pytest.mark.asyncio
+async def test_download_papers(tools):
+    client = MagicMock()
+    client.get_paper = AsyncMock(side_effect=lambda src, pid: MagicMock(id=pid))
+    client.download_papers = AsyncMock(return_value=[{"paper_id": "1", "status": "downloaded"}])
+    with patch("scholarx.mcp_server._get_client", return_value=client):
+        out = await tools.tools["sx_download_papers"](source="arxiv", paper_ids="1,2", concurrency=3)
+    assert out == {"results": [{"paper_id": "1", "status": "downloaded"}]}
+    assert len(client.download_papers.call_args.args[0]) == 2
+    assert client.download_papers.call_args.kwargs == {"concurrency": 3}
+
+
+@pytest.mark.asyncio
+async def test_download_papers_rejects_bad_input(tools):
+    with patch("scholarx.mcp_server._get_client", return_value=MagicMock()):
+        out = await tools.tools["sx_download_papers"](source="nope", paper_ids="1", concurrency=0)
+    assert "error" in out
+
+
+@pytest.mark.asyncio
+async def test_download_urls(tools):
+    client = MagicMock()
+    client.download_urls = AsyncMock(return_value=[{"paper_id": "2603.09022", "status": "cached"}])
+    with patch("scholarx.mcp_server._get_client", return_value=client):
+        out = await tools.tools["sx_download_urls"](paper_ids="2603.09022, 2603.09023", concurrency=0)
+    assert out["results"][0]["status"] == "cached"
+    assert client.download_urls.call_args.args[0] == ["2603.09022", "2603.09023"]
+
+
+@pytest.mark.asyncio
+async def test_download_urls_requires_ids_and_maps_limit_errors(tools):
+    client = MagicMock()
+    client.download_urls = AsyncMock(side_effect=ValueError("limit"))
+    with patch("scholarx.mcp_server._get_client", return_value=client):
+        assert "error" in await tools.tools["sx_download_urls"](paper_ids="", concurrency=0)
+        assert "error" in await tools.tools["sx_download_urls"](paper_ids="1", concurrency=0)
+
+
+def test_coverage_gate_holds_at_the_baseline():
+    script = (ROOT / "scripts/verify_api_integration.py").read_text()
+    assert '"scholarx": 90.0' in script
+    # The checker names the agent from the directory; run it from a directory called scholarx.
+    result = subprocess.run(
+        [
+            sys.executable,
+            "-c",
+            "import sys, importlib.util as u;"
+            "s=u.spec_from_file_location('v', sys.argv[1]);m=u.module_from_spec(s);s.loader.exec_module(m);"
+            "r=m.verify_agent(sys.argv[2]);print(r['coverage'])",
+            str(ROOT / "scripts/verify_api_integration.py"),
+            str(ROOT),
+        ],
+        capture_output=True,
+        text=True,
+        check=True,
+    )
+    assert float(result.stdout.strip()) >= 90.0