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

crossref_local/_cli/mcp_server.py

@@ -0,0 +1,457 @@
+"""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,
+    save_path: str | None = None,
+    save_format: str = "json",
+) -> 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)
+        offset: Skip first N results for pagination (default: 0)
+        with_abstracts: Include abstracts in results (default: False)
+        save_path: Optional file path to save results (e.g., "results.json", "papers.bib")
+        save_format: Output format for save_path: "text", "json", or "bibtex" (default: "json")
+
+    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)
+        search("epilepsy", save_path="epilepsy.bib", save_format="bibtex")
+    """
+    results = _search(query, limit=limit, offset=offset)
+
+    # Save to file if requested
+    saved_path = None
+    if save_path:
+        from .._core.export import save as _save
+
+        try:
+            saved_path = _save(
+                results, save_path, format=save_format, include_abstract=with_abstracts
+            )
+        except Exception as e:
+            return json.dumps({"error": f"Failed to save: {e}"})
+
+    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)
+
+    result = {
+        "query": results.query,
+        "total": results.total,
+        "returned": len(works_data),
+        "elapsed_ms": round(results.elapsed_ms, 2),
+        "works": works_data,
+    }
+
+    if saved_path:
+        result["saved_to"] = saved_path
+
+    return json.dumps(result, indent=2)
+
+
+@mcp.tool()
+def search_by_doi(
+    doi: str,
+    as_citation: bool = False,
+    save_path: str | None = None,
+    save_format: str = "json",
+) -> 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
+        save_path: Optional file path to save result (e.g., "paper.json", "paper.bib")
+        save_format: Output format for save_path: "text", "json", or "bibtex" (default: "json")
+
+    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)
+        search_by_doi("10.1038/nature12373", save_path="paper.bib", save_format="bibtex")
+    """
+    work = _get(doi)
+
+    if work is None:
+        return json.dumps({"error": f"DOI not found: {doi}"})
+
+    # Save to file if requested
+    saved_path = None
+    if save_path:
+        from .._core.export import save as _save
+
+        try:
+            saved_path = _save(work, save_path, format=save_format)
+        except Exception as e:
+            return json.dumps({"error": f"Failed to save: {e}"})
+
+    if as_citation:
+        result = work.citation()
+        if saved_path:
+            result += f"\n\n(Saved to: {saved_path})"
+        return result
+
+    result = work.to_dict()
+    if saved_path:
+        result["saved_to"] = saved_path
+
+    return json.dumps(result, 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/_cli/search.py

@@ -0,0 +1,199 @@
+"""Search commands for crossref-local CLI."""
+
+import json
+import re
+import sys
+from typing import Optional
+
+import click
+from rich.console import Console
+
+from .. import get, search
+from .._core.export import save as _save
+
+console = Console()
+
+CONTEXT_SETTINGS = {"help_option_names": ["-h", "--help"]}
+
+
+def _strip_xml_tags(text: str) -> str:
+    """Strip XML/JATS tags from abstract text."""
+    if not text:
+        return text
+    text = re.sub(r"<[^>]+>", " ", text)
+    text = re.sub(r"\s+", " ", text)
+    return text.strip()
+
+
+def _get_if_fast(db, issn: str, cache: dict) -> Optional[float]:
+    """Fast IF lookup from OpenAlex data."""
+    if issn in cache:
+        return cache[issn]
+    q = "SELECT two_year_mean_citedness FROM journals_openalex WHERE issns LIKE ?"
+    row = db.fetchone(q, (f"%{issn}%",))
+    cache[issn] = row["two_year_mean_citedness"] if row else None
+    return cache[issn]
+
+
+@click.command("search", context_settings=CONTEXT_SETTINGS)
+@click.argument("query")
+@click.option(
+    "-n", "--number", "limit", default=10, show_default=True, help="Number of results"
+)
+@click.option("-o", "--offset", default=0, help="Skip first N results")
+@click.option("-a", "--abstracts", is_flag=True, help="Show abstracts")
+@click.option("-A", "--authors", is_flag=True, help="Show authors")
+@click.option(
+    "-if", "--impact-factor", "with_if", is_flag=True, help="Show journal impact factor"
+)
+@click.option("--json", "as_json", is_flag=True, help="Output as JSON")
+@click.option(
+    "--save",
+    "save_path",
+    type=click.Path(),
+    help="Save results to file",
+)
+@click.option(
+    "--format",
+    "save_format",
+    type=click.Choice(["text", "json", "bibtex"]),
+    default="json",
+    help="Output format for --save (default: json)",
+)
+def search_cmd(
+    query: str,
+    limit: int,
+    offset: int,
+    abstracts: bool,
+    authors: bool,
+    with_if: bool,
+    as_json: bool,
+    save_path: Optional[str],
+    save_format: str,
+):
+    """Search for works by title, abstract, or authors."""
+    from .._core.config import Config
+    from .._core.db import get_db
+
+    try:
+        results = search(query, limit=limit, offset=offset, with_if=with_if)
+    except ConnectionError as e:
+        click.secho(f"Error: {e}", fg="red", err=True)
+        sys.exit(1)
+
+    # Local IF lookup only in DB mode (HTTP gets IF from API)
+    if_cache, db = {}, None
+    if with_if and Config.get_mode() != "http":
+        try:
+            db = get_db()
+        except FileNotFoundError:
+            pass
+
+    # Save to file if requested
+    if save_path:
+        try:
+            saved = _save(
+                results, save_path, format=save_format, include_abstract=abstracts
+            )
+            click.secho(
+                f"Saved {len(results)} results to {saved}", fg="green", err=True
+            )
+        except Exception as e:
+            click.secho(f"Error saving: {e}", fg="red", err=True)
+            sys.exit(1)
+
+    if as_json:
+        output = {
+            "query": results.query,
+            "total": results.total,
+            "elapsed_ms": results.elapsed_ms,
+            "works": [w.to_dict() for w in results.works],
+        }
+        click.echo(json.dumps(output, indent=2))
+    else:
+        click.secho(
+            f"Found {results.total:,} matches in {results.elapsed_ms:.1f}ms\n",
+            fg="green",
+        )
+        for i, work in enumerate(results.works, start=offset + 1):
+            title = _strip_xml_tags(work.title) if work.title else "Untitled"
+            year = f"({work.year})" if work.year else ""
+            click.secho(f"{i}. {title} {year}", fg="cyan", bold=True)
+            click.echo(f"   DOI: {work.doi or 'N/A'}")
+            if authors and work.authors:
+                authors_str = ", ".join(work.authors[:5])
+                if len(work.authors) > 5:
+                    authors_str += f" et al. ({len(work.authors)} total)"
+                click.echo(f"   Authors: {authors_str}")
+            journal_line = f"   Journal: {work.journal or 'N/A'}"
+            if_val = work.impact_factor or (
+                db and work.issn and _get_if_fast(db, work.issn, if_cache)
+            )
+            if if_val:
+                journal_line += f" (IF: {if_val:.2f}, OpenAlex)"
+            click.echo(journal_line)
+            if abstracts and work.abstract:
+                abstract = _strip_xml_tags(work.abstract)[:500]
+                click.echo(
+                    f"   Abstract: {abstract}{'...' if len(work.abstract) > 500 else ''}"
+                )
+            click.echo()
+
+
+@click.command("search-by-doi", context_settings=CONTEXT_SETTINGS)
+@click.argument("doi")
+@click.option("--json", "as_json", is_flag=True, help="Output as JSON")
+@click.option("--citation", is_flag=True, help="Output as citation")
+@click.option(
+    "--save",
+    "save_path",
+    type=click.Path(),
+    help="Save result to file",
+)
+@click.option(
+    "--format",
+    "save_format",
+    type=click.Choice(["text", "json", "bibtex"]),
+    default="json",
+    help="Output format for --save (default: json)",
+)
+def search_by_doi_cmd(
+    doi: str,
+    as_json: bool,
+    citation: bool,
+    save_path: Optional[str],
+    save_format: str,
+):
+    """Search for a work by DOI."""
+    try:
+        work = get(doi)
+    except ConnectionError as e:
+        click.echo(f"Error: {e}", err=True)
+        click.echo("\nRun 'crossref-local status' to check configuration.", err=True)
+        sys.exit(1)
+
+    if work is None:
+        click.echo(f"DOI not found: {doi}", err=True)
+        sys.exit(1)
+
+    # Save to file if requested
+    if save_path:
+        try:
+            saved = _save(work, save_path, format=save_format)
+            click.secho(f"Saved to {saved}", fg="green", err=True)
+        except Exception as e:
+            click.secho(f"Error saving: {e}", fg="red", err=True)
+            sys.exit(1)
+
+    if as_json:
+        click.echo(json.dumps(work.to_dict(), indent=2))
+    elif citation:
+        click.echo(work.citation())
+    else:
+        click.echo(f"Title: {work.title}")
+        click.echo(f"Authors: {', '.join(work.authors)}")
+        click.echo(f"Year: {work.year}")
+        click.echo(f"Journal: {work.journal}")
+        click.echo(f"DOI: {work.doi}")
+        if work.citation_count:
+            click.echo(f"Citations: {work.citation_count}")

crossref_local/_core/__init__.py

@@ -0,0 +1,62 @@
+#!/usr/bin/env python3
+"""Internal core modules for crossref_local."""
+
+from .api import (
+    configure,
+    configure_http,
+    configure_remote,
+    count,
+    enrich,
+    enrich_dois,
+    exists,
+    get,
+    get_many,
+    get_mode,
+    info,
+    search,
+)
+from .citations import (
+    CitationNetwork,
+    get_citation_count,
+    get_cited,
+    get_citing,
+)
+from .config import Config
+from .db import Database, close_db, get_db
+from .export import SUPPORTED_FORMATS, save
+from .models import SearchResult, Work
+
+__all__ = [
+    # API functions
+    "search",
+    "count",
+    "get",
+    "get_many",
+    "exists",
+    "enrich",
+    "enrich_dois",
+    "configure",
+    "configure_http",
+    "configure_remote",
+    "get_mode",
+    "info",
+    # Models
+    "Work",
+    "SearchResult",
+    # Citations
+    "get_citing",
+    "get_cited",
+    "get_citation_count",
+    "CitationNetwork",
+    # Database
+    "Database",
+    "get_db",
+    "close_db",
+    # Config
+    "Config",
+    # Export
+    "save",
+    "SUPPORTED_FORMATS",
+]
+
+# EOF