@crowley/rag-mcp 1.0.1 → 1.0.3

package/dist/formatters.d.ts

@@ -26,6 +26,19 @@ export declare function formatMemoryResults(results: Array<{
     memory: Record<string, unknown>;
     score: number;
 }>, emptyMessage?: string): string;
+/** Format navigate-mode search results as compact navigation pointers */
+export declare function formatNavigationResults(results: Array<{
+    file: string;
+    lines?: [number, number];
+    symbols?: string[];
+    imports?: string[];
+    connections?: string[];
+    layer?: string;
+    service?: string;
+    preview?: string;
+    score: number;
+    graphExpanded?: boolean;
+}>): string;
 /** Format a simple list of files with scores */
 export declare function formatFileList(files: Array<{
     file: string;

package/dist/formatters.js

@@ -60,6 +60,26 @@ export function formatMemoryResults(results, emptyMessage = "No memories found."
     });
     return result;
 }
+/** Format navigate-mode search results as compact navigation pointers */
+export function formatNavigationResults(results) {
+    if (!results?.length)
+        return "No results found.";
+    return results.map(r => {
+        const loc = r.lines ? `:${r.lines[0]}-${r.lines[1]}` : '';
+        let out = `**${r.file}${loc}** (${pct(r.score)})`;
+        if (r.layer)
+            out += ` [${r.layer}]`;
+        if (r.graphExpanded)
+            out += ' _(graph)_';
+        if (r.preview)
+            out += `\n\`${truncate(r.preview, 100)}\``;
+        if (r.symbols?.length)
+            out += `\nSymbols: ${r.symbols.join(', ')}`;
+        if (r.connections?.length)
+            out += `\nConnections: ${r.connections.map(c => '`' + c + '`').join(', ')}`;
+        return out;
+    }).join('\n\n');
+}
 /** Format a simple list of files with scores */
 export function formatFileList(files, emptyMessage = "No files found.") {
     if (!files || files.length === 0)

package/dist/tool-registry.d.ts

@@ -7,8 +7,16 @@ export declare class ToolRegistry {
     private tools;
     private handlers;
     private enricher?;
+    private autoSessionPromise;
     /** Set the context enricher */
     setEnricher(enricher: ContextEnricher): void;
+    /**
+     * Ensure an active session exists before handling a tool call.
+     * Skips for session management tools. Handles post-end_session restart.
+     */
+    private ensureSession;
+    /** Start an auto-session via the RAG API */
+    private doAutoStartSession;
     /** Register a tool module */
     register(module: ToolModule): void;
     /** Get all registered tool definitions */

package/dist/tool-registry.js

@@ -12,6 +12,12 @@ const TRACKING_EXCLUDE = new Set([
     "get_prediction_stats",
     "get_rag_guidelines",
 ]);
+/** Session management tools — skip auto-session to avoid recursion */
+const SESSION_TOOLS = new Set([
+    "start_session",
+    "end_session",
+    "get_session_context",
+]);
 /** Summarize tool args into a short string for analytics */
 function summarizeInput(name, args) {
     // Common patterns: query, question, content, feature, code, file
@@ -48,10 +54,54 @@ export class ToolRegistry {
     tools = [];
     handlers = new Map();
     enricher;
+    autoSessionPromise = null;
     /** Set the context enricher */
     setEnricher(enricher) {
         this.enricher = enricher;
     }
+    /**
+     * Ensure an active session exists before handling a tool call.
+     * Skips for session management tools. Handles post-end_session restart.
+     */
+    async ensureSession(ctx) {
+        if (ctx.activeSessionId)
+            return;
+        // If already starting, wait for it
+        if (this.autoSessionPromise) {
+            await this.autoSessionPromise;
+            return;
+        }
+        this.autoSessionPromise = this.doAutoStartSession(ctx);
+        try {
+            await this.autoSessionPromise;
+        }
+        finally {
+            this.autoSessionPromise = null;
+        }
+    }
+    /** Start an auto-session via the RAG API */
+    async doAutoStartSession(ctx) {
+        try {
+            const response = await ctx.api.post("/api/session/start", {
+                projectName: ctx.projectName,
+                initialContext: "auto-started by MCP tool call",
+            });
+            const session = response.data?.session;
+            const sid = session?.sessionId || response.data?.sessionId;
+            if (sid) {
+                ctx.activeSessionId = sid;
+            }
+            // Fire-and-forget: ensure critical collections exist
+            ctx.api
+                .post("/api/ensure-collections", { projectName: ctx.projectName })
+                .catch(() => {
+                // Silent — must never break tool execution
+            });
+        }
+        catch {
+            // Silent — auto-session must never block tool execution
+        }
+    }
     /** Register a tool module */
     register(module) {
         this.tools.push(...module.tools);
@@ -88,6 +138,10 @@ export class ToolRegistry {
         if (!handler) {
             return `Unknown tool: ${name}`;
         }
+        // Auto-start session on first tool call (skip for session management tools)
+        if (!SESSION_TOOLS.has(name)) {
+            await this.ensureSession(ctx);
+        }
         const startTime = Date.now();
         try {
             // Before: auto-enrich context

package/dist/tools/search.js

@@ -2,7 +2,7 @@
  * Search tools module - codebase search, similarity search, grouped/hybrid search,
  * documentation search, and project statistics.
  */
-import { formatCodeResults, truncate, pct } from "../formatters.js";
+import { formatCodeResults, formatNavigationResults, truncate } from "../formatters.js";
 /**
  * Create the search tools module with project-specific descriptions.
  */
@@ -10,7 +10,7 @@ export function createSearchTools(projectName) {
     const tools = [
         {
             name: "search_codebase",
-            description: `Search the ${projectName} codebase for relevant code. Returns matching files with code snippets and relevance scores.`,
+            description: `Search the ${projectName} codebase. Returns file locations, symbols, and graph connections. Use Read tool to view the actual code at returned locations.`,
             inputSchema: {
                 type: "object",
                 properties: {
@@ -64,7 +64,7 @@ export function createSearchTools(projectName) {
         },
         {
             name: "grouped_search",
-            description: `Search ${projectName} codebase with results grouped by file. Returns one best match per file instead of multiple chunks.`,
+            description: `Search ${projectName} codebase grouped by file. Returns file locations with symbols and connections. Use Read tool to view the actual code.`,
             inputSchema: {
                 type: "object",
                 properties: {
@@ -100,7 +100,7 @@ export function createSearchTools(projectName) {
         },
         {
             name: "hybrid_search",
-            description: `Hybrid search combining keyword matching and semantic similarity for ${projectName}. Better for finding exact terms + related concepts.`,
+            description: `Hybrid search combining keyword matching and semantic similarity for ${projectName}. Returns file locations with symbols and connections. Use Read tool to view code.`,
             inputSchema: {
                 type: "object",
                 properties: {
@@ -186,7 +186,7 @@ export function createSearchTools(projectName) {
         },
         {
             name: "search_graph",
-            description: `Search ${projectName} codebase with graph expansion. Finds semantically similar code plus connected files via import/call relationships.`,
+            description: `Search ${projectName} codebase with graph expansion. Returns file locations plus connected files via import/call relationships. Use Read tool to view code.`,
             inputSchema: {
                 type: "object",
                 properties: {
@@ -216,13 +216,14 @@ export function createSearchTools(projectName) {
                 collection: `${ctx.collectionPrefix}codebase`,
                 query,
                 limit,
+                mode: "navigate",
                 filters: { language, path, layer, service },
             });
             const results = response.data.results;
             if (!results || results.length === 0) {
                 return "No results found for this query.";
             }
-            return formatCodeResults(results, 500);
+            return formatNavigationResults(results);
         },
         search_similar: async (args, ctx) => {
             const { code, limit = 5 } = args;
@@ -246,23 +247,15 @@ export function createSearchTools(projectName) {
                 query,
                 groupBy,
                 limit,
+                mode: "navigate",
                 filters: hasFilters ? filters : undefined,
             });
             const groups = response.data.groups;
             if (!groups || groups.length === 0) {
                 return "No results found.";
             }
-            return groups
-                .map((g) => {
-                const r = g.results[0];
-                return (`**${g[groupBy]}** (score: ${pct(r.score)})\n` +
-                    "```" +
-                    (r.language || "") +
-                    "\n" +
-                    truncate(r.content, 300) +
-                    "\n```");
-            })
-                .join("\n\n---\n\n");
+            const allResults = groups.flatMap((g) => g.results);
+            return formatNavigationResults(allResults);
         },
         hybrid_search: async (args, ctx) => {
             const { query, limit = 10, semanticWeight = 0.7, language, layer, service } = args;
@@ -273,20 +266,14 @@ export function createSearchTools(projectName) {
                 query,
                 limit,
                 semanticWeight,
+                mode: "navigate",
                 filters: hasFilters ? filters : undefined,
             });
             const results = response.data.results;
             if (!results || results.length === 0) {
                 return "No results found.";
             }
-            return results
-                .map((r) => `**${r.file}** (combined: ${pct(r.score)}${r.semanticScore != null ? `, semantic: ${pct(r.semanticScore)}` : ''}${r.keywordScore != null ? `, keyword: ${pct(r.keywordScore)}` : ''})\n` +
-                "```" +
-                (r.language || "") +
-                "\n" +
-                truncate(r.content, 300) +
-                "\n```")
-                .join("\n\n---\n\n");
+            return formatNavigationResults(results);
         },
         search_docs: async (args, ctx) => {
             const { query, limit = 5 } = args;
@@ -329,27 +316,20 @@ export function createSearchTools(projectName) {
                 query,
                 limit,
                 expandHops,
+                mode: "navigate",
             });
             const { results, graphExpanded, expandedFiles } = response.data;
+            if ((!results || results.length === 0) && (!graphExpanded || graphExpanded.length === 0)) {
+                return "No results found.";
+            }
             let output = "";
             if (results && results.length > 0) {
                 output += "**Direct matches:**\n\n";
-                output += results
-                    .map((r) => `**${r.file}** (score: ${pct(r.score)})\n` +
-                    "```" + (r.language || "") + "\n" +
-                    truncate(r.content, 300) + "\n```")
-                    .join("\n\n");
+                output += formatNavigationResults(results);
             }
             if (graphExpanded && graphExpanded.length > 0) {
                 output += "\n\n---\n\n**Graph-connected files:**\n\n";
-                output += graphExpanded
-                    .map((r) => `**${r.file}** (score: ${pct(r.score)})\n` +
-                    "```" + (r.language || "") + "\n" +
-                    truncate(r.content, 300) + "\n```")
-                    .join("\n\n");
-            }
-            if (!output) {
-                return "No results found.";
+                output += formatNavigationResults(graphExpanded);
             }
             if (expandedFiles && expandedFiles.length > 0) {
                 output += `\n\n_Graph expanded to ${expandedFiles.length} additional files._`;

package/dist/tools/session.js

@@ -270,26 +270,32 @@ export function createSessionTools(projectName, sharedCtx) {
                 resumeFrom,
             });
             const data = response.data;
+            const session = data.session;
+            // Extract fields — API returns { session: { sessionId, startedAt, ... } }
+            const sid = session?.sessionId || data.sessionId;
+            const started = session?.startedAt || data.started;
+            const resumedFrom = session?.metadata?.resumedFrom || data.resumedFrom;
+            const initialFiles = session?.currentFiles || data.initialFiles;
             // Update shared context with active session ID
-            if (sharedCtx && data.sessionId) {
-                sharedCtx.activeSessionId = data.sessionId;
+            if (sharedCtx && sid) {
+                sharedCtx.activeSessionId = sid;
             }
             let result = `**Session Started**\n\n`;
-            result += `- **Session ID:** ${data.sessionId}\n`;
-            result += `- **Started:** ${data.started}\n`;
-            if (data.resumedFrom) {
-                result += `- **Resumed From:** ${data.resumedFrom}\n`;
+            result += `- **Session ID:** ${sid}\n`;
+            result += `- **Started:** ${started}\n`;
+            if (resumedFrom) {
+                result += `- **Resumed From:** ${resumedFrom}\n`;
             }
-            if (data.initialFiles && data.initialFiles.length > 0) {
+            if (initialFiles && initialFiles.length > 0) {
                 result += `\n**Initial Files:**\n`;
-                result += data.initialFiles
+                result += initialFiles
                     .map((f) => `- ${f}`)
                     .join("\n");
                 result += "\n";
             }
             // Include prefetch stats if available
-            if (data.session?.metadata?.prefetchStats) {
-                const pf = data.session.metadata.prefetchStats;
+            if (session?.metadata?.prefetchStats) {
+                const pf = session.metadata.prefetchStats;
                 result += `\n**Predictive Prefetch:** ${pf.prefetchedCount ?? 0} resources prefetched\n`;
             }
             // Include briefing if available (Sprint E)

package/package.json

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