@crowley/rag-mcp 1.0.0

package/dist/tools/feedback.js

@@ -0,0 +1,220 @@
+/**
+ * Feedback tools module - search feedback, memory feedback, query suggestions,
+ * and quality metrics.
+ */
+import { pct } from "../formatters.js";
+/**
+ * Create the feedback tools module with project-specific descriptions.
+ */
+export function createFeedbackTools(projectName) {
+    const tools = [
+        {
+            name: "feedback_search",
+            description: `Provide feedback on a search result quality for ${projectName}. Helps improve future search results.`,
+            inputSchema: {
+                type: "object",
+                properties: {
+                    query: {
+                        type: "string",
+                        description: "The original search query",
+                    },
+                    feedbackType: {
+                        type: "string",
+                        enum: ["helpful", "not_helpful", "partially"],
+                        description: "How helpful the results were",
+                    },
+                    file: {
+                        type: "string",
+                        description: "The file from results being rated",
+                    },
+                    suggestedQuery: {
+                        type: "string",
+                        description: "A better query that would have found the right results",
+                    },
+                },
+                required: ["query", "feedbackType"],
+            },
+        },
+        {
+            name: "feedback_memory",
+            description: `Provide feedback on a memory's accuracy for ${projectName}. Helps keep memory quality high.`,
+            inputSchema: {
+                type: "object",
+                properties: {
+                    memoryId: {
+                        type: "string",
+                        description: "The memory ID to provide feedback on",
+                    },
+                    feedback: {
+                        type: "string",
+                        enum: ["accurate", "outdated", "incorrect"],
+                        description: "Feedback on the memory's accuracy",
+                    },
+                    correction: {
+                        type: "string",
+                        description: "Corrected information if the memory is wrong",
+                    },
+                },
+                required: ["memoryId", "feedback"],
+            },
+        },
+        {
+            name: "suggest_better_query",
+            description: `Get query improvement suggestions based on feedback patterns for ${projectName}.`,
+            inputSchema: {
+                type: "object",
+                properties: {
+                    query: {
+                        type: "string",
+                        description: "The query to get suggestions for",
+                    },
+                    context: {
+                        type: "string",
+                        description: "Additional context about what you are looking for",
+                    },
+                },
+                required: ["query"],
+            },
+        },
+        {
+            name: "get_quality_metrics",
+            description: `Get search and memory quality metrics for ${projectName}.`,
+            inputSchema: {
+                type: "object",
+                properties: {},
+            },
+        },
+    ];
+    const handlers = {
+        feedback_search: async (args, ctx) => {
+            const { query, feedbackType, file, suggestedQuery } = args;
+            const response = await ctx.api.post("/api/feedback/search", {
+                projectName: ctx.projectName,
+                query,
+                feedbackType,
+                file,
+                suggestedQuery,
+            });
+            const emojis = {
+                helpful: "\ud83d\udc4d",
+                not_helpful: "\ud83d\udc4e",
+                partially: "\ud83e\udd14",
+            };
+            const emoji = emojis[feedbackType] || "";
+            let result = `${emoji} **Search Feedback Recorded**\n\n`;
+            result += `- **Query:** ${query}\n`;
+            result += `- **Feedback:** ${feedbackType}\n`;
+            if (file)
+                result += `- **File:** ${file}\n`;
+            if (suggestedQuery)
+                result += `- **Suggested Query:** ${suggestedQuery}\n`;
+            return result;
+        },
+        feedback_memory: async (args, ctx) => {
+            const { memoryId, feedback, correction } = args;
+            const response = await ctx.api.post("/api/feedback/memory", {
+                projectName: ctx.projectName,
+                memoryId,
+                feedback,
+                correction,
+            });
+            const emojis = {
+                accurate: "\u2705",
+                outdated: "\u23f0",
+                incorrect: "\u274c",
+            };
+            const emoji = emojis[feedback] || "";
+            let result = `${emoji} **Memory Feedback Recorded**\n\n`;
+            result += `- **Memory ID:** ${memoryId}\n`;
+            result += `- **Feedback:** ${feedback}\n`;
+            if (correction)
+                result += `- **Correction:** ${correction}\n`;
+            return result;
+        },
+        suggest_better_query: async (args, ctx) => {
+            const { query, context } = args;
+            let suggestions = [];
+            try {
+                const response = await ctx.api.post("/api/query/suggest", {
+                    projectName: ctx.projectName,
+                    query,
+                    context,
+                });
+                suggestions = response.data.suggestions || [];
+            }
+            catch {
+                // Fallback to query analyze
+            }
+            if (!suggestions || suggestions.length === 0) {
+                try {
+                    const fallback = await ctx.api.post("/api/query/analyze", {
+                        projectName: ctx.projectName,
+                        query,
+                        context,
+                    });
+                    suggestions = fallback.data.suggestions || [];
+                }
+                catch {
+                    return "No query suggestions available.";
+                }
+            }
+            if (!suggestions || suggestions.length === 0) {
+                return "No query suggestions available.";
+            }
+            const sourceEmojis = {
+                feedback: "\ud83d\udcca",
+                pattern: "\ud83d\udd04",
+                ai: "\ud83e\udd16",
+            };
+            let result = `## Query Suggestions\n\n`;
+            for (const s of suggestions) {
+                const emoji = sourceEmojis[s.source] || "";
+                result += `- ${emoji} **${s.query || s.suggestion}**`;
+                if (s.confidence)
+                    result += ` (confidence: ${pct(s.confidence)})`;
+                result += "\n";
+            }
+            return result;
+        },
+        get_quality_metrics: async (_args, ctx) => {
+            const response = await ctx.api.get(`/api/quality/${ctx.projectName}`);
+            const data = response.data;
+            let result = `## Quality Metrics: ${projectName}\n\n`;
+            if (data.searchQuality) {
+                const sq = data.searchQuality;
+                result += `### Search Quality\n`;
+                result += `- Helpful: ${pct(sq.helpfulRate || 0)}\n`;
+                result += `- Partially Helpful: ${pct(sq.partialRate || 0)}\n`;
+                result += `- Not Helpful: ${pct(sq.notHelpfulRate || 0)}\n\n`;
+            }
+            if (data.memoryQuality) {
+                const mq = data.memoryQuality;
+                result += `### Memory Quality\n`;
+                result += `- Accuracy: ${pct(mq.accuracyRate || 0)}\n`;
+                result += `- Outdated: ${pct(mq.outdatedRate || 0)}\n`;
+                result += `- Incorrect: ${pct(mq.incorrectRate || 0)}\n\n`;
+            }
+            if (data.trends) {
+                const trendEmojis = {
+                    up: "\ud83d\udcc8",
+                    down: "\ud83d\udcc9",
+                    flat: "\u27a1\ufe0f",
+                };
+                result += `### Trends\n`;
+                for (const [metric, direction] of Object.entries(data.trends)) {
+                    const emoji = trendEmojis[direction] || "\u27a1\ufe0f";
+                    result += `- ${emoji} ${metric}: ${direction}\n`;
+                }
+                result += "\n";
+            }
+            if (data.problematicQueries && data.problematicQueries.length > 0) {
+                result += `### Problematic Queries\n`;
+                for (const q of data.problematicQueries) {
+                    result += `- "${q.query}" (${q.count || 0} times)\n`;
+                }
+            }
+            return result;
+        },
+    };
+    return { tools, handlers };
+}

package/dist/tools/guidelines.d.ts

@@ -0,0 +1,5 @@
+/**
+ * RAG Guidelines Tool
+ */
+import type { ToolModule } from "../types.js";
+export declare function createGuidelinesTools(projectName: string): ToolModule;

package/dist/tools/guidelines.js

@@ -0,0 +1,146 @@
+/**
+ * RAG Guidelines Tool
+ */
+export function createGuidelinesTools(projectName) {
+    const tools = [
+        {
+            name: "get_rag_guidelines",
+            description: `Get recommended settings and best practices for working with RAG in ${projectName}. Shows optimal tool usage patterns, query strategies, and session management tips.`,
+            inputSchema: {
+                type: "object",
+                properties: {
+                    focus: {
+                        type: "string",
+                        enum: ["all", "search", "memory", "session", "feedback", "performance"],
+                        description: "Focus area for guidelines (default: all)",
+                        default: "all",
+                    },
+                    context: {
+                        type: "string",
+                        enum: ["coding", "debugging", "reviewing", "learning", "documenting"],
+                        description: "Current work context for tailored recommendations",
+                    },
+                },
+            },
+        },
+    ];
+    const handlers = {
+        get_rag_guidelines: async (args, ctx) => {
+            const { focus = "all", context } = args;
+            let result = `# 📚 RAG Guidelines for ${ctx.projectName}\n\n`;
+            if (context) {
+                const contextTips = {
+                    coding: "🔧 **Mode: Coding** - Focus on implementation patterns and related code",
+                    debugging: "🐛 **Mode: Debugging** - Focus on error patterns and similar issues",
+                    reviewing: "👀 **Mode: Reviewing** - Focus on patterns, ADRs, and best practices",
+                    learning: "📖 **Mode: Learning** - Focus on documentation and explanations",
+                    documenting: "📝 **Mode: Documenting** - Focus on existing docs and patterns",
+                };
+                result += `${contextTips[context] || ""}\n\n`;
+            }
+            if (focus === "all" || focus === "search") {
+                result += `## 🔍 Search Best Practices\n\n`;
+                result += `### Query Formulation\n`;
+                result += `- **Be specific**: "authentication middleware express" > "auth code"\n`;
+                result += `- **Include context**: Add file types, modules, or features\n`;
+                result += `- **Use technical terms**: Match actual code terminology\n`;
+                result += `- **Combine concepts**: "error handling async database"\n\n`;
+                result += `### Tool Selection\n`;
+                result += `| Goal | Tool | When |\n`;
+                result += `|------|------|------|\n`;
+                result += `| Find code | \`search_codebase\` | General code search |\n`;
+                result += `| Find similar | \`search_similar\` | Have code snippet |\n`;
+                result += `| Understand | \`ask_codebase\` | Need explanation |\n`;
+                result += `| Find feature | \`find_feature\` | Know what it does |\n`;
+                result += `| Group by file | \`grouped_search\` | Overview needed |\n`;
+                result += `| Exact + semantic | \`hybrid_search\` | Specific terms |\n\n`;
+            }
+            if (focus === "all" || focus === "memory") {
+                result += `## 🧠 Memory Best Practices\n\n`;
+                result += `### What to Remember\n`;
+                result += `| Type | Use For | Example |\n`;
+                result += `|------|---------|----------|\n`;
+                result += `| \`decision\` | Architecture choices | "Use WebSocket for real-time" |\n`;
+                result += `| \`insight\` | Learned patterns | "Service X fails under load" |\n`;
+                result += `| \`context\` | Project knowledge | "Module Y handles payments" |\n`;
+                result += `| \`todo\` | Tasks to track | "Refactor auth after v2" |\n`;
+                result += `| \`note\` | General notes | "Config in .env.local" |\n\n`;
+                result += `### Architecture Knowledge\n`;
+                result += `- Record ADRs: \`record_adr\` for major decisions\n`;
+                result += `- Record patterns: \`record_pattern\` for code structures\n`;
+                result += `- Record tech debt: \`record_tech_debt\` for known issues\n`;
+                result += `- Check before coding: \`check_architecture\`\n\n`;
+            }
+            if (focus === "all" || focus === "session") {
+                result += `## 📋 Session Management\n\n`;
+                result += `### Recommended Workflow\n`;
+                result += `\`\`\`\n`;
+                result += `1. start_session          # Begin with context\n`;
+                result += `2. warm_cache             # Pre-load embeddings\n`;
+                result += `3. ... work ...           # Tools auto-track activity\n`;
+                result += `4. end_session            # Save learnings, get summary\n`;
+                result += `\`\`\`\n\n`;
+            }
+            if (focus === "all" || focus === "feedback") {
+                result += `## 👍 Feedback Guidelines\n\n`;
+                result += `| Result Quality | Action |\n`;
+                result += `|----------------|--------|\n`;
+                result += `| Found what needed | \`feedback_search\` -> helpful |\n`;
+                result += `| Partially useful | \`feedback_search\` -> partially_helpful |\n`;
+                result += `| Not relevant | \`feedback_search\` -> not_helpful + better query |\n\n`;
+            }
+            if (focus === "all" || focus === "performance") {
+                result += `## ⚡ Performance Optimization\n\n`;
+                result += `### Expected Performance\n`;
+                result += `| Operation | L1 Hit | L2 Hit | Miss |\n`;
+                result += `|-----------|--------|--------|------|\n`;
+                result += `| Embedding | 1-5ms | 5-15ms | 50-200ms |\n`;
+                result += `| Search | 20-50ms | 50-150ms | 100-500ms |\n`;
+                result += `| Memory recall | 10-30ms | 30-100ms | 100-300ms |\n\n`;
+            }
+            if (context) {
+                result += `## 🎯 Recommendations for ${context.charAt(0).toUpperCase() + context.slice(1)}\n\n`;
+                const contextRecs = {
+                    coding: [
+                        "Use `suggest_implementation` before writing new code",
+                        "Check `suggest_related_code` for dependencies",
+                        "Run `check_architecture` to validate patterns",
+                    ],
+                    debugging: [
+                        "Search for error messages with `hybrid_search`",
+                        "Use `ask_codebase` to understand error context",
+                        "Record solutions as `insight` memories",
+                    ],
+                    reviewing: [
+                        "Check `get_adrs` for architectural decisions",
+                        "Use `get_patterns` for expected structures",
+                        "Run `check_architecture` on changes",
+                    ],
+                    learning: [
+                        "Start with `ask_codebase` for explanations",
+                        "Use `explain_code` for complex snippets",
+                        "Remember insights for future reference",
+                    ],
+                    documenting: [
+                        "Use `search_docs` for existing documentation",
+                        "Check `get_patterns` for structure templates",
+                        "Record new patterns with `record_pattern`",
+                    ],
+                };
+                const recs = contextRecs[context] || [];
+                recs.forEach((rec, i) => {
+                    result += `${i + 1}. ${rec}\n`;
+                });
+                result += "\n";
+            }
+            result += `## 📌 Quick Reference\n\n`;
+            result += `- \`search_codebase\` - Find code\n`;
+            result += `- \`ask_codebase\` - Get explanations\n`;
+            result += `- \`remember\` - Save knowledge\n`;
+            result += `- \`recall\` - Retrieve knowledge\n`;
+            result += `- \`suggest_better_query\` - Improve searches\n`;
+            return result;
+        },
+    };
+    return { tools, handlers };
+}

package/dist/tools/indexing.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Indexing tools module - codebase indexing, status, zero-downtime reindex,
+ * and alias management.
+ */
+import type { ToolModule } from "../types.js";
+/**
+ * Create the indexing tools module with project-specific descriptions.
+ */
+export declare function createIndexingTools(projectName: string): ToolModule;

package/dist/tools/indexing.js

@@ -0,0 +1,129 @@
+/**
+ * Indexing tools module - codebase indexing, status, zero-downtime reindex,
+ * and alias management.
+ */
+/**
+ * Create the indexing tools module with project-specific descriptions.
+ */
+export function createIndexingTools(projectName) {
+    const tools = [
+        {
+            name: "index_codebase",
+            description: `Index or re-index the ${projectName} codebase for RAG search.`,
+            inputSchema: {
+                type: "object",
+                properties: {
+                    path: {
+                        type: "string",
+                        description: "Path to index (default: entire project)",
+                    },
+                    force: {
+                        type: "boolean",
+                        description: "Force re-index even if already indexed",
+                        default: false,
+                    },
+                },
+            },
+        },
+        {
+            name: "get_index_status",
+            description: `Get the indexing status for ${projectName} codebase.`,
+            inputSchema: {
+                type: "object",
+                properties: {},
+            },
+        },
+        {
+            name: "reindex_zero_downtime",
+            description: `Reindex ${projectName} codebase with zero downtime using alias swap.`,
+            inputSchema: {
+                type: "object",
+                properties: {
+                    path: {
+                        type: "string",
+                        description: "Path to index (default: entire project)",
+                    },
+                    patterns: {
+                        type: "array",
+                        items: { type: "string" },
+                        description: "File patterns to include (e.g., ['**/*.ts', '**/*.py'])",
+                    },
+                    excludePatterns: {
+                        type: "array",
+                        items: { type: "string" },
+                        description: "File patterns to exclude (e.g., ['node_modules/**'])",
+                    },
+                },
+            },
+        },
+        {
+            name: "list_aliases",
+            description: "List all collection aliases and their mappings.",
+            inputSchema: {
+                type: "object",
+                properties: {},
+            },
+        },
+    ];
+    const handlers = {
+        index_codebase: async (args, ctx) => {
+            const { path, force = false } = args;
+            const response = await ctx.api.post("/api/index", {
+                collection: `${ctx.collectionPrefix}codebase`,
+                path: path || ctx.projectPath,
+                force,
+            });
+            const data = response.data;
+            let result = `## Indexing ${projectName}\n\n`;
+            result += `- **Status:** ${data.status || "started"}\n`;
+            result += `- **Files to process:** ${data.filesToProcess ?? "N/A"}\n`;
+            return result;
+        },
+        get_index_status: async (_args, ctx) => {
+            const response = await ctx.api.get(`/api/index/status/${ctx.collectionPrefix}codebase`);
+            const data = response.data;
+            let result = `## Index Status: ${projectName}\n\n`;
+            result += `- **Status:** ${data.status || "unknown"}\n`;
+            result += `- **Total Files:** ${data.totalFiles ?? "N/A"}\n`;
+            result += `- **Indexed Files:** ${data.indexedFiles ?? "N/A"}\n`;
+            result += `- **Last Updated:** ${data.lastUpdated ? new Date(data.lastUpdated).toLocaleString() : "Never"}\n`;
+            result += `- **Vector Count:** ${data.vectorCount ?? "N/A"}\n`;
+            return result;
+        },
+        reindex_zero_downtime: async (args, ctx) => {
+            const { path, patterns, excludePatterns } = args;
+            const response = await ctx.api.post("/api/reindex", {
+                collection: `${ctx.collectionPrefix}codebase`,
+                path: path || ctx.projectPath,
+                patterns,
+                excludePatterns,
+            });
+            const data = response.data;
+            let result = `## Zero-Downtime Reindex: ${projectName}\n\n`;
+            result += `- **Alias:** ${data.alias || "N/A"}\n`;
+            result += `- **Status:** ${data.status || "started"}\n`;
+            result += `- **Message:** ${data.message || "Reindex initiated"}\n`;
+            return result;
+        },
+        list_aliases: async (_args, ctx) => {
+            const response = await ctx.api.get("/api/aliases");
+            const aliases = response.data.aliases || response.data;
+            if (!aliases || (Array.isArray(aliases) && aliases.length === 0)) {
+                return "No aliases configured.";
+            }
+            let result = `## Collection Aliases\n\n`;
+            if (Array.isArray(aliases)) {
+                for (const a of aliases) {
+                    result += `- **${a.alias}** -> ${a.collection}\n`;
+                }
+            }
+            else {
+                for (const [alias, collection] of Object.entries(aliases)) {
+                    result += `- **${alias}** -> ${collection}\n`;
+                }
+            }
+            return result;
+        },
+    };
+    return { tools, handlers };
+}

package/dist/tools/memory.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Memory tools module - Agent memory management tools.
+ *
+ * Tools: remember, recall, list_memories, forget, update_todo,
+ *        batch_remember, validate_memory, review_memories,
+ *        promote_memory, run_quality_gates, memory_maintenance
+ */
+import type { ToolModule } from "../types.js";
+export declare function createMemoryTools(projectName: string): ToolModule;