@crowley/rag-mcp 1.0.5 → 1.0.6

package/dist/tools/ask.d.ts

@@ -2,8 +2,8 @@
  * Ask tools module - question answering, code explanation, feature finding,
  * conversation analysis, and auto-remember.
  */
-import type { ToolModule } from "../types.js";
+import type { ToolSpec } from "../types.js";
 /**
  * Create the ask tools module with project-specific descriptions.
  */
-export declare function createAskTools(projectName: string): ToolModule;
+export declare function createAskTools(projectName: string): ToolSpec[];

package/dist/tools/ask.js

@@ -3,254 +3,199 @@
  * conversation analysis, and auto-remember.
  */
 import { pct } from "../formatters.js";
+import { z } from "zod";
+import { TOOL_ANNOTATIONS } from "../annotations.js";
 /**
  * Create the ask tools module with project-specific descriptions.
  */
 export function createAskTools(projectName) {
-    const tools = [
+    return [
         {
             name: "ask_codebase",
             description: `Ask a question about the ${projectName} codebase. Uses RAG + LLM to provide contextual answers.`,
-            inputSchema: {
-                type: "object",
-                properties: {
-                    question: {
-                        type: "string",
-                        description: "Question about the codebase",
-                    },
-                },
-                required: ["question"],
+            schema: z.object({
+                question: z.string().describe("Question about the codebase"),
+            }),
+            annotations: TOOL_ANNOTATIONS["ask_codebase"],
+            handler: async (args, ctx) => {
+                const { question } = args;
+                const response = await ctx.api.post("/api/ask", {
+                    collection: `${ctx.collectionPrefix}codebase`,
+                    question,
+                });
+                return response.data.answer || "No answer could be generated.";
             },
         },
         {
             name: "explain_code",
             description: "Get a detailed explanation of a code snippet.",
-            inputSchema: {
-                type: "object",
-                properties: {
-                    code: {
-                        type: "string",
-                        description: "Code snippet to explain",
-                    },
-                    filePath: {
-                        type: "string",
-                        description: "Optional file path for context",
-                    },
-                },
-                required: ["code"],
+            schema: z.object({
+                code: z.string().describe("Code snippet to explain"),
+                filePath: z.string().optional().describe("Optional file path for context"),
+            }),
+            annotations: TOOL_ANNOTATIONS["explain_code"],
+            handler: async (args, ctx) => {
+                const { code, filePath } = args;
+                const response = await ctx.api.post("/api/explain", {
+                    collection: `${ctx.collectionPrefix}codebase`,
+                    code,
+                    filePath,
+                });
+                const data = response.data;
+                let result = `## Summary\n${data.summary || "N/A"}\n\n`;
+                result += `## Purpose\n${data.purpose || "N/A"}\n\n`;
+                if (data.keyComponents && data.keyComponents.length > 0) {
+                    result += `## Key Components\n`;
+                    for (const comp of data.keyComponents) {
+                        result += `- ${comp}\n`;
+                    }
+                    result += "\n";
+                }
+                if (data.dependencies && data.dependencies.length > 0) {
+                    result += `## Dependencies\n`;
+                    for (const dep of data.dependencies) {
+                        result += `- ${dep}\n`;
+                    }
+                }
+                return result;
             },
         },
         {
             name: "find_feature",
             description: `Find where a specific feature is implemented in the ${projectName} codebase.`,
-            inputSchema: {
-                type: "object",
-                properties: {
-                    description: {
-                        type: "string",
-                        description: "Description of the feature to find",
-                    },
-                },
-                required: ["description"],
+            schema: z.object({
+                description: z.string().describe("Description of the feature to find"),
+            }),
+            annotations: TOOL_ANNOTATIONS["find_feature"],
+            handler: async (args, ctx) => {
+                const { description } = args;
+                const response = await ctx.api.post("/api/find-feature", {
+                    collection: `${ctx.collectionPrefix}codebase`,
+                    description,
+                });
+                const data = response.data;
+                let result = `## Feature: ${data.name || description}\n\n`;
+                result += `${data.explanation || "No explanation available."}\n\n`;
+                if (data.mainFiles && data.mainFiles.length > 0) {
+                    result += `### Main Files\n`;
+                    for (const f of data.mainFiles) {
+                        result += `- **${f.file}** (${pct(f.score)} match)\n`;
+                    }
+                    result += "\n";
+                }
+                if (data.relatedFiles && data.relatedFiles.length > 0) {
+                    result += `### Related Files\n`;
+                    for (const f of data.relatedFiles) {
+                        result += `- ${f.file}\n`;
+                    }
+                }
+                return result;
             },
         },
         {
             name: "analyze_conversation",
             description: `Analyze a conversation to extract learnings, decisions, and insights for ${projectName}.`,
-            inputSchema: {
-                type: "object",
-                properties: {
-                    conversation: {
-                        type: "string",
-                        description: "The conversation text to analyze",
-                    },
-                    context: {
-                        type: "string",
-                        description: "Additional context about the conversation",
-                    },
-                    autoSave: {
-                        type: "boolean",
-                        description: "Automatically save extracted learnings (default: false)",
-                        default: false,
-                    },
-                    minConfidence: {
-                        type: "number",
-                        description: "Minimum confidence threshold for learnings (0-1, default: 0.7)",
-                        default: 0.7,
-                    },
-                },
-                required: ["conversation"],
+            schema: z.object({
+                conversation: z.string().describe("The conversation text to analyze"),
+                context: z.string().optional().describe("Additional context about the conversation"),
+                autoSave: z.boolean().optional().describe("Automatically save extracted learnings (default: false)"),
+                minConfidence: z.number().optional().describe("Minimum confidence threshold for learnings (0-1, default: 0.7)"),
+            }),
+            annotations: TOOL_ANNOTATIONS["analyze_conversation"],
+            handler: async (args, ctx) => {
+                const { conversation, context, autoSave = false, minConfidence = 0.7 } = args;
+                const response = await ctx.api.post("/api/analyze-conversation", {
+                    projectName: ctx.projectName,
+                    conversation,
+                    context,
+                    autoSave,
+                    minConfidence,
+                });
+                const data = response.data;
+                let result = `## Conversation Analysis\n\n`;
+                result += `**Summary:** ${data.summary || "N/A"}\n\n`;
+                if (data.learnings && data.learnings.length > 0) {
+                    result += `### Extracted Learnings\n`;
+                    for (const l of data.learnings) {
+                        result += `- **[${l.type}]** (confidence: ${pct(l.confidence)}) ${l.content}\n`;
+                        if (l.tags && l.tags.length > 0) {
+                            result += `  Tags: ${l.tags.join(", ")}\n`;
+                        }
+                    }
+                    result += "\n";
+                }
+                if (data.entities) {
+                    if (data.entities.files && data.entities.files.length > 0) {
+                        result += `### Referenced Files\n`;
+                        for (const f of data.entities.files) {
+                            result += `- ${f}\n`;
+                        }
+                        result += "\n";
+                    }
+                    if (data.entities.functions && data.entities.functions.length > 0) {
+                        result += `### Referenced Functions\n`;
+                        for (const f of data.entities.functions) {
+                            result += `- ${f}\n`;
+                        }
+                        result += "\n";
+                    }
+                }
+                if (data.savedCount !== undefined) {
+                    result += `**Saved:** ${data.savedCount} learnings\n`;
+                }
+                return result;
             },
         },
         {
             name: "auto_remember",
             description: `Automatically classify and remember information for ${projectName}. Analyzes content to determine the best memory type.`,
-            inputSchema: {
-                type: "object",
-                properties: {
-                    content: {
-                        type: "string",
-                        description: "Content to analyze and remember",
-                    },
-                    context: {
-                        type: "string",
-                        description: "Additional context",
-                    },
-                    relatedTo: {
-                        type: "string",
-                        description: "Related feature or topic",
-                    },
-                    tags: {
-                        type: "array",
-                        items: { type: "string" },
-                        description: "Tags for categorization",
+            schema: z.object({
+                content: z.string().describe("Content to analyze and remember"),
+                context: z.string().optional().describe("Additional context"),
+                relatedTo: z.string().optional().describe("Related feature or topic"),
+                tags: z.array(z.string()).optional().describe("Tags for categorization"),
+            }),
+            annotations: TOOL_ANNOTATIONS["auto_remember"],
+            handler: async (args, ctx) => {
+                const { content, context, relatedTo, tags } = args;
+                // First, analyze the content to classify it
+                const analyzeResponse = await ctx.api.post("/api/analyze-conversation", {
+                    projectName: ctx.projectName,
+                    conversation: content,
+                    context,
+                    autoSave: false,
+                    minConfidence: 0.5,
+                });
+                const analysis = analyzeResponse.data;
+                let memoryType = "note";
+                let confidence = 0;
+                if (analysis.learnings && analysis.learnings.length > 0) {
+                    const best = analysis.learnings[0];
+                    memoryType = best.type || "note";
+                    confidence = best.confidence || 0;
+                }
+                // Save with the classified type
+                const rememberResponse = await ctx.api.post("/api/memory", {
+                    projectName: ctx.projectName,
+                    type: memoryType,
+                    content,
+                    relatedTo,
+                    tags: tags || (analysis.learnings?.[0]?.tags),
+                    metadata: {
+                        source: 'auto_pattern',
+                        confidence,
                     },
-                },
-                required: ["content"],
+                });
+                const saved = rememberResponse.data;
+                let result = `## Auto-Remembered\n\n`;
+                result += `- **Type:** ${memoryType}\n`;
+                result += `- **Confidence:** ${confidence > 0 ? pct(confidence) : "N/A (fallback to note)"}\n`;
+                result += `- **ID:** ${saved.id || "N/A"}\n`;
+                if (saved.tags && saved.tags.length > 0) {
+                    result += `- **Tags:** ${saved.tags.join(", ")}\n`;
+                }
+                return result;
             },
         },
     ];
-    const handlers = {
-        ask_codebase: async (args, ctx) => {
-            const { question } = args;
-            const response = await ctx.api.post("/api/ask", {
-                collection: `${ctx.collectionPrefix}codebase`,
-                question,
-            });
-            return response.data.answer || "No answer could be generated.";
-        },
-        explain_code: async (args, ctx) => {
-            const { code, filePath } = args;
-            const response = await ctx.api.post("/api/explain", {
-                collection: `${ctx.collectionPrefix}codebase`,
-                code,
-                filePath,
-            });
-            const data = response.data;
-            let result = `## Summary\n${data.summary || "N/A"}\n\n`;
-            result += `## Purpose\n${data.purpose || "N/A"}\n\n`;
-            if (data.keyComponents && data.keyComponents.length > 0) {
-                result += `## Key Components\n`;
-                for (const comp of data.keyComponents) {
-                    result += `- ${comp}\n`;
-                }
-                result += "\n";
-            }
-            if (data.dependencies && data.dependencies.length > 0) {
-                result += `## Dependencies\n`;
-                for (const dep of data.dependencies) {
-                    result += `- ${dep}\n`;
-                }
-            }
-            return result;
-        },
-        find_feature: async (args, ctx) => {
-            const { description } = args;
-            const response = await ctx.api.post("/api/find-feature", {
-                collection: `${ctx.collectionPrefix}codebase`,
-                description,
-            });
-            const data = response.data;
-            let result = `## Feature: ${data.name || description}\n\n`;
-            result += `${data.explanation || "No explanation available."}\n\n`;
-            if (data.mainFiles && data.mainFiles.length > 0) {
-                result += `### Main Files\n`;
-                for (const f of data.mainFiles) {
-                    result += `- **${f.file}** (${pct(f.score)} match)\n`;
-                }
-                result += "\n";
-            }
-            if (data.relatedFiles && data.relatedFiles.length > 0) {
-                result += `### Related Files\n`;
-                for (const f of data.relatedFiles) {
-                    result += `- ${f.file}\n`;
-                }
-            }
-            return result;
-        },
-        analyze_conversation: async (args, ctx) => {
-            const { conversation, context, autoSave = false, minConfidence = 0.7 } = args;
-            const response = await ctx.api.post("/api/analyze-conversation", {
-                projectName: ctx.projectName,
-                conversation,
-                context,
-                autoSave,
-                minConfidence,
-            });
-            const data = response.data;
-            let result = `## Conversation Analysis\n\n`;
-            result += `**Summary:** ${data.summary || "N/A"}\n\n`;
-            if (data.learnings && data.learnings.length > 0) {
-                result += `### Extracted Learnings\n`;
-                for (const l of data.learnings) {
-                    result += `- **[${l.type}]** (confidence: ${pct(l.confidence)}) ${l.content}\n`;
-                    if (l.tags && l.tags.length > 0) {
-                        result += `  Tags: ${l.tags.join(", ")}\n`;
-                    }
-                }
-                result += "\n";
-            }
-            if (data.entities) {
-                if (data.entities.files && data.entities.files.length > 0) {
-                    result += `### Referenced Files\n`;
-                    for (const f of data.entities.files) {
-                        result += `- ${f}\n`;
-                    }
-                    result += "\n";
-                }
-                if (data.entities.functions && data.entities.functions.length > 0) {
-                    result += `### Referenced Functions\n`;
-                    for (const f of data.entities.functions) {
-                        result += `- ${f}\n`;
-                    }
-                    result += "\n";
-                }
-            }
-            if (data.savedCount !== undefined) {
-                result += `**Saved:** ${data.savedCount} learnings\n`;
-            }
-            return result;
-        },
-        auto_remember: async (args, ctx) => {
-            const { content, context, relatedTo, tags } = args;
-            // First, analyze the content to classify it
-            const analyzeResponse = await ctx.api.post("/api/analyze-conversation", {
-                projectName: ctx.projectName,
-                conversation: content,
-                context,
-                autoSave: false,
-                minConfidence: 0.5,
-            });
-            const analysis = analyzeResponse.data;
-            let memoryType = "note";
-            let confidence = 0;
-            if (analysis.learnings && analysis.learnings.length > 0) {
-                const best = analysis.learnings[0];
-                memoryType = best.type || "note";
-                confidence = best.confidence || 0;
-            }
-            // Save with the classified type
-            const rememberResponse = await ctx.api.post("/api/memory", {
-                projectName: ctx.projectName,
-                type: memoryType,
-                content,
-                relatedTo,
-                tags: tags || (analysis.learnings?.[0]?.tags),
-                metadata: {
-                    source: 'auto_pattern',
-                    confidence,
-                },
-            });
-            const saved = rememberResponse.data;
-            let result = `## Auto-Remembered\n\n`;
-            result += `- **Type:** ${memoryType}\n`;
-            result += `- **Confidence:** ${confidence > 0 ? pct(confidence) : "N/A (fallback to note)"}\n`;
-            result += `- **ID:** ${saved.id || "N/A"}\n`;
-            if (saved.tags && saved.tags.length > 0) {
-                result += `- **Tags:** ${saved.tags.join(", ")}\n`;
-            }
-            return result;
-        },
-    };
-    return { tools, handlers };
 }

package/dist/tools/cache.d.ts

@@ -1,5 +1,5 @@
 /**
  * Cache Management Tools
  */
-import type { ToolModule } from "../types.js";
-export declare function createCacheTools(projectName: string): ToolModule;
+import type { ToolSpec } from "../types.js";
+export declare function createCacheTools(projectName: string): ToolSpec[];

package/dist/tools/cache.js

@@ -1,98 +1,79 @@
 /**
  * Cache Management Tools
  */
+import { z } from "zod";
+import { TOOL_ANNOTATIONS } from "../annotations.js";
 export function createCacheTools(projectName) {
-    const tools = [
+    return [
         {
             name: "get_cache_stats",
             description: `Get cache statistics for ${projectName}. Shows hit rates, cache levels, and memory usage.`,
-            inputSchema: {
-                type: "object",
-                properties: {
-                    sessionId: {
-                        type: "string",
-                        description: "Optional session ID for session-specific stats",
-                    },
-                },
+            schema: z.object({
+                sessionId: z.string().optional().describe("Optional session ID for session-specific stats"),
+            }),
+            annotations: TOOL_ANNOTATIONS["get_cache_stats"],
+            handler: async (args, ctx) => {
+                const { sessionId } = args;
+                if (sessionId) {
+                    const response = await ctx.api.get(`/api/cache/session/${sessionId}`);
+                    const stats = response.data;
+                    let result = `# 📊 Cache Stats for Session\n\n`;
+                    result += `**Session ID**: ${sessionId}\n\n`;
+                    result += `## Hit Rates\n`;
+                    result += `- **Total Hits**: ${stats.hits}\n`;
+                    result += `- **Misses**: ${stats.misses}\n`;
+                    result += `- **Hit Rate**: ${(stats.hitRate * 100).toFixed(1)}%\n\n`;
+                    result += `## Cache Level Distribution\n`;
+                    result += `- **L1 (Session)**: ${stats.l1Hits} hits\n`;
+                    result += `- **L2 (Project)**: ${stats.l2Hits} hits\n`;
+                    result += `- **L3 (Global)**: ${stats.l3Hits} hits\n`;
+                    return result;
+                }
+                const response = await ctx.api.get("/api/cache/analytics");
+                const analytics = response.data;
+                let result = `# 📊 Global Cache Analytics\n\n`;
+                result += `**Status**: ${analytics.enabled ? (analytics.connected ? "🟢 Connected" : "🟡 Disconnected") : "🔴 Disabled"}\n\n`;
+                if (analytics.connected) {
+                    result += `## Keys\n`;
+                    result += `- **Total**: ${analytics.totalKeys?.toLocaleString() || "N/A"}\n`;
+                    result += `- **Embeddings**: ${analytics.embeddingKeys?.toLocaleString() || "N/A"}\n`;
+                    result += `- **Search**: ${analytics.searchKeys?.toLocaleString() || "N/A"}\n`;
+                    result += `- **Sessions**: ${analytics.sessionKeys?.toLocaleString() || "N/A"}\n\n`;
+                    result += `## Memory\n`;
+                    result += `- **Used**: ${analytics.memoryUsage || "N/A"}\n`;
+                }
+                return result;
             },
         },
         {
             name: "warm_cache",
             description: `Warm the embedding cache for ${projectName}. Pre-loads frequently used embeddings for faster responses.`,
-            inputSchema: {
-                type: "object",
-                properties: {
-                    sessionId: {
-                        type: "string",
-                        description: "Session ID to warm cache for",
-                    },
-                    previousSessionId: {
-                        type: "string",
-                        description: "Previous session to copy cache from (for session resumption)",
-                    },
-                    recentQueries: {
-                        type: "array",
-                        items: { type: "string" },
-                        description: "Recent queries to pre-warm in cache",
-                    },
-                },
-                required: ["sessionId"],
+            schema: z.object({
+                sessionId: z.string().describe("Session ID to warm cache for"),
+                previousSessionId: z.string().optional().describe("Previous session to copy cache from (for session resumption)"),
+                recentQueries: z.array(z.string()).optional().describe("Recent queries to pre-warm in cache"),
+            }),
+            annotations: TOOL_ANNOTATIONS["warm_cache"],
+            handler: async (args, ctx) => {
+                const { sessionId, previousSessionId, recentQueries } = args;
+                const response = await ctx.api.post("/api/cache/warm", {
+                    sessionId,
+                    previousSessionId,
+                    recentQueries,
+                });
+                const { warmedCount } = response.data;
+                let result = `🔥 **Cache Warmed**\n\n`;
+                result += `- **Session ID**: ${sessionId}\n`;
+                result += `- **Pre-loaded**: ${warmedCount} embeddings\n`;
+                if (previousSessionId) {
+                    result += `- **Resumed from**: ${previousSessionId}\n`;
+                }
+                if (recentQueries && recentQueries.length > 0) {
+                    result += `- **Queries warmed**: ${recentQueries.length}\n`;
+                }
+                result += `\nThe session cache is now primed for faster responses!`;
+                return result;
             },
         },
     ];
-    const handlers = {
-        get_cache_stats: async (args, ctx) => {
-            const { sessionId } = args;
-            if (sessionId) {
-                const response = await ctx.api.get(`/api/cache/session/${sessionId}`);
-                const stats = response.data;
-                let result = `# 📊 Cache Stats for Session\n\n`;
-                result += `**Session ID**: ${sessionId}\n\n`;
-                result += `## Hit Rates\n`;
-                result += `- **Total Hits**: ${stats.hits}\n`;
-                result += `- **Misses**: ${stats.misses}\n`;
-                result += `- **Hit Rate**: ${(stats.hitRate * 100).toFixed(1)}%\n\n`;
-                result += `## Cache Level Distribution\n`;
-                result += `- **L1 (Session)**: ${stats.l1Hits} hits\n`;
-                result += `- **L2 (Project)**: ${stats.l2Hits} hits\n`;
-                result += `- **L3 (Global)**: ${stats.l3Hits} hits\n`;
-                return result;
-            }
-            const response = await ctx.api.get("/api/cache/analytics");
-            const analytics = response.data;
-            let result = `# 📊 Global Cache Analytics\n\n`;
-            result += `**Status**: ${analytics.enabled ? (analytics.connected ? "🟢 Connected" : "🟡 Disconnected") : "🔴 Disabled"}\n\n`;
-            if (analytics.connected) {
-                result += `## Keys\n`;
-                result += `- **Total**: ${analytics.totalKeys?.toLocaleString() || "N/A"}\n`;
-                result += `- **Embeddings**: ${analytics.embeddingKeys?.toLocaleString() || "N/A"}\n`;
-                result += `- **Search**: ${analytics.searchKeys?.toLocaleString() || "N/A"}\n`;
-                result += `- **Sessions**: ${analytics.sessionKeys?.toLocaleString() || "N/A"}\n\n`;
-                result += `## Memory\n`;
-                result += `- **Used**: ${analytics.memoryUsage || "N/A"}\n`;
-            }
-            return result;
-        },
-        warm_cache: async (args, ctx) => {
-            const { sessionId, previousSessionId, recentQueries } = args;
-            const response = await ctx.api.post("/api/cache/warm", {
-                sessionId,
-                previousSessionId,
-                recentQueries,
-            });
-            const { warmedCount } = response.data;
-            let result = `🔥 **Cache Warmed**\n\n`;
-            result += `- **Session ID**: ${sessionId}\n`;
-            result += `- **Pre-loaded**: ${warmedCount} embeddings\n`;
-            if (previousSessionId) {
-                result += `- **Resumed from**: ${previousSessionId}\n`;
-            }
-            if (recentQueries && recentQueries.length > 0) {
-                result += `- **Queries warmed**: ${recentQueries.length}\n`;
-            }
-            result += `\nThe session cache is now primed for faster responses!`;
-            return result;
-        },
-    };
-    return { tools, handlers };
 }

package/dist/tools/clustering.d.ts

@@ -2,8 +2,8 @@
  * Clustering tools module - code clustering, duplicate detection,
  * similarity recommendations, and learning extraction.
  */
-import type { ToolModule } from "../types.js";
+import type { ToolSpec } from "../types.js";
 /**
  * Create the clustering tools module with project-specific descriptions.
  */
-export declare function createClusteringTools(projectName: string): ToolModule;
+export declare function createClusteringTools(projectName: string): ToolSpec[];