@crowley/rag-mcp 1.0.0

package/dist/tools/ask.d.ts

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

package/dist/tools/ask.js

@@ -0,0 +1,256 @@
+/**
+ * Ask tools module - question answering, code explanation, feature finding,
+ * conversation analysis, and auto-remember.
+ */
+import { pct } from "../formatters.js";
+/**
+ * Create the ask tools module with project-specific descriptions.
+ */
+export function createAskTools(projectName) {
+    const tools = [
+        {
+            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"],
+            },
+        },
+        {
+            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"],
+            },
+        },
+        {
+            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"],
+            },
+        },
+        {
+            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"],
+            },
+        },
+        {
+            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",
+                    },
+                },
+                required: ["content"],
+            },
+        },
+    ];
+    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

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

package/dist/tools/cache.js

@@ -0,0 +1,98 @@
+/**
+ * Cache Management Tools
+ */
+export function createCacheTools(projectName) {
+    const tools = [
+        {
+            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",
+                    },
+                },
+            },
+        },
+        {
+            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"],
+            },
+        },
+    ];
+    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

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

package/dist/tools/clustering.js

@@ -0,0 +1,251 @@
+/**
+ * Clustering tools module - code clustering, duplicate detection,
+ * similarity recommendations, and learning extraction.
+ */
+import { truncate, pct, PREVIEW } from "../formatters.js";
+/**
+ * Create the clustering tools module with project-specific descriptions.
+ */
+export function createClusteringTools(projectName) {
+    const tools = [
+        {
+            name: "cluster_code",
+            description: `Cluster code in the ${projectName} codebase by similarity. Groups related files around seed points.`,
+            inputSchema: {
+                type: "object",
+                properties: {
+                    seedIds: {
+                        type: "array",
+                        items: { type: "string" },
+                        description: "Seed point IDs to cluster around",
+                    },
+                    limit: {
+                        type: "number",
+                        description: "Max results per cluster (default: 5)",
+                        default: 5,
+                    },
+                    threshold: {
+                        type: "number",
+                        description: "Minimum similarity threshold (0-1, default: 0.7)",
+                        default: 0.7,
+                    },
+                },
+                required: ["seedIds"],
+            },
+        },
+        {
+            name: "find_duplicates",
+            description: `Find duplicate or near-duplicate code in ${projectName}. Groups similar files by content.`,
+            inputSchema: {
+                type: "object",
+                properties: {
+                    collection: {
+                        type: "string",
+                        description: "Collection to search (default: codebase)",
+                    },
+                    limit: {
+                        type: "number",
+                        description: "Max duplicate groups to return (default: 10)",
+                        default: 10,
+                    },
+                    threshold: {
+                        type: "number",
+                        description: "Minimum similarity threshold (0-1, default: 0.9)",
+                        default: 0.9,
+                    },
+                },
+            },
+        },
+        {
+            name: "recommend_similar",
+            description: `Recommend similar code based on positive and negative examples in ${projectName}.`,
+            inputSchema: {
+                type: "object",
+                properties: {
+                    positiveIds: {
+                        type: "array",
+                        items: { type: "string" },
+                        description: "IDs of vectors to find similar code to",
+                    },
+                    negativeIds: {
+                        type: "array",
+                        items: { type: "string" },
+                        description: "IDs of vectors to avoid (dissimilar)",
+                    },
+                    limit: {
+                        type: "number",
+                        description: "Max results (default: 5)",
+                        default: 5,
+                    },
+                },
+                required: ["positiveIds"],
+            },
+        },
+        {
+            name: "extract_learnings",
+            description: `Extract learnings and insights from text for ${projectName}. Identifies decisions, patterns, and concepts.`,
+            inputSchema: {
+                type: "object",
+                properties: {
+                    text: {
+                        type: "string",
+                        description: "Text to extract learnings from",
+                    },
+                    context: {
+                        type: "string",
+                        description: "Additional context about the text",
+                    },
+                    autoSave: {
+                        type: "boolean",
+                        description: "Automatically save extracted learnings (default: false)",
+                        default: false,
+                    },
+                    minConfidence: {
+                        type: "number",
+                        description: "Minimum confidence threshold (0-1, default: 0.7)",
+                        default: 0.7,
+                    },
+                },
+                required: ["text"],
+            },
+        },
+    ];
+    const handlers = {
+        cluster_code: async (args, ctx) => {
+            const { seedIds, limit = 5, threshold = 0.7 } = args;
+            const response = await ctx.api.post("/api/clusters", {
+                collection: `${ctx.projectName}_codebase`,
+                seedIds,
+                limit,
+                threshold,
+            });
+            const data = response.data;
+            const clusters = data.clusters || data;
+            if (!clusters || (Array.isArray(clusters) && clusters.length === 0)) {
+                return "No clusters found.";
+            }
+            let result = `## Code Clusters\n\n`;
+            for (const cluster of Array.isArray(clusters) ? clusters : [clusters]) {
+                result += `### Seed: ${cluster.seedId || cluster.seed || "unknown"}\n`;
+                const files = cluster.similar || cluster.files || cluster.results || [];
+                for (const f of files) {
+                    result += `- **${f.file || f.name}** (${pct(f.score || f.similarity)})`;
+                    if (f.content)
+                        result += `\n  ${truncate(f.content, PREVIEW.SHORT)}`;
+                    result += "\n";
+                }
+                result += "\n";
+            }
+            return result;
+        },
+        find_duplicates: async (args, ctx) => {
+            const { collection, limit = 10, threshold = 0.9 } = args;
+            const fullCollection = collection
+                ? (collection.startsWith(ctx.collectionPrefix) ? collection : `${ctx.collectionPrefix}${collection}`)
+                : `${ctx.collectionPrefix}codebase`;
+            const response = await ctx.api.post("/api/duplicates", {
+                collection: fullCollection,
+                limit,
+                threshold,
+            });
+            const data = response.data;
+            const groups = data.groups || data.duplicates || data;
+            if (!groups || (Array.isArray(groups) && groups.length === 0)) {
+                return "No duplicates found.";
+            }
+            let result = `## Duplicate Code Groups\n\n`;
+            let groupNum = 1;
+            for (const group of Array.isArray(groups) ? groups : [groups]) {
+                result += `### Group ${groupNum++}\n`;
+                const files = group.files || group.items || group.results || [];
+                const similarity = group.similarity || group.score;
+                if (similarity) {
+                    result += `**Similarity:** ${pct(similarity)}\n`;
+                }
+                for (const f of files) {
+                    result += `- **${f.file || f.name}**`;
+                    if (f.content)
+                        result += `\n  ${truncate(f.content, 80)}`;
+                    result += "\n";
+                }
+                result += "\n";
+            }
+            return result;
+        },
+        recommend_similar: async (args, ctx) => {
+            const { positiveIds, negativeIds, limit = 5 } = args;
+            const response = await ctx.api.post("/api/recommend", {
+                collection: `${ctx.projectName}_codebase`,
+                positiveIds,
+                negativeIds,
+                limit,
+            });
+            const results = response.data.results || response.data;
+            if (!results || results.length === 0) {
+                return "No recommendations found.";
+            }
+            let result = `## Recommendations\n\n`;
+            for (const r of results) {
+                result += `- **${r.file || r.name}** (${pct(r.score || r.similarity)})`;
+                if (r.content)
+                    result += `\n  ${truncate(r.content, PREVIEW.SHORT)}`;
+                result += "\n";
+            }
+            return result;
+        },
+        extract_learnings: async (args, ctx) => {
+            const { text, context, autoSave = false, minConfidence = 0.7 } = args;
+            const response = await ctx.api.post("/api/memory/extract", {
+                projectName: ctx.projectName,
+                text,
+                context,
+                autoSave,
+                minConfidence,
+            });
+            const data = response.data;
+            let result = `## Extracted Learnings\n\n`;
+            result += `**Summary:** ${data.summary || "N/A"}\n\n`;
+            if (data.learnings && data.learnings.length > 0) {
+                result += `### 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`;
+                    }
+                    if (l.reasoning) {
+                        result += `  *Reasoning: ${l.reasoning}*\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.entities.concepts && data.entities.concepts.length > 0) {
+                    result += `### Concepts\n`;
+                    for (const c of data.entities.concepts) {
+                        result += `- ${c}\n`;
+                    }
+                    result += "\n";
+                }
+            }
+            if (data.savedCount !== undefined) {
+                result += `**Saved:** ${data.savedCount} learnings\n`;
+            }
+            return result;
+        },
+    };
+    return { tools, handlers };
+}

package/dist/tools/confluence.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Confluence tools module - search, index, status, and space listing
+ * for Confluence integration.
+ */
+import type { ToolModule } from "../types.js";
+/**
+ * Create the Confluence tools module with project-specific descriptions.
+ */
+export declare function createConfluenceTools(projectName: string): ToolModule;