@toolbaux/guardian 0.1.10 → 0.1.12

package/README.md

@@ -79,6 +79,58 @@ Guardian auto-injects architecture context into `CLAUDE.md` so your AI tool read
 
 The block between markers is replaced on every save (VSCode extension) and every commit (pre-commit hook). Your manual content outside the markers is never touched.
 
+## MCP Server — AI Tools Connect Directly
+
+Guardian includes an MCP server that Claude Code and Cursor connect to automatically. The VSCode extension sets this up on first activation — no manual config needed.
+
+**6 compact tools available to AI:**
+
+| Tool | Tokens | Purpose |
+|------|--------|---------|
+| `guardian_orient` | ~100 | Project summary at session start |
+| `guardian_context` | ~50-80 | File or endpoint dependencies before editing |
+| `guardian_impact` | ~30 | What breaks if you change a file |
+| `guardian_search` | ~70 | Find endpoints, models, modules by keyword |
+| `guardian_model` | ~90 | Full field details (only when needed) |
+| `guardian_metrics` | ~50 | Session usage stats |
+
+All responses are compact JSON — no pretty-printing, no verbose keys. Repeated calls are cached (30s TTL). Usage metrics tracked per session.
+
+**Manual setup** (if the extension doesn't auto-configure):
+
+Create `.mcp.json` at your project root:
+```json
+{
+  "mcpServers": {
+    "guardian": {
+      "command": "guardian",
+      "args": ["mcp-serve", "--specs", ".specs"]
+    }
+  }
+}
+```
+
+## VSCode Extension
+
+Install from [VS Code Marketplace](https://marketplace.visualstudio.com/items?itemName=toolbaux.toolbaux-guardian):
+
+Search "ToolBaux Guardian" in Extensions, or:
+```
+Cmd+Shift+P → "Extensions: Install from VSIX"
+```
+
+**What it does automatically:**
+- Creates `.specs/`, config, and pre-commit hook on first activation
+- Configures MCP server for Claude Code and Cursor (`.mcp.json`)
+- Extracts architecture on every file save (5s debounce)
+- Shows drift status in status bar: `✓ Guardian: stable · 35 ep · 8 pg`
+
+**Commands** (Cmd+Shift+P):
+- Guardian: Initialize Project
+- Guardian: Generate AI Context
+- Guardian: Drift Check
+- Guardian: Generate Constraints
+
 ## Key Commands
 
 ```bash

package/dist/commands/mcp-serve.js

@@ -17,6 +17,65 @@
 import fs from "node:fs/promises";
 import path from "node:path";
 import readline from "node:readline";
+const metrics = {
+    session_start: Date.now(),
+    calls: [],
+    intel_reloads: 0,
+    cache_hits: 0,
+    record(tool, args, responseText, cacheHit) {
+        const chars = responseText.length;
+        const estimatedTokens = Math.ceil(chars / 3.5); // rough token estimate
+        this.calls.push({
+            tool,
+            args,
+            timestamp: Date.now(),
+            response_chars: chars,
+            estimated_tokens: estimatedTokens,
+            cache_hit: cacheHit,
+        });
+        if (cacheHit)
+            this.cache_hits++;
+    },
+    summary() {
+        const duration = Math.round((Date.now() - this.session_start) / 1000);
+        const totalCalls = this.calls.length;
+        const totalTokensSpent = this.calls.reduce((s, c) => s + c.estimated_tokens, 0);
+        // Estimate tokens saved: each guardian call replaces ~3 Read/Grep calls (~400 tokens each)
+        const estimatedTokensSaved = totalCalls * 400 - totalTokensSpent;
+        const toolBreakdown = {};
+        for (const c of this.calls) {
+            if (!toolBreakdown[c.tool])
+                toolBreakdown[c.tool] = { calls: 0, tokens: 0 };
+            toolBreakdown[c.tool].calls++;
+            toolBreakdown[c.tool].tokens += c.estimated_tokens;
+        }
+        return {
+            session_duration_seconds: duration,
+            total_mcp_calls: totalCalls,
+            total_tokens_spent: totalTokensSpent,
+            estimated_tokens_saved: Math.max(0, estimatedTokensSaved),
+            savings_ratio: totalCalls > 0
+                ? `${Math.round((estimatedTokensSaved / (totalCalls * 400)) * 100)}%`
+                : "n/a",
+            cache_hits: this.cache_hits,
+            intel_reloads: this.intel_reloads,
+            tool_breakdown: toolBreakdown,
+            avg_tokens_per_call: totalCalls > 0 ? Math.round(totalTokensSpent / totalCalls) : 0,
+        };
+    },
+};
+// ── Response cache (dedup repeated queries) ──
+const responseCache = new Map();
+const CACHE_TTL = 30_000; // 30s cache
+function getCached(key) {
+    const entry = responseCache.get(key);
+    if (entry && Date.now() - entry.time < CACHE_TTL)
+        return entry.text;
+    return null;
+}
+function setCache(key, text) {
+    responseCache.set(key, { text, time: Date.now() });
+}
 // ── Intelligence loader ──
 let intel = null;
 let intelPath = "";
@@ -39,199 +98,181 @@ async function loadIntel() {
     }
     return intel;
 }
-// ── Tool implementations ──
-async function fileContext(args) {
-    const data = await loadIntel();
-    const file = args.file.replace(/^\.\//, "");
-    // Find which module this file belongs to
-    const module = data.service_map?.find((m) => m.path && file.startsWith(m.path.replace(/^\.\//, "")));
-    // Find endpoints in this file
-    const endpoints = Object.values(data.api_registry || {}).filter((ep) => ep.file && file.includes(ep.file.replace(/^\.\//, "")));
-    // Find models in this file
-    const models = Object.values(data.model_registry || {}).filter((m) => m.file && file.includes(m.file.replace(/^\.\//, "")));
-    // Find which endpoints call services defined in this file
-    const calledBy = [];
+// ── Helpers ──
+const SKIP_SERVICES = new Set(["str", "dict", "int", "len", "float", "max", "join", "getattr", "lower", "open", "params.append", "updates.append"]);
+function compact(obj) {
+    return JSON.stringify(obj);
+}
+function findModule(data, file) {
+    return data.service_map?.find((m) => m.path && file.replace(/^\.\//, "").startsWith(m.path.replace(/^\.\//, "")));
+}
+function findEndpointsInFile(data, file) {
+    const f = file.replace(/^\.\//, "");
+    return Object.values(data.api_registry || {}).filter((ep) => ep.file && f.includes(ep.file.replace(/^\.\//, "")));
+}
+function findModelsInFile(data, file) {
+    const f = file.replace(/^\.\//, "");
+    return Object.values(data.model_registry || {}).filter((m) => m.file && f.includes(m.file.replace(/^\.\//, "")));
+}
+// ── Tool implementations (compact JSON, no redundancy) ──
+async function orient() {
+    const d = await loadIntel();
+    const c = d.meta?.counts || {};
+    const mods = (d.service_map || []).filter((m) => m.file_count > 0);
+    const topMods = mods.sort((a, b) => (b.endpoint_count || 0) - (a.endpoint_count || 0)).slice(0, 6);
+    return compact({
+        p: d.meta?.project,
+        ep: c.endpoints, mod: c.models, pg: c.pages, m: c.modules,
+        top: topMods.map((m) => [m.id, m.endpoint_count, m.layer]),
+        pages: (d.frontend_pages || []).map((p) => p.path),
+    });
+}
+async function context(args) {
+    const d = await loadIntel();
+    const t = args.target;
+    // Check if target is an endpoint (e.g. "POST /sessions/start")
+    const epMatch = t.match(/^(GET|POST|PUT|DELETE|PATCH)\s+(.+)$/i);
+    if (epMatch) {
+        const ep = d.api_registry?.[`${epMatch[1].toUpperCase()} ${epMatch[2]}`]
+            || Object.values(d.api_registry || {}).find((e) => e.method === epMatch[1].toUpperCase() && e.path === epMatch[2]);
+        if (!ep)
+            return compact({ err: "not found" });
+        const svcs = (ep.service_calls || []).filter((s) => !SKIP_SERVICES.has(s));
+        return compact({
+            ep: `${ep.method} ${ep.path}`, h: ep.handler, f: ep.file, m: ep.module,
+            req: ep.request_schema, res: ep.response_schema,
+            calls: svcs, ai: ep.ai_operations?.length || 0,
+        });
+    }
+    // Otherwise treat as file path
+    const file = t.replace(/^\.\//, "");
+    const mod = findModule(d, file);
+    const eps = findEndpointsInFile(d, file);
+    const models = findModelsInFile(d, file);
     const fileName = path.basename(file, path.extname(file));
-    for (const [key, ep] of Object.entries(data.api_registry || {})) {
-        const e = ep;
-        if (e.service_calls?.some((s) => s.toLowerCase().includes(fileName.toLowerCase()))) {
-            calledBy.push(`${e.method} ${e.path} (${e.handler})`);
+    const calledBy = [];
+    for (const ep of Object.values(d.api_registry || {})) {
+        if (ep.service_calls?.some((s) => s.toLowerCase().includes(fileName.toLowerCase()))) {
+            calledBy.push(`${ep.method} ${ep.path}`);
         }
     }
-    // Find what this file's endpoints call
-    const calls = endpoints.flatMap((ep) => (ep.service_calls || []).filter((s) => !["str", "dict", "int", "len", "float", "max", "join", "getattr"].includes(s)));
-    // Find frontend pages that use APIs from this module
-    const pages = (data.frontend_pages || []).filter((p) => p.api_calls?.some((call) => endpoints.some((ep) => call.includes(ep.path?.split("{")[0]))));
-    return JSON.stringify({
-        file,
-        module: module ? { id: module.id, layer: module.layer, file_count: module.file_count, imports: module.imports } : null,
-        endpoints_in_file: endpoints.map((ep) => `${ep.method} ${ep.path} → ${ep.handler}`),
-        models_in_file: models.map((m) => `${m.name} (${m.framework}, ${m.fields?.length || 0} fields)`),
-        calls_downstream: [...new Set(calls)],
-        called_by_upstream: calledBy.slice(0, 10),
-        frontend_pages_using: pages.map((p) => p.path),
-        coupling: module?.coupling_score ?? null,
-    }, null, 2);
+    const calls = eps.flatMap((ep) => (ep.service_calls || []).filter((s) => !SKIP_SERVICES.has(s)));
+    return compact({
+        f: file,
+        mod: mod ? [mod.id, mod.layer] : null,
+        ep: eps.map((e) => `${e.method} ${e.path}`),
+        models: models.map((m) => [m.name, m.fields?.length || 0]),
+        calls: [...new Set(calls)],
+        calledBy: calledBy.slice(0, 8),
+    });
+}
+async function impact(args) {
+    const d = await loadIntel();
+    const file = args.target.replace(/^\.\//, "");
+    const eps = findEndpointsInFile(d, file);
+    const models = findModelsInFile(d, file);
+    const modelNames = new Set(models.map((m) => m.name));
+    const affectedEps = Object.values(d.api_registry || {}).filter((ep) => (ep.request_schema && modelNames.has(ep.request_schema)) ||
+        (ep.response_schema && modelNames.has(ep.response_schema)));
+    const mod = findModule(d, file);
+    const depMods = mod ? (d.service_map || []).filter((m) => m.imports?.includes(mod.id)) : [];
+    const affectedPages = (d.frontend_pages || []).filter((p) => p.api_calls?.some((call) => eps.some((ep) => call.includes(ep.path?.split("{")[0]))));
+    const total = eps.length + affectedEps.length + depMods.length + affectedPages.length;
+    return compact({
+        f: file,
+        risk: total > 5 ? "HIGH" : total > 2 ? "MED" : "LOW",
+        ep: eps.map((e) => `${e.method} ${e.path}`),
+        models: models.map((m) => m.name),
+        affectedEp: affectedEps.map((e) => `${e.method} ${e.path}`),
+        depMods: depMods.map((m) => m.id),
+        pages: affectedPages.map((p) => p.path),
+    });
 }
 async function search(args) {
-    const data = await loadIntel();
+    const d = await loadIntel();
     const q = args.query.toLowerCase();
-    const types = (args.types || "models,endpoints,modules").split(",").map((t) => t.trim());
-    const results = {};
-    if (types.includes("endpoints")) {
-        results.endpoints = Object.values(data.api_registry || {})
-            .filter((ep) => ep.path?.toLowerCase().includes(q) ||
-            ep.handler?.toLowerCase().includes(q) ||
-            ep.service_calls?.some((s) => s.toLowerCase().includes(q)))
-            .slice(0, 10)
-            .map((ep) => `${ep.method} ${ep.path} → ${ep.handler} [${ep.module}]`);
-    }
-    if (types.includes("models")) {
-        results.models = Object.values(data.model_registry || {})
-            .filter((m) => m.name?.toLowerCase().includes(q) ||
-            m.fields?.some((f) => f.toLowerCase().includes(q)))
-            .slice(0, 10)
-            .map((m) => `${m.name} (${m.framework}, ${m.fields?.length} fields, ${m.file})`);
-    }
-    if (types.includes("modules")) {
-        results.modules = (data.service_map || [])
-            .filter((m) => m.id?.toLowerCase().includes(q) ||
-            m.path?.toLowerCase().includes(q))
-            .slice(0, 10)
-            .map((m) => `${m.id} (${m.type}, ${m.endpoint_count} eps, ${m.file_count} files, imports: ${m.imports?.join(",") || "none"})`);
-    }
-    return JSON.stringify(results, null, 2);
-}
-async function endpointTrace(args) {
-    const data = await loadIntel();
-    const key = `${args.method.toUpperCase()} ${args.path}`;
-    const ep = data.api_registry?.[key] || Object.values(data.api_registry || {}).find((e) => e.method === args.method.toUpperCase() && e.path === args.path);
-    if (!ep)
-        return JSON.stringify({ error: `Endpoint ${key} not found` });
-    // Find which frontend pages call this endpoint
-    const frontendCallers = (data.frontend_pages || []).filter((p) => p.api_calls?.some((call) => call.includes(args.path.split("{")[0])));
-    // Find what models this endpoint uses
-    const models = Object.values(data.model_registry || {}).filter((m) => ep.request_schema === m.name || ep.response_schema === m.name);
-    return JSON.stringify({
-        endpoint: `${ep.method} ${ep.path}`,
-        handler: ep.handler,
-        file: ep.file,
-        module: ep.module,
-        request_schema: ep.request_schema,
-        response_schema: ep.response_schema,
-        service_calls: ep.service_calls,
-        ai_operations: ep.ai_operations,
-        patterns: ep.patterns,
-        models_used: models.map((m) => ({ name: m.name, fields: m.fields })),
-        frontend_callers: frontendCallers.map((p) => p.path),
-    }, null, 2);
-}
-async function impactCheck(args) {
-    const data = await loadIntel();
-    const file = args.file.replace(/^\.\//, "");
-    // Find all endpoints in this file
-    const endpoints = Object.values(data.api_registry || {}).filter((ep) => ep.file && file.includes(ep.file.replace(/^\.\//, "")));
-    // Find all models in this file
-    const models = Object.values(data.model_registry || {}).filter((m) => m.file && file.includes(m.file.replace(/^\.\//, "")));
-    // Find endpoints that USE these models
-    const modelNames = new Set(models.map((m) => m.name));
-    const affectedEndpoints = Object.values(data.api_registry || {}).filter((ep) => ep.request_schema && modelNames.has(ep.request_schema) ||
-        ep.response_schema && modelNames.has(ep.response_schema));
-    // Find modules that import from this file's module
-    const fileModule = data.service_map?.find((m) => m.path && file.startsWith(m.path.replace(/^\.\//, "")));
-    const dependentModules = fileModule
-        ? (data.service_map || []).filter((m) => m.imports?.includes(fileModule.id))
-        : [];
-    // Find frontend pages affected
-    const affectedPages = (data.frontend_pages || []).filter((p) => p.api_calls?.some((call) => endpoints.some((ep) => call.includes(ep.path?.split("{")[0]))));
-    return JSON.stringify({
-        file,
-        direct_endpoints: endpoints.map((ep) => `${ep.method} ${ep.path}`),
-        models_defined: models.map((m) => m.name),
-        endpoints_using_these_models: affectedEndpoints.map((ep) => `${ep.method} ${ep.path}`),
-        dependent_modules: dependentModules.map((m) => m.id),
-        affected_frontend_pages: affectedPages.map((p) => p.path),
-        risk: endpoints.length + affectedEndpoints.length + dependentModules.length > 5 ? "HIGH" : "LOW",
-    }, null, 2);
+    const eps = Object.values(d.api_registry || {}).filter((ep) => ep.path?.toLowerCase().includes(q) || ep.handler?.toLowerCase().includes(q) ||
+        ep.service_calls?.some((s) => s.toLowerCase().includes(q))).slice(0, 8).map((ep) => `${ep.method} ${ep.path} [${ep.module}]`);
+    const models = Object.values(d.model_registry || {}).filter((m) => m.name?.toLowerCase().includes(q) || m.fields?.some((f) => f.toLowerCase().includes(q))).slice(0, 8).map((m) => `${m.name}:${m.fields?.length}f`);
+    const mods = (d.service_map || []).filter((m) => m.id?.toLowerCase().includes(q)).slice(0, 5).map((m) => `${m.id}:${m.endpoint_count}ep`);
+    return compact({ ep: eps, mod: models, m: mods });
 }
-async function overview() {
-    const data = await loadIntel();
-    return JSON.stringify({
-        project: data.meta?.project,
-        counts: data.meta?.counts,
-        modules: (data.service_map || [])
-            .filter((m) => m.file_count > 0)
-            .map((m) => ({ id: m.id, type: m.type, layer: m.layer, endpoints: m.endpoint_count, files: m.file_count, imports: m.imports })),
-        pages: (data.frontend_pages || []).map((p) => ({ route: p.path, component: p.component })),
-        top_endpoints: Object.values(data.api_registry || {})
-            .sort((a, b) => (b.service_calls?.length || 0) - (a.service_calls?.length || 0))
-            .slice(0, 5)
-            .map((ep) => `${ep.method} ${ep.path} (${ep.service_calls?.length || 0} service calls)`),
-    }, null, 2);
+async function model(args) {
+    const d = await loadIntel();
+    const m = d.model_registry?.[args.name];
+    if (!m)
+        return compact({ err: "not found" });
+    const usedBy = Object.values(d.api_registry || {}).filter((ep) => ep.request_schema === args.name || ep.response_schema === args.name).map((ep) => `${ep.method} ${ep.path}`);
+    return compact({
+        name: m.name, fw: m.framework, f: m.file,
+        fields: m.fields, rels: m.relationships,
+        usedBy,
+    });
 }
 // ── MCP protocol ──
 const TOOLS = [
     {
-        name: "guardian_file_context",
-        description: "Get upstream/downstream dependencies, endpoints, models, and coupling for a file. Call this BEFORE editing any file.",
+        name: "guardian_orient",
+        description: "Compact project summary. Call at session start. Returns: project name, counts, top modules, page routes.",
+        inputSchema: { type: "object", properties: {} },
+    },
+    {
+        name: "guardian_context",
+        description: "Get dependencies for a file or endpoint. Pass a file path (e.g. 'backend/service-conversation/engine.py') or an endpoint (e.g. 'POST /sessions/start').",
         inputSchema: {
             type: "object",
             properties: {
-                file: { type: "string", description: "File path relative to project root (e.g. 'backend/service-conversation/engine.py')" },
+                target: { type: "string", description: "File path or 'METHOD /path' endpoint" },
             },
-            required: ["file"],
+            required: ["target"],
         },
     },
     {
-        name: "guardian_search",
-        description: "Search the codebase for endpoints, models, or modules matching a keyword.",
+        name: "guardian_impact",
+        description: "What breaks if you change this file? Returns affected endpoints, models, modules, pages, and risk level.",
         inputSchema: {
             type: "object",
             properties: {
-                query: { type: "string", description: "Search keyword (e.g. 'session', 'auth', 'TTS')" },
-                types: { type: "string", description: "Comma-separated: models,endpoints,modules (default: all)" },
+                target: { type: "string", description: "File path to check" },
             },
-            required: ["query"],
+            required: ["target"],
         },
     },
     {
-        name: "guardian_endpoint_trace",
-        description: "Trace an API endpoint's full chain: frontend callers, handler, service calls, models, AI operations.",
+        name: "guardian_search",
+        description: "Find endpoints, models, modules by keyword. Returns compact one-line results.",
         inputSchema: {
             type: "object",
             properties: {
-                method: { type: "string", description: "HTTP method (GET, POST, PUT, DELETE)" },
-                path: { type: "string", description: "Endpoint path (e.g. '/sessions/start')" },
+                query: { type: "string", description: "Search keyword" },
             },
-            required: ["method", "path"],
+            required: ["query"],
         },
     },
     {
-        name: "guardian_impact_check",
-        description: "Check what endpoints, models, modules, and pages are affected if you change a file. Call this BEFORE making changes to high-coupling files.",
+        name: "guardian_model",
+        description: "Get full field list and usage for a specific model. Only call when you need field details.",
         inputSchema: {
             type: "object",
             properties: {
-                file: { type: "string", description: "File path to check impact for" },
+                name: { type: "string", description: "Model name (e.g. 'StartSessionRequest')" },
             },
-            required: ["file"],
+            required: ["name"],
         },
     },
     {
-        name: "guardian_overview",
-        description: "Get project summary: modules, pages, top endpoints, counts. Call this at session start for orientation.",
-        inputSchema: {
-            type: "object",
-            properties: {},
-        },
+        name: "guardian_metrics",
+        description: "MCP usage stats for this session. Call at end to evaluate guardian's usefulness.",
+        inputSchema: { type: "object", properties: {} },
     },
 ];
 const TOOL_HANDLERS = {
-    guardian_file_context: fileContext,
+    guardian_orient: orient,
+    guardian_context: context,
+    guardian_impact: impact,
     guardian_search: search,
-    guardian_endpoint_trace: endpointTrace,
-    guardian_impact_check: impactCheck,
-    guardian_overview: overview,
+    guardian_model: model,
+    guardian_metrics: async () => compact(metrics.summary()),
 };
 function respond(id, result) {
     const msg = JSON.stringify({ jsonrpc: "2.0", id, result });
@@ -268,7 +309,17 @@ async function handleRequest(req) {
                 break;
             }
             try {
+                // Check cache first
+                const cacheKey = `${toolName}:${JSON.stringify(toolArgs)}`;
+                const cached = getCached(cacheKey);
+                if (cached) {
+                    metrics.record(toolName, toolArgs, cached, true);
+                    respond(req.id, { content: [{ type: "text", text: cached }] });
+                    break;
+                }
                 const result = await handler(toolArgs);
+                setCache(cacheKey, result);
+                metrics.record(toolName, toolArgs, result, false);
                 respond(req.id, {
                     content: [{ type: "text", text: result }],
                 });
@@ -307,7 +358,18 @@ export async function runMcpServe(options) {
             respondError(null, -32700, `Parse error: ${err.message}`);
         }
     });
-    rl.on("close", () => {
+    rl.on("close", async () => {
+        // Persist session metrics to .specs/machine/mcp-metrics.jsonl
+        const metricsPath = path.join(specsDir, "machine", "mcp-metrics.jsonl");
+        try {
+            const entry = JSON.stringify({
+                ...metrics.summary(),
+                session_end: new Date().toISOString(),
+            });
+            await fs.appendFile(metricsPath, entry + "\n", "utf8");
+            process.stderr.write(`Guardian metrics saved to ${metricsPath}\n`);
+        }
+        catch { }
         process.stderr.write("Guardian MCP server stopped.\n");
         process.exit(0);
     });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@toolbaux/guardian",
-  "version": "0.1.10",
+  "version": "0.1.12",
   "type": "module",
   "description": "Architectural intelligence for codebases. Verify that AI-generated code matches your architectural intent.",
   "keywords": [