Add MCP server

Author: satyaog

config/basic.yaml

@@ -91,3 +91,7 @@ paperoni:
           search: []
           validate: [search]
           dev: []
+  mcp:
+    api_client:
+      $class: paperoni.mcp.client:PaperoniAPIClient
+      endpoint: ${paperoni.server.protocol}://${paperoni.server.host}:${paperoni.server.port}

pyproject.toml

@@ -39,6 +39,7 @@ dependencies = [
     "filelock>=3.20.0",
     "jinja2>=3.1.6",
     "easy-oauth",
+    "fastmcp>=2.14.2",
 ]
 
 [project.urls]

src/paperoni/__main__.py

@@ -871,7 +871,7 @@ class Login:
     """Retrieve an access token from the paperoni server."""
 
     # Endpoint to login to
-    endpoint: str = "http://localhost:8000"
+    endpoint: str = None
 
     # Whether to use headless mode
     headless: bool = False
@@ -880,8 +880,29 @@ def run(self):
         print_field("Access token", login(self.endpoint, self.headless))
 
 
+@dataclass
+class MCP:
+    """MCP server for paperoni."""
+
+    # Paperoni API
+    endpoint: str = None
+
+    transport: Literal["stdio", "http"] = "stdio"
+    host: str = "localhost"
+    port: int = 9000
+
+    def run(self):
+        from .mcp.server import create_mcp
+
+        mcp = create_mcp(self.endpoint)
+        if self.transport == "stdio":
+            mcp.run(transport="stdio")
+        elif self.transport == "http":
+            mcp.run(transport="http", host=self.host, port=self.port)
+
+
 PaperoniCommand = TaggedUnion[
-    Discover, Refine, Fulltext, Work, Coll, Batch, Focus, Serve, Login
+    Discover, Refine, Fulltext, Work, Coll, Batch, Focus, Serve, Login, MCP
 ]
 
 

src/paperoni/config.py

@@ -13,6 +13,7 @@
 from .collection.abc import PaperCollection
 from .embed.cfg import Embedding
 from .get import Fetcher, RequestsFetcher
+from .mcp.client import PaperoniAPIClient
 from .model.focus import AutoFocus, Focuses
 from .prompt import GenAIPrompt, Prompt
 
@@ -52,6 +53,13 @@ def __post_init__(self):
             self.process_pool = ProcessPoolExecutor(**self.process_pool_executor)
 
 
+@dataclass(kw_only=True)
+class MCP:
+    api_client: TaggedSubclass[PaperoniAPIClient] = field(
+        default_factory=PaperoniAPIClient
+    )
+
+
 @dataclass
 class PaperoniConfig:
     cache_path: Path = None
@@ -67,6 +75,7 @@ class PaperoniConfig:
     reporters: list[TaggedSubclass[Reporter]] = field(default_factory=list)
     embedding: TaggedSubclass[Embedding] = field(default_factory=Embedding)
     server: Server = field(default_factory=Server)
+    mcp: MCP = field(default_factory=MCP)
 
     def __post_init__(self):
         self.metadata: Meta[Path | list[Path] | Meta | Any] = Meta()

src/paperoni/mcp/__init__.py

@@ -0,0 +1 @@
+"""MCP server for paperoni."""

src/paperoni/mcp/client.py

@@ -0,0 +1,122 @@
+"""HTTP client for paperoni REST API."""
+
+import os
+from dataclasses import dataclass, field
+from datetime import date
+from typing import Any
+
+from fastapi import HTTPException
+from serieux.features.encrypt import Secret
+
+from ..get import Fetcher, RequestsFetcher
+
+
+@dataclass
+class PaperoniAPIClient:
+    """Client for interacting with paperoni REST API."""
+
+    endpoint: str
+    token: Secret[str] = os.getenv("PAPERONI_TOKEN")
+    fetch: Fetcher = field(default_factory=RequestsFetcher)
+
+    def __post_init__(self):
+        self.headers = {
+            "Accept": "application/json",
+        }
+        if self.token is not None:
+            self.headers["Authorization"] = f"Bearer {self.token}"
+
+    def search_papers(
+        self,
+        paper_id: int = None,
+        title: str = None,
+        institution: str = None,
+        author: str = None,
+        venue: str = None,
+        start_date: date = None,
+        end_date: date = None,
+        include_flags: list[str] = None,
+        exclude_flags: list[str] = None,
+        query: str = None,
+        similarity_threshold: float = 0.75,
+        offset: int = 0,
+        limit: int = 100,
+    ) -> dict[str, Any]:
+        params: dict[str, Any] = {
+            "offset": offset,
+            "limit": limit,
+        }
+
+        if paper_id:
+            params["paper_id"] = paper_id
+        if title:
+            params["title"] = title
+        if institution:
+            params["institution"] = institution
+        if author:
+            params["author"] = author
+        if venue:
+            params["venue"] = venue
+        if start_date:
+            params["start_date"] = start_date.isoformat()
+        if end_date:
+            params["end_date"] = end_date.isoformat()
+        if include_flags:
+            params["include_flags"] = ",".join(include_flags)
+        if exclude_flags:
+            params["exclude_flags"] = ",".join(exclude_flags)
+        if query:
+            params["query"] = query
+        if similarity_threshold:
+            params["similarity_threshold"] = similarity_threshold
+
+        url = f"{self.endpoint}/api/v1/search"
+
+        try:
+            resp = self.fetch.read(
+                url,
+                format="json",
+                cache_into=None,
+                headers=self.headers,
+                params=params,
+            )
+            resp.pop("total", None)
+            return resp
+
+        except Exception as e:
+            if isinstance(e, HTTPException) and e.status_code == 404:
+                return {
+                    "results": [],
+                    "similarities": None,
+                    "count": 0,
+                    "next_offset": None,
+                }
+            raise
+
+    def count_papers(
+        self,
+        paper_id: int = None,
+        title: str = None,
+        institution: str = None,
+        author: str = None,
+        venue: str = None,
+        start_date: date = None,
+        end_date: date = None,
+        include_flags: list[str] = None,
+        exclude_flags: list[str] = None,
+    ) -> int:
+        # Fetch first page to get total count
+        resp = self.search_papers(
+            paper_id=paper_id,
+            title=title,
+            institution=institution,
+            author=author,
+            venue=venue,
+            start_date=start_date,
+            end_date=end_date,
+            include_flags=include_flags,
+            exclude_flags=exclude_flags,
+            offset=0,
+            limit=1,  # Only need the total count
+        )
+        return resp.get("total", 0)

src/paperoni/mcp/server.py

@@ -0,0 +1,127 @@
+"""MCP server implementation using fastmcp."""
+
+from datetime import date
+
+from fastmcp import FastMCP
+
+from ..config import config
+from .client import PaperoniAPIClient
+
+
+def create_mcp(endpoint: str = None):
+    api_client = PaperoniAPIClient(
+        endpoint or config.mcp.api_client.endpoint,
+        token=config.mcp.api_client.token,
+        fetch=config.mcp.api_client.fetch,
+    )
+
+    mcp = FastMCP(name="Paperoni")
+
+    @mcp.tool
+    def search_papers(
+        paper_id: int = None,
+        title: str = None,
+        institution: str = None,
+        author: str = None,
+        venue: str = None,
+        start_date: date = None,
+        end_date: date = None,
+        include_flags: list[str] = None,
+        exclude_flags: list[str] = None,
+        query: str = None,
+        similarity_threshold: float = 0.75,
+        offset: int = 0,
+        limit: int = 100,
+    ):
+        """Search for papers in the paperoni collection.
+
+        This tool allows searching for papers using various filters including
+        semantic search, institution, venue, author, and date ranges. Results
+        include paper metadata (title, abstract, authors, venues, topics) but
+        exclude PDF content.
+
+        If a query is provided, the results will be sorted by similarity score.
+        Note that unrelated papers may still be returned with a low similarity
+        score.
+
+        Args:
+            paper_id: Paper ID
+            title: Title of the paper
+            institution: Institution of an author
+            author: Author of the paper
+            venue: Venue name (long or short)
+            start_date: Start date to consider
+            end_date: End date to consider
+            include_flags: Flags that must be present
+            exclude_flags: Flags that must not be present
+            query: Semantic search query
+            similarity_threshold: Similarity threshold (default: 0.75)
+            offset: Pagination offset (default: 0)
+            limit: Maximum number of results to return (default: 100)
+
+        Returns:
+            Dictionary containing:
+            - results: List of paper objects with metadata
+            - similarities: List of similarity scores (None if no query was provided)
+            - count: Number of results in this page
+            - next_offset: Offset for next page (None if no more pages)
+        """
+
+        return api_client.search_papers(
+            paper_id=paper_id,
+            title=title,
+            institution=institution,
+            author=author,
+            venue=venue,
+            start_date=start_date,
+            end_date=end_date,
+            include_flags=include_flags,
+            exclude_flags=exclude_flags,
+            query=query,
+            similarity_threshold=similarity_threshold,
+            offset=offset,
+            limit=limit,
+        )
+
+    @mcp.tool
+    def count_papers(
+        paper_id: int = None,
+        title: str = None,
+        institution: str = None,
+        author: str = None,
+        venue: str = None,
+        start_date: date = None,
+        end_date: date = None,
+        include_flags: list[str] = None,
+        exclude_flags: list[str] = None,
+    ) -> int:
+        """Count papers matching criteria without fetching all results.
+
+        Args:
+            paper_id: Paper ID
+            title: Title of the paper
+            institution: Institution of an author
+            author: Author of the paper
+            venue: Venue name (long or short)
+            start_date: Start date to consider
+            end_date: End date to consider
+            include_flags: Flags that must be present
+            exclude_flags: Flags that must not be present
+
+        Returns:
+            Total count of matching papers
+        """
+
+        return api_client.count_papers(
+            paper_id=paper_id,
+            title=title,
+            institution=institution,
+            author=author,
+            venue=venue,
+            start_date=start_date,
+            end_date=end_date,
+            include_flags=include_flags,
+            exclude_flags=exclude_flags,
+        )
+
+    return mcp