openalex-local 0.1.0__py3-none-any.whl → 0.3.1__py3-none-any.whl

openalex_local/_cli/mcp.py

@@ -0,0 +1,210 @@
+#!/usr/bin/env python3
+"""MCP CLI subcommands for openalex_local."""
+
+import sys
+
+import click
+
+from .. import info
+
+CONTEXT_SETTINGS = {"help_option_names": ["-h", "--help"]}
+
+
+@click.group(context_settings=CONTEXT_SETTINGS)
+def mcp():
+    """MCP (Model Context Protocol) server commands.
+
+    \b
+    Commands:
+      start        - Start the MCP server
+      doctor       - Diagnose MCP setup
+      installation - Show installation instructions
+      list-tools   - List available MCP tools
+    """
+    pass
+
+
+@mcp.command("start", context_settings=CONTEXT_SETTINGS)
+@click.option(
+    "-t",
+    "--transport",
+    type=click.Choice(["stdio", "sse", "http"]),
+    default="stdio",
+    help="Transport protocol (http recommended for remote)",
+)
+@click.option(
+    "--host",
+    default="localhost",
+    envvar="OPENALEX_LOCAL_MCP_HOST",
+    help="Host for HTTP/SSE transport",
+)
+@click.option(
+    "--port",
+    default=8083,
+    type=int,
+    envvar="OPENALEX_LOCAL_MCP_PORT",
+    help="Port for HTTP/SSE transport",
+)
+def mcp_start(transport: str, host: str, port: int):
+    """Start the MCP server.
+
+    \b
+    Transports:
+      stdio  - Standard I/O (default, for Claude Desktop local)
+      http   - Streamable HTTP (recommended for remote/persistent)
+      sse    - Server-Sent Events (deprecated as of MCP spec 2025-03-26)
+
+    \b
+    Local configuration (stdio):
+      {
+        "mcpServers": {
+          "openalex": {
+            "command": "openalex-local",
+            "args": ["mcp", "start"]
+          }
+        }
+      }
+
+    \b
+    Remote configuration (http):
+      # Start server:
+      openalex-local mcp start -t http --host 0.0.0.0 --port 8083
+
+      # Client config:
+      {
+        "mcpServers": {
+          "openalex-remote": {
+            "url": "http://your-server:8083/mcp"
+          }
+        }
+      }
+    """
+    run_mcp_server(transport, host, port)
+
+
+@mcp.command("doctor", context_settings=CONTEXT_SETTINGS)
+def mcp_doctor():
+    """Diagnose MCP server setup and dependencies."""
+    click.echo("MCP Server Diagnostics")
+    click.echo("=" * 50)
+    click.echo()
+
+    # Check fastmcp
+    click.echo("Dependencies:")
+    try:
+        import fastmcp
+
+        click.echo(
+            f"  [OK] fastmcp installed (v{getattr(fastmcp, '__version__', 'unknown')})"
+        )
+    except ImportError:
+        click.echo("  [FAIL] fastmcp not installed")
+        click.echo("         Fix: pip install openalex-local[mcp]")
+        sys.exit(1)
+
+    click.echo()
+
+    # Check database
+    click.echo("Database:")
+    try:
+        db_info = info()
+        click.echo("  [OK] Database accessible")
+        click.echo(f"       Works: {db_info.get('work_count', 0):,}")
+        click.echo(f"       FTS indexed: {db_info.get('fts_indexed', 0):,}")
+    except Exception as e:
+        click.echo(f"  [FAIL] Database error: {e}")
+        sys.exit(1)
+
+    click.echo()
+    click.echo("All checks passed! MCP server is ready.")
+    click.echo()
+    click.echo("Start with:")
+    click.echo("  openalex-local mcp start              # stdio (Claude Desktop)")
+    click.echo("  openalex-local mcp start -t http      # HTTP transport")
+
+
+@mcp.command("installation", context_settings=CONTEXT_SETTINGS)
+def mcp_installation():
+    """Show MCP client installation instructions."""
+    click.echo("MCP Client Configuration")
+    click.echo("=" * 50)
+    click.echo()
+    click.echo("1. Local (stdio) - Claude Desktop / Claude Code:")
+    click.echo()
+    click.echo("   Add to your MCP client config (e.g., claude_desktop_config.json):")
+    click.echo()
+    click.echo("   {")
+    click.echo('     "mcpServers": {')
+    click.echo('       "openalex-local": {')
+    click.echo('         "command": "openalex-local",')
+    click.echo('         "args": ["mcp", "start"],')
+    click.echo('         "env": {')
+    click.echo('           "OPENALEX_LOCAL_DB": "/path/to/openalex.db"')
+    click.echo("         }")
+    click.echo("       }")
+    click.echo("     }")
+    click.echo("   }")
+    click.echo()
+    click.echo("2. Remote (HTTP) - Persistent server:")
+    click.echo()
+    click.echo("   Server side:")
+    click.echo("     openalex-local mcp start -t http --host 0.0.0.0 --port 8083")
+    click.echo()
+    click.echo("   Client config:")
+    click.echo("   {")
+    click.echo('     "mcpServers": {')
+    click.echo('       "openalex-remote": {')
+    click.echo('         "url": "http://your-server:8083/mcp"')
+    click.echo("       }")
+    click.echo("     }")
+    click.echo("   }")
+
+
+@mcp.command("list-tools", context_settings=CONTEXT_SETTINGS)
+def mcp_list_tools():
+    """List available MCP tools."""
+    click.echo("Available MCP Tools")
+    click.echo("=" * 50)
+    click.echo()
+    click.echo("1. search")
+    click.echo("   Search for academic works by title, abstract, or authors.")
+    click.echo("   Parameters:")
+    click.echo("     - query (str): Search query")
+    click.echo("     - limit (int): Max results (default: 10, max: 100)")
+    click.echo("     - offset (int): Skip first N results")
+    click.echo("     - with_abstracts (bool): Include abstracts")
+    click.echo()
+    click.echo("2. search_by_id")
+    click.echo("   Get detailed information about a work by OpenAlex ID or DOI.")
+    click.echo("   Parameters:")
+    click.echo("     - identifier (str): OpenAlex ID or DOI")
+    click.echo("     - as_citation (bool): Return formatted citation")
+    click.echo()
+    click.echo("3. status")
+    click.echo("   Get database statistics and status.")
+    click.echo("   Parameters: none")
+    click.echo()
+    click.echo("4. enrich_ids")
+    click.echo("   Enrich OpenAlex IDs or DOIs with full metadata.")
+    click.echo("   Parameters:")
+    click.echo("     - identifiers (list[str]): List of OpenAlex IDs or DOIs")
+
+
+def run_mcp_server(transport: str, host: str, port: int):
+    """Internal function to run MCP server."""
+    try:
+        from .mcp_server import run_server
+    except ImportError:
+        click.echo(
+            "MCP server requires fastmcp. Install with:\n"
+            "  pip install openalex-local[mcp]",
+            err=True,
+        )
+        sys.exit(1)
+
+    run_server(transport=transport, host=host, port=port)
+
+
+def register_mcp_commands(cli_group):
+    """Register MCP commands with the main CLI group."""
+    cli_group.add_command(mcp)

openalex_local/_cli/mcp_server.py

@@ -0,0 +1,235 @@
+#!/usr/bin/env python3
+"""MCP server for OpenAlex Local - Claude integration.
+
+This server exposes openalex-local functionality as MCP tools,
+enabling Claude Desktop and other MCP clients to search academic papers.
+
+Usage:
+    openalex-local mcp start                    # stdio (Claude Desktop)
+    openalex-local mcp start -t http --port 8083  # HTTP transport
+"""
+
+import json
+
+from fastmcp import FastMCP
+
+from .. import (
+    get as _get,
+    get_many as _get_many,
+    info as _info,
+    search as _search,
+)
+
+# Initialize MCP server
+mcp = FastMCP(
+    name="openalex-local",
+    instructions="Local OpenAlex database with 284M+ works and full-text search. "
+    "Use search to find papers by title/abstract, search_by_id for OpenAlex ID or DOI lookup, "
+    "and status for database 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 284M+ 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 = {
+            "openalex_id": work.openalex_id,
+            "doi": work.doi,
+            "title": work.title,
+            "authors": work.authors,
+            "year": work.year,
+            "source": work.source,
+            "cited_by_count": work.cited_by_count,
+        }
+        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_id(
+    identifier: str,
+    as_citation: bool = False,
+    save_path: str | None = None,
+    save_format: str = "json",
+) -> str:
+    """Get detailed information about a work by OpenAlex ID or DOI.
+
+    Args:
+        identifier: OpenAlex ID (e.g., "W2741809807") or DOI (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_id("W2741809807")
+        search_by_id("10.1038/nature12373")
+        search_by_id("10.1126/science.aax0758", as_citation=True)
+        search_by_id("W2741809807", save_path="paper.bib", save_format="bibtex")
+    """
+    work = _get(identifier)
+
+    if work is None:
+        return json.dumps({"error": f"Not found: {identifier}"})
+
+    # 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.
+    """
+    db_info = _info()
+    return json.dumps(db_info, indent=2)
+
+
+@mcp.tool()
+def enrich_ids(identifiers: list[str]) -> str:
+    """Enrich OpenAlex IDs or DOIs with full metadata.
+
+    Use this after search() to get detailed metadata for papers.
+    The search() tool returns basic info (title, authors, year, source).
+    This tool adds: abstract, concepts, is_oa, oa_url, etc.
+
+    Typical workflow:
+    1. search("epilepsy seizure prediction") -> get IDs
+    2. enrich_ids([id1, id2, ...]) -> get full metadata
+
+    Args:
+        identifiers: List of OpenAlex IDs or DOIs
+
+    Returns:
+        JSON string with enriched works.
+
+    Examples:
+        enrich_ids(["W2741809807"])
+        enrich_ids(["10.1038/nature12373", "W2741809807"])
+    """
+    works = _get_many(identifiers)
+
+    works_data = []
+    for work in works:
+        works_data.append(work.to_dict())
+
+    return json.dumps(
+        {
+            "requested": len(identifiers),
+            "found": len(works_data),
+            "works": works_data,
+        },
+        indent=2,
+    )
+
+
+def run_server(
+    transport: str = "stdio",
+    host: str = "localhost",
+    port: int = 8083,
+) -> 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 openalex-local-mcp command."""
+    run_server(transport="stdio")
+
+
+if __name__ == "__main__":
+    main()

openalex_local/_core/__init__.py

@@ -0,0 +1,42 @@
+#!/usr/bin/env python3
+"""Internal core modules - public API only."""
+
+from .api import (
+    SearchResult,
+    Work,
+    configure,
+    count,
+    enrich,
+    enrich_ids,
+    exists,
+    get,
+    get_many,
+    get_mode,
+    info,
+    search,
+)
+from .export import SUPPORTED_FORMATS, save
+
+__all__ = [
+    # Core functions
+    "search",
+    "count",
+    "get",
+    "get_many",
+    "exists",
+    "info",
+    # Enrich functions
+    "enrich",
+    "enrich_ids",
+    # Configuration
+    "configure",
+    "get_mode",
+    # Models
+    "Work",
+    "SearchResult",
+    # Export
+    "save",
+    "SUPPORTED_FORMATS",
+]
+
+# EOF