@crowley/rag-mcp 1.0.4 → 1.0.5

package/dist/context-enrichment.d.ts

@@ -26,9 +26,9 @@ export declare class ContextEnricher {
      */
     before(name: string, args: Record<string, unknown>, ctx: ToolContext): Promise<string | null>;
     /**
-     * After hook: fire-and-forget session activity tracking.
+     * After hook: fire-and-forget session activity tracking + implicit feedback.
      */
-    after(name: string, _args: Record<string, unknown>, _result: string, ctx: ToolContext): void;
+    after(name: string, args: Record<string, unknown>, result: string, ctx: ToolContext): void;
     /**
      * Extract a semantic query string from tool arguments.
      */

package/dist/context-enrichment.js

@@ -18,6 +18,7 @@ export const DEFAULT_ENRICHABLE_TOOLS = new Set([
     "suggest_implementation",
     "suggest_related_code",
     "check_architecture",
+    "context_briefing",
     "run_agent",
 ]);
 export const DEFAULT_SKIP_TOOLS = new Set([
@@ -79,21 +80,36 @@ export class ContextEnricher {
         }
     }
     /**
-     * After hook: fire-and-forget session activity tracking.
+     * After hook: fire-and-forget session activity tracking + implicit feedback.
      */
-    after(name, _args, _result, ctx) {
-        if (!ctx.activeSessionId)
-            return;
-        // Fire-and-forget: track tool usage in session
-        ctx.api
-            .post(`/api/session/${ctx.activeSessionId}/activity`, {
-            projectName: ctx.projectName,
-            type: "tool",
-            value: name,
-        })
-            .catch(() => {
-            // Silently ignore tracking errors
-        });
+    after(name, args, result, ctx) {
+        // Session activity tracking
+        if (ctx.activeSessionId) {
+            ctx.api
+                .post(`/api/session/${ctx.activeSessionId}/activity`, {
+                projectName: ctx.projectName,
+                type: "tool",
+                value: name,
+            })
+                .catch(() => { });
+        }
+        // Implicit positive feedback for enrichable search tools
+        if (this.config.enrichableTools.has(name)) {
+            const query = this.extractQuery(args);
+            if (query &&
+                result &&
+                !result.includes("No results") &&
+                !result.includes("not found") &&
+                !result.includes("No relevant context found")) {
+                ctx.api
+                    .post("/api/feedback/search", {
+                    projectName: ctx.projectName,
+                    query,
+                    feedbackType: "helpful",
+                })
+                    .catch(() => { });
+            }
+        }
     }
     /**
      * Extract a semantic query string from tool arguments.

package/dist/index.js

@@ -99,6 +99,24 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
         content: [{ type: "text", text: result }],
     };
 });
+// Graceful shutdown: close active session on exit
+async function cleanup() {
+    if (ctx.activeSessionId) {
+        try {
+            await api.post(`/api/session/${ctx.activeSessionId}/end`, {
+                projectName: PROJECT_NAME,
+                summary: "Session ended by MCP server shutdown",
+                autoSaveLearnings: true,
+            });
+        }
+        catch {
+            // Best-effort, don't block shutdown
+        }
+    }
+    process.exit(0);
+}
+process.on("SIGINT", cleanup);
+process.on("SIGTERM", cleanup);
 // Start server
 async function main() {
     const transport = new StdioServerTransport();

package/dist/tools/architecture.js

@@ -291,6 +291,7 @@ ${alternatives ? `## Alternatives Considered\n${alternatives}` : ""}`;
             query: query || "architecture decision ADR",
             type: "decision",
             limit,
+            tag: "adr",
         });
         const results = response.data.results || [];
         const adrs = results.filter((r) => r.memory.tags?.includes("adr") &&
@@ -349,6 +350,7 @@ ${appliesTo ? `## Applies To\n${appliesTo}` : ""}`;
             query: query || "architectural pattern structure",
             type: "context",
             limit,
+            tag: "pattern",
         });
         const results = response.data.results || [];
         const patterns = results.filter((r) => {
@@ -383,6 +385,7 @@ ${appliesTo ? `## Applies To\n${appliesTo}` : ""}`;
             query: patternQuery,
             type: "context",
             limit: 5,
+            tag: "pattern",
         });
         // Get relevant ADRs
         const adrsResponse = await ctx.api.post("/api/memory/recall", {
@@ -390,6 +393,7 @@ ${appliesTo ? `## Applies To\n${appliesTo}` : ""}`;
             query: patternQuery,
             type: "decision",
             limit: 5,
+            tag: "adr",
         });
         // Search similar code in codebase
         let similarCode = [];
@@ -499,6 +503,7 @@ Provide a structured analysis:
             query: `${type} ${feature} pattern structure`,
             type: "context",
             limit: 5,
+            tag: "pattern",
         });
         // Get relevant ADRs
         const adrsResponse = await ctx.api.post("/api/memory/recall", {
@@ -506,6 +511,7 @@ Provide a structured analysis:
             query: `${type} ${feature}`,
             type: "decision",
             limit: 3,
+            tag: "adr",
         });
         // Get similar implementations
         const codeResponse = await ctx.api.post("/api/search", {
@@ -602,6 +608,7 @@ ${relatedAdr ? `## Related ADR\n${relatedAdr}` : ""}`;
             query: "technical debt violation issue",
             type: "insight",
             limit: limit * 2, // Fetch extra to account for filtering
+            tag: "tech-debt",
         });
         const results = response.data.results || [];
         const debts = results
@@ -649,6 +656,7 @@ ${relatedAdr ? `## Related ADR\n${relatedAdr}` : ""}`;
             query: "pattern structure organization",
             type: "context",
             limit: 10,
+            tag: "pattern",
         });
         // Get codebase structure
         const codeResponse = await ctx.api.post("/api/search", {

package/dist/tools/indexing.js

@@ -100,6 +100,9 @@ async function uploadFiles(ctx, projectPath, opts) {
         duration: totalDuration,
     };
 }
+// In-memory cache for get_index_status (30 min TTL)
+let _statusCache = null;
+const STATUS_CACHE_TTL = 30 * 60 * 1000; // 30 minutes
 /**
  * Create the indexing tools module with project-specific descriptions.
  */
@@ -125,7 +128,7 @@ export function createIndexingTools(projectName) {
         },
         {
             name: "get_index_status",
-            description: `Get the indexing status for ${projectName} codebase.`,
+            description: `Get the indexing status for ${projectName} codebase. Results cached for 30 minutes.`,
             inputSchema: {
                 type: "object",
                 properties: {},
@@ -168,6 +171,7 @@ export function createIndexingTools(projectName) {
             const { path: indexPath, force = false } = args;
             const projectPath = indexPath || ctx.projectPath;
             const stats = await uploadFiles(ctx, projectPath, { force });
+            _statusCache = null; // Invalidate status cache after indexing
             let result = `## Indexing ${projectName}\n\n`;
             result += `- **Total files found:** ${stats.totalFiles}\n`;
             result += `- **Files indexed:** ${stats.indexedFiles}\n`;
@@ -177,6 +181,11 @@ export function createIndexingTools(projectName) {
             return result;
         },
         get_index_status: async (_args, ctx) => {
+            // Return cached result if still valid
+            if (_statusCache && Date.now() < _statusCache.expiresAt) {
+                const remainingMin = Math.round((_statusCache.expiresAt - Date.now()) / 60000);
+                return _statusCache.data + `\n_Cached (expires in ${remainingMin}min)_`;
+            }
             const response = await ctx.api.get(`/api/index/status/${ctx.collectionPrefix}codebase`);
             const data = response.data;
             let result = `## Index Status: ${projectName}\n\n`;
@@ -185,6 +194,8 @@ export function createIndexingTools(projectName) {
             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`;
+            // Cache for 30 minutes
+            _statusCache = { data: result, expiresAt: Date.now() + STATUS_CACHE_TTL };
             return result;
         },
         reindex_zero_downtime: async (args, ctx) => {
@@ -195,6 +206,7 @@ export function createIndexingTools(projectName) {
                 excludePatterns,
                 force: true,
             });
+            _statusCache = null; // Invalidate status cache after reindex
             let result = `## Reindex: ${projectName}\n\n`;
             result += `- **Total files found:** ${stats.totalFiles}\n`;
             result += `- **Files indexed:** ${stats.indexedFiles}\n`;

package/dist/tools/suggestions.js

@@ -2,12 +2,33 @@
  * Suggestions tools module - contextual suggestions, related code,
  * implementation suggestions, test suggestions, and code context.
  */
+import * as fs from "fs";
+import * as path from "path";
 import { truncate, pct, PREVIEW } from "../formatters.js";
 /**
  * Create the suggestions tools module with project-specific descriptions.
  */
 export function createSuggestionTools(projectName) {
     const tools = [
+        {
+            name: "context_briefing",
+            description: `REQUIRED before code changes. Parallel lookup of recall + search + patterns + ADRs + graph for ${projectName}. One call replaces 5 separate RAG lookups.`,
+            inputSchema: {
+                type: "object",
+                properties: {
+                    task: {
+                        type: "string",
+                        description: "What you will implement/change",
+                    },
+                    files: {
+                        type: "array",
+                        items: { type: "string" },
+                        description: "Files you plan to modify",
+                    },
+                },
+                required: ["task"],
+            },
+        },
         {
             name: "get_contextual_suggestions",
             description: `Get contextual suggestions based on current work context for ${projectName}. Returns relevant suggestions, triggers, and related memories.`,
@@ -116,8 +137,153 @@ export function createSuggestionTools(projectName) {
                 },
             },
         },
+        {
+            name: "setup_project",
+            description: "Configure Claude Code for RAG integration. Creates/updates .mcp.json, adds RAG instructions to CLAUDE.md, and configures permissions. Call after index_codebase on a new project.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    projectPath: {
+                        type: "string",
+                        description: "Absolute path to project root",
+                    },
+                    projectName: {
+                        type: "string",
+                        description: "Project name in Qdrant (collection prefix)",
+                    },
+                    ragApiUrl: {
+                        type: "string",
+                        description: "RAG API URL (default: from MCP env)",
+                    },
+                    ragApiKey: {
+                        type: "string",
+                        description: "RAG API key (default: from MCP env)",
+                    },
+                    updateClaudeMd: {
+                        type: "boolean",
+                        description: "Add RAG section to CLAUDE.md (default: true)",
+                    },
+                },
+                required: ["projectPath", "projectName"],
+            },
+        },
     ];
     const handlers = {
+        context_briefing: async (args, ctx) => {
+            const { task, files } = args;
+            // 5 parallel lookups
+            const [memoriesRes, searchRes, patternsRes, adrsRes, graphRes] = await Promise.all([
+                // 1. Recall relevant memories
+                ctx.api
+                    .post("/api/memory/recall", {
+                    projectName: ctx.projectName,
+                    query: task,
+                    limit: 5,
+                    type: "all",
+                })
+                    .catch(() => null),
+                // 2. Hybrid search for related code
+                ctx.api
+                    .post("/api/search-hybrid", {
+                    projectName: ctx.projectName,
+                    query: task,
+                    limit: 5,
+                    mode: "navigate",
+                })
+                    .catch(() => null),
+                // 3. Architectural patterns
+                ctx.api
+                    .post("/api/memory/recall", {
+                    projectName: ctx.projectName,
+                    query: task,
+                    type: "context",
+                    limit: 5,
+                    tag: "pattern",
+                })
+                    .catch(() => null),
+                // 4. ADRs
+                ctx.api
+                    .post("/api/memory/recall", {
+                    projectName: ctx.projectName,
+                    query: task,
+                    type: "decision",
+                    limit: 3,
+                    tag: "adr",
+                })
+                    .catch(() => null),
+                // 5. Graph dependencies (if files specified)
+                files && files.length > 0
+                    ? ctx.api
+                        .post("/api/search-graph", {
+                        projectName: ctx.projectName,
+                        query: files[0],
+                        expandHops: 1,
+                        limit: 5,
+                    })
+                        .catch(() => null)
+                    : Promise.resolve(null),
+            ]);
+            let result = `# Context Briefing: ${task}\n\n`;
+            // Memories
+            const memories = memoriesRes?.data?.results || memoriesRes?.data?.memories || [];
+            if (memories.length > 0) {
+                result += `## Memories (${memories.length})\n`;
+                for (const m of memories) {
+                    const mem = m.memory || m;
+                    result += `- [${mem.type || "note"}] ${truncate(mem.content || "", 150)}\n`;
+                }
+                result += "\n";
+            }
+            // Related code
+            const codeResults = searchRes?.data?.results || [];
+            if (codeResults.length > 0) {
+                result += `## Related Code (${codeResults.length})\n`;
+                for (const r of codeResults) {
+                    result += `- \`${r.file}\``;
+                    if (r.symbols?.length)
+                        result += ` — ${r.symbols.join(", ")}`;
+                    result += "\n";
+                }
+                result += "\n";
+            }
+            // Patterns
+            const patterns = (patternsRes?.data?.results || []).filter((r) => r.memory?.tags?.includes("pattern"));
+            if (patterns.length > 0) {
+                result += `## Patterns (${patterns.length})\n`;
+                for (const p of patterns) {
+                    const name = p.memory?.metadata?.patternName || p.memory?.relatedTo || "Pattern";
+                    result += `- **${name}**: ${truncate(p.memory?.content || "", 120)}\n`;
+                }
+                result += "\n";
+            }
+            // ADRs
+            const adrs = (adrsRes?.data?.results || []).filter((r) => r.memory?.tags?.includes("adr"));
+            if (adrs.length > 0) {
+                result += `## ADRs (${adrs.length})\n`;
+                for (const a of adrs) {
+                    const title = a.memory?.metadata?.adrTitle || a.memory?.relatedTo || "ADR";
+                    result += `- **${title}**: ${truncate(a.memory?.content || "", 120)}\n`;
+                }
+                result += "\n";
+            }
+            // Graph dependencies
+            const graphResults = graphRes?.data?.results || graphRes?.data?.directResults || [];
+            const connectedFiles = graphRes?.data?.connectedFiles || graphRes?.data?.expandedResults || [];
+            if (graphResults.length > 0 || connectedFiles.length > 0) {
+                result += `## Dependencies\n`;
+                for (const g of graphResults) {
+                    result += `- \`${g.file}\`\n`;
+                }
+                for (const c of connectedFiles) {
+                    result += `- \`${c.file}\` (connected)\n`;
+                }
+                result += "\n";
+            }
+            if (result.endsWith(`# Context Briefing: ${task}\n\n`)) {
+                result += "_No relevant context found. Proceed with implementation._\n";
+            }
+            return result;
+        },
         get_contextual_suggestions: async (args, ctx) => {
             const { currentFile, currentCode, recentFiles, task } = args;
             const response = await ctx.api.post("/api/suggestions", {
@@ -296,6 +462,116 @@ export function createSuggestionTools(projectName) {
             }
             return result;
         },
+        setup_project: async (args, ctx) => {
+            const { projectPath, projectName: targetProject, ragApiUrl, ragApiKey, updateClaudeMd = true, } = args;
+            const apiUrl = ragApiUrl || process.env.RAG_API_URL || "http://localhost:3100";
+            const apiKey = ragApiKey || process.env.RAG_API_KEY;
+            const serverName = `${targetProject}-rag`;
+            const changes = [];
+            // 1. Create/update .mcp.json
+            const mcpJsonPath = path.join(projectPath, ".mcp.json");
+            let mcpConfig = {};
+            try {
+                const existing = fs.readFileSync(mcpJsonPath, "utf-8");
+                mcpConfig = JSON.parse(existing);
+            }
+            catch {
+                // File doesn't exist or invalid JSON
+            }
+            if (!mcpConfig.mcpServers)
+                mcpConfig.mcpServers = {};
+            const serverEnv = {
+                RAG_API_URL: apiUrl,
+                PROJECT_NAME: targetProject,
+                PROJECT_PATH: projectPath,
+            };
+            if (apiKey)
+                serverEnv.RAG_API_KEY = apiKey;
+            mcpConfig.mcpServers[serverName] = {
+                command: "npx",
+                args: ["-y", "@crowley/rag-mcp@latest"],
+                env: serverEnv,
+            };
+            fs.writeFileSync(mcpJsonPath, JSON.stringify(mcpConfig, null, 2) + "\n");
+            changes.push(`.mcp.json — added \`${serverName}\` server`);
+            // 2. Update CLAUDE.md with RAG section
+            if (updateClaudeMd) {
+                const claudeMdPath = path.join(projectPath, "CLAUDE.md");
+                let claudeMd = "";
+                try {
+                    claudeMd = fs.readFileSync(claudeMdPath, "utf-8");
+                }
+                catch {
+                    // File doesn't exist
+                }
+                const ragSection = `\n## RAG Integration
+
+You MUST call \`context_briefing\` before making any code changes.
+This single tool performs all RAG lookups in parallel (recall, search, patterns, ADRs, graph).
+
+Example: \`context_briefing(task: "describe your change", files: ["path/to/file.ts"])\`
+
+After completing significant changes:
+- \`remember\` — save important context for future sessions
+- \`record_adr\` — document architectural decisions
+`;
+                if (claudeMd.includes("## RAG")) {
+                    changes.push("CLAUDE.md — RAG section already exists, skipped");
+                }
+                else {
+                    claudeMd = claudeMd ? claudeMd.trimEnd() + "\n" + ragSection : `# CLAUDE.md\n${ragSection}`;
+                    fs.writeFileSync(claudeMdPath, claudeMd);
+                    changes.push("CLAUDE.md — added RAG Integration section");
+                }
+            }
+            // 3. Create/update .claude/settings.local.json permissions
+            const claudeDir = path.join(projectPath, ".claude");
+            const settingsPath = path.join(claudeDir, "settings.local.json");
+            let settings = {};
+            try {
+                const existing = fs.readFileSync(settingsPath, "utf-8");
+                settings = JSON.parse(existing);
+            }
+            catch {
+                // File doesn't exist or invalid JSON
+            }
+            if (!settings.permissions)
+                settings.permissions = {};
+            if (!settings.permissions.allow)
+                settings.permissions.allow = [];
+            const mcpPermission = `mcp__${serverName}__*`;
+            if (!settings.permissions.allow.includes(mcpPermission)) {
+                settings.permissions.allow.push(mcpPermission);
+                if (!fs.existsSync(claudeDir))
+                    fs.mkdirSync(claudeDir, { recursive: true });
+                fs.writeFileSync(settingsPath, JSON.stringify(settings, null, 2) + "\n");
+                changes.push(`.claude/settings.local.json — added \`${mcpPermission}\` permission`);
+            }
+            else {
+                changes.push(".claude/settings.local.json — permission already exists, skipped");
+            }
+            // 4. Check index status
+            let indexInfo = "";
+            try {
+                const statusRes = await ctx.api.get(`/api/index/status/${targetProject}_codebase`);
+                const data = statusRes.data;
+                indexInfo = `\n## Index Status\n- **Vectors:** ${data.vectorCount ?? "N/A"}\n- **Status:** ${data.status || "unknown"}\n`;
+            }
+            catch {
+                indexInfo = "\n## Index Status\n_Not indexed yet. Run `index_codebase` first._\n";
+            }
+            let result = `# Project Setup: ${targetProject}\n\n`;
+            result += `## Files Updated\n`;
+            for (const c of changes) {
+                result += `- ${c}\n`;
+            }
+            result += indexInfo;
+            result += `\n## Next Steps\n`;
+            result += `1. Restart Claude Code to load the new MCP server\n`;
+            result += `2. Run \`index_codebase\` if not indexed yet\n`;
+            result += `3. Use \`context_briefing\` before code changes\n`;
+            return result;
+        },
     };
     return { tools, handlers };
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@crowley/rag-mcp",
-  "version": "1.0.4",
+  "version": "1.0.5",
   "description": "Universal RAG MCP Server for any project",
   "type": "module",
   "main": "dist/index.js",