crossref-local 0.3.0__py3-none-any.whl → 0.4.0__py3-none-any.whl

crossref_local/mcp_server.py

@@ -0,0 +1,413 @@
+"""MCP server for CrossRef Local - Claude integration.
+
+This server exposes crossref-local functionality as MCP tools,
+enabling Claude Desktop and other MCP clients to search academic papers.
+
+Usage:
+    crossref-local serve                    # stdio (Claude Desktop)
+    crossref-local serve -t http --port 8082  # HTTP transport
+    crossref-local-mcp                      # Direct entry point
+"""
+
+import json
+
+from fastmcp import FastMCP
+
+
+from . import (
+    get as _get,
+    info as _info,
+    search as _search,
+)
+
+# Initialize MCP server
+mcp = FastMCP(
+    name="crossref-local",
+    instructions="Local CrossRef database with 167M+ works and full-text search. "
+    "Use search to find papers, search_by_doi for DOI lookup, enrich_dois to add "
+    "citation counts and references, and status for stats.",
+)
+
+
+@mcp.tool()
+def search(
+    query: str,
+    limit: int = 10,
+    offset: int = 0,
+    with_abstracts: bool = False,
+) -> str:
+    """Search for academic works by title, abstract, or authors.
+
+    Uses FTS5 full-text search index for fast searching across 167M+ papers.
+    Supports FTS5 query syntax: AND, OR, NOT, "exact phrases".
+
+    Args:
+        query: Search query (e.g., "machine learning", "CRISPR", "neural network AND hippocampus")
+        limit: Maximum number of results to return (default: 10, max: 100)
+        offset: Skip first N results for pagination (default: 0)
+        with_abstracts: Include abstracts in results (default: False)
+
+    Returns:
+        JSON string with search results including total count and matching works.
+
+    Examples:
+        search("machine learning")
+        search("CRISPR", limit=20)
+        search("neural network AND memory", with_abstracts=True)
+    """
+    results = _search(query, limit=min(limit, 100), offset=offset)
+
+    works_data = []
+    for work in results.works:
+        work_dict = {
+            "doi": work.doi,
+            "title": work.title,
+            "authors": work.authors,
+            "year": work.year,
+            "journal": work.journal,
+        }
+        if with_abstracts and work.abstract:
+            work_dict["abstract"] = work.abstract
+        works_data.append(work_dict)
+
+    return json.dumps(
+        {
+            "query": results.query,
+            "total": results.total,
+            "returned": len(works_data),
+            "elapsed_ms": round(results.elapsed_ms, 2),
+            "works": works_data,
+        },
+        indent=2,
+    )
+
+
+@mcp.tool()
+def search_by_doi(doi: str, as_citation: bool = False) -> str:
+    """Get detailed information about a work by DOI.
+
+    Args:
+        doi: Digital Object Identifier (e.g., "10.1038/nature12373")
+        as_citation: Return formatted citation instead of full metadata
+
+    Returns:
+        JSON string with work metadata, or formatted citation string.
+
+    Examples:
+        search_by_doi("10.1038/nature12373")
+        search_by_doi("10.1126/science.aax0758", as_citation=True)
+    """
+    work = _get(doi)
+
+    if work is None:
+        return json.dumps({"error": f"DOI not found: {doi}"})
+
+    if as_citation:
+        return work.citation()
+
+    return json.dumps(work.to_dict(), indent=2)
+
+
+@mcp.tool()
+def status() -> str:
+    """Get database statistics and status.
+
+    Returns:
+        JSON string with database path, work count, FTS index count, and citation count.
+    """
+    db_info = _info()
+    return json.dumps(db_info, indent=2)
+
+
+@mcp.tool()
+def enrich_dois(dois: list[str]) -> str:
+    """Enrich DOIs with full metadata including citation counts and references.
+
+    Use this after search() to get detailed metadata for papers.
+    The search() tool returns basic info (title, authors, year, journal).
+    This tool adds: citation_count, references, volume, issue, publisher, etc.
+
+    Typical workflow:
+    1. search("epilepsy seizure prediction") -> get DOIs
+    2. enrich_dois([doi1, doi2, ...]) -> get full metadata
+
+    Args:
+        dois: List of DOIs to enrich (e.g., ["10.1038/nature12373", "10.1126/science.aax0758"])
+
+    Returns:
+        JSON string with enriched works including citation_count and references.
+
+    Examples:
+        enrich_dois(["10.1038/nature12373"])
+        enrich_dois(["10.1038/s41467-017-02577-y", "10.1093/brain/aww019"])
+    """
+    from . import get_many as _get_many
+
+    works = _get_many(dois)
+
+    works_data = []
+    for work in works:
+        works_data.append(work.to_dict())
+
+    return json.dumps(
+        {
+            "requested": len(dois),
+            "found": len(works_data),
+            "works": works_data,
+        },
+        indent=2,
+    )
+
+
+@mcp.tool()
+def cache_create(
+    name: str,
+    query: str,
+    limit: int = 1000,
+) -> str:
+    """Create a paper cache from search query.
+
+    Fetches full metadata for papers matching query and saves to disk cache.
+    Use this to build a reusable paper collection for a research topic.
+
+    Args:
+        name: Cache name (e.g., "epilepsy", "alzheimers")
+        query: FTS search query
+        limit: Max papers to cache (default: 1000)
+
+    Returns:
+        JSON with cache info (path, paper count, size)
+
+    Example:
+        cache_create("epilepsy", "epilepsy seizure prediction", limit=500)
+    """
+    from . import cache
+
+    info = cache.create(name, query=query, limit=limit)
+    return json.dumps(info.to_dict(), indent=2)
+
+
+@mcp.tool()
+def cache_query(
+    name: str,
+    fields: list[str] | None = None,
+    include_abstract: bool = False,
+    include_references: bool = False,
+    include_citations: bool = False,
+    year_min: int | None = None,
+    year_max: int | None = None,
+    journal: str | None = None,
+    limit: int | None = None,
+) -> str:
+    """Query cached papers with field filtering.
+
+    Returns minimal data to reduce context usage. Specify only fields needed.
+
+    Args:
+        name: Cache name
+        fields: Explicit field list (e.g., ["doi", "title", "year"])
+        include_abstract: Include abstract (default: False)
+        include_references: Include references list (default: False)
+        include_citations: Include citation_count (default: False)
+        year_min: Filter by minimum year
+        year_max: Filter by maximum year
+        journal: Filter by journal name (substring match)
+        limit: Max results to return
+
+    Returns:
+        JSON array of filtered papers
+
+    Examples:
+        cache_query("epilepsy", fields=["doi", "title", "year"])
+        cache_query("epilepsy", year_min=2020, include_citations=True, limit=50)
+    """
+    from . import cache
+
+    papers = cache.query(
+        name,
+        fields=fields,
+        include_abstract=include_abstract,
+        include_references=include_references,
+        include_citations=include_citations,
+        year_min=year_min,
+        year_max=year_max,
+        journal=journal,
+        limit=limit,
+    )
+    return json.dumps({"count": len(papers), "papers": papers}, indent=2)
+
+
+@mcp.tool()
+def cache_stats(name: str) -> str:
+    """Get cache statistics.
+
+    Returns year distribution, top journals, citation stats without loading full data.
+
+    Args:
+        name: Cache name
+
+    Returns:
+        JSON with statistics (paper_count, year_range, top_journals, etc.)
+    """
+    from . import cache
+
+    stats = cache.stats(name)
+    return json.dumps(stats, indent=2)
+
+
+@mcp.tool()
+def cache_list() -> str:
+    """List all available caches.
+
+    Returns:
+        JSON array of cache info (name, path, paper_count, size)
+    """
+    from . import cache
+
+    caches = cache.list_caches()
+    return json.dumps([c.to_dict() for c in caches], indent=2)
+
+
+@mcp.tool()
+def cache_top_cited(
+    name: str,
+    n: int = 20,
+    year_min: int | None = None,
+    year_max: int | None = None,
+) -> str:
+    """Get top cited papers from cache.
+
+    Args:
+        name: Cache name
+        n: Number of papers to return
+        year_min: Filter by minimum year
+        year_max: Filter by maximum year
+
+    Returns:
+        JSON array of top cited papers
+    """
+    from .cache_viz import get_top_cited
+
+    papers = get_top_cited(name, n=n, year_min=year_min, year_max=year_max)
+    return json.dumps(papers, indent=2)
+
+
+@mcp.tool()
+def cache_citation_summary(name: str) -> str:
+    """Get citation statistics for cached papers.
+
+    Returns mean, median, max citations and counts of highly cited papers.
+
+    Args:
+        name: Cache name
+
+    Returns:
+        JSON with citation statistics
+    """
+    from .cache_viz import get_citation_summary
+
+    summary = get_citation_summary(name)
+    return json.dumps(summary, indent=2)
+
+
+@mcp.tool()
+def cache_plot_scatter(
+    name: str,
+    output: str,
+    top_n: int = 10,
+) -> str:
+    """Generate year vs citations scatter plot.
+
+    Saves plot to file and returns top cited papers.
+
+    Args:
+        name: Cache name
+        output: Output file path (png/pdf/svg)
+        top_n: Number of top papers to label on plot
+
+    Returns:
+        JSON with output path and top papers list
+    """
+    from .cache_viz import plot_year_citations
+
+    result = plot_year_citations(name, output=output, top_n=top_n)
+    return json.dumps(result, indent=2)
+
+
+@mcp.tool()
+def cache_plot_network(
+    name: str,
+    output: str,
+    max_nodes: int = 100,
+) -> str:
+    """Generate citation network visualization.
+
+    Creates interactive HTML graph showing citation relationships.
+
+    Args:
+        name: Cache name
+        output: Output HTML file path
+        max_nodes: Maximum papers to include
+
+    Returns:
+        JSON with network stats
+    """
+    from .cache_viz import plot_citation_network
+
+    result = plot_citation_network(name, output=output, max_nodes=max_nodes)
+    return json.dumps(result, indent=2)
+
+
+@mcp.tool()
+def cache_export(
+    name: str,
+    output_path: str,
+    format: str = "json",
+    fields: list[str] | None = None,
+) -> str:
+    """Export cache to file.
+
+    Args:
+        name: Cache name
+        output_path: Output file path
+        format: Export format (json, csv, bibtex, dois)
+        fields: Fields to include (for json/csv)
+
+    Returns:
+        JSON with output path
+    """
+    from . import cache
+
+    path = cache.export(name, output_path, format=format, fields=fields)
+    return json.dumps({"exported": path, "format": format})
+
+
+def run_server(
+    transport: str = "stdio",
+    host: str = "localhost",
+    port: int = 8082,
+) -> None:
+    """Run the MCP server.
+
+    Args:
+        transport: Transport protocol ("stdio", "sse", or "http")
+        host: Host for HTTP/SSE transport
+        port: Port for HTTP/SSE transport
+    """
+    if transport == "stdio":
+        mcp.run(transport="stdio")
+    elif transport == "sse":
+        mcp.run(transport="sse", host=host, port=port)
+    elif transport == "http":
+        mcp.run(transport="streamable-http", host=host, port=port)
+    else:
+        raise ValueError(f"Unknown transport: {transport}")
+
+
+def main():
+    """Entry point for crossref-local-mcp command."""
+    run_server(transport="stdio")
+
+
+if __name__ == "__main__":
+    main()

crossref_local/remote.py

@@ -0,0 +1,269 @@
+"""Remote API client for crossref_local.
+
+Connects to a CrossRef Local API server instead of direct database access.
+Use this when the database is on a remote server accessible via HTTP.
+"""
+
+import json
+import urllib.request
+import urllib.parse
+import urllib.error
+from typing import List, Optional, Dict, Any
+
+from .models import Work, SearchResult
+
+
+class RemoteClient:
+    """
+    HTTP client for CrossRef Local API server.
+
+    Provides the same interface as the local API but connects
+    to a remote server via HTTP.
+
+    Example:
+        >>> client = RemoteClient("http://localhost:3333")
+        >>> results = client.search(title="machine learning", limit=10)
+        >>> work = client.get("10.1038/nature12373")
+    """
+
+    def __init__(self, base_url: str = "http://localhost:3333", timeout: int = 30):
+        """
+        Initialize remote client.
+
+        Args:
+            base_url: API server URL (default: http://localhost:3333)
+            timeout: Request timeout in seconds
+        """
+        self.base_url = base_url.rstrip("/")
+        self.timeout = timeout
+
+    def _request(self, endpoint: str, params: Optional[Dict[str, Any]] = None) -> Dict:
+        """Make HTTP GET request to API."""
+        url = f"{self.base_url}{endpoint}"
+        if params:
+            # Filter out None values
+            params = {k: v for k, v in params.items() if v is not None}
+            if params:
+                url = f"{url}?{urllib.parse.urlencode(params)}"
+
+        try:
+            req = urllib.request.Request(url)
+            req.add_header("Accept", "application/json")
+            with urllib.request.urlopen(req, timeout=self.timeout) as response:
+                return json.loads(response.read().decode("utf-8"))
+        except urllib.error.HTTPError as e:
+            if e.code == 404:
+                return None
+            raise ConnectionError(f"API request failed: {e.code} {e.reason}") from e
+        except urllib.error.URLError as e:
+            raise ConnectionError(
+                f"Cannot connect to API at {self.base_url}: {e.reason}"
+            ) from e
+
+    def health(self) -> Dict:
+        """Check API server health."""
+        return self._request("/health")
+
+    def info(self) -> Dict:
+        """Get database/API information."""
+        root = self._request("/")
+        info_data = self._request("/info")
+        return {
+            "api_url": self.base_url,
+            "api_version": root.get("version", "unknown"),
+            "status": root.get("status", "unknown"),
+            "mode": "remote",
+            "works": info_data.get("total_papers", 0) if info_data else 0,
+            "fts_indexed": info_data.get("fts_indexed", 0) if info_data else 0,
+            "citations": info_data.get("citations", 0) if info_data else 0,
+        }
+
+    def search(
+        self,
+        query: Optional[str] = None,
+        doi: Optional[str] = None,
+        title: Optional[str] = None,
+        authors: Optional[str] = None,
+        year: Optional[int] = None,
+        limit: int = 10,
+        offset: int = 0,
+    ) -> SearchResult:
+        """
+        Search for papers.
+
+        Args:
+            query: Full-text search query (searches title by default)
+            doi: Search by DOI
+            title: Search by title (explicit)
+            authors: Search by author name
+            year: Filter by publication year
+            limit: Maximum results (default: 10, max: 100)
+            offset: Skip first N results for pagination
+
+        Returns:
+            SearchResult with matching works
+        """
+        # Use new /works endpoint with FTS5 search
+        search_query = query or title
+
+        params = {
+            "q": search_query,
+            "limit": min(limit, 100),
+            "offset": offset,
+        }
+
+        data = self._request("/works", params)
+
+        if not data:
+            return SearchResult(works=[], total=0, query=query or "", elapsed_ms=0.0)
+
+        works = []
+        for item in data.get("results", []):
+            work = Work(
+                doi=item.get("doi", ""),
+                title=item.get("title", ""),
+                authors=item.get("authors", []),
+                year=item.get("year"),
+                journal=item.get("journal"),
+                volume=item.get("volume"),
+                issue=item.get("issue"),
+                page=item.get("page") or item.get("pages"),
+                abstract=item.get("abstract"),
+                citation_count=item.get("citation_count"),
+            )
+            works.append(work)
+
+        return SearchResult(
+            works=works,
+            total=data.get("total", len(works)),
+            query=query or title or doi or "",
+            elapsed_ms=data.get("elapsed_ms", 0.0),
+        )
+
+    def get(self, doi: str) -> Optional[Work]:
+        """
+        Get a work by DOI.
+
+        Args:
+            doi: Digital Object Identifier
+
+        Returns:
+            Work object or None if not found
+        """
+        # Use /works/{doi} endpoint directly
+        data = self._request(f"/works/{doi}")
+        if not data or "error" in data:
+            return None
+
+        return Work(
+            doi=data.get("doi", doi),
+            title=data.get("title", ""),
+            authors=data.get("authors", []),
+            year=data.get("year"),
+            journal=data.get("journal"),
+            volume=data.get("volume"),
+            issue=data.get("issue"),
+            page=data.get("page"),
+            abstract=data.get("abstract"),
+            citation_count=data.get("citation_count"),
+        )
+
+    def get_many(self, dois: List[str]) -> List[Work]:
+        """
+        Get multiple works by DOI using batch endpoint.
+
+        Args:
+            dois: List of DOIs
+
+        Returns:
+            List of Work objects
+        """
+        # Use batch endpoint if available
+        try:
+            data = {"dois": dois}
+            req_data = json.dumps(data).encode("utf-8")
+            req = urllib.request.Request(
+                f"{self.base_url}/works/batch", data=req_data, method="POST"
+            )
+            req.add_header("Content-Type", "application/json")
+            req.add_header("Accept", "application/json")
+
+            with urllib.request.urlopen(req, timeout=self.timeout) as response:
+                result = json.loads(response.read().decode("utf-8"))
+
+            works = []
+            for item in result.get("results", []):
+                work = Work(
+                    doi=item.get("doi", ""),
+                    title=item.get("title", ""),
+                    authors=item.get("authors", []),
+                    year=item.get("year"),
+                    journal=item.get("journal"),
+                    volume=item.get("volume"),
+                    issue=item.get("issue"),
+                    page=item.get("page"),
+                    abstract=item.get("abstract"),
+                    citation_count=item.get("citation_count"),
+                )
+                works.append(work)
+            return works
+        except Exception:
+            # Fallback to individual lookups
+            works = []
+            for doi in dois:
+                work = self.get(doi)
+                if work:
+                    works.append(work)
+            return works
+
+    def exists(self, doi: str) -> bool:
+        """Check if a DOI exists."""
+        return self.get(doi) is not None
+
+    def get_citations(self, doi: str, direction: str = "both") -> Dict:
+        """
+        Get citations for a paper.
+
+        Args:
+            doi: Paper DOI
+            direction: 'citing', 'cited_by', or 'both'
+
+        Returns:
+            Dict with citation information
+        """
+        params = {"doi": doi, "direction": direction}
+        return self._request("/api/citations/", params) or {}
+
+    def get_journal(
+        self, issn: Optional[str] = None, name: Optional[str] = None
+    ) -> Dict:
+        """
+        Get journal information.
+
+        Args:
+            issn: Journal ISSN
+            name: Journal name
+
+        Returns:
+            Dict with journal information
+        """
+        params = {"issn": issn, "name": name}
+        return self._request("/api/journal/", params) or {}
+
+
+# Module-level client for convenience
+_client: Optional[RemoteClient] = None
+
+
+def get_client(base_url: str = "http://localhost:3333") -> RemoteClient:
+    """Get or create singleton remote client."""
+    global _client
+    if _client is None or _client.base_url != base_url:
+        _client = RemoteClient(base_url)
+    return _client
+
+
+def reset_client() -> None:
+    """Reset singleton client."""
+    global _client
+    _client = None