codebase-mcp 0.1.0__py3-none-any.whl

codebase_mcp/__init__.py

@@ -0,0 +1,3 @@
+"""Codebase MCP — persistent, portable codebase intelligence server."""
+
+__version__ = "0.1.0"

codebase_mcp/__main__.py

@@ -0,0 +1,524 @@
+"""
+CLI entry point for codebase-mcp.
+
+Usage:
+  codebase-mcp setup                      # Auto-install MCP config in all IDEs (run once)
+  codebase-mcp serve                      # Run MCP server (stdio, for Claude Code / Cursor / Cline)
+  codebase-mcp serve --watch              # Serve + auto-reindex on file changes
+  codebase-mcp index [PATH]               # Index a project (or cwd)
+  codebase-mcp status [PATH]             # Show index status + what changed
+  codebase-mcp github URL                 # Clone any GitHub repo and index it
+  codebase-mcp handoff [PATH]            # Create portable bundle for agent/IDE switch
+  codebase-mcp ui [PATH]                 # Open the web UI in a browser
+  codebase-mcp export [PATH]             # Export context to JSON
+  codebase-mcp import FILE [PATH]        # Import a context snapshot
+"""
+
+from __future__ import annotations
+import json
+import os
+import sys
+
+import click
+from rich.console import Console
+from rich.table import Table
+
+console = Console()
+err_console = Console(stderr=True)  # for MCP stdio mode (stdout is the MCP protocol wire)
+
+
+@click.group()
+@click.version_option(package_name="codebase-mcp")
+def cli():
+    """Codebase Intelligence MCP Server — persistent, portable, incremental."""
+    pass
+
+
+@cli.command()
+@click.option("--transport", default="stdio", type=click.Choice(["stdio", "http"]),
+              show_default=True, help="MCP transport mode.")
+@click.option("--host", default="127.0.0.1", show_default=True, help="HTTP host (http transport only).")
+@click.option("--port", default=8765, show_default=True, help="HTTP port (http transport only).")
+@click.option("--project-root", default="", help="Project root to pre-configure.")
+@click.option("--watch", is_flag=True, help="Start file watcher for auto incremental re-index.")
+def serve(transport: str, host: str, port: int, project_root: str, watch: bool):
+    """Start the MCP server. Use with Claude Code, Cursor, Cline, or any MCP client."""
+    from .config import Config, set_config
+    root = os.path.abspath(project_root) if project_root else os.getcwd()
+    cfg = Config(project_root=root)
+    set_config(cfg)
+
+    if watch:
+        from .watcher import start_watcher, WatcherNotAvailable
+        try:
+            start_watcher(root, cfg.db_path, cfg)
+            err_console.print(f"[dim]File watcher active on {root}[/dim]")
+        except WatcherNotAvailable as e:
+            err_console.print(f"[yellow]Watch disabled: {e}[/yellow]")
+
+    from .server import mcp
+    if transport == "stdio":
+        err_console.print("[dim]codebase-mcp running on stdio[/dim]")
+        mcp.run(transport="stdio")
+    else:
+        err_console.print(f"[dim]codebase-mcp HTTP server on {host}:{port}[/dim]")
+        mcp.run(transport="streamable-http", host=host, port=port)
+
+
+@cli.command()
+@click.argument("path", default="", required=False)
+@click.option("--full", is_flag=True, help="Force full re-index (ignore cached hashes).")
+@click.option("--exclude", multiple=True, help="Additional glob patterns to exclude.")
+def index(path: str, full: bool, exclude: tuple):
+    """Index a project directory (defaults to current directory)."""
+    from .config import Config, set_config
+    from .indexer import run_index
+
+    root = os.path.abspath(path or os.getcwd())
+    cfg = Config(project_root=root, exclude_patterns=[])
+    # Merge defaults + custom excludes
+    from .config import DEFAULT_EXCLUDE_PATTERNS
+    cfg.exclude_patterns = list(DEFAULT_EXCLUDE_PATTERNS) + list(exclude)
+    set_config(cfg)
+
+    console.print(f"[bold]Indexing[/bold] {root} {'(full re-index)' if full else '(incremental)'}...")
+
+    result = run_index(cfg.db_path, root, cfg, full_reindex=full)
+
+    table = Table(show_header=False, box=None, padding=(0, 2))
+    table.add_row("[cyan]Files scanned[/cyan]",    str(result.files_scanned))
+    table.add_row("[cyan]Files changed[/cyan]",    str(result.files_changed))
+    table.add_row("[cyan]Files re-parsed[/cyan]",  str(result.files_reparsed))
+    table.add_row("[cyan]Files deleted[/cyan]",    str(result.files_deleted))
+    table.add_row("[cyan]Files errored[/cyan]",    str(result.files_errored))
+    table.add_row("[cyan]Symbols added[/cyan]",    str(result.symbols_added))
+    table.add_row("[cyan]Duration[/cyan]",         f"{result.duration_ms:.0f}ms")
+    table.add_row("[cyan]Database[/cyan]",         cfg.db_path)
+    console.print(table)
+
+    if result.errors:
+        console.print(f"\n[yellow]Parse errors ({len(result.errors)}):[/yellow]")
+        for e in result.errors[:10]:
+            console.print(f"  [red]{e['path']}[/red]: {e['error']}")
+
+
+@cli.command()
+@click.argument("path", default="", required=False)
+def status(path: str):
+    """Show index status and staleness for a project."""
+    from .config import Config, set_config
+    from .db import open_db, get_all_meta, get_stats
+    from .indexer import find_stale_files
+
+    root = os.path.abspath(path or os.getcwd())
+    cfg = Config(project_root=root)
+    set_config(cfg)
+
+    if not os.path.exists(cfg.db_path):
+        console.print(f"[yellow]No index found at {cfg.db_path}[/yellow]")
+        console.print("Run [bold]codebase-mcp index[/bold] to create one.")
+        return
+
+    conn = open_db(cfg.db_path)
+    meta = get_all_meta(conn)
+    stats = get_stats(conn)
+    stale = find_stale_files(conn, root, cfg)
+    db_size = os.path.getsize(cfg.db_path)
+
+    console.print(f"\n[bold]Codebase Index Status[/bold] — {root}\n")
+
+    table = Table(show_header=False, box=None, padding=(0, 2))
+    table.add_row("Project",         meta.get("project_name", "(unnamed)"))
+    table.add_row("Last indexed",    meta.get("last_indexed", "never"))
+    table.add_row("Database",        cfg.db_path)
+    table.add_row("DB size",         f"{db_size:,} bytes")
+    table.add_row("Files indexed",   str(stats["files_indexed"]))
+    table.add_row("Symbols total",   str(stats["symbols_total"]))
+    table.add_row("Functions",       str(stats["functions"]))
+    table.add_row("Classes",         str(stats["classes"]))
+    table.add_row("Decisions",       str(stats["decisions_active"]))
+    table.add_row("Notes",           str(stats["notes"]))
+    table.add_row("Languages",       ", ".join(f"{k}:{v}" for k, v in stats["language_breakdown"].items()))
+    console.print(table)
+
+    if stale:
+        console.print(f"\n[yellow]Index is stale[/yellow] — {len(stale)} file(s) changed:")
+        for f in stale[:15]:
+            console.print(f"  [dim]{f}[/dim]")
+        if len(stale) > 15:
+            console.print(f"  ... and {len(stale) - 15} more")
+        console.print("\nRun [bold]codebase-mcp index[/bold] to update.")
+    else:
+        console.print("\n[green]Index is fresh.[/green]")
+
+
+@cli.command("export")
+@click.argument("path", default="", required=False)
+@click.option("--output", "-o", default="", help="Output file path.")
+@click.option("--no-index", is_flag=True, help="Skip the structural index (decisions+notes only).")
+@click.option("--compress", "-z", is_flag=True, help="Gzip-compress the output.")
+def export_cmd(path: str, output: str, no_index: bool, compress: bool):
+    """Export the full context to a portable JSON snapshot."""
+    from .config import Config, set_config
+    from .exporter import export_context as _export
+
+    root = os.path.abspath(path or os.getcwd())
+    cfg = Config(project_root=root)
+    set_config(cfg)
+
+    result = _export(
+        cfg.db_path, output or None,
+        include_index=not no_index,
+        include_decisions=True,
+        include_notes=True,
+        compress=compress,
+    )
+    console.print(f"[green]Exported[/green] → {result['path']}")
+    console.print(f"  Size: {result['size_bytes']:,} bytes")
+    for k, v in result.items():
+        if k.endswith("_exported"):
+            console.print(f"  {k.replace('_exported', '')}: {v}")
+
+
+@cli.command("import")
+@click.argument("import_file")
+@click.argument("path", default="", required=False)
+@click.option("--replace", is_flag=True, help="Replace existing decisions instead of merging.")
+@click.option("--with-index", is_flag=True, help="Also import the structural index.")
+def import_cmd(import_file: str, path: str, replace: bool, with_index: bool):
+    """Import a context snapshot from a JSON export file."""
+    from .config import Config, set_config
+    from .exporter import import_context as _import
+
+    root = os.path.abspath(path or os.getcwd())
+    cfg = Config(project_root=root)
+    set_config(cfg)
+
+    result = _import(
+        cfg.db_path, import_file,
+        merge_decisions=not replace,
+        reimport_index=with_index,
+    )
+    console.print(f"[green]Imported[/green] from {import_file}")
+    for k, v in result.get("imported", {}).items():
+        console.print(f"  {k}: +{v}")
+
+
+@cli.command("handoff")
+@click.argument("path", default="", required=False)
+@click.option("--output", "-o", default="", help="Output directory path. Default: auto-named in exports/.")
+@click.option("--zip", "as_zip", is_flag=True, help="Package as a .zip file instead of a directory.")
+@click.option("--no-index", is_flag=True, help="Omit the structural index (decisions+notes only).")
+def handoff_cmd(path: str, output: str, as_zip: bool, no_index: bool):
+    """Create a portable handoff bundle for transferring context to a new agent or IDE."""
+    from .config import Config, set_config
+    from .handoff import create_handoff_bundle
+
+    root = os.path.abspath(path or os.getcwd())
+    cfg = Config(project_root=root)
+    set_config(cfg)
+
+    console.print(f"[bold]Creating handoff bundle[/bold] for {root}...")
+    result = create_handoff_bundle(
+        cfg.db_path, root,
+        output_dir=output or None,
+        as_zip=as_zip,
+        include_index=not no_index,
+    )
+
+    console.print(f"[green]Handoff bundle created[/green] -> {result['path']}")
+    console.print(f"  Decisions: {result['decisions']}")
+    stats = result.get("stats", {})
+    console.print(f"  Files indexed: {stats.get('files_indexed', 0)}")
+    console.print(f"  Symbols: {stats.get('symbols_total', 0)}")
+    if as_zip:
+        console.print(f"\n[dim]Share {result['path']} with your next agent.[/dim]")
+    else:
+        console.print(f"\n[dim]The receiving agent should run:[/dim]")
+        console.print(f"  [bold]codebase-mcp import {result['path']}/context.json[/bold]")
+
+
+@cli.command("ui")
+@click.argument("path", default="", required=False)
+@click.option("--host", default="127.0.0.1", show_default=True, help="Host to bind to.")
+@click.option("--port", default=8766, show_default=True, help="Port to listen on.")
+@click.option("--no-browser", is_flag=True, help="Don't auto-open the browser.")
+def ui_cmd(path: str, host: str, port: int, no_browser: bool):
+    """Open the web UI for browsing symbols, decisions, and notes."""
+    from .config import Config, set_config
+    from .webui import start_ui_server
+
+    root = os.path.abspath(path or os.getcwd())
+    cfg = Config(project_root=root)
+    set_config(cfg)
+
+    url = f"http://{host}:{port}"
+    console.print(f"[bold]Web UI[/bold] starting at {url}")
+    console.print(f"  Project: {root}")
+    console.print(f"  Database: {cfg.db_path}")
+    console.print("  Press Ctrl+C to stop.\n")
+
+    if not no_browser:
+        import threading
+        import webbrowser
+        threading.Timer(0.8, lambda: webbrowser.open(url)).start()
+
+    start_ui_server(cfg.db_path, host=host, port=port)
+
+
+@cli.command("github")
+@click.argument("url")
+@click.option("--output", "-o", default="", help="Directory to clone into. Default: ~/codebase-mcp-repos/<repo-name>.")
+@click.option("--branch", "-b", default="", help="Branch or tag to checkout. Default: repo default branch.")
+@click.option("--depth", default=1, show_default=True, help="Git clone depth. 1 = shallow (fast). 0 = full history.")
+@click.option("--handoff", "make_handoff", is_flag=True, help="Also create a handoff bundle after indexing.")
+@click.option("--full", is_flag=True, help="Force full re-index (useful if repo was already cloned).")
+def github_cmd(url: str, output: str, branch: str, depth: int, make_handoff: bool, full: bool):
+    """
+    Clone a GitHub (or any git) repo and index it immediately.
+
+    Examples:\n
+      codebase-mcp github https://github.com/owner/repo\n
+      codebase-mcp github https://github.com/owner/repo --branch dev --handoff\n
+      codebase-mcp github git@github.com:owner/repo.git --output /tmp/myrepo
+    """
+    import re
+    import subprocess
+    from .config import Config, set_config, DEFAULT_EXCLUDE_PATTERNS
+    from .indexer import run_index
+
+    # Derive a clean repo name from the URL
+    repo_name = re.sub(r"\.git$", "", url.rstrip("/").split("/")[-1])
+    if not repo_name:
+        console.print("[red]Could not parse repo name from URL.[/red]")
+        raise click.Abort()
+
+    # Determine clone destination
+    if output:
+        clone_dir = os.path.abspath(output)
+    else:
+        default_base = os.path.join(os.path.expanduser("~"), "codebase-mcp-repos")
+        clone_dir = os.path.join(default_base, repo_name)
+
+    # Clone or update
+    if os.path.exists(os.path.join(clone_dir, ".git")):
+        console.print(f"[dim]Repo already cloned at {clone_dir} — pulling latest...[/dim]")
+        result = subprocess.run(
+            ["git", "-C", clone_dir, "pull", "--ff-only"],
+            capture_output=True, text=True,
+        )
+        if result.returncode != 0:
+            console.print(f"[yellow]git pull failed (may be detached HEAD): {result.stderr.strip()}[/yellow]")
+            console.print("[dim]Continuing with existing clone.[/dim]")
+    else:
+        os.makedirs(os.path.dirname(clone_dir), exist_ok=True)
+
+        # On Windows, enable long path support before cloning (avoids 260-char limit)
+        if sys.platform == "win32":
+            subprocess.run(["git", "config", "--global", "core.longpaths", "true"],
+                           capture_output=True)
+
+        cmd = ["git", "clone"]
+        if depth > 0:
+            cmd += ["--depth", str(depth)]
+        if branch:
+            cmd += ["--branch", branch, "--single-branch"]
+        cmd += [url, clone_dir]
+
+        console.print(f"[bold]Cloning[/bold] {url}")
+        console.print(f"  Into: {clone_dir}")
+        if depth > 0:
+            console.print(f"  [dim](shallow clone --depth {depth} for speed)[/dim]")
+
+        result = subprocess.run(cmd, capture_output=True, text=True)
+        if result.returncode != 0:
+            # If checkout partially failed (e.g. long filenames), warn but continue
+            # if the .git dir was at least created
+            if os.path.exists(os.path.join(clone_dir, ".git")):
+                console.print(f"[yellow]Clone warning (partial checkout): {result.stderr.strip()[:300]}[/yellow]")
+                console.print("[dim]Indexing files that were successfully checked out...[/dim]")
+            else:
+                console.print(f"[red]git clone failed:[/red]\n{result.stderr.strip()}")
+                raise click.Abort()
+
+    console.print(f"[green]Cloned[/green] -> {clone_dir}\n")
+
+    # Index it
+    cfg = Config(project_root=clone_dir, exclude_patterns=list(DEFAULT_EXCLUDE_PATTERNS))
+    set_config(cfg)
+
+    console.print(f"[bold]Indexing[/bold] {repo_name} {'(full)' if full else '(incremental)'}...")
+    idx = run_index(cfg.db_path, clone_dir, cfg, full_reindex=full)
+
+    table = Table(show_header=False, box=None, padding=(0, 2))
+    table.add_row("[cyan]Files scanned[/cyan]",   str(idx.files_scanned))
+    table.add_row("[cyan]Files parsed[/cyan]",    str(idx.files_reparsed))
+    table.add_row("[cyan]Symbols found[/cyan]",   str(idx.symbols_added))
+    table.add_row("[cyan]Duration[/cyan]",         f"{idx.duration_ms:.0f}ms")
+    table.add_row("[cyan]Database[/cyan]",         cfg.db_path)
+    console.print(table)
+
+    if idx.errors:
+        console.print(f"\n[yellow]Parse errors ({len(idx.errors)}):[/yellow]")
+        for e in idx.errors[:5]:
+            console.print(f"  [red]{e['path']}[/red]: {e['error']}")
+
+    # Optionally create handoff bundle
+    if make_handoff:
+        from .handoff import create_handoff_bundle
+        console.print("\n[bold]Creating handoff bundle...[/bold]")
+        bundle = create_handoff_bundle(cfg.db_path, clone_dir)
+        console.print(f"[green]Handoff bundle[/green] -> {bundle['path']}")
+
+    console.print(f"""
+[bold]Done.[/bold] To use this index:
+
+  [bold]MCP server:[/bold]
+    codebase-mcp serve --project-root {clone_dir}
+
+  [bold]Web UI:[/bold]
+    codebase-mcp ui {clone_dir}
+
+  [bold]Handoff bundle (if not created above):[/bold]
+    codebase-mcp handoff {clone_dir}
+""")
+
+
+@cli.command("setup")
+@click.argument("path", default="", required=False)
+@click.option("--ide", default="all",
+              type=click.Choice(["all", "claude-code", "cursor", "windsurf", "vscode", "cline", "zed", "print"]),
+              show_default=True, help="Which IDE/agent to generate config for.")
+@click.option("--global", "is_global", is_flag=True,
+              help="Write to global IDE config instead of project-local.")
+def setup_cmd(path: str, ide: str, is_global: bool):
+    """
+    Generate and install MCP server config for your IDE or agent.
+
+    Supports: Claude Code, Cursor, Windsurf, VS Code (with Cline/Continue), Zed.
+    Run once per project (or with --global for all projects).
+
+    Examples:\n
+      codebase-mcp setup                    # Install for all supported IDEs\n
+      codebase-mcp setup --ide cursor       # Cursor only\n
+      codebase-mcp setup --ide claude-code --global  # Claude Code global config\n
+      codebase-mcp setup --ide print        # Just print the config, don't write
+    """
+    import shutil
+
+    root = os.path.abspath(path or os.getcwd())
+
+    # Find the codebase-mcp executable
+    mcp_exe = shutil.which("codebase-mcp") or "codebase-mcp"
+    python_exe = sys.executable
+
+    # MCP server config block (works for all IDEs)
+    server_config = {
+        "command": python_exe,
+        "args": ["-m", "codebase_mcp", "serve", "--project-root", root],
+        "env": {},
+    }
+
+    ide_configs = {
+        "claude-code": {
+            "file": os.path.join(os.path.expanduser("~"), ".claude", "settings.json") if is_global
+                    else os.path.join(root, ".claude", "settings.json"),
+            "format": "claude",
+            "description": "Claude Code (Anthropic CLI)",
+        },
+        "cursor": {
+            "file": os.path.join(os.path.expanduser("~"), ".cursor", "mcp.json") if is_global
+                    else os.path.join(root, ".cursor", "mcp.json"),
+            "format": "cursor",
+            "description": "Cursor IDE",
+        },
+        "windsurf": {
+            "file": os.path.join(os.path.expanduser("~"), ".codeium", "windsurf", "mcp_config.json"),
+            "format": "windsurf",
+            "description": "Windsurf (Codeium)",
+        },
+        "vscode": {
+            "file": os.path.join(root, ".vscode", "mcp.json"),
+            "format": "vscode",
+            "description": "VS Code (with MCP extension / Cline / Continue)",
+        },
+        "cline": {
+            "file": os.path.join(os.path.expanduser("~"), ".vscode", "globalStorage", "saoudrizwan.claude-dev", "settings", "cline_mcp_settings.json"),
+            "format": "cline",
+            "description": "Cline (VS Code extension)",
+        },
+        "zed": {
+            "file": os.path.join(os.path.expanduser("~"), ".config", "zed", "settings.json"),
+            "format": "zed",
+            "description": "Zed editor",
+        },
+    }
+
+    targets = list(ide_configs.keys()) if ide in ("all", "print") else [ide]
+
+    console.print(f"\n[bold]codebase-mcp setup[/bold] for project: {root}\n")
+
+    for target in targets:
+        cfg_info = ide_configs[target]
+        config_file = cfg_info["file"]
+        desc = cfg_info["description"]
+        fmt = cfg_info["format"]
+
+        # Build the config snippet for this IDE
+        if fmt == "claude":
+            snippet = {"mcpServers": {"codebase-intel": server_config}}
+        elif fmt in ("cursor", "windsurf", "cline"):
+            snippet = {"mcpServers": {"codebase-intel": server_config}}
+        elif fmt == "vscode":
+            snippet = {"servers": {"codebase-intel": {"type": "stdio", **server_config}}}
+        elif fmt == "zed":
+            snippet = {"context_servers": {"codebase-intel": {"command": {"path": python_exe, "args": server_config["args"]}}}}
+        else:
+            snippet = {"mcpServers": {"codebase-intel": server_config}}
+
+        if ide == "print":
+            console.print(f"[bold cyan]{desc}[/bold cyan] ({config_file})")
+            console.print(json.dumps(snippet, indent=2))
+            console.print()
+            continue
+
+        # Read existing config and merge
+        os.makedirs(os.path.dirname(config_file), exist_ok=True)
+        existing = {}
+        if os.path.exists(config_file):
+            try:
+                with open(config_file, encoding="utf-8") as f:
+                    existing = json.load(f)
+            except (json.JSONDecodeError, OSError):
+                pass  # Overwrite corrupt config
+
+        # Deep merge at the mcpServers / servers / context_servers level
+        for top_key, inner in snippet.items():
+            if top_key not in existing:
+                existing[top_key] = {}
+            existing[top_key].update(inner)
+
+        try:
+            with open(config_file, "w", encoding="utf-8") as f:
+                json.dump(existing, f, indent=2)
+            console.print(f"[green]OK[/green]  {desc}")
+            console.print(f"     {config_file}")
+        except OSError as e:
+            console.print(f"[yellow]SKIP[/yellow] {desc}: {e}")
+
+    console.print(f"""
+[bold]Done.[/bold] The MCP server entry is named [cyan]codebase-intel[/cyan].
+
+To verify in Claude Code:
+  /mcp
+
+To verify in Cursor/Windsurf:
+  Open MCP settings and look for codebase-intel.
+
+The server starts automatically when your IDE opens.
+First use in a new session: call session_bootstrap() to load full context.
+""")
+
+
+if __name__ == "__main__":
+    cli()