carto-md 2.0.6 → 2.0.7

package/README.md

@@ -7,93 +7,104 @@
 
 **The structural intelligence layer for AI coding tools.**
 
+Your AI coding tool sees files. Carto sees architecture — domains, blast radius, import graph, routes. Every AI tool you use stops guessing about your codebase and starts knowing it.
+
 ```bash
 npm install -g carto-md
 cd your-project
 carto init
 ```
 
-Carto indexes your codebase — routes, models, import graph, blast radius, domain clusters — and keeps it live via SQLite. Every AI tool you use gets accurate structural facts about your project instead of guessing.
+That's it. Carto auto-wires itself into every AI tool you have installed. Restart your AI tool and it now knows your codebase architecturally.
+
+**Works with:** Cursor · Claude Code · Kiro · Claude Desktop · Windsurf · VS Code Copilot · JetBrains · Zed
 
 ---
 
-## Benchmarks
+## Use it with your AI tool
 
-Measured on real open-source repos. Apple M-series, 8 CPUs, 8GB RAM.
+`carto init` auto-wires the MCP server into every AI tool it detects. If yours wasn't detected, here's the manual config — **one block, copy-paste, done.**
 
-| Repo | Language | Source Files | Indexed | First Run | Second Run | DB Size | Import Edges |
-|------|----------|-------------|---------|-----------|------------|---------|--------------|
-| [prisma/prisma](https://github.com/prisma/prisma) | TypeScript | 3,303 | 3,303 | **1.6s** | **178ms** | 2.2 MB | 3,590 |
-| [supabase/supabase](https://github.com/supabase/supabase) | TypeScript | 6,818 | 6,746 | **4.9s** | **725ms** | 4.3 MB | 5,754 |
-| [microsoft/vscode](https://github.com/microsoft/vscode) | TypeScript | 10,565 | 10,565 | **9.7s** | **1.2s** | 10.6 MB | 19,769 |
-| [zed-industries/zed](https://github.com/zed-industries/zed) | Rust | 1,837 | 1,837 | **2.7s** | **83ms** | 4.7 MB | 2,176 |
+### Cursor
 
-**Second run** = only changed files re-parsed. mtime+size checked before reading content — if nothing changed, nothing is re-parsed.
+`carto init` writes this for you. Manual: `~/.cursor/mcp.json`
+```json
+{ "mcpServers": { "carto": { "command": "carto", "args": ["serve"], "cwd": "/your/project" } } }
+```
 
-**All MCP queries** (blast radius, routes, structure, domains): **<5ms** on all repos.
+### Claude Code (CLI)
 
-### Domains detected
+One command from your project root:
+```bash
+claude mcp add carto -- carto serve
+```
+Or create `.mcp.json` at the project root:
+```json
+{ "mcpServers": { "carto": { "command": "carto", "args": ["serve"] } } }
+```
 
-| Repo | Domains |
-|------|---------|
-| prisma | DATABASE · CORE · EVENTS · AUTH |
-| supabase | CORE · AUTH · DATABASE · PAYMENTS · EVENTS · NOTIFICATIONS · TRPC |
-| vscode | CORE · AUTH · EVENTS · DATABASE · NOTIFICATIONS |
-| zed (Rust) | CORE · DATABASE · AUTH · EVENTS · PAYMENTS · NOTIFICATIONS |
+### Kiro
 
-vscode at 10,565 files in under 10 seconds. Rust import graph working on zed (2,176 edges from `mod` declarations and `use crate::` paths).
+`carto init` writes this for you. Manual: `~/.kiro/settings/mcp.json`
+```json
+{ "mcpServers": { "carto": { "command": "carto", "args": ["serve"], "cwd": "/your/project" } } }
+```
 
----
+### Claude Desktop
+
+`carto init` writes this for you. Manual: `~/Library/Application Support/Claude/claude_desktop_config.json`
+```json
+{ "mcpServers": { "carto": { "command": "carto", "args": ["serve"], "cwd": "/your/project" } } }
+```
 
-## What it does
+### VS Code Copilot
 
+`.vscode/mcp.json` in your project root, or Command Palette → `MCP: Add Server`
+```json
+{ "servers": { "carto": { "command": "carto", "args": ["serve"], "cwd": "/your/project" } } }
 ```
-carto init / carto sync
-  ↓
-Discovers all files (no cap — SQLite handles the volume)
-mtime+size check → skip unchanged files
-tree-sitter parse → imports + symbols (0.05–0.2ms/file)
-Babel deep parse → routes + models (API handler files only)
-Leiden+CPM graph clustering → auto-detects domains
-Computes reverse deps → blast radius for every file
-Writes AGENTS.md + .carto/context/*.md (lazy, on-demand)
-Auto-wires MCP into Kiro, Cursor, Claude Desktop
-  ↓
-carto watch
-  ↓
-File saved → debounce 50ms → re-parse 1 file → SQLite write → <50ms
+
+### Windsurf
+
+`~/.windsurf/mcp.json`
+```json
+{ "mcpServers": { "carto": { "command": "carto", "args": ["serve"], "cwd": "/your/project" } } }
 ```
 
+### Zed / JetBrains / VS Code (full agent mode)
+
+Carto also runs as a full **ACP agent** — not just a passive MCP server, but an active coding agent with architectural awareness. See [ACP Agent](#acp-agent-zed--jetbrains--vs-code) below.
+
 ---
 
-## 16 MCP tools
+## What changes for your AI
 
-`carto serve` exposes a local MCP server. Kiro, Cursor, and Claude query it mid-task.
+Without carto, your AI greps text and guesses. With carto, it queries structural facts:
 
-| Tool | What it returns |
-|------|----------------|
-| `get_architecture()` | 500-word project overview: domains, entry points, stack, key patterns. **Use this first.** |
-| `get_blast_radius(file)` | All files affected by changing a given file, with hop distance |
-| `get_context(file)` | Everything about a file: domain, blast radius, neighbors, routes, models |
-| `get_change_plan(intent)` | Given "add rate limiting to /api/users" → files to touch, domains affected, blast radius, similar patterns |
-| `get_file_summary(file)` | What a file does, its role, key deps and dependents |
-| `get_similar_patterns(file)` | Files with same domain, same route shape, or shared dependencies — find conventions before writing new code |
-| `get_routes()` | All API endpoints with file mapping |
-| `get_structure()` | Import graph, entry points, high-impact files, tech stack |
-| `get_domain(name)` | All routes, models, functions for a domain. Lazily regenerated when stale. |
-| `get_neighbors(file, hops)` | Import graph neighbors: nodes and edges |
-| `get_cross_domain()` | Import edges that cross domain boundaries |
-| `search_routes(query)` | Search API routes by path or method |
-| `get_models(domain?)` | All data models, optionally filtered by domain |
-| `get_high_impact_files(n)` | Top N files by blast radius |
-| `get_env_vars(domain?)` | All env vars with domain mapping |
-| `get_domains_list()` | All detected domains with file, route, model counts |
+> *"Add rate limiting to /api/users"*
+
+**Without carto:** AI grep-searches your codebase, finds 12 files mentioning "users", picks 3 at random, hopes for the best.
+
+**With carto:** AI calls `get_change_plan("add rate limiting to /api/users")` and gets back:
+- The exact route handler file
+- All 7 files that import it (blast radius)
+- The AUTH domain it lives in
+- Similar middleware patterns already in the codebase
+- Cross-domain dependencies that could break
+
+Your AI's response goes from "here's a guess" to "here's the right change with the architectural context."
+
+### In the wild
+
+![Claude Code reviewing the supabase repo through carto's MCP server](docs/screenshots/claude-code-supabase.png)
+
+*Claude Code analyzing the [supabase](https://github.com/supabase/supabase) repo via carto. Real session, no editing — 5,974 files indexed in ~780ms, 86 routes, 4,839 import edges, 7 domains. The agent's own verdict at the bottom: "useful, especially for a large codebase like supabase. The blast radius + cross-domain tools are the most valuable."*
 
 ---
 
 ## Languages and frameworks
 
-### Import graph + symbols (tree-sitter — works on any repo)
+### Import graph + symbols (any repo)
 
 | Language | Extensions |
 |----------|-----------|
@@ -106,16 +117,16 @@ File saved → debounce 50ms → re-parse 1 file → SQLite write → <50ms
 | C# | `.cs` |
 | Ruby | `.rb` |
 
-### Route extraction (framework-specific)
+### Route extraction (framework-aware)
 
 | Framework | Language |
 |-----------|---------|
-| Express, Next.js (App + Pages Router), tRPC, React Router | TypeScript / JavaScript |
+| Express, Next.js (App + Pages), tRPC, React Router | TypeScript / JavaScript |
 | FastAPI, Flask, Django | Python |
 | Gin, Echo, Chi, net/http | Go |
 | Actix-web, Axum, Rocket | Rust |
 | Spring MVC / Boot, JAX-RS | Java |
-| ASP.NET Core (attribute routing + minimal API) | C# |
+| ASP.NET Core | C# |
 | Rails, Sinatra | Ruby |
 
 ### Model extraction
@@ -127,52 +138,18 @@ File saved → debounce 50ms → re-parse 1 file → SQLite write → <50ms
 | Go structs | Go |
 | Rust structs | Rust |
 | JPA `@Entity`, Java records | Java |
-| EF Core classes, C# records | C# |
+| EF Core, C# records | C# |
 | ActiveRecord | Ruby |
 
 ### TypeScript path aliases
 
-Reads `tsconfig.json` / `jsconfig.json` for `paths` config. `@/components/Button` resolves to the actual file in the import graph — blast radius works correctly for Next.js and Vite projects.
-
----
-
-## Domain detection
-
-Carto uses **Leiden+CPM graph clustering** — files that import each other heavily cluster together. Domain names are inferred from path tokens, with keyword hints for well-known patterns (AUTH, PAYMENTS, DATABASE, etc.).
-
-Works on any repo — not just SaaS apps. vscode gets AUTH/EVENTS/DATABASE. zed (Rust) gets DATABASE/AUTH/EVENTS. A game engine would get RENDERER/PHYSICS/AUDIO.
-
-Custom domains via `carto.config.json`:
-
-```json
-{
-  "domains": {
-    "EDITOR": ["editor", "monaco", "text"],
-    "WORKBENCH": ["workbench", "layout", "panel"]
-  }
-}
-```
-
----
-
-## Commands
-
-| Command | What it does |
-|---------|-------------|
-| `carto init` | Detect project, index codebase, generate AGENTS.md, wire MCP |
-| `carto sync` | Full re-index (skips unchanged files via mtime+size cache) |
-| `carto watch` | Incremental live re-index on every file save (<50ms) |
-| `carto serve` | Start MCP server for Kiro / Cursor / Claude |
-| `carto agent` | Start ACP agent mode (for Zed / JetBrains / VS Code) |
-| `carto impact <file>` | Blast radius: risk level, affected files, routes at risk |
-| `carto check` | Cross-domain violations, high-risk uncommitted changes, domain health |
-| `carto remove` | Remove AGENTS.md and .carto/ from project |
+Reads `tsconfig.json` / `jsconfig.json` `paths` config. `@/components/Button` resolves to the actual file in the import graph — blast radius works correctly for Next.js and Vite projects.
 
 ---
 
 ## ACP Agent (Zed / JetBrains / VS Code)
 
-Carto works as a full **ACP agent** — not just a passive tool server, but an active coding agent with architectural awareness.
+Beyond MCP, Carto runs as a full **ACP agent** — an active coding agent with built-in architectural awareness.
 
 ```
 User: "Add rate limiting to /api/users"
@@ -189,20 +166,16 @@ Sends to LLM (your API key) → streams answer + diffs back to editor
 
 ### Setup in Zed
 
-Add to `~/.config/zed/settings.json`:
-
+`~/.config/zed/settings.json`:
 ```json
 {
   "agent_servers": {
-    "Carto": {
-      "command": "carto",
-      "args": ["agent"]
-    }
+    "Carto": { "command": "carto", "args": ["agent"] }
   }
 }
 ```
 
-### BYOK (Bring Your Own Key)
+### Bring Your Own Key
 
 Carto supports any LLM provider — configure in your editor:
 
@@ -217,53 +190,123 @@ Carto supports any LLM provider — configure in your editor:
 | Together AI | Open-source models |
 | Azure OpenAI | Enterprise deployments |
 
-### What makes it different
+---
+
+## The 16 MCP tools
+
+Once carto is wired in, your AI tool can call any of these mid-task. You don't need to memorize them — your AI will pick the right ones.
+
+| Tool | What it returns |
+|------|----------------|
+| `get_architecture()` | 500-word project overview: domains, entry points, stack, key patterns. **Use this first.** |
+| `get_change_plan(intent)` | Given "add rate limiting to /api/users" → files to touch, domains affected, blast radius, similar patterns |
+| `get_blast_radius(file)` | All files affected by changing a given file, with hop distance |
+| `get_context(file)` | Everything about a file: domain, blast radius, neighbors, routes, models |
+| `get_file_summary(file)` | What a file does, its role, key deps and dependents |
+| `get_similar_patterns(file)` | Files with same domain, route shape, or shared deps — find conventions before writing new code |
+| `get_routes()` | All API endpoints with file mapping |
+| `get_structure()` | Import graph, entry points, high-impact files, tech stack |
+| `get_domain(name)` | All routes, models, functions for a domain. Lazily regenerated when stale. |
+| `get_neighbors(file, hops)` | Import graph neighbors: nodes and edges |
+| `get_cross_domain()` | Import edges that cross domain boundaries |
+| `search_routes(query)` | Search API routes by path or method |
+| `get_models(domain?)` | All data models, optionally filtered by domain |
+| `get_high_impact_files(n)` | Top N files by blast radius |
+| `get_env_vars(domain?)` | All env vars with domain mapping |
+| `get_domains_list()` | All detected domains with file, route, model counts |
 
-Other agents are smart but blind. Carto sees the architecture:
-- Auto-indexes your project on first session (1-10s depending on size)
-- Injects structural context into every LLM call (blast radius, domains, routes)
-- 12 internal tools the LLM can call during reasoning
-- Zero cost to you beyond your own API key
+**All MCP queries:** **<5ms** on every benchmarked repo.
 
 ---
 
-## MCP config (if auto-wire missed your IDE)
+## Domain detection
 
-`carto init` auto-wires into Kiro, Cursor, and Claude Desktop. If it missed yours, add manually:
+Carto uses **Leiden+CPM graph clustering** — files that import each other heavily cluster together. Domain names are inferred from path tokens, with keyword hints for well-known patterns (AUTH, PAYMENTS, DATABASE, etc.).
 
-**Kiro** — `~/.kiro/settings/mcp.json`
-```json
-{ "mcpServers": { "carto": { "command": "carto", "args": ["serve"], "cwd": "/your/project" } } }
-```
+Works on any repo — not just SaaS apps. vscode gets AUTH/EVENTS/DATABASE. zed (Rust) gets DATABASE/AUTH/EVENTS. A game engine would get RENDERER/PHYSICS/AUDIO.
 
-**Cursor** — `~/.cursor/mcp.json`
+Custom domains via `carto.config.json`:
 ```json
-{ "mcpServers": { "carto": { "command": "carto", "args": ["serve"], "cwd": "/your/project" } } }
+{
+  "domains": {
+    "EDITOR": ["editor", "monaco", "text"],
+    "WORKBENCH": ["workbench", "layout", "panel"]
+  }
+}
 ```
 
-**Claude Desktop** — `~/Library/Application Support/Claude/claude_desktop_config.json`
-```json
-{ "mcpServers": { "carto": { "command": "carto", "args": ["serve"], "cwd": "/your/project" } } }
-```
+---
 
-**VS Code Copilot** — `.vscode/mcp.json` in your project root, or Command Palette → `MCP: Add Server`
-```json
-{ "servers": { "carto": { "command": "carto", "args": ["serve"], "cwd": "/your/project" } } }
-```
+## CLI commands
 
-**Windsurf** — `~/.windsurf/mcp.json`
-```json
-{ "mcpServers": { "carto": { "command": "carto", "args": ["serve"], "cwd": "/your/project" } } }
+| Command | What it does |
+|---------|-------------|
+| `carto init` | Detect project, index codebase, generate AGENTS.md, auto-wire MCP into every AI tool found |
+| `carto sync` | Full re-index (skips unchanged files via mtime+size cache) |
+| `carto watch` | Incremental live re-index on every file save (<50ms) |
+| `carto serve` | Start MCP server (called by your AI tool — usually you don't run this directly) |
+| `carto agent` | Start ACP agent mode (for Zed / JetBrains / VS Code) |
+| `carto impact <file>` | Blast radius: risk level, affected files, routes at risk |
+| `carto check` | Cross-domain violations, high-risk uncommitted changes, domain health |
+| `carto remove` | Remove AGENTS.md and .carto/ from project |
+
+---
+
+## Benchmarks
+
+Measured on real open-source repos. Apple M-series, 8 CPUs, 8GB RAM. SHAs pinned in `~/carto-test-repos`.
+
+| Repo | Language | Indexed Files | First Run | Second Run | DB Size | Import Edges |
+|------|----------|---------------|-----------|------------|---------|--------------|
+| [prisma/prisma](https://github.com/prisma/prisma) | TypeScript | 961 | **649ms** | **110ms** | 0.7 MB | 1,387 |
+| [supabase/supabase](https://github.com/supabase/supabase) | TypeScript | 6,259 | **4.8s** | **751ms** | 4.0 MB | 5,321 |
+| [microsoft/vscode](https://github.com/microsoft/vscode) | TypeScript | 7,567 | **7.8s** | **387ms** | 6.7 MB | 13,420 |
+| [zed-industries/zed](https://github.com/zed-industries/zed) | Rust | 1,752 | **3.0s** | **182ms** | 4.4 MB | 2,113 |
+
+**Indexed Files** counts what Carto actually parses — `.ts/.js/.py/.go/.rs/...` after excluding `node_modules`, build output, and per-file `*.test.*` / `*.spec.*` / `*.stories.*` / `test_*.py` patterns. The on-disk file count of the repo is larger.
+
+**Second run** = only changed files re-parsed. mtime+size checked before reading content — if nothing changed, nothing is re-parsed.
+
+### Domains detected
+
+| Repo | Domains |
+|------|---------|
+| prisma | CORE · DATABASE · EVENTS · AUTH |
+| supabase | CORE · AUTH · DATABASE · PAYMENTS · EVENTS · NOTIFICATIONS · TRPC |
+| vscode | CORE · DATABASE · AUTH · EVENTS · NOTIFICATIONS |
+| zed (Rust) | CORE · DATABASE · AUTH · EVENTS · PAYMENTS · NOTIFICATIONS · TRPC |
+
+vscode at 7,567 indexed files in under 8 seconds. Rust import graph working on zed (2,113 edges from `mod` declarations and `use crate::` paths).
+
+---
+
+## How it works
+
+```
+carto init / carto sync
+  ↓
+Discovers all files (no cap — SQLite handles the volume)
+mtime+size check → skip unchanged files
+tree-sitter parse → imports + symbols (0.05–0.2ms/file)
+Babel deep parse → routes + models (API handler files only)
+Leiden+CPM graph clustering → auto-detects domains
+Computes reverse deps → blast radius for every file
+Writes AGENTS.md + .carto/context/*.md (lazy, on-demand)
+Auto-wires MCP into every AI tool found
+  ↓
+carto watch (optional)
+  ↓
+File saved → debounce 50ms → re-parse 1 file → SQLite write → <50ms
 ```
 
 ---
 
 ## What Carto never does
 
-- Sends your code anywhere. Local only. SQLite on disk.
-- Writes secrets into AGENTS.md. `.cartoignore` blocks `.env` and credential files by default.
-- Touches your manual notes. Writes only between `<!-- CARTO:AUTO:START -->` and `<!-- CARTO:AUTO:END -->`.
-- Costs money. MIT license. Free forever.
+- **Sends your code anywhere.** Local only. SQLite on disk.
+- **Writes secrets into AGENTS.md.** `.cartoignore` blocks `.env` and credential files by default.
+- **Touches your manual notes.** Writes only between `<!-- CARTO:AUTO:START -->` and `<!-- CARTO:AUTO:END -->`.
+- **Costs money.** MIT license. Free forever.
 
 ---
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "carto-md",
-  "version": "2.0.6",
+  "version": "2.0.7",
   "description": "Structural intelligence layer for AI coding tools. Indexes your codebase into SQLite — routes, models, import graph, blast radius, domains — and exposes 16 MCP tools for Kiro, Cursor, and Claude.",
   "bin": {
     "carto": "src/cli/index.js"
@@ -29,7 +29,7 @@
     "tree-sitter-typescript": "0.23.2"
   },
   "engines": {
-    "node": ">=18.0.0"
+    "node": ">=18.0.0 <26.0.0"
   },
   "author": {
     "name": "Ansh Sonkar",

package/src/acp/agent.js

@@ -70,19 +70,12 @@ class CartoAgent {
   }
 
   // Provider methods
-  async unstable_listProviders(_params) {
-    return { providers: this.providers.list() };
-  }
-
-  async unstable_setProvider(params) {
-    this.providers.set(params);
-    return {};
-  }
-
-  async unstable_disableProvider(_params) {
-    this.providers.disable();
-    return {};
-  }
+  // The custom `unstable_*` provider-management methods (list / set / disable)
+  // were removed in 2.0.7 (Spec 7 Bug 3). The ACP SDK only dispatches the
+  // methods declared in its AGENT_METHODS constant, so those custom routes
+  // returned -32601 "Method not found" anyway. Provider config flows
+  // through env vars / editor settings; ProviderRegistry remains as the
+  // internal configuration carrier.
 
   // Session list/load stubs
   async listSessions(_params) { return { sessions: [] }; }

package/src/acp/providers/index.js

@@ -30,20 +30,12 @@ class ProviderRegistry {
     this._config = null;
   }
 
-  /**
-   * list() — Returns supported providers for ACP providers/list.
-   */
-  list() {
-    return SUPPORTED_PROVIDERS.map(p => ({
-      id: p.id,
-      name: p.name,
-      defaultModel: p.defaultModel,
-      models: p.models,
-    }));
-  }
+  // list() was removed in 2.0.7 (Spec 7 Bug 3). It was only called by the
+  // dropped custom provider-list ACP method, which the SDK never dispatched.
+  // SUPPORTED_PROVIDERS is still exported for external callers / tests.
 
   /**
-   * set(params) — Configures the active provider from ACP providers/set.
+   * set(params) — Configures the active provider.
    * params: { providerId, apiKey, baseUrl?, model? }
    */
   set(params) {

package/src/cli/impact.js

@@ -1,6 +1,7 @@
 'use strict';
 
 const { StoreAdapter } = require('../store/store-adapter');
+const { normalizeFileArg } = require('../store/path-utils');
 const { checkForUpdate } = require('./update-check');
 
 async function run(projectRoot, fileArg) {
@@ -10,6 +11,10 @@ async function run(projectRoot, fileArg) {
     process.exit(1);
   }
 
+  // Normalize so `./lib/x.js`, absolute paths, and Windows separators
+  // all resolve to the same `files.path` value stored in SQLite.
+  const file = normalizeFileArg(projectRoot, fileArg);
+
   const carto = new StoreAdapter();
   try {
     await carto.index(projectRoot);
@@ -18,7 +23,7 @@ async function run(projectRoot, fileArg) {
     process.exit(1);
   }
 
-  const br = carto.getBlastRadius(fileArg);
+  const br = carto.getBlastRadius(file);
   if (!br) {
     console.error(`[CARTO] File not found in project graph: ${fileArg}`);
     carto.close();

package/src/cli/init.js

@@ -95,6 +95,21 @@ function wireIDEs(projectRoot) {
   const home = os.homedir();
   const wired = [];
 
+  // Claude Code (project-scoped). Spec 7: write .mcp.json at the project root.
+  // Claude Code reads this file automatically when opened in the project — no
+  // host-level config needed, and no detection required (it's a project-local
+  // file that only takes effect when the user actually uses Claude Code here).
+  try {
+    const mcpJsonPath = path.join(projectRoot, '.mcp.json');
+    const config = fs.existsSync(mcpJsonPath)
+      ? JSON.parse(fs.readFileSync(mcpJsonPath, 'utf-8'))
+      : { mcpServers: {} };
+    config.mcpServers = config.mcpServers || {};
+    config.mcpServers.carto = { command: 'carto', args: ['serve'] };
+    fs.writeFileSync(mcpJsonPath, JSON.stringify(config, null, 2) + '\n', 'utf-8');
+    wired.push('Claude Code');
+  } catch {}
+
   // Kiro
   const kiroDir = path.join(home, '.kiro', 'settings');
   if (fs.existsSync(path.join(home, '.kiro'))) {

package/src/extractors/imports.js

@@ -36,7 +36,11 @@ function extractImports(content, filePath, projectRoot) {
   if (['.js', '.jsx', '.ts', '.tsx', '.mjs', '.cjs'].includes(ext)) {
     rawImports = extractJSImports(content);
   } else if (ext === '.py') {
-    rawImports = extractPythonImports(content, filePath, projectRoot);
+    // Python returns absolute paths from resolvePythonRelativeImport / tryResolvePythonModule.
+    // Relativize to project root and return early — the JS-style dedup loop below only handles
+    // `./` and `@/~/#` prefixed strings, so falling through silently drops every Python edge.
+    const abs = extractPythonImports(content, filePath, projectRoot);
+    return [...new Set(abs.map(p => path.relative(projectRoot, p)))].sort();
   } else if (ext === '.r') {
     return extractRImports(content, filePath, projectRoot);
   } else if (ext === '.go') {

package/src/mcp/server-v2.js

@@ -7,9 +7,22 @@ const { Server } = require('@modelcontextprotocol/sdk/server/index.js');
 const { StdioServerTransport } = require('@modelcontextprotocol/sdk/server/stdio.js');
 const { CallToolRequestSchema, ListToolsRequestSchema } = require('@modelcontextprotocol/sdk/types.js');
 const { SQLiteStore } = require('../store/sqlite-store');
+const { normalizeFileArg } = require('../store/path-utils');
 
 const projectRoot = process.cwd();
 
+// Process-level safety nets — Spec 7 Bug 5c. Without these, any error that
+// escapes the request handler (very rare, but possible from native bindings
+// or async stack frames) takes the whole MCP server down, and Claude Code /
+// Kiro surface `-32000 Failed to reconnect`. We log to stderr (which the
+// host logs but never terminates the JSON-RPC channel) and stay alive.
+process.on('uncaughtException', (err) => {
+  process.stderr.write(`[CARTO MCP] Uncaught exception: ${err && err.stack ? err.stack : err}\n`);
+});
+process.on('unhandledRejection', (reason) => {
+  process.stderr.write(`[CARTO MCP] Unhandled rejection: ${reason && reason.stack ? reason.stack : reason}\n`);
+});
+
 // Open SQLite directly — no re-indexing, instant startup
 let store = null;
 
@@ -17,8 +30,13 @@ function getStore() {
   if (store) return store;
   const dbPath = path.join(projectRoot, '.carto', 'carto.db');
   if (!fs.existsSync(dbPath)) return null;
-  store = new SQLiteStore(projectRoot);
-  store.open();
+  // Open BEFORE assigning to the module-scoped `store` so that if open()
+  // throws (corrupt DB, locked file, schema mismatch) we don't poison the
+  // cache with a broken instance — every subsequent call would otherwise
+  // return the broken object and never recover.
+  const s = new SQLiteStore(projectRoot);
+  s.open({ readonly: true }); // Spec 8 — defense in depth: MCP tools never write
+  store = s;
   return store;
 }
 
@@ -62,8 +80,20 @@ server.setRequestHandler(ListToolsRequestSchema, async () => ({ tools: TOOLS }))
 
 server.setRequestHandler(CallToolRequestSchema, async (request) => {
   const { name, arguments: args } = request.params;
-  const s = getStore();
-  if (!s) return notIndexed();
+  // Normalize file-arg tools to the canonical SQLite-stored form so
+  // `./lib/x.js`, absolute paths, and Windows separators all resolve.
+  // Tools that don't take a `file` arg are unaffected.
+  if (args && typeof args.file === 'string') {
+    args.file = normalizeFileArg(projectRoot, args.file);
+  }
+  // Wrap entire handler body so any tool error (SQLite, null deref, bad
+  // input) returns a structured error response instead of crashing the
+  // MCP transport — Spec 7 Bug 5 fix. Pre-2.0.7, an unhandled throw here
+  // killed the stdio connection and Claude Code/Kiro would surface
+  // `-32000 Failed to reconnect`.
+  try {
+    const s = getStore();
+    if (!s) return notIndexed();
 
   if (name === 'get_routes') {
     const routes = s.getRoutes();
@@ -105,6 +135,11 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
   }
 
   if (name === 'get_domain') {
+    // Guard: AI clients sometimes call this with no/empty `domain` arg.
+    // Pre-2.0.7 we'd then call args.domain.toUpperCase() on undefined and crash.
+    if (!args.domain || typeof args.domain !== 'string') {
+      return text('Missing required argument: domain. Use get_domains_list to see available domains.');
+    }
     const domain = s.getDomain(args.domain);
     if (!domain) return text(`Domain not found: ${args.domain}. Use get_domains_list to see available domains.`);
 
@@ -133,7 +168,11 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
       models: domain.models.map(m => ({
         ...m,
         className: m.name,
-        fields: m.fields_json ? JSON.parse(m.fields_json) : []
+        // Wrap parse so one corrupt row doesn't take down the whole tool call.
+        fields: (() => {
+          if (!m.fields_json) return [];
+          try { return JSON.parse(m.fields_json); } catch { return []; }
+        })()
       })),
       functions: {},
       envVars: [],
@@ -446,6 +485,13 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
   }
 
   return text(`Unknown tool: ${name}`);
+  } catch (err) {
+    process.stderr.write(`[CARTO MCP] Tool "${name}" error: ${err.stack || err.message || err}\n`);
+    return {
+      content: [{ type: 'text', text: `Error in ${name}: ${err.message || String(err)}` }],
+      isError: true,
+    };
+  }
 });
 
 async function main() {

package/src/security/ignore.js

@@ -2,8 +2,11 @@ const fs = require('fs');
 const path = require('path');
 
 const DEFAULT_IGNORE_PATTERNS = [
+  // Env files
   '.env',
   '.env.*',
+
+  // Generic secret/credential name globs
   '*secret*',
   '*SECRET*',
   '*password*',
@@ -12,8 +15,60 @@ const DEFAULT_IGNORE_PATTERNS = [
   '*CREDENTIAL*',
   '*private_key*',
   '*PRIVATE_KEY*',
+
+  // Generic key/cert extensions
   '*.pem',
-  '*.key'
+  '*.key',
+
+  // SSH keys (no extension, won't be caught by *.key)
+  'id_rsa',
+  'id_rsa.pub',
+  'id_ed25519',
+  'id_ed25519.pub',
+  'id_ecdsa',
+  'id_ecdsa.pub',
+  'id_dsa',
+  'id_dsa.pub',
+  'authorized_keys',
+  'known_hosts',
+
+  // Package registry credentials
+  '.npmrc',
+  '.pypirc',
+  '.netrc',
+  '.pip/pip.conf',
+  '.gem/credentials',
+  '.cargo/credentials.toml',
+
+  // Cloud / K8s / Docker
+  'kubeconfig',
+  '*.kubeconfig',
+  '.docker/config.json',
+  '.dockercfg',
+  '*service-account*.json',
+  '*service_account*.json',
+  '*-credentials.json',
+  '.aws/credentials',
+  '.aws/config',
+  '.gcp/*',
+  '.gnupg/*',
+
+  // Cert / keystore formats (defense in depth — already excluded by CODE_EXTS today)
+  '*.crt',
+  '*.cer',
+  '*.p12',
+  '*.pfx',
+  '*.jks',
+  '*.keystore',
+  '*.pkcs12'
+
+  // NOTE: deliberately NOT including `*api_key*` / `*api-key*` globs.
+  // Real SaaS projects (cal.com, supabase, fastapi, zed) ship legitimate
+  // feature code under these filenames — `api_key.py`, `api-keys-service.ts`,
+  // `language_model/src/api_key.rs` — and a broad glob would silently delete
+  // 17+ files per repo from the import graph. Raw-credential files literally
+  // named `api_key.txt` are unusual; the realistic threat surface (.env,
+  // *credentials.json, .npmrc, id_rsa, kubeconfig, *secret*) is covered above.
 ];
 
 /**

package/src/store/path-utils.js

@@ -0,0 +1,50 @@
+'use strict';
+
+const path = require('path');
+
+/**
+ * normalizeFileArg(projectRoot, fileArg) → string
+ *
+ * Convert a user-provided file path into the canonical form stored in the
+ * SQLite `files.path` column: relative-to-project-root, forward-slashed,
+ * no leading `./`.
+ *
+ * Handles every form a user / IDE / shell tab-completion realistically
+ * produces:
+ *   - relative form already correct          ("lib/application.js"   → "lib/application.js")
+ *   - leading "./"                           ("./lib/application.js" → "lib/application.js")
+ *   - leading "/" absolute under projectRoot ("/abs/.../lib/application.js" → "lib/application.js")
+ *   - Windows backslashes                    ("lib\\application.js"  → "lib/application.js")
+ *   - paths containing "../" (e.g. typed from a sibling dir) — resolved.
+ *
+ * Falsy / empty input returns the input unchanged so the caller's
+ * "missing argument" check still fires the same way.
+ */
+function normalizeFileArg(projectRoot, fileArg) {
+  if (typeof fileArg !== 'string' || fileArg.length === 0) return fileArg;
+
+  let p = fileArg;
+
+  // Normalize separators first so the absolute-path check works on Windows.
+  p = p.split('\\').join('/');
+
+  // Absolute → relative-to-project-root
+  if (path.isAbsolute(p) || /^[a-zA-Z]:\//.test(p)) {
+    p = path.relative(projectRoot, p);
+    p = p.split(path.sep).join('/');
+  }
+
+  // Strip leading "./" (or repeated "./././")
+  while (p.startsWith('./')) p = p.slice(2);
+
+  // Resolve any embedded "../" segments without going absolute.
+  // e.g. "src/foo/../bar.js" → "src/bar.js"
+  if (p.includes('/../') || p.startsWith('../')) {
+    const abs = path.resolve(projectRoot, p);
+    p = path.relative(projectRoot, abs).split(path.sep).join('/');
+  }
+
+  return p;
+}
+
+module.exports = { normalizeFileArg };

package/src/store/sqlite-store.js

@@ -41,14 +41,35 @@ class SQLiteStore {
   }
 
   /**
-   * open() — Opens or creates the database. Applies pragmas and schema.
+   * open(opts) — Opens or creates the database. Applies pragmas and schema.
+   *
+   * Options:
+   *   readonly  — Open the DB in read-only mode. Used by the MCP server
+   *               (`carto serve`) so a malformed/buggy tool can never write
+   *               through the SQLite layer. Skips mkdir, schema bootstrap, and
+   *               WAL pragma (WAL needs write capability and would otherwise
+   *               create `carto.db-wal`/`carto.db-shm` in repos that only run
+   *               the MCP server). Sets `fileMustExist: true` so a missing DB
+   *               returns a clear SQLite error instead of silently creating an
+   *               empty file in the wrong location.
    */
-  open() {
+  open(opts = {}) {
     const cartoDir = path.join(this._projectRoot, '.carto');
-    fs.mkdirSync(cartoDir, { recursive: true });
-
     const dbPath = path.join(cartoDir, 'carto.db');
 
+    if (opts.readonly) {
+      // Read-only path: dir must already exist (a writer process — `carto sync`
+      // or `carto init` — created the DB). Don't mkdir, don't ensure schema,
+      // don't apply write-only pragmas.
+      this._db = new Database(dbPath, { readonly: true, fileMustExist: true });
+      // Read-only safe pragmas only:
+      this._db.pragma('busy_timeout = 5000');
+      this._db.pragma('cache_size = -64000'); // 64MB cache
+      return this;
+    }
+
+    fs.mkdirSync(cartoDir, { recursive: true });
+
     try {
       this._db = new Database(dbPath);
     } catch (err) {
@@ -618,7 +639,12 @@ class SQLiteStore {
       },
       entryPoints,
       highImpact,
-      stack: stack ? JSON.parse(stack) : [],
+      // Defensive parse — a corrupt stack_json row must never crash callers.
+      // Spec 7 Bug 5f.
+      stack: (() => {
+        if (!stack) return [];
+        try { return JSON.parse(stack); } catch { return []; }
+      })(),
       domains
     };
   }