sdl-mcp 0.6.0

package/migrations/0004_metrics_audit.sql

@@ -0,0 +1,23 @@
+CREATE TABLE IF NOT EXISTS metrics (
+  symbol_id TEXT PRIMARY KEY,
+  fan_in INTEGER NOT NULL DEFAULT 0,
+  fan_out INTEGER NOT NULL DEFAULT 0,
+  churn_30d INTEGER NOT NULL DEFAULT 0,
+  test_refs_json TEXT,
+  updated_at TEXT NOT NULL,
+  FOREIGN KEY(symbol_id) REFERENCES symbols(symbol_id) ON DELETE CASCADE
+);
+
+CREATE TABLE IF NOT EXISTS audit (
+  event_id INTEGER PRIMARY KEY AUTOINCREMENT,
+  timestamp TEXT NOT NULL,
+  tool TEXT NOT NULL,
+  decision TEXT NOT NULL,
+  repo_id TEXT,
+  symbol_id TEXT,
+  details_json TEXT NOT NULL
+);
+
+CREATE INDEX IF NOT EXISTS idx_audit_tool ON audit(tool);
+CREATE INDEX IF NOT EXISTS idx_audit_timestamp ON audit(timestamp);
+CREATE INDEX IF NOT EXISTS idx_audit_repo ON audit(repo_id);

package/migrations/0005_slice_handles.sql

@@ -0,0 +1,15 @@
+CREATE TABLE IF NOT EXISTS slice_handles (
+  handle TEXT PRIMARY KEY,
+  repo_id TEXT NOT NULL,
+  created_at TEXT NOT NULL,
+  expires_at TEXT NOT NULL,
+  min_version TEXT,
+  max_version TEXT,
+  slice_hash TEXT NOT NULL,
+  spillover_ref TEXT,
+  FOREIGN KEY(repo_id) REFERENCES repos(repo_id) ON DELETE CASCADE
+);
+
+CREATE INDEX IF NOT EXISTS idx_slice_handles_repo ON slice_handles(repo_id);
+CREATE INDEX IF NOT EXISTS idx_slice_handles_expires ON slice_handles(expires_at);
+CREATE INDEX IF NOT EXISTS idx_slice_handles_repo_version ON slice_handles(repo_id, max_version);

package/migrations/0006_content_addressed.sql

@@ -0,0 +1,29 @@
+CREATE TABLE IF NOT EXISTS card_hashes (
+  card_hash TEXT PRIMARY KEY,
+  card_blob TEXT NOT NULL,
+  created_at TEXT NOT NULL
+);
+
+CREATE TABLE IF NOT EXISTS tool_policy_hashes (
+  policy_hash TEXT PRIMARY KEY,
+  policy_blob TEXT NOT NULL,
+  created_at TEXT NOT NULL
+);
+
+CREATE TABLE IF NOT EXISTS tsconfig_hashes (
+  tsconfig_hash TEXT PRIMARY KEY,
+  tsconfig_blob TEXT NOT NULL,
+  created_at TEXT NOT NULL
+);
+
+ALTER TABLE versions ADD COLUMN prev_version_hash TEXT;
+ALTER TABLE versions ADD COLUMN version_hash TEXT;
+
+UPDATE versions SET prev_version_hash = NULL WHERE prev_version_hash IS NULL;
+UPDATE versions SET version_hash = NULL WHERE version_hash IS NULL;
+
+CREATE INDEX IF NOT EXISTS idx_card_hashes_created ON card_hashes(created_at);
+CREATE INDEX IF NOT EXISTS idx_tool_policy_hashes_created ON tool_policy_hashes(created_at);
+CREATE INDEX IF NOT EXISTS idx_tsconfig_hashes_created ON tsconfig_hashes(created_at);
+CREATE INDEX IF NOT EXISTS idx_versions_version_hash ON versions(version_hash);
+CREATE INDEX IF NOT EXISTS idx_versions_prev_hash ON versions(prev_version_hash);

package/migrations/0007_add_language_to_symbols.sql

@@ -0,0 +1,28 @@
+-- ML-D.2: Add language field to symbol records
+
+-- Add language column to symbols table
+ALTER TABLE symbols ADD COLUMN language TEXT;
+
+-- Backfill existing symbols with language based on file extension
+-- Infer language from file's extension by joining with files table
+UPDATE symbols
+SET language = (
+  CASE
+    WHEN substr(f.rel_path, -3) = '.ts' THEN 'typescript'
+    WHEN substr(f.rel_path, -4) = '.tsx' THEN 'typescript'
+    WHEN substr(f.rel_path, -3) = '.js' THEN 'javascript'
+    WHEN substr(f.rel_path, -4) = '.jsx' THEN 'typescript'
+    WHEN substr(f.rel_path, -3) = '.py' THEN 'python'
+    WHEN substr(f.rel_path, -3) = '.go' THEN 'go'
+    WHEN substr(f.rel_path, -5) = '.java' THEN 'java'
+    WHEN substr(f.rel_path, -6) = '.cs' THEN 'csharp'
+    WHEN substr(f.rel_path, -3) = '.cs' THEN 'csharp'
+    ELSE f.language
+  END
+)
+FROM files f
+WHERE symbols.file_id = f.file_id AND symbols.language IS NULL;
+
+-- Add index on language column for query performance
+CREATE INDEX IF NOT EXISTS idx_symbols_language ON symbols(language);
+CREATE INDEX IF NOT EXISTS idx_symbols_repo_language ON symbols(repo_id, language);

package/migrations/0008_performance_indexes.sql

@@ -0,0 +1,21 @@
+-- Add performance indexes for frequently queried columns
+-- Migration: 0008_performance_indexes.sql
+
+-- Index for getSymbolsByFile() - frequently called during indexing
+CREATE INDEX IF NOT EXISTS idx_symbols_file_id ON symbols(file_id);
+
+-- Index for searchSymbols() - improves LIKE queries on name with repo_id filter
+CREATE INDEX IF NOT EXISTS idx_symbols_repo_name_idx ON symbols(repo_id, name);
+
+-- Index for getFilesByRepo() - frequently called during operations
+CREATE INDEX IF NOT EXISTS idx_files_repo_id ON files(repo_id);
+
+-- Index for version queries with ordering by created_at
+-- Covers getLatestVersion() and listVersions()
+CREATE INDEX IF NOT EXISTS idx_versions_repo_created ON versions(repo_id, created_at DESC);
+
+-- Index for slice_handles by repo_id
+CREATE INDEX IF NOT EXISTS idx_slice_handles_repo_id ON slice_handles(repo_id);
+
+-- Composite index for symbols with repo_id and kind (common filter combo)
+CREATE INDEX IF NOT EXISTS idx_symbols_repo_kind ON symbols(repo_id, kind);

package/migrations/0009_fix_edge_fks.sql

@@ -0,0 +1,37 @@
+-- RR-G.7: Add missing foreign key constraints to edges table
+-- Note: to_symbol_id intentionally has no FK constraint because the indexer
+-- creates "unresolved" edges (e.g., "unresolved:call:functionName") for
+-- cross-file references that haven't been resolved yet.
+
+-- Create new edges table with proper FK constraints
+CREATE TABLE edges_new (
+  edge_id INTEGER PRIMARY KEY AUTOINCREMENT,
+  repo_id TEXT NOT NULL,
+  from_symbol_id TEXT NOT NULL,
+  to_symbol_id TEXT NOT NULL,
+  type TEXT NOT NULL,
+  weight REAL NOT NULL,
+  provenance TEXT,
+  created_at TEXT NOT NULL,
+  FOREIGN KEY(repo_id) REFERENCES repos(repo_id) ON DELETE CASCADE,
+  FOREIGN KEY(from_symbol_id) REFERENCES symbols(symbol_id) ON DELETE CASCADE
+  -- to_symbol_id has no FK: allows unresolved edges like "unresolved:call:foo"
+);
+
+-- Copy only valid data (with existing FK references) from old table
+-- Only validate repo_id and from_symbol_id; to_symbol_id may be unresolved
+INSERT INTO edges_new
+SELECT e.* FROM edges e
+WHERE EXISTS (SELECT 1 FROM repos r WHERE r.repo_id = e.repo_id)
+  AND EXISTS (SELECT 1 FROM symbols s WHERE s.symbol_id = e.from_symbol_id);
+
+-- Drop old table
+DROP TABLE edges;
+
+-- Rename new table
+ALTER TABLE edges_new RENAME TO edges;
+
+-- Recreate indexes
+CREATE INDEX idx_edges_repo_from ON edges(from_symbol_id);
+CREATE INDEX idx_edges_repo_to ON edges(to_symbol_id);
+CREATE INDEX idx_edges_repo ON edges(repo_id);

package/migrations/0010_standardize_fks.sql

@@ -0,0 +1,35 @@
+-- RR-H.1: Database schema standardization
+
+-- Issue 1: Add missing FK on symbol_versions.symbol_id with CASCADE
+-- Recreate symbol_versions table with proper FK constraint
+CREATE TABLE symbol_versions_new (
+  version_id TEXT NOT NULL,
+  symbol_id TEXT NOT NULL,
+  ast_fingerprint TEXT NOT NULL,
+  signature_json TEXT,
+  summary TEXT,
+  invariants_json TEXT,
+  side_effects_json TEXT,
+  PRIMARY KEY(version_id, symbol_id),
+  FOREIGN KEY(version_id) REFERENCES versions(version_id) ON DELETE CASCADE,
+  FOREIGN KEY(symbol_id) REFERENCES symbols(symbol_id) ON DELETE CASCADE
+);
+
+-- Copy only valid data (with existing FK references) from old table
+INSERT INTO symbol_versions_new
+SELECT sv.* FROM symbol_versions sv
+WHERE EXISTS (SELECT 1 FROM versions v WHERE v.version_id = sv.version_id)
+  AND EXISTS (SELECT 1 FROM symbols s WHERE s.symbol_id = sv.symbol_id);
+
+-- Drop old table
+DROP TABLE symbol_versions;
+
+-- Rename new table
+ALTER TABLE symbol_versions_new RENAME TO symbol_versions;
+
+-- Recreate index
+CREATE INDEX idx_symbol_versions_symbol ON symbol_versions(symbol_id);
+
+-- Issue 3: Remove duplicate index idx_symbols_repo_name_idx from migration 0008
+-- (idx_symbols_repo_name already exists from migration 0001)
+DROP INDEX IF EXISTS idx_symbols_repo_name_idx;

package/migrations/0011_add_directory_column.sql

@@ -0,0 +1,20 @@
+-- Migration: Add directory column to files table
+-- Purpose: Improve performance of directory aggregate queries by storing computed directory
+
+-- Add directory column
+ALTER TABLE files ADD COLUMN directory TEXT NOT NULL DEFAULT '';
+
+-- Populate existing rows with directory from rel_path
+-- Extract directory by finding the last slash (like JavaScript's lastIndexOf)
+-- Using reverse() to find the last occurrence of '/'
+-- Formula: substr(rel_path, 1, length(rel_path) - instr(reverse(rel_path), '/'))
+-- Note: instr() is 1-indexed in SQLite, so we don't need to adjust further
+UPDATE files SET directory =
+  CASE
+    WHEN instr(rel_path, '/') > 0
+    THEN substr(rel_path, 1, length(rel_path) - instr(reverse(rel_path), '/'))
+    ELSE ''
+  END;
+
+-- Add index for directory queries (composite with repo_id for better filtering)
+CREATE INDEX idx_files_directory ON files(repo_id, directory);

package/migrations/0012_symbol_references.sql

@@ -0,0 +1,16 @@
+-- Migration 0012: Create symbol_references table for inverted index
+-- This table tracks symbol references in test files for O(1) lookup
+
+CREATE TABLE IF NOT EXISTS symbol_references (
+  ref_id INTEGER PRIMARY KEY AUTOINCREMENT,
+  repo_id TEXT NOT NULL,
+  symbol_name TEXT NOT NULL,
+  file_id INTEGER NOT NULL,
+  line_number INTEGER,
+  created_at TEXT NOT NULL,
+  FOREIGN KEY(repo_id) REFERENCES repos(repo_id) ON DELETE CASCADE,
+  FOREIGN KEY(file_id) REFERENCES files(file_id) ON DELETE CASCADE
+);
+
+CREATE INDEX IF NOT EXISTS idx_symbol_refs_name ON symbol_references(repo_id, symbol_name);
+CREATE INDEX IF NOT EXISTS idx_symbol_refs_file ON symbol_references(file_id);

package/migrations/0013_sync_artifacts.sql

@@ -0,0 +1,17 @@
+CREATE TABLE IF NOT EXISTS sync_artifacts (
+  artifact_id TEXT PRIMARY KEY,
+  repo_id TEXT NOT NULL,
+  version_id TEXT NOT NULL,
+  commit_sha TEXT,
+  branch TEXT,
+  artifact_hash TEXT NOT NULL,
+  compressed_data TEXT NOT NULL,
+  created_at TEXT NOT NULL,
+  size_bytes INTEGER NOT NULL,
+  FOREIGN KEY(repo_id) REFERENCES repos(repo_id),
+  FOREIGN KEY(version_id) REFERENCES versions(version_id)
+);
+
+CREATE INDEX IF NOT EXISTS idx_sync_artifacts_repo ON sync_artifacts(repo_id);
+CREATE INDEX IF NOT EXISTS idx_sync_artifacts_version ON sync_artifacts(version_id);
+CREATE INDEX IF NOT EXISTS idx_sync_artifacts_commit ON sync_artifacts(commit_sha);

package/package.json

@@ -0,0 +1,107 @@
+{
+  "name": "sdl-mcp",
+  "version": "0.6.0",
+  "description": "Symbol Delta Ledger MCP Server - Cards-first code context for TypeScript/JavaScript repositories",
+  "type": "module",
+  "main": "dist/main.js",
+  "bin": {
+    "sdl-mcp": "dist/cli/index.js"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/GlitterKill/sdl-mcp.git"
+  },
+  "bugs": {
+    "url": "https://github.com/GlitterKill/sdl-mcp/issues"
+  },
+  "homepage": "https://github.com/GlitterKill/sdl-mcp#readme",
+  "files": [
+    "dist",
+    "config",
+    "migrations",
+    "templates",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "clean:dist": "node scripts/clean-dist.mjs",
+    "build": "tsc -p tsconfig.build.json",
+    "build:scripts": "tsc -p tsconfig.scripts.json && tsx scripts/fix-imports.ts",
+    "build:runtime": "npm run clean:dist && npm run build",
+    "build:all": "npm run clean:dist && npm run build && npm run build:scripts",
+    "watch": "tsc -p tsconfig.build.json --watch",
+    "dev": "tsx src/main.ts",
+    "typecheck": "tsc --noEmit",
+    "lint": "eslint src --ext .ts",
+    "format": "prettier --write \"src/**/*.ts\"",
+    "test": "node scripts/run-tests.mjs",
+    "test:harness": "npm run test:adapters",
+    "test:adapters": "npm run build && npx tsc --rootDir tests/harness --outDir dist/tests/harness --module nodenext tests/harness/adapter-runner.ts && node dist/tests/harness/adapter-runner.js",
+    "test:golden": "npm run build && tsx scripts/golden/update-goldens.ts validate",
+    "golden:update": "npm run build && tsx scripts/golden/update-goldens.ts generate",
+    "benchmark:ci": "node dist/cli/index.js benchmark:ci",
+    "migrate": "npm run build:scripts && node dist/scripts/migrate.js",
+    "index": "npm run build:scripts && node dist/scripts/index-repo.js",
+    "index-repo": "npm run build:scripts && node dist/scripts/index-repo.js",
+    "dump-symbol": "npm run build:scripts && node dist/scripts/dump-symbol.js",
+    "benchmark": "tsx scripts/benchmark.ts",
+    "benchmark:real": "tsx scripts/real-world-benchmark.ts",
+    "benchmark:matrix": "tsx scripts/real-world-benchmark-matrix.ts",
+    "benchmark:claims": "tsx scripts/check-benchmark-claims.ts",
+    "benchmark:sweep": "tsx scripts/budget-sensitivity-sweep.ts",
+    "benchmark:record-trace": "tsx scripts/record-trace.ts",
+    "benchmark:setup-external": "tsx scripts/setup-external-benchmark-repos.ts",
+    "package:exe": "node scripts/build-exe.js",
+    "prepack": "npm run build:runtime",
+    "prepublishOnly": "npm run build:all && npm run lint && npm run typecheck"
+  },
+  "keywords": [
+    "mcp",
+    "model-context-protocol",
+    "code-indexing",
+    "symbol-ledger",
+    "typescript",
+    "javascript",
+    "code-context",
+    "ast",
+    "code-analysis",
+    "developer-tools"
+  ],
+  "author": "",
+  "license": "MIT",
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.26.0",
+    "better-sqlite3": "^11.0.0",
+    "fast-glob": "^3.3.3",
+    "tree-sitter": "^0.21.1",
+    "tree-sitter-bash": "^0.21.0",
+    "tree-sitter-c": "^0.21.0",
+    "tree-sitter-c-sharp": "0.23.1",
+    "tree-sitter-cpp": "^0.21.0",
+    "tree-sitter-go": "0.23.4",
+    "tree-sitter-java": "0.23.5",
+    "tree-sitter-kotlin": "0.3.8",
+    "tree-sitter-php": "0.22.8",
+    "tree-sitter-python": "0.23.3",
+    "tree-sitter-rust": "0.21.0",
+    "tree-sitter-typescript": "0.23.2",
+    "typescript": "^5.9.3",
+    "zod": "^3.23.0",
+    "zod-to-json-schema": "^3.25.1"
+  },
+  "optionalDependencies": {
+    "chokidar": "^3.5.3"
+  },
+  "devDependencies": {
+    "@types/better-sqlite3": "^7.6.0",
+    "@types/node": "^20.0.0",
+    "@typescript-eslint/eslint-plugin": "^7.0.0",
+    "@typescript-eslint/parser": "^7.0.0",
+    "eslint": "^8.0.0",
+    "prettier": "^3.0.0",
+    "tsx": "^4.0.0"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  }
+}

package/templates/CLAUDE.md.template

@@ -0,0 +1,179 @@
+# CLAUDE.md - SDL-MCP Integration
+
+This file instructs Claude Code (and other AI agents) to use SDL-MCP for efficient code context.
+
+## Code Context Protocol
+
+**IMPORTANT**: This project uses SDL-MCP for code understanding. Always prefer SDL-MCP tools over reading raw files directly.
+
+### Repository Configuration
+
+- **Repository ID**: `{{REPO_ID}}`
+- **MCP Server**: sdl-mcp
+
+### Context Ladder (Use in Order)
+
+When you need to understand code, follow this escalation path:
+
+| Step | Tool | Token Cost | When to Use |
+|------|------|------------|-------------|
+| 1 | `sdl.symbol.search` | ~50 | Find symbols by name |
+| 2 | `sdl.symbol.getCard` | ~135 | Understand signatures, deps, summary |
+| 3 | `sdl.slice.build` | ~800 | Get related symbols for a task |
+| 4 | `sdl.code.getSkeleton` | ~113 | See control flow structure |
+| 5 | `sdl.code.getHotPath` | ~200 | Find specific identifiers |
+| 6 | `sdl.code.needWindow` | Variable | Full code (last resort) |
+
+### Tool Usage Guidelines
+
+#### Finding Code
+
+```
+# Search for symbols by name
+sdl.symbol.search({ repoId: "{{REPO_ID}}", query: "functionName" })
+
+# Search with filters
+sdl.symbol.search({
+  repoId: "{{REPO_ID}}",
+  query: "parse",
+  kinds: ["function", "method"],
+  limit: 20
+})
+```
+
+#### Understanding Code
+
+```
+# Get symbol metadata (signature, summary, dependencies)
+sdl.symbol.getCard({ repoId: "{{REPO_ID}}", symbolId: "<id>" })
+
+# Get related symbols for context
+sdl.slice.build({
+  repoId: "{{REPO_ID}}",
+  entrySymbols: ["<symbolId>"],
+  maxCards: 30
+})
+```
+
+#### Reading Code (When Necessary)
+
+```
+# Get code skeleton (signatures + control flow, elided bodies)
+sdl.code.getSkeleton({ repoId: "{{REPO_ID}}", symbolId: "<id>" })
+
+# Find specific identifiers in code
+sdl.code.getHotPath({
+  repoId: "{{REPO_ID}}",
+  symbolId: "<id>",
+  identifiers: ["errorHandler", "validate"]
+})
+
+# Get raw code (requires justification)
+sdl.code.needWindow({
+  repoId: "{{REPO_ID}}",
+  symbolId: "<id>",
+  reason: "Need to understand validation implementation details",
+  expectedIdentifiers: ["validateInput"]
+})
+```
+
+### Required Practices
+
+1. **Always search first**: Use `sdl.symbol.search` before trying to read files
+2. **Get cards before code**: Use `sdl.symbol.getCard` to understand what a symbol does
+3. **Use slices for context**: Use `sdl.slice.build` to find related code
+4. **Justify raw code requests**: Always provide a `reason` for `sdl.code.needWindow`
+5. **Follow nextBestAction**: If a request is denied, use the suggested alternative
+
+### Do NOT
+
+- Read entire files with the `Read` tool when SDL-MCP can provide the context
+- Skip cards and go directly to raw code
+- Ignore policy denials - use the `nextBestAction` suggestion
+- Request raw code without trying cards/skeletons first
+
+### Workflow Examples
+
+#### Bug Investigation
+
+1. Search for the problematic function:
+   ```
+   sdl.symbol.search({ repoId: "{{REPO_ID}}", query: "handleError" })
+   ```
+
+2. Get the card to understand its purpose and dependencies:
+   ```
+   sdl.symbol.getCard({ repoId: "{{REPO_ID}}", symbolId: "<found-id>" })
+   ```
+
+3. Build a slice to see related error handling:
+   ```
+   sdl.slice.build({ repoId: "{{REPO_ID}}", entrySymbols: ["<id>"], maxCards: 20 })
+   ```
+
+4. If needed, get the skeleton to see control flow:
+   ```
+   sdl.code.getSkeleton({ repoId: "{{REPO_ID}}", symbolId: "<id>" })
+   ```
+
+5. Only if the bug requires seeing exact implementation:
+   ```
+   sdl.code.needWindow({
+     repoId: "{{REPO_ID}}",
+     symbolId: "<id>",
+     reason: "Need to see exact error condition logic",
+     expectedIdentifiers: ["errorCode", "throwError"]
+   })
+   ```
+
+#### Feature Implementation
+
+1. Search for similar existing features:
+   ```
+   sdl.symbol.search({ repoId: "{{REPO_ID}}", query: "create", kinds: ["function"] })
+   ```
+
+2. Get cards for relevant symbols to understand patterns:
+   ```
+   sdl.symbol.getCard({ repoId: "{{REPO_ID}}", symbolId: "<id>" })
+   ```
+
+3. Build a slice from the entry point:
+   ```
+   sdl.slice.build({ repoId: "{{REPO_ID}}", entrySymbols: ["<entry-id>"], maxCards: 50 })
+   ```
+
+4. Use skeletons to understand structure without full code:
+   ```
+   sdl.code.getSkeleton({ repoId: "{{REPO_ID}}", symbolId: "<id>" })
+   ```
+
+#### Code Review
+
+1. Get the delta pack to see what changed:
+   ```
+   sdl.delta.get({ repoId: "{{REPO_ID}}" })
+   ```
+
+2. For each changed symbol, get its card:
+   ```
+   sdl.symbol.getCard({ repoId: "{{REPO_ID}}", symbolId: "<changed-id>" })
+   ```
+
+3. Check blast radius for impact:
+   ```
+   sdl.delta.get({ repoId: "{{REPO_ID}}", includeBlastRadius: true })
+   ```
+
+### Refreshing the Index
+
+If you've made changes and need to update the symbol database:
+
+```
+sdl.index.refresh({ repoId: "{{REPO_ID}}", mode: "incremental" })
+```
+
+### Getting Help
+
+- Check repository status: `sdl.repo.status({ repoId: "{{REPO_ID}}" })`
+- View current policy: `sdl.policy.get({ repoId: "{{REPO_ID}}" })`