@musashishao/agent-kit 1.2.2 → 1.4.0

package/.agent/mcp-gateway/README.md

@@ -0,0 +1,121 @@
+# Agent Kit MCP Gateway
+
+> Live Project Cortex - MCP Server providing real-time project context to AI agents.
+
+## Features
+
+- **get_project_context** - Read AGENTS.md sections
+- **analyze_dependencies** - Query dependency graph
+- **search_code_logic** - Semantic code search
+- **get_impact_zone** - Impact analysis for changes
+- **force_sync** - Refresh all AI data
+
+## Installation
+
+```bash
+cd .agent/mcp-gateway
+npm install
+npm run build
+```
+
+## Usage
+
+### With Claude Desktop
+
+Add to `~/Library/Application Support/Claude/claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "agent-kit": {
+      "command": "node",
+      "args": ["/path/to/.agent/mcp-gateway/dist/index.js"],
+      "env": {
+        "PROJECT_ROOT": "/path/to/your/project"
+      }
+    }
+  }
+}
+```
+
+### With Cursor
+
+Add to `.cursor/mcp.json`:
+
+```json
+{
+  "mcpServers": {
+    "agent-kit": {
+      "command": "node",
+      "args": [".agent/mcp-gateway/dist/index.js"],
+      "env": {
+        "PROJECT_ROOT": "."
+      }
+    }
+  }
+}
+```
+
+### Development
+
+```bash
+# Run in dev mode
+npm run dev
+
+# Build for production
+npm run build
+```
+
+## Environment Variables
+
+| Variable | Description | Default |
+|----------|-------------|---------|
+| `PROJECT_ROOT` | Path to project root | Current directory |
+| `AGENT_KIT_PATH` | Path to Agent Kit installation | Auto-detected |
+
+## Tools Reference
+
+### get_project_context
+
+```json
+{
+  "section": "tech_stack" // or "structure", "conventions", "commands", "all"
+}
+```
+
+### analyze_dependencies
+
+```json
+{
+  "file_path": "src/components/Button.tsx",
+  "direction": "both", // "imports", "imported_by", "both"
+  "depth": 2
+}
+```
+
+### search_code_logic
+
+```json
+{
+  "query": "authentication login",
+  "file_filter": "*.ts",
+  "top_k": 10
+}
+```
+
+### get_impact_zone
+
+```json
+{
+  "file_path": "src/utils/auth.ts",
+  "depth": 3
+}
+```
+
+### force_sync
+
+```json
+{
+  "target": "all" // or "graph", "rag", "agents_md"
+}
+```

package/.agent/mcp-gateway/dist/index.d.ts

@@ -0,0 +1,11 @@
+#!/usr/bin/env node
+/**
+ * Agent Kit MCP Gateway Server
+ *
+ * Provides AI agents with live access to project context, dependency graphs,
+ * and semantic code search with automatic sync capabilities.
+ *
+ * Usage:
+ *   node dist/index.js [--project-root /path/to/project]
+ */
+export {};

package/.agent/mcp-gateway/dist/index.js

@@ -0,0 +1,504 @@
+#!/usr/bin/env node
+/**
+ * Agent Kit MCP Gateway Server
+ *
+ * Provides AI agents with live access to project context, dependency graphs,
+ * and semantic code search with automatic sync capabilities.
+ *
+ * Usage:
+ *   node dist/index.js [--project-root /path/to/project]
+ */
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { z } from "zod";
+import * as fs from "fs";
+import * as path from "path";
+// Import sync modules
+import { IncrementalSyncer, getGlobalDebouncer, TimestampChecker } from "./sync/index.js";
+// Get project root from environment or command line
+const PROJECT_ROOT = process.env.PROJECT_ROOT || process.cwd();
+// Initialize sync components
+const syncer = new IncrementalSyncer(PROJECT_ROOT);
+const debouncer = getGlobalDebouncer(30000); // 30 second cooldown
+const timestampChecker = new TimestampChecker(PROJECT_ROOT);
+// ============================================================================
+// Auto-Sync Helper
+// ============================================================================
+async function autoSyncIfNeeded() {
+    // Check if data is stale
+    const status = timestampChecker.getSyncStatus();
+    if (!status.needsSync) {
+        return { synced: false, message: "Data is fresh" };
+    }
+    // Try to sync with debouncing
+    const result = await debouncer.executeWithDebounce(async () => {
+        return await syncer.syncAll();
+    });
+    if (result.executed) {
+        return { synced: true, message: `Auto-synced ${status.changedFiles} changed files` };
+    }
+    else {
+        return { synced: false, message: result.reason || "Sync skipped" };
+    }
+}
+// ============================================================================
+// Utility Functions
+// ============================================================================
+function readJsonFile(filePath) {
+    try {
+        const fullPath = path.resolve(PROJECT_ROOT, filePath);
+        if (!fs.existsSync(fullPath)) {
+            return null;
+        }
+        return JSON.parse(fs.readFileSync(fullPath, "utf-8"));
+    }
+    catch (error) {
+        return null;
+    }
+}
+function readTextFile(filePath) {
+    try {
+        const fullPath = path.resolve(PROJECT_ROOT, filePath);
+        if (!fs.existsSync(fullPath)) {
+            return null;
+        }
+        return fs.readFileSync(fullPath, "utf-8");
+    }
+    catch (error) {
+        return null;
+    }
+}
+function getFileModTime(filePath) {
+    try {
+        const fullPath = path.resolve(PROJECT_ROOT, filePath);
+        const stats = fs.statSync(fullPath);
+        return stats.mtimeMs;
+    }
+    catch {
+        return 0;
+    }
+}
+// ============================================================================
+// Create MCP Server
+// ============================================================================
+const server = new McpServer({
+    name: "agent-kit-gateway",
+    version: "1.0.0",
+});
+// ============================================================================
+// Tool 1: get_project_context
+// ============================================================================
+server.tool("get_project_context", "Get project overview including tech stack, structure, and conventions from AGENTS.md", {
+    section: z
+        .enum(["all", "tech_stack", "structure", "conventions", "commands"])
+        .optional()
+        .default("all")
+        .describe("Specific section to retrieve"),
+}, async ({ section }) => {
+    const agentsMd = readTextFile("AGENTS.md");
+    if (!agentsMd) {
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: JSON.stringify({
+                        error: "AGENTS.md not found",
+                        suggestion: "Run 'ak init' to generate AI infrastructure",
+                        project_root: PROJECT_ROOT,
+                    }),
+                },
+            ],
+        };
+    }
+    // Parse sections from AGENTS.md
+    const sections = {};
+    const sectionRegex = /^## (.+)$/gm;
+    let matches;
+    let lastIndex = 0;
+    let lastSection = "";
+    const lines = agentsMd.split("\n");
+    let currentSection = "";
+    let currentContent = [];
+    for (const line of lines) {
+        if (line.startsWith("## ")) {
+            if (currentSection) {
+                sections[currentSection] = currentContent.join("\n").trim();
+            }
+            currentSection = line.replace("## ", "").trim();
+            currentContent = [];
+        }
+        else {
+            currentContent.push(line);
+        }
+    }
+    if (currentSection) {
+        sections[currentSection] = currentContent.join("\n").trim();
+    }
+    // Map section names to content
+    const sectionMap = {
+        tech_stack: sections["🛠️ Tech Stack"] || sections["Tech Stack"],
+        structure: sections["📁 Directory Map"] || sections["Directory Map"],
+        conventions: sections["📜 Rules & Conventions"] || sections["Rules & Conventions"],
+        commands: sections["🔧 Commands Reference"] || sections["Commands Reference"],
+        all: agentsMd,
+    };
+    const result = sectionMap[section] || agentsMd;
+    return {
+        content: [
+            {
+                type: "text",
+                text: result,
+            },
+        ],
+    };
+});
+// ============================================================================
+// Tool 2: analyze_dependencies
+// ============================================================================
+server.tool("analyze_dependencies", "Get dependency graph for a file or module. Shows imports and files that import this file. Auto-syncs if data is stale.", {
+    file_path: z.string().describe("File path to analyze (relative to project root)"),
+    direction: z
+        .enum(["imports", "imported_by", "both"])
+        .optional()
+        .default("both")
+        .describe("Direction of dependencies to show"),
+    depth: z.number().optional().default(2).describe("Depth of traversal"),
+}, async ({ file_path, direction, depth }) => {
+    // Auto-sync if data is stale
+    const syncStatus = await autoSyncIfNeeded();
+    const graph = readJsonFile(".agent/graph.json");
+    if (!graph) {
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: JSON.stringify({
+                        error: "Dependency graph not found",
+                        suggestion: "Run 'ak sync' to generate dependency graph",
+                    }),
+                },
+            ],
+        };
+    }
+    // Normalize file path
+    const normalizedPath = file_path.replace(/^\.\//, "");
+    // Find the node
+    const node = graph.nodes?.find((n) => n.id === normalizedPath || n.path === normalizedPath);
+    if (!node) {
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: JSON.stringify({
+                        error: `File not found in graph: ${file_path}`,
+                        available_files: graph.nodes?.slice(0, 10).map((n) => n.id),
+                    }),
+                },
+            ],
+        };
+    }
+    // Build result based on direction
+    const result = {
+        file: normalizedPath,
+        type: node.type,
+    };
+    if (direction === "imports" || direction === "both") {
+        result.imports = node.imports || [];
+    }
+    if (direction === "imported_by" || direction === "both") {
+        // Find files that import this file
+        const importedBy = graph.edges
+            ?.filter((e) => e.target === normalizedPath)
+            .map((e) => e.source) || [];
+        result.imported_by = importedBy;
+    }
+    // Calculate impact score
+    result.impact_score = (result.imported_by?.length || 0);
+    return {
+        content: [
+            {
+                type: "text",
+                text: JSON.stringify(result, null, 2),
+            },
+        ],
+    };
+});
+// ============================================================================
+// Tool 3: search_code_logic
+// ============================================================================
+server.tool("search_code_logic", "Semantic search through code chunks with context. Auto-syncs if data is stale.", {
+    query: z.string().describe("Search query describing what you're looking for"),
+    file_filter: z.string().optional().describe("Glob pattern to filter files (e.g., '*.ts')"),
+    top_k: z.number().optional().default(10).describe("Number of results to return"),
+}, async ({ query, file_filter, top_k }) => {
+    // Auto-sync if data is stale
+    const syncStatus = await autoSyncIfNeeded();
+    const chunks = readJsonFile(".agent/rag/chunks.json");
+    if (!chunks || !chunks.chunks) {
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: JSON.stringify({
+                        error: "RAG chunks not found",
+                        suggestion: "Run 'ak sync' to generate code chunks",
+                    }),
+                },
+            ],
+        };
+    }
+    // Simple keyword-based search (in production, use embeddings)
+    const queryWords = query.toLowerCase().split(/\s+/);
+    const scored = chunks.chunks.map((chunk) => {
+        const content = (chunk.content || "").toLowerCase();
+        const metadata = chunk.metadata || {};
+        // Apply file filter
+        if (file_filter) {
+            const pattern = file_filter.replace("*", ".*");
+            if (!new RegExp(pattern).test(metadata.file_path || "")) {
+                return { chunk, score: -1 };
+            }
+        }
+        // Score based on keyword matches
+        let score = 0;
+        for (const word of queryWords) {
+            if (content.includes(word)) {
+                score += 1;
+            }
+            if ((metadata.name || "").toLowerCase().includes(word)) {
+                score += 2; // Boost for name matches
+            }
+        }
+        return { chunk, score };
+    });
+    // Sort and take top k
+    const results = scored
+        .filter((s) => s.score > 0)
+        .sort((a, b) => b.score - a.score)
+        .slice(0, top_k)
+        .map((s) => ({
+        file: s.chunk.metadata?.file_path,
+        type: s.chunk.metadata?.chunk_type,
+        name: s.chunk.metadata?.name,
+        lines: `${s.chunk.metadata?.start_line}-${s.chunk.metadata?.end_line}`,
+        preview: s.chunk.content?.substring(0, 200) + "...",
+        relevance_score: s.score,
+    }));
+    return {
+        content: [
+            {
+                type: "text",
+                text: JSON.stringify({
+                    query,
+                    total_results: results.length,
+                    results,
+                }, null, 2),
+            },
+        ],
+    };
+});
+// ============================================================================
+// Tool 4: get_impact_zone
+// ============================================================================
+server.tool("get_impact_zone", "Get all files that would be affected if a specific file is modified. Auto-syncs if data is stale.", {
+    file_path: z.string().describe("File path to analyze impact for"),
+    depth: z.number().optional().default(3).describe("How many levels of dependencies to traverse"),
+}, async ({ file_path, depth }) => {
+    // Auto-sync if data is stale
+    const syncStatus = await autoSyncIfNeeded();
+    const graph = readJsonFile(".agent/graph.json");
+    if (!graph) {
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: JSON.stringify({
+                        error: "Dependency graph not found",
+                        suggestion: "Run 'ak sync' to generate dependency graph",
+                    }),
+                },
+            ],
+        };
+    }
+    const normalizedPath = file_path.replace(/^\.\//, "");
+    // Build adjacency list for reverse dependencies (who imports this?)
+    const reverseGraph = {};
+    for (const edge of graph.edges || []) {
+        if (!reverseGraph[edge.target]) {
+            reverseGraph[edge.target] = [];
+        }
+        reverseGraph[edge.target].push(edge.source);
+    }
+    // BFS to find all affected files
+    const visited = new Set();
+    const queue = [{ file: normalizedPath, level: 0 }];
+    const impactByLevel = {};
+    while (queue.length > 0) {
+        const { file, level } = queue.shift();
+        if (visited.has(file) || level > depth) {
+            continue;
+        }
+        visited.add(file);
+        if (level > 0) {
+            if (!impactByLevel[level]) {
+                impactByLevel[level] = [];
+            }
+            impactByLevel[level].push(file);
+        }
+        // Add files that import this file
+        const dependents = reverseGraph[file] || [];
+        for (const dep of dependents) {
+            if (!visited.has(dep)) {
+                queue.push({ file: dep, level: level + 1 });
+            }
+        }
+    }
+    // Flatten results
+    const allAffected = Object.values(impactByLevel).flat();
+    return {
+        content: [
+            {
+                type: "text",
+                text: JSON.stringify({
+                    source_file: normalizedPath,
+                    total_affected: allAffected.length,
+                    impact_by_level: impactByLevel,
+                    all_affected_files: allAffected,
+                    warning: allAffected.length > 10
+                        ? "High impact change! Review carefully."
+                        : null,
+                }, null, 2),
+            },
+        ],
+    };
+});
+// ============================================================================
+// Tool 5: force_sync
+// ============================================================================
+server.tool("force_sync", "Force refresh all AI infrastructure data (AGENTS.md, graph, RAG chunks)", {
+    target: z
+        .enum(["all", "graph", "rag", "agents_md"])
+        .optional()
+        .default("all")
+        .describe("What to sync"),
+}, async ({ target }) => {
+    const { spawn } = await import("child_process");
+    const results = {};
+    const runScript = (scriptPath, args) => {
+        return new Promise((resolve, reject) => {
+            const proc = spawn("python", [scriptPath, ...args], {
+                cwd: PROJECT_ROOT,
+            });
+            let output = "";
+            let error = "";
+            proc.stdout.on("data", (data) => {
+                output += data.toString();
+            });
+            proc.stderr.on("data", (data) => {
+                error += data.toString();
+            });
+            proc.on("close", (code) => {
+                if (code === 0) {
+                    resolve(output);
+                }
+                else {
+                    resolve(`Error: ${error || output}`);
+                }
+            });
+            proc.on("error", (err) => {
+                resolve(`Failed to run: ${err.message}`);
+            });
+        });
+    };
+    // Determine script paths (relative to kit installation)
+    const kitPath = process.env.AGENT_KIT_PATH || path.join(__dirname, "..", "..");
+    if (target === "all" || target === "graph") {
+        const graphScript = path.join(kitPath, "skills/graph-mapper/scripts/generate_graph.py");
+        if (fs.existsSync(graphScript)) {
+            results.graph = await runScript(graphScript, [
+                "--src", path.join(PROJECT_ROOT, "src"),
+                "--output", path.join(PROJECT_ROOT, ".agent/graph.json"),
+                "--format", "both"
+            ]);
+        }
+        else {
+            results.graph = "Graph script not found";
+        }
+    }
+    if (target === "all" || target === "rag") {
+        const ragScript = path.join(kitPath, "skills/rag-engineering/scripts/chunk_code.py");
+        if (fs.existsSync(ragScript)) {
+            results.rag = await runScript(ragScript, [
+                "--src", path.join(PROJECT_ROOT, "src"),
+                "--output", path.join(PROJECT_ROOT, ".agent/rag/chunks.json")
+            ]);
+        }
+        else {
+            results.rag = "RAG script not found";
+        }
+    }
+    if (target === "all" || target === "agents_md") {
+        const infraScript = path.join(kitPath, "skills/app-builder/scripts/generate_ai_infra.py");
+        if (fs.existsSync(infraScript)) {
+            results.agents_md = await runScript(infraScript, [
+                "--project-root", PROJECT_ROOT
+            ]);
+        }
+        else {
+            results.agents_md = "AI infra script not found";
+        }
+    }
+    return {
+        content: [
+            {
+                type: "text",
+                text: JSON.stringify({
+                    status: "Sync completed",
+                    target,
+                    results,
+                    timestamp: new Date().toISOString(),
+                }, null, 2),
+            },
+        ],
+    };
+});
+// ============================================================================
+// Resource: Project Status
+// ============================================================================
+server.resource("project-status", "status://project", async (uri) => {
+    const agentsMd = fs.existsSync(path.join(PROJECT_ROOT, "AGENTS.md"));
+    const graphJson = fs.existsSync(path.join(PROJECT_ROOT, ".agent/graph.json"));
+    const ragChunks = fs.existsSync(path.join(PROJECT_ROOT, ".agent/rag/chunks.json"));
+    const status = {
+        project_root: PROJECT_ROOT,
+        infrastructure: {
+            agents_md: agentsMd ? "✅ Present" : "❌ Missing",
+            graph: graphJson ? "✅ Present" : "❌ Missing",
+            rag: ragChunks ? "✅ Present" : "❌ Missing",
+        },
+        last_checked: new Date().toISOString(),
+    };
+    return {
+        contents: [
+            {
+                uri: uri.href,
+                mimeType: "application/json",
+                text: JSON.stringify(status, null, 2),
+            },
+        ],
+    };
+});
+// ============================================================================
+// Start Server
+// ============================================================================
+async function main() {
+    console.error(`Agent Kit MCP Gateway starting...`);
+    console.error(`Project root: ${PROJECT_ROOT}`);
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    console.error("MCP Gateway ready and listening on stdio");
+}
+main().catch((error) => {
+    console.error("Fatal error:", error);
+    process.exit(1);
+});

package/.agent/mcp-gateway/dist/sync/debouncer.d.ts

@@ -0,0 +1,56 @@
+/**
+ * Debouncer
+ *
+ * Prevents excessive syncing by enforcing a cooldown period
+ * between sync operations. Essential for performance when
+ * AI makes many rapid queries.
+ */
+export declare class Debouncer {
+    private lastSync;
+    private cooldownMs;
+    private pendingSync;
+    /**
+     * @param cooldownMs Minimum time between syncs (default: 30 seconds)
+     */
+    constructor(cooldownMs?: number);
+    /**
+     * Check if enough time has passed since last sync
+     */
+    canSync(): boolean;
+    /**
+     * Get remaining cooldown time in milliseconds
+     */
+    getRemainingCooldown(): number;
+    /**
+     * Get remaining cooldown time in human-readable format
+     */
+    getRemainingCooldownFormatted(): string;
+    /**
+     * Mark that a sync has occurred
+     */
+    markSynced(): void;
+    /**
+     * Execute a sync operation with debouncing
+     *
+     * @param syncFn The sync function to execute
+     * @returns Result of sync or null if debounced
+     */
+    executeWithDebounce<T>(syncFn: () => Promise<T>): Promise<{
+        executed: boolean;
+        result?: T;
+        reason?: string;
+    }>;
+    /**
+     * Force reset the debouncer (for manual sync commands)
+     */
+    reset(): void;
+    /**
+     * Get debouncer status
+     */
+    getStatus(): {
+        lastSync: string;
+        canSync: boolean;
+        cooldownRemaining: string;
+    };
+}
+export declare function getGlobalDebouncer(cooldownMs?: number): Debouncer;