mcp-adr-analysis-server

Instructions

Implementation Reference

• src/tools/conversation-memory-tool.ts:95-170 (handler)

  The core handler function that implements the query_conversation_history tool. It constructs a SessionQuery from input args, calls memoryManager.querySessions(), formats the results into a markdown summary of matching conversation sessions, and returns an MCP CallToolResult.

  export async function queryConversationHistory(
    args: {
      projectPath?: string;
      dateRange?: { start: string; end: string };
      toolsUsed?: string[];
      keyword?: string;
      limit?: number;
    },
    memoryManager: ConversationMemoryManager
  ): Promise<CallToolResult> {
    try {
      const query: SessionQuery = {
        ...(args.projectPath ? { projectPath: args.projectPath } : {}),
        ...(args.dateRange ? { dateRange: args.dateRange } : {}),
        ...(args.toolsUsed ? { toolsUsed: args.toolsUsed } : {}),
        ...(args.keyword ? { keyword: args.keyword } : {}),
        limit: args.limit ?? 10,
      };
  
      const sessions = await memoryManager.querySessions(query);
  
      if (sessions.length === 0) {
        return {
          content: [
            {
              type: 'text',
              text: 'No conversation sessions found matching the query.',
            },
          ],
        };
      }
  
      let output = `# Conversation History (${sessions.length} sessions found)\n\n`;
  
      sessions.forEach((session, index) => {
        output += `## ${index + 1}. Session ${session.sessionId}\n\n`;
        output += `- **Project**: ${session.projectPath}\n`;
        output += `- **Started**: ${session.startedAt}\n`;
        output += `- **Last Activity**: ${session.lastActivityAt}\n`;
        output += `- **Turns**: ${session.turns.length}\n`;
        output += `- **Total Tokens**: ${session.metadata.totalTokensUsed}\n`;
        output += `- **Tools Used**: ${session.metadata.toolsUsed.join(', ')}\n`;
  
        // Show recent turns
        if (session.turns.length > 0) {
          output += `\n### Recent Turns:\n`;
          const recentTurns = session.turns.slice(-3);
          recentTurns.forEach(turn => {
            output += `- **Turn ${turn.turnNumber}**: ${turn.request.toolName || 'message'} `;
            output += `(${turn.metadata.duration}ms)\n`;
          });
        }
  
        output += `\n`;
      });
  
      return {
        content: [
          {
            type: 'text',
            text: output,
          },
        ],
      };
    } catch (error) {
      return {
        content: [
          {
            type: 'text',
            text: `❌ Failed to query conversation history: ${error instanceof Error ? error.message : String(error)}`,
          },
        ],
        isError: true,
      };
    }
  }

• src/types/conversation-memory.ts:181-199 (schema)

  Type definition for SessionQuery interface, which defines the input parameters used by the tool handler (maps directly to tool args). This serves as the input schema validation for the tool.

  export interface SessionQuery {
    /** Filter by project path */
    projectPath?: string;
  
    /** Filter by date range */
    dateRange?: {
      start: string;
      end: string;
    };
  
    /** Filter by tools used */
    toolsUsed?: string[];
  
    /** Filter by keyword in turns */
    keyword?: string;
  
    /** Limit results */
    limit?: number;
  }

• src/utils/conversation-memory-manager.ts:289-312 (helper)

  The underlying querySessions method in ConversationMemoryManager that performs the actual database/file query for conversation sessions based on the SessionQuery parameters. Called directly by the tool handler.

  async querySessions(query: SessionQuery): Promise<ConversationSession[]> {
    try {
      const sessionFiles = await fs.readdir(this.sessionsDir);
      const sessions: ConversationSession[] = [];
  
      for (const file of sessionFiles) {
        if (!file.endsWith('.json')) continue;
  
        const filePath = path.join(this.sessionsDir, file);
        const data = await fs.readFile(filePath, 'utf-8');
        const session = JSON.parse(data) as ConversationSession;
  
        // Apply filters
        if (query.projectPath && session.projectPath !== query.projectPath) continue;
        if (
          query.toolsUsed &&
          !query.toolsUsed.some(tool => session.metadata.toolsUsed.includes(tool))
        )
          continue;
        if (query.dateRange) {
          const sessionDate = new Date(session.startedAt);
          const start = new Date(query.dateRange.start);
          const end = new Date(query.dateRange.end);
          if (sessionDate < start || sessionDate > end) continue;

• src/tools/tool-catalog.ts:921-939 (schema)

  Metadata and approximate input schema registration in the central TOOL_CATALOG used for dynamic tool discovery and ListTools responses.

  TOOL_CATALOG.set('query_conversation_history', {
    name: 'query_conversation_history',
    shortDescription: 'Query conversation history',
    fullDescription: 'Queries the conversation history for relevant context.',
    category: 'memory',
    complexity: 'simple',
    tokenCost: { min: 500, max: 1500 },
    hasCEMCPDirective: true, // Phase 4.3: Simple tool - history query
    relatedTools: ['get_conversation_snapshot', 'memory_loading'],
    keywords: ['conversation', 'history', 'query', 'search'],
    requiresAI: false,
    inputSchema: {
      type: 'object',
      properties: {
        query: { type: 'string' },
        limit: { type: 'number', default: 20 },
      },
    },
  });