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

crossref_local/mcp_server.py

@@ -1,413 +1,8 @@
-"""MCP server for CrossRef Local - Claude integration.
+#!/usr/bin/env python3
+"""Backward compatibility: re-export from _cli.mcp_server."""
 
-This server exposes crossref-local functionality as MCP tools,
-enabling Claude Desktop and other MCP clients to search academic papers.
+from ._cli.mcp_server import mcp, run_server, main
 
-Usage:
-    crossref-local serve                    # stdio (Claude Desktop)
-    crossref-local serve -t http --port 8082  # HTTP transport
-    crossref-local-mcp                      # Direct entry point
-"""
+__all__ = ["mcp", "run_server", "main"]
 
-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()
+# EOF

crossref_local/remote.py

@@ -1,269 +1,8 @@
-"""Remote API client for crossref_local.
+#!/usr/bin/env python3
+"""Backward compatibility: re-export from _remote."""
 
-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.
-"""
+from ._remote import RemoteClient, DEFAULT_API_URL, get_client, reset_client
 
-import json
-import urllib.request
-import urllib.parse
-import urllib.error
-from typing import List, Optional, Dict, Any
+__all__ = ["RemoteClient", "DEFAULT_API_URL", "get_client", "reset_client"]
 
-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
+# EOF