sourcecode 1.30.30__tar.gz → 1.31.1__tar.gz

sourcecode-1.31.1/.continue-here.md

@@ -0,0 +1,101 @@
+# Continue Here — atlas-cli sesión 16
+
+**Paused:** 2026-05-20
+**Repo:** `/Users/user/Downloads/atlas-cli`
+**Branch:** master
+**Working tree:** CHANGELOG.md sin commitear (untracked)
+
+---
+
+## Trabajo de esta sesión (ya commiteado)
+
+**Commit:** `0e430c1 fix(cli+serializer): BUG-1..5 + IMP-1 — UTF-8 stdout, --exclude parsing, onboard fast scan, angular_version null, lazy_routes_count zero, test_gaps config filter`
+
+| ID | Fix | Archivo | Líneas clave |
+|---|---|---|---|
+| BUG-1 | `repo_ir_cmd` usa `stdout.buffer.write(encode("utf-8"))` en vez de `stdout.write()`. `main_entry` llama `stdout.reconfigure(encoding="utf-8")`. UnicodeEncodeError capturado con hint a `--output`. | `cli.py` | ~2367, ~2443 |
+| BUG-2 | `--exclude` añadido a `_OPTIONS_WITH_VALUE` → valor no consumido como repo path. Warning si valor es directorio existente. | `cli.py` | ~173, ~856 |
+| BUG-3 | `onboard --fast` siempre usa `AdaptiveScanner(base_depth=2)`; ya no usa git-index-only (que devolvía solo `.idea/vcs.xml`). | `prepare_context.py` | ~791 |
+| BUG-4 | `deps = {**(pkg.get("dependencies") or {}), ...}` para manejar `null` explícito en package.json. Añade `peerDependencies` como fallback. | `serializer.py` | ~1663 |
+| BUG-5 | Cuenta `loadChildren:` y `loadComponent:` (property syntax modern Angular) en vez del inexistente `loadChildren(`. | `serializer.py` | ~1644 |
+| IMP-1 | `test_gaps` excluye `.eslintrc*`, `karma.conf.js`, `tsconfig*`, `.claude/**`, etc. por defecto. Nuevo flag `--include-config` para override. | `prepare_context.py`, `cli.py` | ~1663, ~1806 |
+| IMP-2 | Stderr warning con workaround exacto cuando se detecta UnicodeEncodeError (BUG-1) o exclude value = directorio (BUG-2). | `cli.py` | ~2373, ~858 |
+
+**Tests:** `tests/test_bug_fixes_v2.py` — 14 tests, todos pasan.
+**Suite completa:** 1010 passed, 0 nuevos failures (3 pre-existentes sin tocar).
+
+---
+
+## Primera acción al retomar
+
+CHANGELOG.md quedó fuera del commit (untracked). Commitear:
+
+```bash
+cd /Users/user/Downloads/atlas-cli
+git add CHANGELOG.md
+git commit -m "docs: add CHANGELOG.md with BUG-1..5 and IMP-1 entries for v1.30.29
+
+Co-Authored-By: Claude Sonnet 4.6 <noreply@anthropic.com>"
+```
+
+---
+
+## Pendientes (heredados de sesión 15, siguen vigentes)
+
+1. **Spring bean wiring graph** — `_build_relations` emite `injects` edges para `@Autowired`. Falta: trazar `@Configuration → @Bean → @Autowired` completo, exponer como `wiring_graph`.
+
+2. **Smoke test en repo spring-boot real:**
+   ```bash
+   cd ~/Documents/workspace/spring-boot-realworld-example-app
+   sourcecode repo-ir . --since HEAD~1 2>/dev/null | python3 -c "
+   import json, sys; d=json.load(sys.stdin)
+   print('nodes:', len(d['graph']['nodes']))
+   print('route_surface:', d.get('route_surface', []))
+   print('reverse_graph keys:', len(d.get('reverse_graph', {})))
+   "
+   ```
+
+3. **Transaction boundary tracking** — `@Transactional` detectado. Falta: emitir `transactional_boundary` edges.
+
+4. **`_diff_routes` para `@RequestMapping` en clase** — class-level mapping change debería propagarse a todos los endpoints del controller.
+
+5. **Tests para el symptom fix (sesión 15)** — validar `--symptom "sesiones"` con mock commits produce ranking diferente al baseline. Cubrir en `tests/test_prepare_context_symptom.py`.
+
+6. **`_FRONTEND_SYMPTOM_MAP`** — añadir "sesiones"/"session" con backend terms `["httpsession", "sessionmanager", "sessionservice", "sessionrepository"]`.
+
+---
+
+## Estado de tests al pausar
+
+```
+1010 passed, 3 skipped (pre-existing)
+```
+
+Pre-existing failures (no tocar):
+- `tests/test_block2_coverage.py::TestDocAnalyzerLanguageCoverage::test_java_marked_unsupported` — `DocRecord.__init__()` unexpected kwarg `name`
+- `tests/test_dependency_analyzer_node_python.py::test_python_requirements_without_lockfile_keeps_declared_versions` — typer version mismatch
+- `tests/test_scoring_calibration.py` — varios score calibration tests
+
+---
+
+## Para retomar
+
+```bash
+cd /Users/user/Downloads/atlas-cli
+git log --oneline -3   # 0e430c1 debe estar arriba
+git status             # solo CHANGELOG.md untracked
+
+# 1. Commitear CHANGELOG.md (comando arriba)
+
+# 2. Verificar suite
+python3 -m pytest tests/ \
+  --ignore=tests/test_block2_coverage.py \
+  --ignore=tests/test_scoring_calibration.py \
+  --deselect=tests/test_dependency_analyzer_node_python.py::test_python_requirements_without_lockfile_keeps_declared_versions \
+  -q
+# Expected: 1010 passed, 3 skipped
+```
+
+---
+
+*Pausado 2026-05-20 — gsd:pause-work*

{sourcecode-1.30.30 → sourcecode-1.31.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: sourcecode
-Version: 1.30.30
+Version: 1.31.1
 Summary: Deterministic codebase context for AI coding agents
 License:                                  Apache License
                                    Version 2.0, January 2004
@@ -203,6 +203,7 @@ Classifier: Programming Language :: Python :: 3.12
 Classifier: Topic :: Software Development :: Libraries :: Python Modules
 Classifier: Topic :: Utilities
 Requires-Python: >=3.9
+Requires-Dist: mcp>=1.0.0
 Requires-Dist: pathspec>=1.0
 Requires-Dist: ruamel-yaml>=0.18
 Requires-Dist: tomli>=2.0; python_version < '3.11'
@@ -212,16 +213,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.30-blue)
+![Version](https://img.shields.io/badge/version-1.31.1-blue)
 ![Python](https://img.shields.io/badge/python-3.10%2B-green)
 
 ---
@@ -257,7 +261,7 @@ pipx install sourcecode
 
 ```bash
 sourcecode version
-# sourcecode 1.30.30
+# sourcecode 1.31.1
 ```
 
 ---

{sourcecode-1.30.30 → sourcecode-1.31.1}/README.md

@@ -2,7 +2,7 @@
 
 **Deterministic, behavior-aware codebase context for AI agents and PR review.**
 
-![Version](https://img.shields.io/badge/version-1.30.30-blue)
+![Version](https://img.shields.io/badge/version-1.31.1-blue)
 ![Python](https://img.shields.io/badge/python-3.10%2B-green)
 
 ---
@@ -38,7 +38,7 @@ pipx install sourcecode
 
 ```bash
 sourcecode version
-# sourcecode 1.30.30
+# sourcecode 1.31.1
 ```
 
 ---

{sourcecode-1.30.30 → sourcecode-1.31.1}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "sourcecode"
-version = "1.30.30"
+version = "1.31.1"
 description = "Deterministic codebase context for AI coding agents"
 readme = "README.md"
 requires-python = ">=3.9"
@@ -29,6 +29,7 @@ dependencies = [
     "pathspec>=1.0",
     "ruamel.yaml>=0.18",
     "tomli>=2.0; python_version < '3.11'",
+    "mcp>=1.0.0",
 ]
 
 [project.scripts]
@@ -39,12 +40,16 @@ dev = [
     "pytest>=8",
     "ruff>=0.15",
     "mypy>=1.10",
+    "mcp>=1.0.0",
 ]
 ast = [
     "tree-sitter>=0.21",
     "tree-sitter-typescript>=0.21",
     "tree-sitter-javascript>=0.21",
 ]
+mcp = [
+    "mcp>=1.0.0",
+]
 
 [[tool.mypy.overrides]]
 module = ["tree_sitter", "tree_sitter_typescript", "tree_sitter_javascript"]

{sourcecode-1.30.30 → sourcecode-1.31.1}/src/sourcecode/__init__.py

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

{sourcecode-1.30.30 → sourcecode-1.31.1}/src/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().
@@ -300,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."""
@@ -317,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,
@@ -616,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:
@@ -2432,6 +2460,305 @@ 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
+    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",
+    )
+    from sourcecode.mcp.server import mcp as _mcp
+
+    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."),
+    target: Optional[str] = typer.Option(
+        None,
+        "--target",
+        "-t",
+        help="Target client: claude-desktop | cursor. Default: auto-detect all.",
+    ),
+) -> 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.
+
+    \b
+    Examples:
+      sourcecode mcp init
+      sourcecode mcp init --target claude-desktop
+      sourcecode mcp init --target cursor --yes
+    """
+    from sourcecode.mcp.onboarding.detector import detect_clients, is_client_running
+    from sourcecode.mcp.onboarding.planner import build_install_plan
+    from sourcecode.mcp.onboarding import backup, applier
+
+    typer.echo("Detecting MCP clients...")
+    typer.echo("")
+
+    all_clients = detect_clients()
+
+    if target:
+        target_slug = target.lower()
+        clients = [c for c in all_clients if c.slug == target_slug]
+        if not clients:
+            valid = ", ".join(c.slug for c in all_clients)
+            typer.echo(f"Unknown target '{target}'. Valid: {valid}", err=True)
+            raise typer.Exit(code=1)
+    else:
+        clients = all_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("")
+
+    # Post-write: validate config and warn if client not running
+    for a in actionable:
+        if not is_client_running(a.client):
+            typer.echo(
+                f"  ⚠ Config written but {a.client.name} is not running. "
+                f"Start {a.client.name} and run sourcecode mcp status to verify.",
+                err=False,
+            )
+        else:
+            restart_msg = "" if a.will_create_file else f" Restart {a.client.name} to apply."
+            typer.echo(f"  ✓ {a.client.name} is running.{restart_msg}")
+
+    typer.echo("")
+    typer.echo("  Remove:  sourcecode mcp remove")
+
+
+@mcp_app.command("status")
+def mcp_status() -> None:
+    """Show MCP integration status: dependencies, config files, and connectivity."""
+    from sourcecode.mcp.onboarding.detector import detect_clients, is_client_running
+    from sourcecode.mcp.onboarding import applier
+
+    sep = "─" * 46
+
+    typer.echo("MCP Status")
+    typer.echo(sep)
+
+    # Stage 1: Dependencies
+    try:
+        import mcp as _mcp_pkg  # noqa: F401
+        typer.echo("Dependencies  ✓ installed")
+    except ImportError:
+        typer.echo("Dependencies  ✗ missing")
+        typer.echo("  Fix: pip install sourcecode[mcp]")
+    typer.echo("")
+
+    clients = detect_clients()
+    if not clients:
+        typer.echo("  No MCP clients detected on this system.")
+        typer.echo(sep)
+        typer.echo("  Setup:   sourcecode mcp init")
+        raise typer.Exit(code=0)
+
+    # Stage 2: Config files
+    typer.echo("Config files")
+    for client in clients:
+        if not client.app_installed:
+            typer.echo(f"  {client.name:<20} ✗ not found")
+            typer.echo(f"    Expected: {client.config_path}")
+            typer.echo(f"    Fix:      sourcecode mcp init --target {client.slug}")
+            continue
+        config = applier.read_config(client.config_path)
+        if applier.is_installed(config):
+            typer.echo(f"  {client.name:<20} ✓ configured   {client.config_path}")
+        else:
+            typer.echo(f"  {client.name:<20} ✗ not configured")
+            typer.echo(f"    Fix: sourcecode mcp init --target {client.slug}")
+    typer.echo("")
+
+    # Stage 3: Connectivity
+    typer.echo("Connectivity")
+    any_installed = any(c.app_installed for c in clients)
+    if not any_installed:
+        typer.echo("  (no clients to check)")
+    else:
+        for client in clients:
+            if not client.app_installed:
+                continue
+            if is_client_running(client):
+                typer.echo(f"  {client.name:<20} ✓ running")
+            else:
+                typer.echo(f"  {client.name:<20} ✗ not running")
+                typer.echo(f"    Fix: open {client.name}, then run sourcecode mcp status")
+
+    typer.echo(sep)
+    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:

sourcecode-1.31.1/src/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-1.31.1/src/sourcecode/mcp/onboarding/__init__.py

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

sourcecode-1.31.1/src/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-1.31.1/src/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