crossref-local 0.3.1__py3-none-any.whl → 0.5.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,351 @@
+"""MCP CLI subcommands for crossref_local."""
+
+import sys
+import click
+
+from .. import info
+
+CONTEXT_SETTINGS = {"help_option_names": ["-h", "--help"]}
+
+
+class AliasedGroup(click.Group):
+    """Click group that supports command aliases."""
+
+    def __init__(self, *args, **kwargs):
+        super().__init__(*args, **kwargs)
+        self._aliases = {}
+
+    def command(self, *args, aliases=None, **kwargs):
+        def decorator(f):
+            cmd = super(AliasedGroup, self).command(*args, **kwargs)(f)
+            if aliases:
+                for alias in aliases:
+                    self._aliases[alias] = cmd.name
+            return cmd
+
+        return decorator
+
+    def get_command(self, ctx, cmd_name):
+        cmd_name = self._aliases.get(cmd_name, cmd_name)
+        return super().get_command(ctx, cmd_name)
+
+
+@click.group(cls=AliasedGroup, 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="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 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": {
+          "crossref": {
+            "command": "crossref-local",
+            "args": ["mcp", "start"]
+          }
+        }
+      }
+
+    \b
+    Remote configuration (http):
+      # Start server:
+      crossref-local mcp start -t http --host 0.0.0.0 --port 8082
+
+      # Client config:
+      {
+        "mcpServers": {
+          "crossref-remote": {
+            "url": "http://your-server:8082/mcp"
+          }
+        }
+      }
+
+    \b
+    See docs/remote-deployment.md for systemd and Docker setup.
+    """
+    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 crossref-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('works', 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("  crossref-local mcp start              # stdio (Claude Desktop)")
+    click.echo("  crossref-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('       "crossref-local": {')
+    click.echo('         "command": "crossref-local",')
+    click.echo('         "args": ["mcp", "start"],')
+    click.echo('         "env": {')
+    click.echo('           "CROSSREF_LOCAL_DB": "/path/to/crossref.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("     crossref-local mcp start -t http --host 0.0.0.0 --port 8082")
+    click.echo()
+    click.echo("   Client config:")
+    click.echo("   {")
+    click.echo('     "mcpServers": {')
+    click.echo('       "crossref-remote": {')
+    click.echo('         "url": "http://your-server:8082/mcp"')
+    click.echo("       }")
+    click.echo("     }")
+    click.echo("   }")
+    click.echo()
+    click.echo("See docs/remote-deployment.md for systemd and Docker setup.")
+
+
+@mcp.command("list-tools", context_settings=CONTEXT_SETTINGS)
+@click.option(
+    "-v", "--verbose", count=True, help="Verbosity: -v sig, -vv +desc, -vvv full"
+)
+@click.option("-c", "--compact", is_flag=True, help="Compact signatures (single line)")
+@click.option("--json", "as_json", is_flag=True, help="Output as JSON")
+def mcp_list_tools(verbose: int, compact: bool, as_json: bool):
+    """List available MCP tools.
+
+    \b
+    Verbosity levels:
+      (none)  - Tool names only
+      -v      - Signatures
+      -vv     - Signatures + one-line description
+      -vvv    - Signatures + full description
+    """
+    try:
+        from .mcp_server import mcp as mcp_server
+    except ImportError:
+        click.secho("ERROR: Could not import MCP server", fg="red", err=True)
+        click.echo("Install with: pip install crossref-local[mcp]")
+        raise SystemExit(1)
+
+    # Get tools grouped by prefix
+    tools_dict = getattr(mcp_server._tool_manager, "_tools", {})
+    modules = {}
+    for name in sorted(tools_dict.keys()):
+        prefix = name.split("_")[0]
+        if prefix not in modules:
+            modules[prefix] = []
+        modules[prefix].append(name)
+
+    if as_json:
+        import json
+
+        output = {
+            "name": "crossref-local",
+            "total": len(tools_dict),
+            "modules": {
+                mod: {
+                    "count": len(tool_list),
+                    "tools": [
+                        {
+                            "name": t,
+                            "description": tools_dict[t].description
+                            if tools_dict.get(t)
+                            else "",
+                        }
+                        for t in tool_list
+                    ],
+                }
+                for mod, tool_list in modules.items()
+            },
+        }
+        click.echo(json.dumps(output, indent=2))
+        return
+
+    total = len(tools_dict)
+    click.secho("CrossRef Local MCP", fg="cyan", bold=True)
+    click.echo(f"Tools: {total} ({len(modules)} modules)")
+    click.echo()
+
+    for mod, tool_list in sorted(modules.items()):
+        click.secho(f"{mod}: {len(tool_list)} tools", fg="green", bold=True)
+        for tool_name in tool_list:
+            tool_obj = tools_dict.get(tool_name)
+
+            if verbose == 0:
+                # Names only
+                click.echo(f"  {tool_name}")
+            elif verbose == 1:
+                # Signature
+                sig = (
+                    _format_signature(tool_obj, multiline=not compact)
+                    if tool_obj
+                    else f"  {tool_name}"
+                )
+                click.echo(sig)
+            elif verbose == 2:
+                # Signature + one-line description
+                sig = (
+                    _format_signature(tool_obj, multiline=not compact)
+                    if tool_obj
+                    else f"  {tool_name}"
+                )
+                click.echo(sig)
+                if tool_obj and tool_obj.description:
+                    desc = tool_obj.description.split("\n")[0].strip()
+                    click.echo(f"    {desc}")
+                click.echo()
+            else:
+                # Signature + full description
+                sig = (
+                    _format_signature(tool_obj, multiline=not compact)
+                    if tool_obj
+                    else f"  {tool_name}"
+                )
+                click.echo(sig)
+                if tool_obj and tool_obj.description:
+                    for line in tool_obj.description.strip().split("\n"):
+                        click.echo(f"    {line}")
+                click.echo()
+        click.echo()
+
+
+def _format_signature(tool_obj, multiline: bool = False, indent: str = "  ") -> str:
+    """Format tool as Python-like function signature with return type."""
+    import inspect
+
+    params = []
+    if hasattr(tool_obj, "parameters") and tool_obj.parameters:
+        schema = tool_obj.parameters
+        props = schema.get("properties", {})
+        required = schema.get("required", [])
+        for name, pinfo in props.items():
+            ptype = pinfo.get("type", "any")
+            default = pinfo.get("default")
+            if name in required:
+                p = f"{click.style(name, fg='white', bold=True)}: {click.style(ptype, fg='cyan')}"
+            elif default is not None:
+                def_str = repr(default) if len(repr(default)) < 20 else "..."
+                p = f"{click.style(name, fg='white', bold=True)}: {click.style(ptype, fg='cyan')} = {click.style(def_str, fg='yellow')}"
+            else:
+                p = f"{click.style(name, fg='white', bold=True)}: {click.style(ptype, fg='cyan')} = {click.style('None', fg='yellow')}"
+            params.append(p)
+
+    # Get return type
+    ret_type = ""
+    if hasattr(tool_obj, "fn") and tool_obj.fn:
+        try:
+            sig = inspect.signature(tool_obj.fn)
+            if sig.return_annotation != inspect.Parameter.empty:
+                ret = sig.return_annotation
+                ret_name = ret.__name__ if hasattr(ret, "__name__") else str(ret)
+                ret_type = f" -> {click.style(ret_name, fg='magenta')}"
+        except Exception:
+            pass
+
+    name_s = click.style(tool_obj.name, fg="green", bold=True)
+    if multiline and len(params) > 2:
+        param_indent = indent + "    "
+        params_str = ",\n".join(f"{param_indent}{p}" for p in params)
+        return f"{indent}{name_s}(\n{params_str}\n{indent}){ret_type}"
+    return f"{indent}{name_s}({', '.join(params)}){ret_type}"
+
+
+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 crossref-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)