@crowley/rag-mcp 1.0.0

package/dist/api-client.d.ts

@@ -0,0 +1,4 @@
+/**
+ * API Client - Shared axios instance for RAG API calls.
+ */
+export declare function createApiClient(ragApiUrl: string, projectName: string, projectPath: string, apiKey?: string): import("axios").AxiosInstance;

package/dist/api-client.js

@@ -0,0 +1,19 @@
+/**
+ * API Client - Shared axios instance for RAG API calls.
+ */
+import axios from "axios";
+export function createApiClient(ragApiUrl, projectName, projectPath, apiKey) {
+    const headers = {
+        "Content-Type": "application/json",
+        "X-Project-Name": projectName,
+        "X-Project-Path": projectPath,
+    };
+    if (apiKey) {
+        headers["Authorization"] = `Bearer ${apiKey}`;
+    }
+    return axios.create({
+        baseURL: ragApiUrl,
+        timeout: 120000,
+        headers,
+    });
+}

package/dist/context-enrichment.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Context Enrichment Middleware
+ *
+ * Automatically enriches MCP tool responses with relevant project context
+ * (memories, patterns, ADRs) by performing semantic recall before each tool call.
+ */
+import type { ToolContext } from "./types.js";
+export interface EnrichmentConfig {
+    enrichableTools: Set<string>;
+    skipTools: Set<string>;
+    maxAutoRecall: number;
+    minRelevance: number;
+    timeoutMs: number;
+}
+/**
+ * Default sets of tools that should/shouldn't be enriched.
+ */
+export declare const DEFAULT_ENRICHABLE_TOOLS: Set<string>;
+export declare const DEFAULT_SKIP_TOOLS: Set<string>;
+export declare class ContextEnricher {
+    private config;
+    constructor(config?: Partial<EnrichmentConfig>);
+    /**
+     * Before hook: auto-recall relevant memories/patterns/ADRs.
+     * Returns a context prefix string or null if nothing relevant found.
+     */
+    before(name: string, args: Record<string, unknown>, ctx: ToolContext): Promise<string | null>;
+    /**
+     * After hook: fire-and-forget session activity tracking.
+     */
+    after(name: string, _args: Record<string, unknown>, _result: string, ctx: ToolContext): void;
+    /**
+     * Extract a semantic query string from tool arguments.
+     */
+    private extractQuery;
+    /**
+     * Recall memories with a hard timeout.
+     */
+    private recallWithTimeout;
+    /**
+     * Format recalled memories into a compact context prefix.
+     */
+    private formatContext;
+}

package/dist/context-enrichment.js

@@ -0,0 +1,190 @@
+/**
+ * Context Enrichment Middleware
+ *
+ * Automatically enriches MCP tool responses with relevant project context
+ * (memories, patterns, ADRs) by performing semantic recall before each tool call.
+ */
+/**
+ * Default sets of tools that should/shouldn't be enriched.
+ */
+export const DEFAULT_ENRICHABLE_TOOLS = new Set([
+    "search_codebase",
+    "hybrid_search",
+    "ask_codebase",
+    "explain_code",
+    "find_feature",
+    "review_code",
+    "generate_tests",
+    "suggest_implementation",
+    "suggest_related_code",
+    "check_architecture",
+    "run_agent",
+]);
+export const DEFAULT_SKIP_TOOLS = new Set([
+    "get_cache_stats",
+    "warm_cache",
+    "get_prediction_stats",
+    "get_tool_analytics",
+    "list_aliases",
+    "backup_collection",
+    "enable_quantization",
+    "list_backups",
+    "get_index_status",
+    "get_project_stats",
+    "get_rag_guidelines",
+    "list_memories",
+    "get_behavior_patterns",
+    "merge_memories",
+    "feedback_search",
+    "feedback_memory",
+    "get_quality_metrics",
+    "get_knowledge_gaps",
+    "get_agent_types",
+    "get_platform_stats",
+]);
+export class ContextEnricher {
+    config;
+    constructor(config = {}) {
+        this.config = {
+            enrichableTools: config.enrichableTools ?? DEFAULT_ENRICHABLE_TOOLS,
+            skipTools: config.skipTools ?? DEFAULT_SKIP_TOOLS,
+            maxAutoRecall: config.maxAutoRecall ?? 3,
+            minRelevance: config.minRelevance ?? 0.6,
+            timeoutMs: config.timeoutMs ?? 2000,
+        };
+    }
+    /**
+     * Before hook: auto-recall relevant memories/patterns/ADRs.
+     * Returns a context prefix string or null if nothing relevant found.
+     */
+    async before(name, args, ctx) {
+        // Skip non-enrichable tools
+        if (this.config.skipTools.has(name))
+            return null;
+        if (!this.config.enrichableTools.has(name))
+            return null;
+        // Extract semantic query from args
+        const query = this.extractQuery(args);
+        if (!query)
+            return null;
+        try {
+            const memories = await this.recallWithTimeout(query, ctx);
+            if (memories.length === 0)
+                return null;
+            return this.formatContext(memories);
+        }
+        catch {
+            // Enrichment should never break tool calls
+            return null;
+        }
+    }
+    /**
+     * After hook: fire-and-forget session activity tracking.
+     */
+    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
+        });
+    }
+    /**
+     * Extract a semantic query string from tool arguments.
+     */
+    extractQuery(args) {
+        // Try common argument patterns in priority order
+        if (typeof args.query === "string" && args.query.length > 0) {
+            return args.query;
+        }
+        if (typeof args.question === "string" && args.question.length > 0) {
+            return args.question;
+        }
+        if (typeof args.description === "string" && args.description.length > 0) {
+            return args.description;
+        }
+        if (typeof args.feature === "string" && args.feature.length > 0) {
+            return args.feature;
+        }
+        if (typeof args.task === "string" && args.task.length > 0) {
+            return args.task;
+        }
+        if (typeof args.code === "string" && args.code.length > 0) {
+            return args.code.slice(0, 200);
+        }
+        return null;
+    }
+    /**
+     * Recall memories with a hard timeout.
+     */
+    async recallWithTimeout(query, ctx) {
+        const controller = new AbortController();
+        const timeout = setTimeout(() => controller.abort(), this.config.timeoutMs);
+        try {
+            // Parallel recall: general memories + decisions/ADRs
+            const [memoriesRes, decisionsRes] = await Promise.all([
+                ctx.api
+                    .post("/api/memory/recall-durable", {
+                    projectName: ctx.projectName,
+                    query,
+                    limit: this.config.maxAutoRecall,
+                    type: "all",
+                }, { signal: controller.signal })
+                    .catch(() => null),
+                ctx.api
+                    .post("/api/memory/recall-durable", {
+                    projectName: ctx.projectName,
+                    query,
+                    limit: 2,
+                    type: "decision",
+                }, { signal: controller.signal })
+                    .catch(() => null),
+            ]);
+            const memories = [];
+            const seenIds = new Set();
+            // Process general memories
+            if (memoriesRes?.data?.memories) {
+                for (const m of memoriesRes.data.memories) {
+                    if (m.score >= this.config.minRelevance && !seenIds.has(m.memory?.id)) {
+                        seenIds.add(m.memory?.id);
+                        memories.push({
+                            type: m.memory?.type || "note",
+                            content: m.memory?.content || "",
+                            score: m.score,
+                        });
+                    }
+                }
+            }
+            // Process decisions/ADRs
+            if (decisionsRes?.data?.memories) {
+                for (const m of decisionsRes.data.memories) {
+                    if (m.score >= this.config.minRelevance && !seenIds.has(m.memory?.id)) {
+                        seenIds.add(m.memory?.id);
+                        memories.push({
+                            type: m.memory?.type || "decision",
+                            content: m.memory?.content || "",
+                            score: m.score,
+                        });
+                    }
+                }
+            }
+            return memories.slice(0, this.config.maxAutoRecall + 2);
+        }
+        finally {
+            clearTimeout(timeout);
+        }
+    }
+    /**
+     * Format recalled memories into a compact context prefix.
+     */
+    formatContext(memories) {
+        const lines = memories.map((m) => `- [${m.type}] ${m.content.slice(0, 150).replace(/\n/g, " ")}`);
+        return `--- Project Context ---\n${lines.join("\n")}\n---`;
+    }
+}

package/dist/formatters.d.ts

@@ -0,0 +1,33 @@
+/**
+ * Shared formatters and content helpers for tool output.
+ */
+/** Content preview length constants */
+export declare const PREVIEW: {
+    readonly SHORT: 100;
+    readonly MEDIUM: 300;
+    readonly LONG: 500;
+    readonly FULL: 800;
+};
+/** Truncate text to max length with ellipsis */
+export declare function truncate(text: string, max: number): string;
+/** Format a score as percentage */
+export declare function pct(score: number): string;
+/** Format code search results into markdown */
+export declare function formatCodeResults(results: Array<{
+    file: string;
+    content: string;
+    score: number;
+    language?: string;
+    startLine?: number;
+    endLine?: number;
+}>, contentLimit?: number): string;
+/** Format memory results into markdown */
+export declare function formatMemoryResults(results: Array<{
+    memory: Record<string, unknown>;
+    score: number;
+}>, emptyMessage?: string): string;
+/** Format a simple list of files with scores */
+export declare function formatFileList(files: Array<{
+    file: string;
+    score?: number;
+}>, emptyMessage?: string): string;

package/dist/formatters.js

@@ -0,0 +1,70 @@
+/**
+ * Shared formatters and content helpers for tool output.
+ */
+/** Content preview length constants */
+export const PREVIEW = {
+    SHORT: 100,
+    MEDIUM: 300,
+    LONG: 500,
+    FULL: 800,
+};
+/** Truncate text to max length with ellipsis */
+export function truncate(text, max) {
+    if (!text || text.length <= max)
+        return text;
+    return text.slice(0, max) + "...";
+}
+/** Format a score as percentage */
+export function pct(score) {
+    return (score * 100).toFixed(1) + "%";
+}
+/** Format code search results into markdown */
+export function formatCodeResults(results, contentLimit = PREVIEW.LONG) {
+    if (!results || results.length === 0)
+        return "No results found.";
+    return results
+        .map((r) => `**${r.file}** (${pct(r.score)} match)\n` +
+        (r.startLine ? `Lines ${r.startLine}-${r.endLine || "?"}\n` : "") +
+        "```" + (r.language || "") + "\n" +
+        truncate(r.content, contentLimit) +
+        "\n```")
+        .join("\n\n---\n\n");
+}
+/** Format memory results into markdown */
+export function formatMemoryResults(results, emptyMessage = "No memories found.") {
+    if (!results || results.length === 0)
+        return emptyMessage;
+    const typeEmojis = {
+        decision: "🎯",
+        insight: "💡",
+        context: "📌",
+        todo: "📋",
+        conversation: "💬",
+        note: "📝",
+    };
+    let result = "";
+    results.forEach((r, i) => {
+        const m = r.memory;
+        const type = m.type;
+        const emoji = type === "todo" && m.status === "done" ? "✅" : (typeEmojis[type] || "📝");
+        result += `### ${i + 1}. ${emoji} ${(type || "note").toUpperCase()}\n`;
+        result += `**Relevance:** ${pct(r.score)}\n`;
+        result += `${m.content}\n`;
+        if (m.relatedTo)
+            result += `*Related to: ${m.relatedTo}*\n`;
+        if (m.tags?.length > 0)
+            result += `*Tags: ${m.tags.join(", ")}*\n`;
+        if (m.status)
+            result += `*Status: ${m.status}*\n`;
+        result += `*${new Date(m.createdAt).toLocaleDateString()}*\n\n`;
+    });
+    return result;
+}
+/** Format a simple list of files with scores */
+export function formatFileList(files, emptyMessage = "No files found.") {
+    if (!files || files.length === 0)
+        return emptyMessage;
+    return files
+        .map((f) => `- ${f.file}${f.score ? ` (${pct(f.score)})` : ""}`)
+        .join("\n");
+}

package/dist/index.d.ts

@@ -0,0 +1,13 @@
+#!/usr/bin/env node
+/**
+ * Universal RAG MCP Server
+ *
+ * A shared MCP server that can be used by any project.
+ * Each project has its own namespace/collection in Qdrant.
+ *
+ * Environment variables:
+ * - PROJECT_NAME: Unique project identifier (e.g., "cypro", "myproject")
+ * - PROJECT_PATH: Path to project codebase for indexing
+ * - RAG_API_URL: URL of the shared RAG API (default: http://localhost:3100)
+ */
+export {};

package/dist/index.js

@@ -0,0 +1,109 @@
+#!/usr/bin/env node
+/**
+ * Universal RAG MCP Server
+ *
+ * A shared MCP server that can be used by any project.
+ * Each project has its own namespace/collection in Qdrant.
+ *
+ * Environment variables:
+ * - PROJECT_NAME: Unique project identifier (e.g., "cypro", "myproject")
+ * - PROJECT_PATH: Path to project codebase for indexing
+ * - RAG_API_URL: URL of the shared RAG API (default: http://localhost:3100)
+ */
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { CallToolRequestSchema, ListToolsRequestSchema, } from "@modelcontextprotocol/sdk/types.js";
+import { createApiClient } from "./api-client.js";
+import { ToolRegistry } from "./tool-registry.js";
+import { ContextEnricher } from "./context-enrichment.js";
+// Tool modules
+import { createSearchTools } from "./tools/search.js";
+import { createAskTools } from "./tools/ask.js";
+import { createIndexingTools } from "./tools/indexing.js";
+import { createMemoryTools } from "./tools/memory.js";
+import { createArchitectureTools } from "./tools/architecture.js";
+import { createDatabaseTools } from "./tools/database.js";
+import { createConfluenceTools } from "./tools/confluence.js";
+import { createPmTools } from "./tools/pm.js";
+import { createReviewTools } from "./tools/review.js";
+import { createAnalyticsTools } from "./tools/analytics.js";
+import { createClusteringTools } from "./tools/clustering.js";
+import { createSessionTools } from "./tools/session.js";
+import { createFeedbackTools } from "./tools/feedback.js";
+import { createSuggestionTools } from "./tools/suggestions.js";
+import { createCacheTools } from "./tools/cache.js";
+import { createGuidelinesTools } from "./tools/guidelines.js";
+import { createAdvancedTools } from "./tools/advanced.js";
+import { createAgentTools } from "./tools/agents.js";
+// Configuration from environment
+const PROJECT_NAME = process.env.PROJECT_NAME || "default";
+const PROJECT_PATH = process.env.PROJECT_PATH || process.cwd();
+const RAG_API_URL = process.env.RAG_API_URL || "http://localhost:3100";
+const RAG_API_KEY = process.env.RAG_API_KEY;
+const COLLECTION_PREFIX = `${PROJECT_NAME}_`;
+// API client
+const api = createApiClient(RAG_API_URL, PROJECT_NAME, PROJECT_PATH, RAG_API_KEY);
+// Mutable tool context shared by all handlers (session state updates in-place)
+const ctx = {
+    api,
+    projectName: PROJECT_NAME,
+    projectPath: PROJECT_PATH,
+    collectionPrefix: COLLECTION_PREFIX,
+    enrichmentEnabled: true,
+};
+// Build tool registry from modules
+const registry = new ToolRegistry();
+registry.register(createSearchTools(PROJECT_NAME));
+registry.register(createAskTools(PROJECT_NAME));
+registry.register(createIndexingTools(PROJECT_NAME));
+registry.register(createMemoryTools(PROJECT_NAME));
+registry.register(createArchitectureTools(PROJECT_NAME));
+registry.register(createDatabaseTools(PROJECT_NAME));
+registry.register(createConfluenceTools(PROJECT_NAME));
+registry.register(createPmTools(PROJECT_NAME));
+registry.register(createReviewTools(PROJECT_NAME));
+registry.register(createAnalyticsTools(PROJECT_NAME));
+registry.register(createClusteringTools(PROJECT_NAME));
+registry.register(createSessionTools(PROJECT_NAME, ctx));
+registry.register(createFeedbackTools(PROJECT_NAME));
+registry.register(createSuggestionTools(PROJECT_NAME));
+registry.register(createCacheTools(PROJECT_NAME));
+registry.register(createGuidelinesTools(PROJECT_NAME));
+registry.register(createAdvancedTools(PROJECT_NAME));
+registry.register(createAgentTools(PROJECT_NAME));
+// Initialize context enrichment middleware
+const enricher = new ContextEnricher({
+    maxAutoRecall: 3,
+    minRelevance: 0.6,
+    timeoutMs: 2000,
+});
+registry.setEnricher(enricher);
+// MCP Server
+const server = new Server({
+    name: `${PROJECT_NAME}-rag`,
+    version: "1.0.0",
+}, {
+    capabilities: {
+        tools: {},
+    },
+});
+// List tools handler
+server.setRequestHandler(ListToolsRequestSchema, async () => ({
+    tools: registry.getTools(),
+}));
+// Call tool handler
+server.setRequestHandler(CallToolRequestSchema, async (request) => {
+    const { name, arguments: args } = request.params;
+    const result = await registry.handle(name, args || {}, ctx);
+    return {
+        content: [{ type: "text", text: result }],
+    };
+});
+// Start server
+async function main() {
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    console.error(`${PROJECT_NAME} RAG MCP server running (collection prefix: ${COLLECTION_PREFIX})`);
+    console.error(`Registered ${registry.getTools().length} tools from 18 modules`);
+}
+main().catch(console.error);

package/dist/tool-registry.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Tool Registry - Registration and dispatch for tool modules.
+ */
+import type { ToolDefinition, ToolModule, ToolContext } from "./types.js";
+import type { ContextEnricher } from "./context-enrichment.js";
+export declare class ToolRegistry {
+    private tools;
+    private handlers;
+    private enricher?;
+    /** Set the context enricher */
+    setEnricher(enricher: ContextEnricher): void;
+    /** Register a tool module */
+    register(module: ToolModule): void;
+    /** Get all registered tool definitions */
+    getTools(): ToolDefinition[];
+    /** Fire-and-forget usage tracking */
+    private trackUsage;
+    /** Dispatch a tool call */
+    handle(name: string, args: Record<string, unknown>, ctx: ToolContext): Promise<string>;
+}

package/dist/tool-registry.js

@@ -0,0 +1,123 @@
+/**
+ * Tool Registry - Registration and dispatch for tool modules.
+ */
+/** Tools that should NOT be tracked (meta/admin tools, avoid recursive tracking) */
+const TRACKING_EXCLUDE = new Set([
+    "get_tool_analytics",
+    "get_knowledge_gaps",
+    "analyze_usage_patterns",
+    "get_behavior_patterns",
+    "get_quality_metrics",
+    "get_cache_stats",
+    "get_prediction_stats",
+    "get_rag_guidelines",
+]);
+/** Summarize tool args into a short string for analytics */
+function summarizeInput(name, args) {
+    // Common patterns: query, question, content, feature, code, file
+    const q = args.query || args.question || args.feature || args.description || args.task || "";
+    if (q && typeof q === "string")
+        return q.slice(0, 200);
+    const content = args.content || args.code || args.diff || "";
+    if (content && typeof content === "string")
+        return content.slice(0, 100);
+    const file = args.file || args.filePath || args.currentFile || "";
+    if (file && typeof file === "string")
+        return file;
+    // Fallback: first string arg
+    for (const v of Object.values(args)) {
+        if (typeof v === "string" && v.length > 0)
+            return v.slice(0, 150);
+    }
+    return name;
+}
+/** Count results from a tool response string */
+function countResults(result) {
+    // Heuristic: count numbered list items, file matches, or "No results" = 0
+    if (result.includes("No results") || result.includes("No matches") || result.includes("not found"))
+        return 0;
+    const numbered = result.match(/^\d+\./gm);
+    if (numbered)
+        return numbered.length;
+    const bullets = result.match(/^[-*] /gm);
+    if (bullets)
+        return bullets.length;
+    return 1;
+}
+export class ToolRegistry {
+    tools = [];
+    handlers = new Map();
+    enricher;
+    /** Set the context enricher */
+    setEnricher(enricher) {
+        this.enricher = enricher;
+    }
+    /** Register a tool module */
+    register(module) {
+        this.tools.push(...module.tools);
+        for (const [name, handler] of Object.entries(module.handlers)) {
+            this.handlers.set(name, handler);
+        }
+    }
+    /** Get all registered tool definitions */
+    getTools() {
+        return this.tools;
+    }
+    /** Fire-and-forget usage tracking */
+    trackUsage(name, args, startTime, success, result, errorMessage, ctx) {
+        if (TRACKING_EXCLUDE.has(name))
+            return;
+        ctx.api
+            .post("/api/track-usage", {
+            projectName: ctx.projectName,
+            sessionId: ctx.activeSessionId,
+            toolName: name,
+            inputSummary: summarizeInput(name, args),
+            startTime,
+            resultCount: success ? countResults(result) : 0,
+            success,
+            errorMessage,
+        })
+            .catch(() => {
+            // Silent — tracking must never break tool execution
+        });
+    }
+    /** Dispatch a tool call */
+    async handle(name, args, ctx) {
+        const handler = this.handlers.get(name);
+        if (!handler) {
+            return `Unknown tool: ${name}`;
+        }
+        const startTime = Date.now();
+        try {
+            // Before: auto-enrich context
+            const contextPrefix = ctx.enrichmentEnabled && this.enricher
+                ? await this.enricher.before(name, args, ctx)
+                : null;
+            // Execute original handler
+            const result = await handler(args, ctx);
+            // After: track interaction (fire-and-forget)
+            if (this.enricher) {
+                this.enricher.after(name, args, result, ctx);
+            }
+            // Track usage (fire-and-forget)
+            this.trackUsage(name, args, startTime, true, result, undefined, ctx);
+            // Prepend context if available
+            return contextPrefix ? contextPrefix + "\n\n" + result : result;
+        }
+        catch (error) {
+            const err = error;
+            const errorMessage = err.message || String(error);
+            // Track failed usage (fire-and-forget)
+            this.trackUsage(name, args, startTime, false, "", errorMessage, ctx);
+            if (err.code === "ECONNREFUSED") {
+                return `Error: Cannot connect to RAG API at ${ctx.api.defaults.baseURL}. Is it running?\n` +
+                    `Start with: cd docker && docker-compose up -d`;
+            }
+            if (err.response) {
+                return `API Error (${err.response.status}): ${JSON.stringify(err.response.data)}`;
+            }
+            return `Error: ${errorMessage}`;
+        }
+    }
+}

package/dist/tools/advanced.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Advanced tools module - memory merging, code completion context,
+ * import suggestions, type context, and behavior patterns.
+ */
+import type { ToolModule } from "../types.js";
+/**
+ * Create the advanced tools module with project-specific descriptions.
+ */
+export declare function createAdvancedTools(projectName: string): ToolModule;