sourcebook 0.5.2 → 0.6.0

package/README.md

@@ -64,6 +64,7 @@ npx sourcebook init --budget 1000
 | `sourcebook init` | Analyze codebase and generate context files |
 | `sourcebook update` | Re-analyze while preserving sections you added manually |
 | `sourcebook diff` | Show what would change without writing files (exit code 1 if changes found — useful for CI) |
+| `sourcebook serve` | Start an MCP server exposing live codebase intelligence (Pro) |
 
 ### Options
 
@@ -144,6 +145,59 @@ Then applies a **discoverability filter**: for every finding, asks "can an agent
 
 Output is formatted for **context-rot resistance** — critical constraints go at the top and bottom of the file (where LLMs pay the most attention), lightweight reference info goes in the middle.
 
+## MCP Server Mode
+
+> **Pro feature** — requires a sourcebook Pro license.
+
+`sourcebook serve` starts a local MCP (Model Context Protocol) server that exposes live codebase intelligence to any MCP-compatible AI client — Claude Desktop, Cursor, and others.
+
+Instead of a static context file, your AI agent can query your project's architecture on demand: look up blast radius before editing, check conventions before writing code, mine git history for anti-patterns.
+
+### Setup
+
+**Claude Desktop** — add to `~/Library/Application Support/Claude/claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "sourcebook": {
+      "command": "npx",
+      "args": ["sourcebook", "serve", "--dir", "/path/to/your/project"]
+    }
+  }
+}
+```
+
+**Cursor** — add to `.cursor/mcp.json` in your project or `~/.cursor/mcp.json` globally:
+
+```json
+{
+  "mcpServers": {
+    "sourcebook": {
+      "command": "npx",
+      "args": ["sourcebook", "serve", "--dir", "/path/to/your/project"]
+    }
+  }
+}
+```
+
+Restart your client after updating the config.
+
+### Available Tools
+
+| Tool | What it does |
+|------|-------------|
+| `analyze_codebase` | Full analysis: languages, frameworks, findings, top files by PageRank importance |
+| `get_file_context` | File-level context: importance score, hub status, co-change partners, applicable conventions |
+| `get_blast_radius` | Risk assessment for editing a file: dependents, co-change coupling, fragility, circular deps |
+| `query_conventions` | All detected project conventions: import style, error handling, naming, commit format |
+| `get_import_graph` | Dependency architecture: hub files, circular deps, dead code, PageRank rankings |
+| `get_git_insights` | Git history mining: fragile files, reverted commits, anti-patterns, active dev areas |
+| `get_pressing_questions` | Pre-edit briefing: everything important to know before touching a specific file |
+| `search_codebase_context` | Keyword search across all findings, conventions, structure, and frameworks |
+
+The server caches the scan in memory — subsequent tool calls are fast. Pass `refresh: true` to `analyze_codebase` to force a re-scan.
+
 ## Roadmap
 
 - [x] `.cursor/rules/sourcebook.mdc` + legacy `.cursorrules` output
@@ -155,9 +209,9 @@ Output is formatted for **context-rot resistance** — critical constraints go a
 - [x] Python support (Django, FastAPI, Flask, pytest)
 - [x] Go support (Gin, Echo, Fiber, module layout)
 - [x] GitHub Action for CI
+- [x] `sourcebook serve` — MCP server mode
 - [ ] Framework knowledge packs (community-contributed)
 - [ ] Tree-sitter AST parsing for deeper convention detection
-- [ ] `sourcebook serve` — MCP server mode
 - [ ] Hosted dashboard with context quality scores
 
 ## Research Foundation

package/dist/cli.js

@@ -4,6 +4,7 @@ import { init } from "./commands/init.js";
 import { update } from "./commands/update.js";
 import { diff } from "./commands/diff.js";
 import { activate } from "./commands/activate.js";
+import { serve } from "./commands/serve.js";
 const program = new Command();
 program
     .name("sourcebook")
@@ -35,4 +36,9 @@ program
     .command("activate <key>")
     .description("Activate a Pro or Team license key")
     .action(activate);
+program
+    .command("serve")
+    .description("Start an MCP server over STDIO for AI tool integration")
+    .option("-d, --dir <path>", "Target directory to analyze", ".")
+    .action(serve);
 program.parse();

package/dist/commands/serve.d.ts

@@ -0,0 +1,5 @@
+interface ServeOptions {
+    dir: string;
+}
+export declare function serve(options: ServeOptions): Promise<void>;
+export {};

package/dist/commands/serve.js

@@ -0,0 +1,556 @@
+import { Server } from "@modelcontextprotocol/sdk/server";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio";
+import { CallToolRequestSchema, ListToolsRequestSchema, } from "@modelcontextprotocol/sdk/types";
+import path from "node:path";
+import { requirePro } from "../auth/license.js";
+import { scanProject } from "../scanner/index.js";
+import { analyzeImportGraph } from "../scanner/graph.js";
+// Cache the scan to avoid re-running on every tool call
+let cachedScan = null;
+let cachedDir = null;
+async function getScan(dir) {
+    const resolved = path.resolve(dir);
+    if (cachedScan && cachedDir === resolved) {
+        return cachedScan;
+    }
+    cachedScan = await scanProject(resolved);
+    cachedDir = resolved;
+    return cachedScan;
+}
+function invalidateCache() {
+    cachedScan = null;
+    cachedDir = null;
+}
+const TOOLS = [
+    {
+        name: "analyze_codebase",
+        description: "Run a full sourcebook analysis on the codebase. Returns the complete ProjectScan including detected languages, frameworks, build commands, project structure, architectural findings, file importance rankings, and repo mode. Use this for a comprehensive overview before making changes.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                refresh: {
+                    type: "boolean",
+                    description: "Force a fresh scan instead of using cached results. Default: false.",
+                },
+            },
+        },
+    },
+    {
+        name: "get_file_context",
+        description: "Get context for a specific file: its importance score (PageRank), what imports it, what it imports, which conventions apply to it, and whether it appears in co-change clusters. Use this before editing a file to understand its role and impact.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                file: {
+                    type: "string",
+                    description: "Relative file path from the project root (e.g. 'src/utils/auth.ts').",
+                },
+            },
+            required: ["file"],
+        },
+    },
+    {
+        name: "get_blast_radius",
+        description: "Determine what could break if you edit a given file. Returns direct dependents (files that import it), co-change partners (files historically modified together), and whether the file is a hub module. Use this to assess risk before modifying critical code.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                file: {
+                    type: "string",
+                    description: "Relative file path from the project root (e.g. 'src/lib/db.ts').",
+                },
+            },
+            required: ["file"],
+        },
+    },
+    {
+        name: "query_conventions",
+        description: "Return all detected conventions and patterns in the codebase: import styles, error handling, naming conventions, framework-specific patterns, and commit conventions. Use this to ensure new code follows established project patterns.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                category: {
+                    type: "string",
+                    description: "Optional filter by category (e.g. 'Import conventions', 'Error handling', 'Commit conventions'). Returns all conventions if omitted.",
+                },
+            },
+        },
+    },
+    {
+        name: "get_import_graph",
+        description: "Get import relationship data: hub files (most depended-on), circular dependencies, dead code candidates, and file importance rankings from PageRank analysis. Use this to understand the dependency architecture.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                file: {
+                    type: "string",
+                    description: "Optional file path to focus on. If provided, returns only edges involving this file. If omitted, returns the full graph summary.",
+                },
+            },
+        },
+    },
+    {
+        name: "get_git_insights",
+        description: "Get insights mined from git history: fragile files (high churn), reverted commits (failed approaches to avoid), active development areas, co-change coupling (invisible dependencies), and commit conventions. Use this to avoid repeating past mistakes.",
+        inputSchema: {
+            type: "object",
+            properties: {},
+        },
+    },
+    {
+        name: "get_pressing_questions",
+        description: "Get the most important things to know before editing a specific file or area of the codebase. Combines blast radius, conventions, git history, and structural context into prioritized guidance. This is the 'what should I know?' briefing.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                file: {
+                    type: "string",
+                    description: "Relative file path you're about to edit (e.g. 'src/api/routes.ts').",
+                },
+            },
+            required: ["file"],
+        },
+    },
+    {
+        name: "search_codebase_context",
+        description: "Search across all analyzed context (findings, conventions, structure, frameworks) by keyword. Returns matching findings with their category, confidence, and rationale. Use this when looking for specific architectural knowledge.",
+        inputSchema: {
+            type: "object",
+            properties: {
+                query: {
+                    type: "string",
+                    description: "Keyword or phrase to search for across all findings and context (e.g. 'authentication', 'circular', 'migration').",
+                },
+            },
+            required: ["query"],
+        },
+    },
+];
+// --- Tool Handlers ---
+async function handleAnalyzeCodebase(dir, args) {
+    if (args.refresh)
+        invalidateCache();
+    const scan = await getScan(dir);
+    return {
+        dir: scan.dir,
+        languages: scan.languages,
+        frameworks: scan.frameworks,
+        repoMode: scan.repoMode,
+        commands: scan.commands,
+        structure: {
+            layout: scan.structure.layout,
+            entryPoints: scan.structure.entryPoints,
+            directories: scan.structure.directories,
+        },
+        fileCount: scan.files.length,
+        findingCount: scan.findings.length,
+        findings: scan.findings.map((f) => ({
+            category: f.category,
+            description: f.description,
+            rationale: f.rationale,
+            confidence: f.confidence,
+        })),
+        topFiles: (scan.rankedFiles || []).slice(0, 15).map((f) => ({
+            file: f.file,
+            score: Math.round(f.score * 10000) / 10000,
+        })),
+    };
+}
+async function handleGetFileContext(dir, args) {
+    const scan = await getScan(dir);
+    const file = args.file;
+    // Find importance score
+    const ranked = scan.rankedFiles || [];
+    const fileRank = ranked.find((r) => r.file === file);
+    const rank = ranked.findIndex((r) => r.file === file);
+    // Find findings mentioning this file
+    const relevantFindings = scan.findings.filter((f) => f.evidence?.includes(file) ||
+        f.description.includes(file) ||
+        f.description.includes(path.basename(file)));
+    // Get conventions that apply (category-based)
+    const conventionCategories = new Set([
+        "Import conventions",
+        "Error handling",
+        "TypeScript",
+        "TypeScript imports",
+        "Commit conventions",
+    ]);
+    const conventions = scan.findings.filter((f) => conventionCategories.has(f.category));
+    // Check if it's a hub file
+    const hubFinding = scan.findings.find((f) => f.category === "Core modules" && f.description.includes(file));
+    // Check co-change clusters
+    const coChangeFinding = scan.findings.find((f) => f.category === "Hidden dependencies" &&
+        (f.description.includes(path.basename(file)) ||
+            f.description.includes(file)));
+    return {
+        file,
+        exists: scan.files.includes(file),
+        importance: fileRank
+            ? {
+                score: Math.round(fileRank.score * 10000) / 10000,
+                rank: rank + 1,
+                totalFiles: ranked.length,
+            }
+            : null,
+        isHub: !!hubFinding,
+        hubDetail: hubFinding?.description || null,
+        coChangePartners: coChangeFinding?.description || null,
+        relevantFindings: relevantFindings.map((f) => ({
+            category: f.category,
+            description: f.description,
+            confidence: f.confidence,
+        })),
+        applicableConventions: conventions.map((f) => ({
+            category: f.category,
+            description: f.description,
+        })),
+    };
+}
+async function handleGetBlastRadius(dir, args) {
+    const scan = await getScan(dir);
+    const file = args.file;
+    // Re-run import graph to get edge-level data
+    const graphAnalysis = await analyzeImportGraph(path.resolve(dir), scan.files);
+    // Find files that import this file (dependents)
+    // We need to look at the graph findings for hub info
+    const hubFinding = scan.findings.find((f) => f.category === "Core modules" && f.description.includes(file));
+    // Co-change partners from git analysis
+    const coChangeFinding = scan.findings.find((f) => f.category === "Hidden dependencies" &&
+        (f.description.includes(path.basename(file)) ||
+            f.description.includes(file)));
+    // Fragile code mentions
+    const fragileFinding = scan.findings.find((f) => f.category === "Fragile code" && f.description.includes(file));
+    // Circular dependency involvement
+    const circularFinding = scan.findings.find((f) => f.category === "Circular dependencies" &&
+        f.description.includes(path.basename(file)));
+    // Importance rank
+    const ranked = scan.rankedFiles || [];
+    const fileRank = ranked.find((r) => r.file === file);
+    return {
+        file,
+        importance: fileRank
+            ? Math.round(fileRank.score * 10000) / 10000
+            : null,
+        isHub: !!hubFinding,
+        hubDetail: hubFinding?.description || null,
+        coChangePartners: coChangeFinding?.description || null,
+        isFragile: !!fragileFinding,
+        fragileDetail: fragileFinding?.description || null,
+        inCircularDep: !!circularFinding,
+        circularDetail: circularFinding?.description || null,
+        graphFindings: graphAnalysis.findings.map((f) => ({
+            category: f.category,
+            description: f.description,
+            confidence: f.confidence,
+        })),
+        riskLevel: hubFinding
+            ? "high"
+            : circularFinding || fragileFinding
+                ? "medium"
+                : "low",
+    };
+}
+async function handleQueryConventions(dir, args) {
+    const scan = await getScan(dir);
+    // Convention-related categories
+    const conventionCategories = new Set([
+        "Import conventions",
+        "Error handling",
+        "TypeScript",
+        "TypeScript imports",
+        "Commit conventions",
+        "Tailwind",
+        "Next.js routing",
+        "Next.js deployment",
+        "Next.js images",
+        "Expo routing",
+        "Expo builds",
+        "Expo deep linking",
+        "Supabase",
+        "Django",
+        "FastAPI",
+        "Go module",
+        "Go layout",
+        "Go visibility",
+        "Testing",
+        "Python environment",
+        "Dominant patterns",
+    ]);
+    let conventions = scan.findings.filter((f) => conventionCategories.has(f.category) ||
+        f.category.includes("convention") ||
+        f.category.includes("pattern"));
+    if (args.category) {
+        const cat = args.category.toLowerCase();
+        conventions = conventions.filter((f) => f.category.toLowerCase().includes(cat));
+    }
+    return {
+        conventions: conventions.map((f) => ({
+            category: f.category,
+            description: f.description,
+            rationale: f.rationale,
+            confidence: f.confidence,
+        })),
+        frameworks: scan.frameworks,
+        repoMode: scan.repoMode,
+    };
+}
+async function handleGetImportGraph(dir, args) {
+    const scan = await getScan(dir);
+    const graphFindings = scan.findings.filter((f) => ["Core modules", "Circular dependencies", "Dead code candidates"].includes(f.category));
+    const ranked = scan.rankedFiles || [];
+    if (args.file) {
+        const fileRank = ranked.find((r) => r.file === args.file);
+        const rank = ranked.findIndex((r) => r.file === args.file);
+        return {
+            file: args.file,
+            importance: fileRank
+                ? {
+                    score: Math.round(fileRank.score * 10000) / 10000,
+                    rank: rank + 1,
+                    totalFiles: ranked.length,
+                }
+                : null,
+            graphFindings: graphFindings
+                .filter((f) => f.description.includes(args.file) ||
+                f.description.includes(path.basename(args.file)))
+                .map((f) => ({
+                category: f.category,
+                description: f.description,
+                confidence: f.confidence,
+            })),
+        };
+    }
+    return {
+        topFiles: ranked.slice(0, 20).map((f) => ({
+            file: f.file,
+            score: Math.round(f.score * 10000) / 10000,
+        })),
+        findings: graphFindings.map((f) => ({
+            category: f.category,
+            description: f.description,
+            confidence: f.confidence,
+        })),
+    };
+}
+async function handleGetGitInsights(dir) {
+    const scan = await getScan(dir);
+    const gitCategories = new Set([
+        "Git history",
+        "Anti-patterns",
+        "Active development",
+        "Hidden dependencies",
+        "Fragile code",
+        "Commit conventions",
+    ]);
+    const gitFindings = scan.findings.filter((f) => gitCategories.has(f.category));
+    return {
+        findings: gitFindings.map((f) => ({
+            category: f.category,
+            description: f.description,
+            rationale: f.rationale,
+            confidence: f.confidence,
+        })),
+    };
+}
+async function handleGetPressingQuestions(dir, args) {
+    const scan = await getScan(dir);
+    const file = args.file;
+    const basename = path.basename(file);
+    const questions = [];
+    // Check if it's a hub file
+    const hubFinding = scan.findings.find((f) => f.category === "Core modules" && f.description.includes(file));
+    if (hubFinding) {
+        questions.push({
+            priority: 1,
+            question: "This is a hub file with wide blast radius",
+            detail: hubFinding.description,
+        });
+    }
+    // Check circular dependencies
+    const circularFinding = scan.findings.find((f) => f.category === "Circular dependencies" &&
+        f.description.includes(basename));
+    if (circularFinding) {
+        questions.push({
+            priority: 2,
+            question: "This file is involved in a circular dependency",
+            detail: circularFinding.description,
+        });
+    }
+    // Check fragile code
+    const fragileFinding = scan.findings.find((f) => f.category === "Fragile code" && f.description.includes(file));
+    if (fragileFinding) {
+        questions.push({
+            priority: 3,
+            question: "This file has high recent churn (hard to get right)",
+            detail: fragileFinding.description,
+        });
+    }
+    // Check co-change coupling
+    const coChangeFinding = scan.findings.find((f) => f.category === "Hidden dependencies" &&
+        (f.description.includes(basename) || f.description.includes(file)));
+    if (coChangeFinding) {
+        questions.push({
+            priority: 4,
+            question: "This file has hidden dependencies (co-change partners)",
+            detail: coChangeFinding.description,
+        });
+    }
+    // Check anti-patterns
+    const antiPatterns = scan.findings.filter((f) => f.category === "Anti-patterns");
+    if (antiPatterns.length > 0) {
+        questions.push({
+            priority: 5,
+            question: "There are known anti-patterns in this project",
+            detail: antiPatterns.map((f) => f.description).join("; "),
+        });
+    }
+    // Applicable conventions
+    const conventions = scan.findings.filter((f) => f.category.includes("convention") ||
+        f.category.includes("Convention") ||
+        f.category.includes("Import") ||
+        f.category.includes("TypeScript") ||
+        f.category.includes("pattern") ||
+        f.category.includes("Pattern"));
+    if (conventions.length > 0) {
+        questions.push({
+            priority: 6,
+            question: "Follow these project conventions",
+            detail: conventions.map((f) => f.description).join("; "),
+        });
+    }
+    // Active development area?
+    const activeFinding = scan.findings.find((f) => f.category === "Active development" &&
+        f.description.includes(file.split("/")[0]));
+    if (activeFinding) {
+        questions.push({
+            priority: 7,
+            question: "This area is under active development",
+            detail: activeFinding.description,
+        });
+    }
+    questions.sort((a, b) => a.priority - b.priority);
+    return {
+        file,
+        questions,
+        summary: questions.length > 0
+            ? `${questions.length} things to know before editing ${file}`
+            : `No special concerns found for ${file}`,
+    };
+}
+async function handleSearchCodebaseContext(dir, args) {
+    const scan = await getScan(dir);
+    const query = args.query.toLowerCase();
+    const matches = scan.findings.filter((f) => f.description.toLowerCase().includes(query) ||
+        f.category.toLowerCase().includes(query) ||
+        (f.rationale && f.rationale.toLowerCase().includes(query)) ||
+        (f.evidence && f.evidence.toLowerCase().includes(query)));
+    // Also search structure
+    const structureMatches = [];
+    for (const [dir, purpose] of Object.entries(scan.structure.directories)) {
+        if (dir.toLowerCase().includes(query) ||
+            purpose.toLowerCase().includes(query)) {
+            structureMatches.push({ key: dir, value: purpose });
+        }
+    }
+    // Search frameworks
+    const frameworkMatches = scan.frameworks.filter((f) => f.toLowerCase().includes(query));
+    return {
+        query: args.query,
+        findings: matches.map((f) => ({
+            category: f.category,
+            description: f.description,
+            rationale: f.rationale,
+            confidence: f.confidence,
+        })),
+        structureMatches,
+        frameworkMatches,
+        totalResults: matches.length + structureMatches.length + frameworkMatches.length,
+    };
+}
+// --- Main ---
+export async function serve(options) {
+    await requirePro("sourcebook serve");
+    const dir = path.resolve(options.dir);
+    // Suppress all console output — STDIO transport uses stdout for JSON-RPC
+    const originalLog = console.log;
+    const originalError = console.error;
+    console.log = () => { };
+    console.error = () => { };
+    const server = new Server({
+        name: "sourcebook",
+        version: "0.6.0",
+    }, {
+        capabilities: {
+            tools: {},
+        },
+    });
+    server.setRequestHandler(ListToolsRequestSchema, async () => ({
+        tools: TOOLS,
+    }));
+    server.setRequestHandler(CallToolRequestSchema, async (request) => {
+        const { name, arguments: args } = request.params;
+        try {
+            let result;
+            switch (name) {
+                case "analyze_codebase":
+                    result = await handleAnalyzeCodebase(dir, args);
+                    break;
+                case "get_file_context":
+                    result = await handleGetFileContext(dir, args);
+                    break;
+                case "get_blast_radius":
+                    result = await handleGetBlastRadius(dir, args);
+                    break;
+                case "query_conventions":
+                    result = await handleQueryConventions(dir, args);
+                    break;
+                case "get_import_graph":
+                    result = await handleGetImportGraph(dir, args);
+                    break;
+                case "get_git_insights":
+                    result = await handleGetGitInsights(dir);
+                    break;
+                case "get_pressing_questions":
+                    result = await handleGetPressingQuestions(dir, args);
+                    break;
+                case "search_codebase_context":
+                    result = await handleSearchCodebaseContext(dir, args);
+                    break;
+                default:
+                    return {
+                        content: [
+                            {
+                                type: "text",
+                                text: JSON.stringify({ error: `Unknown tool: ${name}` }),
+                            },
+                        ],
+                        isError: true,
+                    };
+            }
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: JSON.stringify(result, null, 2),
+                    },
+                ],
+            };
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            return {
+                content: [
+                    {
+                        type: "text",
+                        text: JSON.stringify({ error: message }),
+                    },
+                ],
+                isError: true,
+            };
+        }
+    });
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    // Restore console for cleanup messages on stderr
+    console.error = originalError;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "sourcebook",
-  "version": "0.5.2",
+  "version": "0.6.0",
   "description": "Extract the conventions, constraints, and architectural truths your AI coding agents keep missing.",
   "type": "module",
   "bin": {
@@ -41,14 +41,15 @@
     "LICENSE"
   ],
   "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.29.0",
+    "chalk": "^5.4.0",
     "commander": "^13.0.0",
-    "glob": "^11.0.0",
-    "chalk": "^5.4.0"
+    "glob": "^11.0.0"
   },
   "devDependencies": {
-    "typescript": "^5.7.0",
+    "@types/node": "^22.0.0",
     "tsx": "^4.19.0",
-    "vitest": "^3.0.0",
-    "@types/node": "^22.0.0"
+    "typescript": "^5.7.0",
+    "vitest": "^3.0.0"
   }
 }