sourcecode 1.30.29__py3-none-any.whl → 1.31.0__py3-none-any.whl

sourcecode/__init__.py

@@ -1,3 +1,3 @@
 """sourcecode — Deterministic codebase context maps for AI coding agents."""
 
-__version__ = "1.30.29"
+__version__ = "1.31.0"

sourcecode/cli.py

@@ -154,6 +154,10 @@ Compressed AI-ready context for Java/Spring enterprise codebases.
 
 [bold]Subcommands:[/bold]
   prepare-context TASK [PATH]  [dim]# task-specific context (onboard, delta, fix-bug, ...)[/dim]
+  mcp init                     [dim]# setup MCP integration (Claude Desktop, Cursor)[/dim]
+  mcp status                   [dim]# show MCP integration status[/dim]
+  mcp remove                   [dim]# remove MCP integration safely[/dim]
+  mcp serve                    [dim]# start MCP server for AI agent integration[/dim]
   telemetry status|enable|disable
   version
 """
@@ -161,7 +165,7 @@ Compressed AI-ready context for Java/Spring enterprise codebases.
 # Known subcommand names — tokens matching these are routed as subcommands,
 # not consumed as a repository path.
 _SUBCOMMANDS: frozenset[str] = frozenset(
-    {"telemetry", "prepare-context", "version", "config", "analyze", "repo-ir"}
+    {"telemetry", "prepare-context", "version", "config", "analyze", "repo-ir", "mcp"}
 )
 
 # Mutable container holding the path extracted by _preprocess_argv().
@@ -188,6 +192,7 @@ _OPTIONS_WITH_VALUE: frozenset[str] = frozenset({
     "--rank-by",
     "--symbol",
     "--max-importers",
+    "--exclude",
 })
 
 
@@ -299,6 +304,9 @@ except Exception:
 telemetry_app = typer.Typer(help="Manage anonymous telemetry (opt-in).", rich_markup_mode="rich")
 app.add_typer(telemetry_app, name="telemetry")
 
+mcp_app = typer.Typer(help="MCP integration: setup, status, serve, remove.", rich_markup_mode="rich")
+app.add_typer(mcp_app, name="mcp")
+
 
 def _maybe_ask_consent() -> None:
     """Show first-run consent prompt once, on interactive TTYs only."""
@@ -316,6 +324,26 @@ def _maybe_ask_consent() -> None:
         pass
 
 
+def _maybe_show_mcp_hint() -> None:
+    """Show MCP integration hint once after first install, on TTY only."""
+    import sys as _sys
+    try:
+        if not _sys.stderr.isatty():
+            return
+        from sourcecode.telemetry.config import _CONFIG_FILE, _load, _save
+        data = _load()
+        if data.get("mcp", {}).get("hint_shown"):
+            return
+        typer.echo("", err=True)
+        typer.echo("  MCP integration available:", err=True)
+        typer.echo("  → sourcecode mcp init", err=True)
+        typer.echo("", err=True)
+        data.setdefault("mcp", {})["hint_shown"] = True
+        _save(data)
+    except Exception:
+        pass
+
+
 def _active_flags(
     dependencies: bool, graph_modules: bool, docs: bool, full_metrics: bool,
     semantics: bool, architecture: bool, git_context: bool, env_map: bool,
@@ -615,6 +643,7 @@ def main(
     # First-run consent (skip for telemetry/version/config subcommands)
     if ctx.invoked_subcommand not in ("telemetry", "version", "config"):
         _maybe_ask_consent()
+        _maybe_show_mcp_hint()
 
     # When a subcommand is invoked, skip the main analysis.
     if ctx.invoked_subcommand is not None:
@@ -851,10 +880,18 @@ def main(
             _copy_to_clipboard(_cache_hit_content)
         return
 
-    # BUG-2: parse --exclude into extra_excludes frozenset
     _extra_excludes: Optional[frozenset[str]] = None
     if exclude:
         _extra_excludes = frozenset(e.strip() for e in exclude.split(",") if e.strip())
+        # IMP-2: warn if the exclude value looks like it was swallowed as a path
+        # (BUG-2 symptom in older versions: --exclude value consumed as repo path).
+        import sys as _sys_warn
+        if len(_extra_excludes) == 1 and Path(list(_extra_excludes)[0]).is_dir():
+            _sys_warn.stderr.write(
+                f"[sourcecode] Warning: --exclude value '{list(_extra_excludes)[0]}' is a directory path. "
+                "If this was meant as a pattern, use --exclude=pattern or --exclude pattern (both are supported).\n"
+            )
+            _sys_warn.stderr.flush()
 
     _progress = Progress()
     _progress.start("scanning files")
@@ -1807,6 +1844,11 @@ def prepare_context_cmd(
         "--fast",
         help="Skip deep analysis (content search, test gap discovery, code annotations). Uses manifest/metadata only. Target: < 6 s.",
     ),
+    include_config: bool = typer.Option(
+        False,
+        "--include-config",
+        help="(generate-tests) Include tooling config files (*.conf.js, .eslintrc*, etc.) in test_gaps. Excluded by default.",
+    ),
 ) -> None:
     """Task-specific context for AI coding agents.
 
@@ -1888,7 +1930,7 @@ def prepare_context_cmd(
             _sys.stderr.flush()
     _t0 = _time.perf_counter()
     try:
-        output = builder.build(task, since=since, symptom=symptom, fast=fast)
+        output = builder.build(task, since=since, symptom=symptom, fast=fast, include_config=include_config)
     finally:
         _progress.finish()
     _t_total = (_time.perf_counter() - _t0) * 1000
@@ -2359,8 +2401,23 @@ def repo_ir_cmd(
             err=True,
         )
     else:
-        _sys.stdout.write(output)
-        _sys.stdout.write("\n")
+        try:
+            _sys.stdout.buffer.write(output.encode("utf-8"))
+            _sys.stdout.buffer.write(b"\n")
+            _sys.stdout.buffer.flush()
+        except UnicodeEncodeError as _ue:
+            # IMP-2: emit workaround before re-raising so the user knows what to do.
+            _sys.stderr.write(
+                f"[sourcecode] UnicodeEncodeError on stdout ({_ue.encoding}): "
+                "your console codec cannot encode this output.\n"
+                "Workaround: sourcecode repo-ir --output ir.json\n"
+            )
+            _sys.stderr.flush()
+            raise
+        except AttributeError:
+            # Fallback for wrapped stdout without buffer (e.g. some test harnesses)
+            _sys.stdout.write(output)
+            _sys.stdout.write("\n")
 
 
 # ── version ───────────────────────────────────────────────────────────────────
@@ -2403,6 +2460,249 @@ def analyze_cmd(
     raise typer.Exit(code=1)
 
 
+# ── MCP server ────────────────────────────────────────────────────────────────
+
+@mcp_app.command("serve")
+def mcp_serve() -> None:
+    """Start the MCP server on stdio for AI agent integration.
+
+    \b
+    Requires the 'mcp' extra:
+      pip install sourcecode[mcp]
+
+    \b
+    Configure in your MCP client (e.g. Claude Desktop):
+      {
+        "sourcecode": {
+          "command": "sourcecode",
+          "args": ["mcp", "serve"]
+        }
+      }
+    """
+    import logging
+    import sys as _sys
+
+    logging.basicConfig(
+        stream=_sys.stderr,
+        level=logging.INFO,
+        format="[sourcecode-mcp] %(levelname)s %(message)s",
+    )
+    try:
+        from sourcecode.mcp.server import mcp as _mcp
+    except ImportError:
+        typer.echo(
+            "MCP support not available. Install with:\n"
+            "  pip install sourcecode[mcp]",
+            err=True,
+        )
+        raise typer.Exit(code=1)
+
+    log = logging.getLogger(__name__)
+    log.info("sourcecode-mcp starting (stdio transport)")
+    try:
+        _mcp.run()
+    except KeyboardInterrupt:
+        log.info("sourcecode-mcp stopped")
+    except Exception as exc:
+        log.critical("sourcecode-mcp fatal error: %s", exc, exc_info=True)
+        raise typer.Exit(code=1)
+
+
+# ── MCP onboarding ────────────────────────────────────────────────────────────
+
+@mcp_app.command("init")
+def mcp_init(
+    yes: bool = typer.Option(False, "--yes", "-y", help="Skip confirmation prompt."),
+) -> None:
+    """Setup MCP integration for Claude Desktop, Cursor, and other clients.
+
+    \b
+    Detects installed MCP clients, backs up their config files, and safely
+    inserts the sourcecode server entry. Fully idempotent — safe to re-run.
+    """
+    from sourcecode.mcp.onboarding.detector import detect_clients
+    from sourcecode.mcp.onboarding.planner import build_install_plan
+    from sourcecode.mcp.onboarding import backup, applier
+
+    typer.echo("Detecting MCP clients...")
+    typer.echo("")
+
+    clients = detect_clients()
+    if not clients:
+        typer.echo("No MCP clients found on this system.")
+        typer.echo("")
+        typer.echo("Manual setup — add to your MCP client config:")
+        typer.echo('  "sourcecode": {"command": "sourcecode", "args": ["mcp", "serve"]}')
+        raise typer.Exit(code=0)
+
+    # Show detection results
+    for client in clients:
+        mark = "✓" if client.app_installed else "○"
+        note = "" if client.app_installed else "  (not found)"
+        typer.echo(f"  {mark}  {client.name:<18} {client.config_path}{note}")
+    typer.echo("")
+
+    # Build plan
+    plan = build_install_plan(clients)
+    actionable = [a for a in plan if a.client.app_installed and not a.already_installed]
+    already_done = [a for a in plan if a.client.app_installed and a.already_installed]
+
+    if already_done and not actionable:
+        typer.echo("Already configured:")
+        for a in already_done:
+            typer.echo(f"  ✓  {a.client.name}   {a.client.config_path}")
+        typer.echo("")
+        typer.echo("Nothing to do. Remove: sourcecode mcp remove")
+        raise typer.Exit(code=0)
+
+    if already_done:
+        typer.echo("Already configured:")
+        for a in already_done:
+            typer.echo(f"  ✓  {a.client.name}   {a.client.config_path}")
+        typer.echo("")
+
+    # Show plan for actionable items
+    typer.echo("This will:")
+    for a in actionable:
+        verb = "Create " if a.will_create_file else "Modify "
+        typer.echo(f"  {verb}  {a.client.config_path}")
+    typer.echo(f"  Backup → ~/.config/sourcecode/mcp-backups/")
+    typer.echo("")
+
+    if not yes:
+        confirmed = typer.confirm("Proceed?", default=False)
+        if not confirmed:
+            typer.echo("Aborted.")
+            raise typer.Exit(code=0)
+        typer.echo("")
+
+    # Apply
+    errors: list[str] = []
+    for a in actionable:
+        try:
+            config = applier.read_config(a.client.config_path)
+            if a.client.config_path.exists():
+                bak = backup.create(a.client.config_path)
+                typer.echo(f"  ✓ Backup   {bak}")
+            updated = applier.apply_entry(config)
+            applier.write_config(a.client.config_path, updated)
+            if not applier.validate(a.client.config_path):
+                errors.append(f"{a.client.name}: JSON validation failed after write")
+                continue
+            typer.echo(f"  ✓ Updated  {a.client.config_path}")
+        except Exception as exc:
+            errors.append(f"{a.client.name}: {exc}")
+
+    typer.echo("")
+
+    if errors:
+        for err in errors:
+            typer.echo(f"  ✗ {err}", err=True)
+        raise typer.Exit(code=1)
+
+    typer.echo("MCP integration active.")
+    typer.echo("")
+
+    restart_needed = [a.client.name for a in actionable if not a.will_create_file]
+    if restart_needed:
+        typer.echo(f"  Restart {', '.join(restart_needed)} to apply changes.")
+    typer.echo("  Remove:  sourcecode mcp remove")
+
+
+@mcp_app.command("status")
+def mcp_status() -> None:
+    """Show MCP integration status for all detected clients."""
+    from sourcecode.mcp.onboarding.detector import detect_clients
+    from sourcecode.mcp.onboarding import applier
+
+    clients = detect_clients()
+    typer.echo("MCP Integration Status")
+    typer.echo("")
+
+    if not clients:
+        typer.echo("  No MCP clients detected on this system.")
+        raise typer.Exit(code=0)
+
+    for client in clients:
+        if not client.app_installed:
+            typer.echo(f"  ○  {client.name:<18} not found")
+            continue
+        config = applier.read_config(client.config_path)
+        if applier.is_installed(config):
+            typer.echo(f"  ✓  {client.name:<18} configured   {client.config_path}")
+        else:
+            typer.echo(f"  ✗  {client.name:<18} not configured")
+    typer.echo("")
+    typer.echo("  Setup:   sourcecode mcp init")
+    typer.echo("  Remove:  sourcecode mcp remove")
+
+
+@mcp_app.command("remove")
+def mcp_remove(
+    yes: bool = typer.Option(False, "--yes", "-y", help="Skip confirmation prompt."),
+) -> None:
+    """Remove sourcecode MCP integration from all configured clients.
+
+    \b
+    Backs up config files before modifying. Restores from backup when available,
+    otherwise removes the sourcecode entry while preserving all other config.
+    """
+    from sourcecode.mcp.onboarding.detector import detect_clients
+    from sourcecode.mcp.onboarding.planner import build_remove_plan
+    from sourcecode.mcp.onboarding import backup, applier
+
+    clients = detect_clients()
+    plan = build_remove_plan(clients)
+    installed = [a for a in plan if a.already_installed]
+
+    if not installed:
+        typer.echo("sourcecode MCP integration not found in any client config.")
+        typer.echo("  Setup: sourcecode mcp init")
+        raise typer.Exit(code=0)
+
+    typer.echo("Remove sourcecode MCP integration from:")
+    typer.echo("")
+    for a in installed:
+        typer.echo(f"  {a.client.name}   {a.client.config_path}")
+        bak = backup.latest(a.client.config_path)
+        if bak:
+            typer.echo(f"    Backup available: {bak}")
+    typer.echo("")
+
+    if not yes:
+        confirmed = typer.confirm("Proceed?", default=False)
+        if not confirmed:
+            typer.echo("Aborted.")
+            raise typer.Exit(code=0)
+        typer.echo("")
+
+    errors: list[str] = []
+    for a in installed:
+        try:
+            bak = backup.create(a.client.config_path)
+            typer.echo(f"  ✓ Backup   {bak}")
+            config = applier.read_config(a.client.config_path)
+            updated = applier.remove_entry(config)
+            applier.write_config(a.client.config_path, updated)
+            if not applier.validate(a.client.config_path):
+                errors.append(f"{a.client.name}: JSON validation failed — restoring backup")
+                backup.restore(bak, a.client.config_path)
+                continue
+            typer.echo(f"  ✓ Updated  {a.client.config_path}")
+        except Exception as exc:
+            errors.append(f"{a.client.name}: {exc}")
+
+    typer.echo("")
+
+    if errors:
+        for err in errors:
+            typer.echo(f"  ✗ {err}", err=True)
+        raise typer.Exit(code=1)
+
+    typer.echo("MCP integration removed.")
+    typer.echo("  Re-add:  sourcecode mcp init")
+
+
 # ── Entry point ───────────────────────────────────────────────────────────────
 
 def main_entry() -> None:
@@ -2413,5 +2713,13 @@ def main_entry() -> None:
     can consume them as positional arguments (which would prevent subcommand
     routing for tokens like 'version' or 'config').
     """
+    import sys as _sys
+    # Force UTF-8 on stdout so Unicode characters (arrows, etc.) survive on
+    # Windows where the default console codec is cp1252 (BUG-1).
+    if hasattr(_sys.stdout, "reconfigure"):
+        try:
+            _sys.stdout.reconfigure(encoding="utf-8")
+        except Exception:
+            pass
     _preprocess_argv()
     app()

sourcecode/mcp/__init__.py

@@ -0,0 +1,5 @@
+"""MCP server integration for sourcecode CLI.
+
+Exposes all CLI capabilities as MCP tools callable by AI agents.
+Install the 'mcp' extra to enable: pip install sourcecode[mcp]
+"""

sourcecode/mcp/onboarding/__init__.py

@@ -0,0 +1 @@
+"""MCP client onboarding: detect, plan, apply, backup, remove."""

sourcecode/mcp/onboarding/applier.py

@@ -0,0 +1,63 @@
+"""Safe JSON config applier for MCP client configuration files."""
+from __future__ import annotations
+
+import json
+from pathlib import Path
+
+_MCP_SERVERS_KEY = "mcpServers"
+_ENTRY_NAME = "sourcecode"
+_ENTRY_VALUE: dict[str, object] = {
+    "command": "sourcecode",
+    "args": ["mcp", "serve"],
+}
+
+
+def read_config(path: Path) -> dict:
+    """Parse JSON config from path. Returns empty dict if missing or empty."""
+    if not path.exists():
+        return {}
+    raw = path.read_text(encoding="utf-8").strip()
+    if not raw:
+        return {}
+    return json.loads(raw)  # type: ignore[no-any-return]
+
+
+def is_installed(config: dict) -> bool:
+    """True if sourcecode entry already present in mcpServers."""
+    return _ENTRY_NAME in config.get(_MCP_SERVERS_KEY, {})
+
+
+def apply_entry(config: dict) -> dict:
+    """Return new config dict with sourcecode merged into mcpServers."""
+    config = dict(config)
+    servers: dict = dict(config.get(_MCP_SERVERS_KEY, {}))
+    servers[_ENTRY_NAME] = _ENTRY_VALUE
+    config[_MCP_SERVERS_KEY] = servers
+    return config
+
+
+def remove_entry(config: dict) -> dict:
+    """Return new config dict with sourcecode removed from mcpServers."""
+    config = dict(config)
+    servers: dict = dict(config.get(_MCP_SERVERS_KEY, {}))
+    servers.pop(_ENTRY_NAME, None)
+    if servers:
+        config[_MCP_SERVERS_KEY] = servers
+    elif _MCP_SERVERS_KEY in config:
+        del config[_MCP_SERVERS_KEY]
+    return config
+
+
+def write_config(path: Path, config: dict) -> None:
+    """Atomically write config as formatted JSON."""
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text(json.dumps(config, indent=2) + "\n", encoding="utf-8")
+
+
+def validate(path: Path) -> bool:
+    """True if path contains parseable JSON."""
+    try:
+        json.loads(path.read_text(encoding="utf-8"))
+        return True
+    except Exception:
+        return False

sourcecode/mcp/onboarding/backup.py

@@ -0,0 +1,40 @@
+"""Timestamped backup management for MCP config files."""
+from __future__ import annotations
+
+from datetime import datetime
+from pathlib import Path
+
+_BACKUP_DIR = Path.home() / ".config" / "sourcecode" / "mcp-backups"
+
+
+def _backup_stem(config_path: Path) -> str:
+    """Stable prefix derived from the config path, safe for filenames."""
+    parts = config_path.parts
+    # Use last two path components to keep names readable but unique enough.
+    label = "_".join(p for p in parts[-2:] if p).replace(".", "_")
+    return label
+
+
+def create(config_path: Path) -> Path:
+    """Copy config_path to a timestamped backup file. Returns backup path."""
+    _BACKUP_DIR.mkdir(parents=True, exist_ok=True)
+    ts = datetime.now().strftime("%Y%m%dT%H%M%S")
+    stem = _backup_stem(config_path)
+    backup_path = _BACKUP_DIR / f"{stem}.{ts}.bak"
+    backup_path.write_bytes(config_path.read_bytes())
+    return backup_path
+
+
+def restore(backup_path: Path, target_path: Path) -> None:
+    """Overwrite target_path with contents of backup_path."""
+    target_path.parent.mkdir(parents=True, exist_ok=True)
+    target_path.write_bytes(backup_path.read_bytes())
+
+
+def latest(config_path: Path) -> Path | None:
+    """Find the most recent backup for config_path, or None."""
+    if not _BACKUP_DIR.exists():
+        return None
+    stem = _backup_stem(config_path)
+    matches = sorted(_BACKUP_DIR.glob(f"{stem}.*.bak"))
+    return matches[-1] if matches else None

sourcecode/mcp/onboarding/detector.py

@@ -0,0 +1,59 @@
+"""Detect MCP-capable clients installed on the current machine."""
+from __future__ import annotations
+
+import os
+import sys
+from dataclasses import dataclass
+from pathlib import Path
+
+
+# Registry of known MCP clients and their config paths per platform.
+# Keys: "darwin", "linux", "win32" — matching sys.platform values.
+_CLIENT_REGISTRY: dict[str, dict[str, str]] = {
+    "Claude Desktop": {
+        "darwin": "~/Library/Application Support/Claude/claude_desktop_config.json",
+        "linux": "~/.config/Claude/claude_desktop_config.json",
+        "win32": "{APPDATA}/Claude/claude_desktop_config.json",
+    },
+    "Cursor": {
+        "darwin": "~/.cursor/mcp.json",
+        "linux": "~/.cursor/mcp.json",
+        "win32": "{USERPROFILE}/.cursor/mcp.json",
+    },
+}
+
+
+@dataclass(frozen=True)
+class MCPClient:
+    name: str
+    config_path: Path
+    app_installed: bool  # True if the config file (or its parent dir) exists
+
+
+def _resolve(template: str) -> Path:
+    """Expand env vars in Windows-style {VAR} templates, then expanduser."""
+    result = template
+    for var in ("APPDATA", "LOCALAPPDATA", "USERPROFILE"):
+        val = os.environ.get(var, "")
+        if val:
+            result = result.replace(f"{{{var}}}", val)
+    return Path(result).expanduser()
+
+
+def detect_clients() -> list[MCPClient]:
+    """Return all known MCP clients with their resolved config paths."""
+    plat = sys.platform
+    clients: list[MCPClient] = []
+    for name, paths in _CLIENT_REGISTRY.items():
+        template = paths.get(plat) or paths.get("linux")
+        if not template:
+            continue
+        config_path = _resolve(template)
+        # Consider client "installed" if its config file OR parent app dir exists.
+        app_installed = config_path.exists() or config_path.parent.exists()
+        clients.append(MCPClient(
+            name=name,
+            config_path=config_path,
+            app_installed=app_installed,
+        ))
+    return clients

sourcecode/mcp/onboarding/planner.py

@@ -0,0 +1,40 @@
+"""Build an install/remove plan from detected MCP clients."""
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from .applier import is_installed, read_config
+from .detector import MCPClient
+
+
+@dataclass(frozen=True)
+class ClientAction:
+    client: MCPClient
+    already_installed: bool  # sourcecode entry already in config
+    will_create_file: bool   # config file doesn't exist yet — will be created
+
+
+def build_install_plan(clients: list[MCPClient]) -> list[ClientAction]:
+    """Describe what `mcp init` would do for each detected client."""
+    actions: list[ClientAction] = []
+    for client in clients:
+        config = read_config(client.config_path)
+        actions.append(ClientAction(
+            client=client,
+            already_installed=is_installed(config),
+            will_create_file=not client.config_path.exists(),
+        ))
+    return actions
+
+
+def build_remove_plan(clients: list[MCPClient]) -> list[ClientAction]:
+    """Describe what `mcp remove` would do for each detected client."""
+    actions: list[ClientAction] = []
+    for client in clients:
+        config = read_config(client.config_path)
+        actions.append(ClientAction(
+            client=client,
+            already_installed=is_installed(config),
+            will_create_file=False,
+        ))
+    return actions

sourcecode/mcp/runner.py

@@ -0,0 +1,40 @@
+"""In-process CLI runner for MCP tool execution.
+
+Replaces the subprocess adapter from the standalone sourcecode-mcp project.
+Calls CLI commands directly in the same process via CliRunner — no binary
+lookup, no process fork, no stdout encoding issues.
+"""
+from __future__ import annotations
+
+from typer.testing import CliRunner
+
+_runner = CliRunner()
+
+
+def run_command(args: list[str]) -> str:
+    """Invoke a sourcecode CLI command in-process and return stdout.
+
+    Raises RuntimeError on non-zero exit or empty output.
+    """
+    from sourcecode.cli import _detected_path, _preprocess_args, app
+
+    _detected_path[0] = "."
+    processed = _preprocess_args(list(args))
+    result = _runner.invoke(app, processed)
+
+    if result.exit_code != 0:
+        snippet = (result.output or "").strip()
+        raise RuntimeError(
+            f"sourcecode command failed (exit {result.exit_code}).\n"
+            f"Args: {args}\n"
+            f"Output: {snippet or '(empty)'}"
+        )
+
+    output = (result.output or "").strip()
+    if not output:
+        raise RuntimeError(
+            f"sourcecode command produced no output.\n"
+            f"Args: {args}"
+        )
+
+    return output

sourcecode/mcp/server.py

@@ -0,0 +1,147 @@
+"""MCP server for sourcecode CLI.
+
+Exposes sourcecode capabilities as MCP tools. Each tool maps to a CLI command
+and delegates execution to the in-process runner — no subprocess, no binary
+lookup, same process as the CLI.
+
+All tools return the canonical contract:
+  {"success": bool, "data": str | None, "error": {"code": str, "message": str} | None}
+"""
+from __future__ import annotations
+
+from typing import Literal
+
+from mcp.server.fastmcp import FastMCP
+
+from sourcecode.mcp.runner import run_command
+
+mcp = FastMCP("sourcecode")
+
+_PREPARE_CONTEXT_TASKS = frozenset({
+    "delta", "review-pr", "fix-bug", "onboard",
+    "explain", "refactor", "generate-tests",
+})
+_TELEMETRY_ACTIONS = frozenset({"status", "enable", "disable"})
+
+
+def _ok(data: str) -> dict:
+    return {"success": True, "data": data, "error": None}
+
+
+def _err(message: str, code: str = "EXECUTION_FAILED") -> dict:
+    return {"success": False, "data": None, "error": {"code": code, "message": message}}
+
+
+def _execute(args: list[str]) -> dict:
+    try:
+        return _ok(run_command(args))
+    except RuntimeError as exc:
+        return _err(str(exc))
+
+
+@mcp.tool()
+def compact(path: str, git_context: bool = False) -> dict:
+    """Compact analysis of a repository (~1000-3000 tokens).
+
+    Maps to: sourcecode <path> --compact [--git-context]
+    """
+    if not isinstance(path, str):
+        return _err("path must be a string", "INVALID_ARGUMENT")
+    if not isinstance(git_context, bool):
+        return _err("git_context must be boolean", "INVALID_ARGUMENT")
+    args = [path, "--compact"]
+    if git_context:
+        args.append("--git-context")
+    return _execute(args)
+
+
+@mcp.tool()
+def agent(path: str, git_context: bool = False) -> dict:
+    """Agent-optimised analysis: identity, entry points, dependencies, gaps.
+
+    Maps to: sourcecode <path> --agent [--git-context]
+    """
+    if not isinstance(path, str):
+        return _err("path must be a string", "INVALID_ARGUMENT")
+    if not isinstance(git_context, bool):
+        return _err("git_context must be boolean", "INVALID_ARGUMENT")
+    args = [path, "--agent"]
+    if git_context:
+        args.append("--git-context")
+    return _execute(args)
+
+
+@mcp.tool()
+def prepare_context(
+    task: Literal[
+        "delta", "review-pr", "fix-bug", "onboard",
+        "explain", "refactor", "generate-tests",
+    ],
+    path: str,
+) -> dict:
+    """Task-specific context for AI coding agents.
+
+    Maps to: sourcecode prepare-context <task> <path>
+
+    task must be one of:
+      explain        Architecture, entry points, key dependencies
+      fix-bug        Risk-ranked files, suspected areas, annotations
+      refactor       Structural issues, improvement opportunities
+      generate-tests Untested source files, test gap analysis
+      onboard        Full project context for new agents/developers
+      review-pr      PR diff with runtime signals and security impact
+      delta          Incremental context: git-changed files only
+    """
+    if task not in _PREPARE_CONTEXT_TASKS:
+        return _err(
+            f"task must be one of {sorted(_PREPARE_CONTEXT_TASKS)}",
+            "INVALID_ARGUMENT",
+        )
+    if not isinstance(path, str):
+        return _err("path must be a string", "INVALID_ARGUMENT")
+    return _execute(["prepare-context", task, path])
+
+
+@mcp.tool()
+def repo_ir(path: str) -> dict:
+    """Deterministic symbol-level IR for Java repositories.
+
+    Maps to: sourcecode repo-ir <path>
+    Output is JSON: graph{nodes,edges}, analysis, impact, subsystems, change_set.
+    """
+    if not isinstance(path, str):
+        return _err("path must be a string", "INVALID_ARGUMENT")
+    return _execute(["repo-ir", path])
+
+
+@mcp.tool()
+def version() -> dict:
+    """Return the installed sourcecode version.
+
+    Maps to: sourcecode version
+    """
+    return _execute(["version"])
+
+
+@mcp.tool()
+def config() -> dict:
+    """Show sourcecode configuration (version, telemetry state, config path).
+
+    Maps to: sourcecode config
+    """
+    return _execute(["config"])
+
+
+@mcp.tool()
+def telemetry(action: Literal["status", "enable", "disable"]) -> dict:
+    """Manage telemetry settings.
+
+    Maps to: sourcecode telemetry <status|enable|disable>
+    action must be one of: status, enable, disable
+    """
+    if action not in _TELEMETRY_ACTIONS:
+        return _err(
+            f"action must be one of {sorted(_TELEMETRY_ACTIONS)}",
+            "INVALID_ARGUMENT",
+        )
+    return _execute(["telemetry", action])

sourcecode/prepare_context.py

@@ -712,7 +712,7 @@ class TaskContextBuilder:
     def __init__(self, root: Path) -> None:
         self.root = root
 
-    def build(self, task_name: str, *, since: Optional[str] = None, symptom: Optional[str] = None, fast: bool = False) -> TaskOutput:
+    def build(self, task_name: str, *, since: Optional[str] = None, symptom: Optional[str] = None, fast: bool = False, include_config: bool = False) -> TaskOutput:
         if task_name not in TASKS:
             raise ValueError(
                 f"Unknown task '{task_name}'. Available: {', '.join(TASKS)}"
@@ -788,6 +788,14 @@ class TaskContextBuilder:
             # for behavioral_impact reverse lookups without scanning the whole repo).
             file_tree: dict = {}
             all_paths = self._expand_scope_for_analysis(_pr_scope_files or [])
+        elif fast and task_name == "onboard":
+            # Onboard fast: always use shallow scan so manifests and entry points
+            # are discoverable — git-changed-only mode would return only dirty files
+            # (e.g. .idea/vcs.xml) which yields no useful entry points (BUG-3).
+            scanner = AdaptiveScanner(self.root, base_depth=2)
+            file_tree = scanner.scan_tree()
+            manifests = scanner.find_manifests()
+            all_paths = [p.replace("\\", "/") for p in flatten_file_tree(file_tree)]
         elif fast and _count_files_bounded(self.root) > MAX_FILES_FAST:
             # Fast mode on large repo: git-index-only — only scan git-changed files.
             # Skips full AdaptiveScanner traversal which takes 35s+ on 7k+ file repos.
@@ -1652,11 +1660,26 @@ class TaskContextBuilder:
                 # Python/JS: test_foo / foo_test
                 return stem.removeprefix("test_").removesuffix("_test")
 
+            # Patterns excluded from test_gaps by default (IMP-1): tooling config
+            # files have no business logic to test. --include-config overrides.
+            _CONFIG_EXCLUDE_PATTERNS = (
+                ".eslintrc", ".prettierrc", "eslint.config",
+                "karma.conf", "jest.config", "babel.config",
+                "webpack.config", "vite.config", "rollup.config",
+                "tsconfig", "angular.json", ".claude/",
+            )
+
+            def _is_config_file(p: str) -> bool:
+                name = Path(p).name.lower()
+                norm = p.replace("\\", "/")
+                return any(pat in name or pat in norm for pat in _CONFIG_EXCLUDE_PATTERNS)
+
             test_stems = {_normalize_test_stem(Path(p).stem) for p in test_set}
             untested = [
                 p for p in source_set
                 if Path(p).stem not in test_stems
                 and not any(pen in p for pen in spec.ranking_penalties)
+                and (include_config or not _is_config_file(p))
             ]
             untested.sort(key=lambda p: (len(p.split("/")), p))
             test_gaps = untested[:15]

sourcecode/serializer.py

@@ -1643,7 +1643,23 @@ def _angular_analysis(sm: "SourceMap") -> "Optional[dict[str, Any]]":
             continue
         component_count += content.count("@Component(")
         service_count += content.count("@Injectable(")
-        lazy_routes_count += content.count("loadChildren(")
+        # Count lazy route patterns: `loadChildren:` (property syntax used in route
+        # configs) and `loadComponent:` (standalone component lazy loading). The old
+        # `loadChildren(` form counted zero because Angular uses property syntax, not
+        # a function call (BUG-5).
+        fname_lower = rel.replace("\\", "/").split("/")[-1].lower()
+        _is_routing_file = (
+            "routing" in fname_lower
+            or fname_lower in ("app.routes.ts", "app-routing.module.ts")
+            or fname_lower.endswith(".routes.ts")
+        )
+        lazy_routes_count += content.count("loadChildren:")
+        lazy_routes_count += content.count("loadComponent:")
+        if _is_routing_file:
+            # Also count standalone dynamic imports that aren't already caught above
+            _lc_imports = content.count("import(") - content.count("loadChildren:") - content.count("loadComponent:")
+            if _lc_imports > 0:
+                lazy_routes_count += _lc_imports
         akita_stores += content.count("@StoreConfig(")
         if not standalone_components and "bootstrapApplication(" in content:
             standalone_components = True
@@ -1661,7 +1677,13 @@ def _angular_analysis(sm: "SourceMap") -> "Optional[dict[str, Any]]":
     if pkg_json.exists():
         try:
             pkg = _json.loads(pkg_json.read_text(encoding="utf-8", errors="replace"))
-            deps = {**pkg.get("dependencies", {}), **pkg.get("devDependencies", {})}
+            # Use `or {}` so explicit `null` values in package.json don't
+            # raise TypeError when unpacking (BUG-4).
+            deps = {
+                **(pkg.get("dependencies") or {}),
+                **(pkg.get("devDependencies") or {}),
+                **(pkg.get("peerDependencies") or {}),
+            }
             av = deps.get("@angular/core")
             if av:
                 angular_version = av.lstrip("^~>=")

{sourcecode-1.30.29.dist-info → sourcecode-1.31.0.dist-info}/METADATA

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sourcecode
-Version: 1.30.29
+Version: 1.31.0
 Summary: Deterministic codebase context for AI coding agents
 License:                                  Apache License
                                    Version 2.0, January 2004
@@ -212,16 +212,19 @@ Requires-Dist: tree-sitter-javascript>=0.21; extra == 'ast'
 Requires-Dist: tree-sitter-typescript>=0.21; extra == 'ast'
 Requires-Dist: tree-sitter>=0.21; extra == 'ast'
 Provides-Extra: dev
+Requires-Dist: mcp>=1.0.0; extra == 'dev'
 Requires-Dist: mypy>=1.10; extra == 'dev'
 Requires-Dist: pytest>=8; extra == 'dev'
 Requires-Dist: ruff>=0.15; extra == 'dev'
+Provides-Extra: mcp
+Requires-Dist: mcp>=1.0.0; extra == 'mcp'
 Description-Content-Type: text/markdown
 
 # sourcecode
 
 **Deterministic, behavior-aware codebase context for AI agents and PR review.**
 
-![Version](https://img.shields.io/badge/version-1.30.29-blue)
+![Version](https://img.shields.io/badge/version-1.31.0-blue)
 ![Python](https://img.shields.io/badge/python-3.10%2B-green)
 
 ---
@@ -257,7 +260,7 @@ pipx install sourcecode
 
 ```bash
 sourcecode version
-# sourcecode 1.30.29
+# sourcecode 1.31.0
 ```
 
 ---

{sourcecode-1.30.29.dist-info → sourcecode-1.31.0.dist-info}/RECORD

@@ -1,10 +1,10 @@
-sourcecode/__init__.py,sha256=dlUu_PMRN5Q_pvsTBF3LbFJMORBN4BVQ0B9j6mA3GWQ,104
+sourcecode/__init__.py,sha256=MiA5_ZlVOCsJoykaFJRoZJpA8VwhlU7ns_GdhCt64L4,103
 sourcecode/adaptive_scanner.py,sha256=XffluXKzJUXrMtjEiAOnSNPZnztdIcts17T9ouHeID0,10521
 sourcecode/architecture_analyzer.py,sha256=MyBa0Hf5HmkudZQDLKrjcWDKETXETXl0mQX1swtTwAA,39091
 sourcecode/architecture_summary.py,sha256=z34_6v7cSwy98cof2UVciGho7SCrZ93tiqMmq5WNzRQ,20405
 sourcecode/ast_extractor.py,sha256=XgrZg2DcWcUm9r87cRG3KGO7IK2TIL_N-CvhSbUmmh4,49901
 sourcecode/classifier.py,sha256=-0t0HLc9L9UleMLfclfLM3AXhBjUb_AYyBPDbvgWtac,7755
-sourcecode/cli.py,sha256=5hKnqahlEko1Z1GV1pg0uzEH2hES3RRqxJ95CRBgXwc,98320
+sourcecode/cli.py,sha256=wncSKjhpDuN5t-tU7vj-kY2x6FREFyXoRetZnUensMs,110219
 sourcecode/code_notes_analyzer.py,sha256=y1MJBnPZHYp4i6cQCXUb9ATIyifS_qMQWjw_8lPkpsU,9215
 sourcecode/confidence_analyzer.py,sha256=H9VHYRzZhqMFlSCZffjtsMUGYLnDvrq1g5FjzyQ1hxE,16381
 sourcecode/context_scorer.py,sha256=QpChSpsmaAYz91rXA4Ue5xzQmNz_ZboZN09YOHScq1U,14679
@@ -22,7 +22,7 @@ sourcecode/git_analyzer.py,sha256=0Gyj-vMpIIN4nfriKXVRouNYBeJ59s6pQDX2Xu9Pq-U,13
 sourcecode/graph_analyzer.py,sha256=iUK-7pSV-cvGqqD2hENdYmhnm0wcXFEyK-xnu5ul8OU,62515
 sourcecode/metrics_analyzer.py,sha256=m0ENgtqKeBL17kUIK3fmGkgo7UfXBNHxCMj0H_Y5K7c,22750
 sourcecode/pr_comment_renderer.py,sha256=smHslxiG14lrytCkq5nFrFu-qTHgA-t-LFYfdrfjz2o,14423
-sourcecode/prepare_context.py,sha256=Too1ziyHGGvZfNhCMfgCvrTI01xYQeUrwA4veXtgTSI,172167
+sourcecode/prepare_context.py,sha256=QNCl8uKk9PQpgXxPHBNSDXXkc1s2wTZwU6H0REC5Qms,173487
 sourcecode/progress.py,sha256=qn30sWaHOkjTgXsSBmiPkz7Rsbwc5oSlIe6JNEMYp_k,3149
 sourcecode/ranking_engine.py,sha256=ZAucq_YX2KkWUuAZf4P0lhtQ_38vEFnUhuGtSZd1S0E,12970
 sourcecode/redactor.py,sha256=xuGcadGEHaPw4qZXlMDvzMCsr4VOkdp3oBQptHyJk8c,2884
@@ -33,7 +33,7 @@ sourcecode/runtime_classifier.py,sha256=zWX3r3HCKHc-qtIobErOa8aKMmaoPYREtJKvPcBG
 sourcecode/scanner.py,sha256=WdOQ78mMzjR1NjmKTlbxdgwinnCTfAhxCVLBEFQiFHU,8899
 sourcecode/schema.py,sha256=fj3BZ3IcnNV4j21BFIEvz8Qnw_vZoqIbzzRg-qQ-nd0,24530
 sourcecode/semantic_analyzer.py,sha256=12TwXYkYbDcBdu0heX_EmfPM2EkO8a_r5osf0SaeQbs,88956
-sourcecode/serializer.py,sha256=JaEJonNIKaSV6dST3Jn8_Z6alYK9Ba1-M3luh8Xf-yw,110442
+sourcecode/serializer.py,sha256=FM4xklb9Ywg9KNdNpo8QXR50izuml5FkbeQgL2uS1HY,111611
 sourcecode/summarizer.py,sha256=lPlKhMh28nueXkPo2xKeD3DUFYVGRlJMIdY-8TSM-ls,17486
 sourcecode/tree_utils.py,sha256=8GAkIfQAsvtEudIeW1l4ooH_oRtrWR8cpJQJsEa_Pfw,2093
 sourcecode/workspace.py,sha256=X_6NmNnitvT3_38V-JDChydo_sR68s249hLFlrQskU0,8271
@@ -58,14 +58,22 @@ sourcecode/detectors/rust.py,sha256=Tij1vz8BFZ332GEvVkL6vyMli2OMHJfHyDAppWfe66c,
 sourcecode/detectors/systems.py,sha256=nYaKbGDFu0EOXFcd_1doWFT3tTUdkbxc2DjHUF5TcqQ,1627
 sourcecode/detectors/terraform.py,sha256=cxORPR_zVLOJpHlh4e9JnFpkQsn_UnqMMom5yG65hZ4,1693
 sourcecode/detectors/tooling.py,sha256=8CKbtxwQoABP-WyBRNmdAmHDOvAH57AR1cF4UKuWEdQ,2074
+sourcecode/mcp/__init__.py,sha256=XU4HfRGbdid8wdUA0x_4f7uKZD1z3mv_XUY_WU_T9Mw,179
+sourcecode/mcp/runner.py,sha256=B167PyUBUwAJC6stKRCd3KHpmrpZOMsAA3gOtIuUauU,1186
+sourcecode/mcp/server.py,sha256=grK87-zeJ98W-DIXqaNg_PXGecFB_WzooKkyQcjJDa0,4480
+sourcecode/mcp/onboarding/__init__.py,sha256=sj2PWqEBmMc4zBNkomg89WtL0M6S7A9yb7_wAuSWNP4,66
+sourcecode/mcp/onboarding/applier.py,sha256=yfSMT0NKdZsjavtLkC8yQ7OtkfepOl5IXGByqg6bdEY,1894
+sourcecode/mcp/onboarding/backup.py,sha256=ihqGOR8QTX8HASRSEDyfFyXr5bkXrygPHamv4p9KTmk,1452
+sourcecode/mcp/onboarding/detector.py,sha256=lcBkERH1WlxTXGTKVtxKv1fvql4NgSnVxGftra-gMvE,1961
+sourcecode/mcp/onboarding/planner.py,sha256=Fopg5f72FDiPfldF7NOxYjcBA_w8hi_jBJpSz39lPb8,1332
 sourcecode/telemetry/__init__.py,sha256=M0eQZFNkmJiLbI_oNP4QEXwVju1dQ2d4P-E1-Bw8PxE,3116
 sourcecode/telemetry/config.py,sha256=Pir0WHp4z-9Qclnn2NDZ3vwitqsMkOAJckmwjUSxrk4,1795
 sourcecode/telemetry/consent.py,sha256=wLMvGNJeSSyZoNkQXpoUioY6mMv4Qdvuw7S9jAEWnII,2237
 sourcecode/telemetry/events.py,sha256=oEvvulfsv5GIDWG2174gSS6tNB95w38AIYiYeifGKlE,2294
 sourcecode/telemetry/filters.py,sha256=Asa71oRl7q3Wt_FMwuufIZJFzSYdgRNKS8LHCIyFeYE,4805
 sourcecode/telemetry/transport.py,sha256=KJeIPCPWMdmbCP3ySGs2iUlia34U6vWne2dZsUezesw,1560
-sourcecode-1.30.29.dist-info/METADATA,sha256=39QsgfOfPa-UUti5nV0iLi-gH7KSIz48owb5RoyX12Q,28956
-sourcecode-1.30.29.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
-sourcecode-1.30.29.dist-info/entry_points.txt,sha256=ex3F9rmbXeyDIoFQHtkEqTsKSaJow8F0LrVu8XfIktQ,57
-sourcecode-1.30.29.dist-info/licenses/LICENSE,sha256=7DdHrU9Z_3e7dSvq4ISijZNjnuHo5NIHNiHDouMQ9JU,10491
-sourcecode-1.30.29.dist-info/RECORD,,
+sourcecode-1.31.0.dist-info/METADATA,sha256=tp3EeSNMJlNOi0f6JNoXdDsfrQDbEm703TurOFj83kw,29057
+sourcecode-1.31.0.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+sourcecode-1.31.0.dist-info/entry_points.txt,sha256=ex3F9rmbXeyDIoFQHtkEqTsKSaJow8F0LrVu8XfIktQ,57
+sourcecode-1.31.0.dist-info/licenses/LICENSE,sha256=7DdHrU9Z_3e7dSvq4ISijZNjnuHo5NIHNiHDouMQ9JU,10491
+sourcecode-1.31.0.dist-info/RECORD,,