search_conversations

Instructions

Implementation Reference

• server/src/mcp/tools.js:250-310 (handler)

  The main tool handler for 'search_conversations'. Registers the tool with server.tool(), defines the Zod schema (query, projectId, allProjects, limit), calls searchDb.search() with the resolved project scope, formats results as structured JSON with session info and snippets, and returns them as text content. On error, returns an error response.

  // ─── search_conversations ────────────────────────────────────────
  server.tool(
    'search_conversations',
    'Search conversations using full-text search. Defaults to the current project. Set allProjects=true to search across all projects, or pass a specific projectId. Use this when the user asks "did we discuss X before?" or references past work, decisions, or code changes.',
    {
      query: z.string().describe('Search query (supports FTS5: AND, OR, NOT, "exact phrases")'),
      projectId: z.string().optional().describe('Search a specific project (defaults to current)'),
      allProjects: z.boolean().default(false).optional().describe('Search across ALL projects instead of just the current one'),
      limit: z.number().min(1).max(50).default(10).optional().describe('Max results (default 10)'),
    },
    async ({ query, projectId, allProjects = false, limit = 10 }) => {
      try {
        const { searchDb, currentProjectId } = await getServices()
  
        // Determine search scope
        const searchProjectId = allProjects ? undefined : (projectId || currentProjectId)
        const scopeLabel = allProjects
          ? 'all projects'
          : `project "${searchProjectId}"`
  
        const results = await searchDb.search({
          query,
          projectId: searchProjectId,
          limit,
          offset: 0,
        })
  
        if (!results.hits || results.hits.length === 0) {
          return {
            content: [{
              type: 'text',
              text: `No results found for "${query}" in ${scopeLabel}. ${!allProjects ? 'Try allProjects=true to search everywhere.' : ''}`,
            }],
          }
        }
  
        const formatted = results.hits.map(hit => ({
          project: hit.projectName,
          session: hit.sessionTitle || hit.sessionId,
          sessionId: hit.sessionId,
          projectId: hit.projectId,
          role: hit.role,
          snippet: hit.snippet,
          timestamp: hit.timestamp,
          score: hit.score,
        }))
  
        return {
          content: [{
            type: 'text',
            text: `Found ${results.total} results for "${query}" in ${scopeLabel} (showing ${formatted.length}):\n\n${JSON.stringify(formatted, null, 2)}`,
          }],
        }
      } catch (error) {
        return {
          content: [{ type: 'text', text: `Search error: ${error.message}` }],
          isError: true,
        }
      }
    }
  )

• server/src/mcp/tools.js:250-259 (schema)

  Zod schema for search_conversations input: 'query' (required string with FTS5 support), 'projectId' (optional string), 'allProjects' (optional boolean, default false), 'limit' (optional number 1-50, default 10).

  // ─── search_conversations ────────────────────────────────────────
  server.tool(
    'search_conversations',
    'Search conversations using full-text search. Defaults to the current project. Set allProjects=true to search across all projects, or pass a specific projectId. Use this when the user asks "did we discuss X before?" or references past work, decisions, or code changes.',
    {
      query: z.string().describe('Search query (supports FTS5: AND, OR, NOT, "exact phrases")'),
      projectId: z.string().optional().describe('Search a specific project (defaults to current)'),
      allProjects: z.boolean().default(false).optional().describe('Search across ALL projects instead of just the current one'),
      limit: z.number().min(1).max(50).default(10).optional().describe('Max results (default 10)'),
    },

• server/src/mcp/index.js:106-106 (registration)

  The tool is registered via registerTools(server, getServices) call in the main MCP server entry point (index.js). This wires the tools.js module into the McpServer instance.

  registerTools(server, getServices)