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

crossref_local/cli_completion.py

@@ -0,0 +1,245 @@
+"""Shell completion commands for crossref-local CLI."""
+
+import os
+import sys
+from pathlib import Path
+
+import click
+
+PROG_NAME = "crossref-local"
+
+# Shell completion scripts
+BASH_COMPLETION = f"""# {PROG_NAME} bash completion
+eval "$(_CROSSREF_LOCAL_COMPLETE=bash_source {PROG_NAME})"
+"""
+
+ZSH_COMPLETION = f"""# {PROG_NAME} zsh completion
+eval "$(_CROSSREF_LOCAL_COMPLETE=zsh_source {PROG_NAME})"
+"""
+
+FISH_COMPLETION = f"""# {PROG_NAME} fish completion
+_CROSSREF_LOCAL_COMPLETE=fish_source {PROG_NAME} | source
+"""
+
+# Shell config files
+SHELL_CONFIGS = {
+    "bash": [Path.home() / ".bashrc", Path.home() / ".bash_profile"],
+    "zsh": [Path.home() / ".zshrc"],
+    "fish": [Path.home() / ".config" / "fish" / "config.fish"],
+}
+
+COMPLETION_SCRIPTS = {
+    "bash": BASH_COMPLETION,
+    "zsh": ZSH_COMPLETION,
+    "fish": FISH_COMPLETION,
+}
+
+COMPLETION_MARKER = f"# >>> {PROG_NAME} completion >>>"
+COMPLETION_END_MARKER = f"# <<< {PROG_NAME} completion <<<"
+
+
+def _detect_shell() -> str:
+    """Detect current shell from $SHELL environment variable."""
+    shell_path = os.environ.get("SHELL", "")
+    shell_name = Path(shell_path).name if shell_path else ""
+
+    if shell_name in ("bash", "zsh", "fish"):
+        return shell_name
+
+    # Fallback to bash
+    return "bash"
+
+
+def _get_config_file(shell: str) -> Path | None:
+    """Get the appropriate config file for the shell."""
+    configs = SHELL_CONFIGS.get(shell, [])
+    for config in configs:
+        if config.exists():
+            return config
+    # Return first option for creation
+    return configs[0] if configs else None
+
+
+def _is_installed(shell: str) -> tuple[bool, Path | None]:
+    """Check if completion is already installed for a shell."""
+    configs = SHELL_CONFIGS.get(shell, [])
+    for config in configs:
+        if config.exists():
+            content = config.read_text()
+            if COMPLETION_MARKER in content:
+                return True, config
+    return False, None
+
+
+def _install_completion(shell: str) -> tuple[bool, str]:
+    """Install completion for a shell. Returns (success, message)."""
+    installed, existing_file = _is_installed(shell)
+    if installed:
+        return True, f"Already installed in {existing_file}"
+
+    config_file = _get_config_file(shell)
+    if config_file is None:
+        return False, f"Could not find config file for {shell}"
+
+    script = COMPLETION_SCRIPTS.get(shell)
+    if script is None:
+        return False, f"Unsupported shell: {shell}"
+
+    # Create parent directory if needed (for fish)
+    config_file.parent.mkdir(parents=True, exist_ok=True)
+
+    # Append completion to config file
+    completion_block = f"\n{COMPLETION_MARKER}\n{script}{COMPLETION_END_MARKER}\n"
+
+    with open(config_file, "a") as f:
+        f.write(completion_block)
+
+    return True, f"Installed to {config_file}"
+
+
+def _uninstall_completion(shell: str) -> tuple[bool, str]:
+    """Uninstall completion for a shell. Returns (success, message)."""
+    installed, config_file = _is_installed(shell)
+    if not installed:
+        return True, f"Not installed for {shell}"
+
+    if config_file is None:
+        return False, f"Could not find config file for {shell}"
+
+    content = config_file.read_text()
+
+    # Remove the completion block
+    start_idx = content.find(COMPLETION_MARKER)
+    end_idx = content.find(COMPLETION_END_MARKER)
+
+    if start_idx == -1 or end_idx == -1:
+        return False, "Could not find completion block to remove"
+
+    # Include the newline before marker and after end marker
+    if start_idx > 0 and content[start_idx - 1] == "\n":
+        start_idx -= 1
+    end_idx = end_idx + len(COMPLETION_END_MARKER)
+    if end_idx < len(content) and content[end_idx] == "\n":
+        end_idx += 1
+
+    new_content = content[:start_idx] + content[end_idx:]
+    config_file.write_text(new_content)
+
+    return True, f"Removed from {config_file}"
+
+
+@click.group("completion", invoke_without_command=True)
+@click.pass_context
+def completion(ctx):
+    """Shell completion commands.
+
+    \b
+    Install shell tab-completion for crossref-local CLI.
+    Running without subcommand auto-installs for detected shell.
+
+    \b
+    Examples:
+      crossref-local completion          # Auto-install for current shell
+      crossref-local completion status   # Check installation status
+      crossref-local completion bash     # Show bash completion script
+    """
+    if ctx.invoked_subcommand is None:
+        # Auto-install for detected shell
+        shell = _detect_shell()
+        click.echo(f"Detected shell: {shell}")
+
+        success, message = _install_completion(shell)
+        if success:
+            click.echo(f"[OK] {message}")
+            click.echo(
+                f"\nRestart your shell or run: source ~/{_get_config_file(shell).name}"
+            )
+        else:
+            click.echo(f"[ERROR] {message}", err=True)
+            sys.exit(1)
+
+
+@completion.command("install")
+@click.option(
+    "--shell",
+    type=click.Choice(["bash", "zsh", "fish"]),
+    default=None,
+    help="Shell to install completion for (default: auto-detect)",
+)
+def install_cmd(shell: str | None):
+    """Install completion to shell config file."""
+    if shell is None:
+        shell = _detect_shell()
+        click.echo(f"Detected shell: {shell}")
+
+    success, message = _install_completion(shell)
+    if success:
+        click.echo(f"[OK] {message}")
+        config_file = _get_config_file(shell)
+        if config_file:
+            click.echo(f"\nRestart your shell or run: source {config_file}")
+    else:
+        click.echo(f"[ERROR] {message}", err=True)
+        sys.exit(1)
+
+
+@completion.command("uninstall")
+@click.option(
+    "--shell",
+    type=click.Choice(["bash", "zsh", "fish"]),
+    default=None,
+    help="Shell to uninstall completion from (default: auto-detect)",
+)
+def uninstall_cmd(shell: str | None):
+    """Remove completion from shell config file."""
+    if shell is None:
+        shell = _detect_shell()
+        click.echo(f"Detected shell: {shell}")
+
+    success, message = _uninstall_completion(shell)
+    if success:
+        click.echo(f"[OK] {message}")
+    else:
+        click.echo(f"[ERROR] {message}", err=True)
+        sys.exit(1)
+
+
+@completion.command("status")
+def status_cmd():
+    """Check completion installation status for all shells."""
+    click.echo(f"{PROG_NAME} Shell Completion Status")
+    click.echo("=" * 40)
+
+    current_shell = _detect_shell()
+    click.echo(f"Current shell: {current_shell}")
+    click.echo()
+
+    for shell in ["bash", "zsh", "fish"]:
+        installed, config_file = _is_installed(shell)
+        marker = "[x]" if installed else "[ ]"
+        location = f" ({config_file})" if installed and config_file else ""
+        current = " (current)" if shell == current_shell else ""
+        click.echo(f"  {marker} {shell}{current}{location}")
+
+
+@completion.command("bash")
+def bash_cmd():
+    """Show bash completion script."""
+    click.echo(BASH_COMPLETION.strip())
+
+
+@completion.command("zsh")
+def zsh_cmd():
+    """Show zsh completion script."""
+    click.echo(ZSH_COMPLETION.strip())
+
+
+@completion.command("fish")
+def fish_cmd():
+    """Show fish completion script."""
+    click.echo(FISH_COMPLETION.strip())
+
+
+def register_completion_commands(cli_group):
+    """Register completion commands with the main CLI group."""
+    cli_group.add_command(completion)

crossref_local/cli_main.py

@@ -0,0 +1,20 @@
+"""Main CLI entry point with all command groups registered."""
+
+from .cli import cli
+from .cli_cache import register_cache_commands
+from .cli_completion import register_completion_commands
+from .cli_mcp import register_mcp_commands
+
+# Register command groups
+register_cache_commands(cli)
+register_completion_commands(cli)
+register_mcp_commands(cli)
+
+
+def main():
+    """Entry point for CLI."""
+    cli()
+
+
+if __name__ == "__main__":
+    main()

crossref_local/cli_mcp.py

@@ -0,0 +1,275 @@
+"""MCP server management commands for crossref-local CLI."""
+
+import json
+import sys
+
+import click
+
+CONTEXT_SETTINGS = {"help_option_names": ["-h", "--help"]}
+
+
+@click.group("mcp", context_settings=CONTEXT_SETTINGS)
+def mcp():
+    """MCP (Model Context Protocol) server management.
+
+    \b
+    Commands for running and managing the MCP server that enables
+    AI assistants like Claude to search academic papers.
+
+    \b
+    Quick start:
+      crossref-local mcp start              # Start stdio server
+      crossref-local mcp start -t http      # Start HTTP server
+      crossref-local mcp doctor             # Check dependencies
+      crossref-local mcp installation       # Show config snippets
+    """
+    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="CROSSREF_LOCAL_MCP_HOST",
+    help="Host for HTTP/SSE transport",
+)
+@click.option(
+    "--port",
+    default=8082,
+    type=int,
+    envvar="CROSSREF_LOCAL_MCP_PORT",
+    help="Port for HTTP/SSE transport",
+)
+def start_cmd(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
+    Examples:
+      crossref-local mcp start                    # stdio for Claude Desktop
+      crossref-local mcp start -t http            # HTTP on localhost:8082
+      crossref-local mcp start -t http --port 9000  # Custom port
+    """
+    try:
+        from .mcp_server import run_server
+    except ImportError:
+        click.echo(
+            "MCP server requires fastmcp. Install with:\n"
+            "  pip install crossref-local[mcp]",
+            err=True,
+        )
+        sys.exit(1)
+
+    run_server(transport=transport, host=host, port=port)
+
+
+@mcp.command("doctor", context_settings=CONTEXT_SETTINGS)
+def doctor_cmd():
+    """Check MCP server dependencies and configuration.
+
+    Verifies that all required packages are installed and
+    the database is accessible.
+    """
+    click.echo("MCP Server Health Check")
+    click.echo("=" * 40)
+
+    issues = []
+
+    # Check fastmcp
+    try:
+        import fastmcp
+
+        click.echo(f"[OK] fastmcp {fastmcp.__version__}")
+    except ImportError:
+        click.echo("[FAIL] fastmcp not installed")
+        issues.append("Install fastmcp: pip install crossref-local[mcp]")
+
+    # Check database
+    try:
+        from . import info
+
+        db_info = info()
+        works = db_info.get("works", 0)
+        click.echo(f"[OK] Database: {works:,} works")
+    except Exception as e:
+        click.echo(f"[FAIL] Database: {e}")
+        issues.append("Configure database: export CROSSREF_LOCAL_DB=/path/to/db")
+
+    # Check FTS index
+    try:
+        from . import info
+
+        db_info = info()
+        fts = db_info.get("fts_indexed", 0)
+        if fts > 0:
+            click.echo(f"[OK] FTS index: {fts:,} indexed")
+        else:
+            click.echo("[WARN] FTS index: not built")
+            issues.append("Build FTS index: make fts-build")
+    except Exception:
+        pass
+
+    click.echo()
+    if issues:
+        click.echo("Issues found:")
+        for issue in issues:
+            click.echo(f"  - {issue}")
+        sys.exit(1)
+    else:
+        click.echo("All checks passed!")
+
+
+@mcp.command("installation", context_settings=CONTEXT_SETTINGS)
+@click.option(
+    "-t",
+    "--transport",
+    type=click.Choice(["stdio", "http"]),
+    default="stdio",
+    help="Transport type for config",
+)
+@click.option("--host", default="localhost", help="Host for HTTP transport")
+@click.option("--port", default=8082, type=int, help="Port for HTTP transport")
+def installation_cmd(transport: str, host: str, port: int):
+    """Show MCP client configuration snippets.
+
+    Outputs JSON configuration for Claude Desktop or other MCP clients.
+
+    \b
+    Examples:
+      crossref-local mcp installation              # stdio config
+      crossref-local mcp installation -t http      # HTTP config
+    """
+    if transport == "stdio":
+        config = {
+            "mcpServers": {
+                "crossref-local": {
+                    "command": "crossref-local",
+                    "args": ["mcp", "start"],
+                }
+            }
+        }
+        click.echo("Claude Desktop configuration (stdio):")
+        click.echo()
+        click.echo(
+            "Add to ~/Library/Application Support/Claude/claude_desktop_config.json"
+        )
+        click.echo("or ~/.config/claude/claude_desktop_config.json:")
+        click.echo()
+    else:
+        url = f"http://{host}:{port}/mcp"
+        config = {"mcpServers": {"crossref-local": {"url": url}}}
+        click.echo(f"Claude Desktop configuration (HTTP at {url}):")
+        click.echo()
+        click.echo("First start the server:")
+        click.echo(f"  crossref-local mcp start -t http --host {host} --port {port}")
+        click.echo()
+        click.echo("Then add to claude_desktop_config.json:")
+        click.echo()
+
+    click.echo(json.dumps(config, indent=2))
+
+
+@mcp.command("list-tools", context_settings=CONTEXT_SETTINGS)
+@click.option("--json", "as_json", is_flag=True, help="Output as JSON")
+def list_tools_cmd(as_json: bool):
+    """List available MCP tools.
+
+    Shows all tools exposed by the MCP server with their descriptions.
+    """
+    tools = [
+        {
+            "name": "search",
+            "description": "Search for academic works by title, abstract, or authors",
+            "parameters": ["query", "limit", "offset", "with_abstracts"],
+        },
+        {
+            "name": "search_by_doi",
+            "description": "Get detailed information about a work by DOI",
+            "parameters": ["doi", "as_citation"],
+        },
+        {
+            "name": "status",
+            "description": "Get database statistics and status",
+            "parameters": [],
+        },
+        {
+            "name": "enrich_dois",
+            "description": "Enrich DOIs with full metadata including citations",
+            "parameters": ["dois"],
+        },
+        {
+            "name": "cache_create",
+            "description": "Create a paper cache from search query",
+            "parameters": ["name", "query", "limit"],
+        },
+        {
+            "name": "cache_query",
+            "description": "Query cached papers with field filtering",
+            "parameters": ["name", "fields", "year_min", "year_max", "limit"],
+        },
+        {
+            "name": "cache_stats",
+            "description": "Get cache statistics",
+            "parameters": ["name"],
+        },
+        {
+            "name": "cache_list",
+            "description": "List all available caches",
+            "parameters": [],
+        },
+        {
+            "name": "cache_top_cited",
+            "description": "Get top cited papers from cache",
+            "parameters": ["name", "n", "year_min", "year_max"],
+        },
+        {
+            "name": "cache_citation_summary",
+            "description": "Get citation statistics for cached papers",
+            "parameters": ["name"],
+        },
+        {
+            "name": "cache_plot_scatter",
+            "description": "Generate year vs citations scatter plot",
+            "parameters": ["name", "output", "top_n"],
+        },
+        {
+            "name": "cache_plot_network",
+            "description": "Generate citation network visualization",
+            "parameters": ["name", "output", "max_nodes"],
+        },
+        {
+            "name": "cache_export",
+            "description": "Export cache to file (json, csv, bibtex, dois)",
+            "parameters": ["name", "output_path", "format", "fields"],
+        },
+    ]
+
+    if as_json:
+        click.echo(json.dumps(tools, indent=2))
+    else:
+        click.echo("CrossRef Local MCP Tools")
+        click.echo("=" * 50)
+        click.echo()
+        for tool in tools:
+            click.echo(f"  {tool['name']}")
+            click.echo(f"    {tool['description']}")
+            if tool["parameters"]:
+                click.echo(f"    Parameters: {', '.join(tool['parameters'])}")
+            click.echo()
+
+
+def register_mcp_commands(cli_group):
+    """Register MCP commands with the main CLI group."""
+    cli_group.add_command(mcp)

crossref_local/config.py

@@ -6,16 +6,13 @@ from typing import Optional
 
 # Default database locations (checked in order)
 DEFAULT_DB_PATHS = [
-    Path("/home/ywatanabe/proj/crossref-local/data/crossref.db"),
-    Path("/home/ywatanabe/proj/crossref_local/data/crossref.db"),
-    Path("/mnt/nas_ug/crossref_local/data/crossref.db"),
-    Path.home() / ".crossref_local" / "crossref.db",
     Path.cwd() / "data" / "crossref.db",
+    Path.home() / ".crossref_local" / "crossref.db",
 ]
 
 # Default remote API URL (via SSH tunnel)
 DEFAULT_API_URLS = [
-    "http://localhost:3333",  # SSH tunnel to NAS
+    "http://localhost:8333",  # SSH tunnel to NAS
 ]
 DEFAULT_API_URL = DEFAULT_API_URLS[0]
 
@@ -58,7 +55,7 @@ class Config:
 
     _db_path: Optional[Path] = None
     _api_url: Optional[str] = None
-    _mode: str = "auto"  # "auto", "local", or "remote"
+    _mode: str = "auto"  # "auto", "db", or "http"
 
     @classmethod
     def get_mode(cls) -> str:
@@ -66,36 +63,36 @@ class Config:
         Get current mode.
 
         Returns:
-            "local" if using direct database access
-            "remote" if using HTTP API
+            "db" if using direct database access
+            "http" if using HTTP API
         """
         if cls._mode == "auto":
             # Check environment variable
             env_mode = os.environ.get("CROSSREF_LOCAL_MODE", "").lower()
-            if env_mode in ("remote", "api"):
-                return "remote"
-            if env_mode == "local":
-                return "local"
+            if env_mode in ("http", "remote", "api"):
+                return "http"
+            if env_mode in ("db", "local"):
+                return "db"
 
             # Check if API URL is set
-            if cls._api_url or os.environ.get("CROSSREF_LOCAL_API"):
-                return "remote"
+            if cls._api_url or os.environ.get("CROSSREF_LOCAL_API_URL"):
+                return "http"
 
             # Check if local database exists
             try:
                 get_db_path()
-                return "local"
+                return "db"
             except FileNotFoundError:
-                # No local DB, try remote
-                return "remote"
+                # No local DB, try http
+                return "http"
 
         return cls._mode
 
     @classmethod
     def set_mode(cls, mode: str) -> None:
-        """Set mode explicitly: 'local', 'remote', or 'auto'."""
-        if mode not in ("auto", "local", "remote"):
-            raise ValueError(f"Invalid mode: {mode}. Use 'auto', 'local', or 'remote'")
+        """Set mode explicitly: 'db', 'http', or 'auto'."""
+        if mode not in ("auto", "db", "http"):
+            raise ValueError(f"Invalid mode: {mode}. Use 'auto', 'db', or 'http'")
         cls._mode = mode
 
     @classmethod
@@ -112,7 +109,7 @@ class Config:
         if not path.exists():
             raise FileNotFoundError(f"Database not found: {path}")
         cls._db_path = path
-        cls._mode = "local"
+        cls._mode = "db"
 
     @classmethod
     def get_api_url(cls, auto_detect: bool = True) -> str:
@@ -128,7 +125,7 @@ class Config:
         if cls._api_url:
             return cls._api_url
 
-        env_url = os.environ.get("CROSSREF_LOCAL_API")
+        env_url = os.environ.get("CROSSREF_LOCAL_API_URL")
         if env_url:
             return env_url
 
@@ -159,9 +156,9 @@ class Config:
 
     @classmethod
     def set_api_url(cls, url: str) -> None:
-        """Set API URL for remote mode."""
+        """Set API URL for http mode."""
         cls._api_url = url.rstrip("/")
-        cls._mode = "remote"
+        cls._mode = "http"
 
     @classmethod
     def reset(cls) -> None: