COA Goldfish MCP

Instructions

Implementation Reference

• archive/src/tools/session.ts:164-328 (handler)

  The main handler function for the 'summarize_session' tool. Fetches relevant session memories (checkpoints), processes them to extract work areas, highlights, git branches, active files, and generates a comprehensive formatted summary report including overview stats, key accomplishments, recent progress, and involved files.

  async summarizeSession(args: {
    sessionId?: string;
    depth?: 'highlights' | 'full';
    workspace?: string;
    since?: string;
    format?: OutputMode;
  }) {
    const {
      sessionId,
      depth = 'highlights',
      workspace,
      since = '1d',
      format
    } = args;
  
    try {
      let memories: GoldfishMemory[] = [];
      let summaryTitle = '';
  
      if (sessionId) {
        memories = await this.getSessionMemories(sessionId, workspace);
        summaryTitle = `Session ${sessionId} Summary`;
      } else {
        // Summarize recent work
        memories = await this.searchEngine.searchMemories({
          type: 'checkpoint',
          since,
          workspace,
          scope: 'current',
          limit: 50
        });
        summaryTitle = `Work Summary (${since})`;
      }
  
      if (memories.length === 0) {
        return {
          content: [
            {
              type: 'text',
              text: '📝 No checkpoints found for summary. Create checkpoints as you work to enable session summaries.'
            }
          ]
        };
      }
  
      // Extract key information
      const workAreas = new Set<string>();
      const allHighlights: string[] = [];
      const gitBranches = new Set<string>();
      const activeFiles = new Set<string>();
      
      for (const memory of memories) {
        if (typeof memory.content === 'object' && memory.content) {
          const content = memory.content as { 
            description?: string; 
            workContext?: string; 
            gitBranch?: string; 
            activeFiles?: string[]; 
            highlights?: string[] 
          };
          
          // Collect work areas from descriptions
          if (content.description) {
            const workArea = this.extractWorkArea(content.description);
            if (workArea) workAreas.add(workArea);
          }
          
          // Collect highlights
          if (Array.isArray(content.highlights)) {
            allHighlights.push(...content.highlights);
          }
          
          // Collect git info
          if (content.gitBranch) {
            gitBranches.add(content.gitBranch);
          }
          
          // Collect files
          if (Array.isArray(content.activeFiles)) {
            content.activeFiles.forEach((file: string) => activeFiles.add(file));
          }
        }
      }
  
      // Build summary
      const output = [`📝 **${summaryTitle}**\n`];
      
      output.push(`📊 **Overview:**`);
      output.push(`   • ${memories.length} checkpoints`);
      output.push(`   • ${workAreas.size} work areas`);
      if (gitBranches.size > 0) {
        output.push(`   • Branches: ${Array.from(gitBranches).join(', ')}`);
      }
      output.push('');
  
      // Work areas
      if (workAreas.size > 0) {
        output.push('🎯 **Work Areas:**');
        Array.from(workAreas).forEach(area => {
          output.push(`   • ${area}`);
        });
        output.push('');
      }
  
      // Key highlights
      const uniqueHighlights = [...new Set(allHighlights)];
      if (uniqueHighlights.length > 0) {
        output.push('✨ **Key Accomplishments:**');
        uniqueHighlights.slice(-8).forEach(highlight => {
          output.push(`   • ${highlight}`);
        });
        output.push('');
      }
  
      // Recent progress (last few checkpoints)
      if (depth === 'full' && memories.length > 1) {
        output.push('🔄 **Recent Progress:**');
        memories.slice(0, 5).forEach(memory => {
          const age = this.formatAge(memory.timestamp);
          if (typeof memory.content === 'object' && memory.content && 'description' in memory.content) {
            const contentObj = memory.content as { description?: string };
            output.push(`   • ${age}: ${contentObj.description}`);
          }
        });
        output.push('');
      }
  
      // Active files
      if (activeFiles.size > 0) {
        output.push('📁 **Files Involved:**');
        Array.from(activeFiles).slice(0, 10).forEach(file => {
          output.push(`   • ${file}`);
        });
        if (activeFiles.size > 10) {
          output.push(`   ... and ${activeFiles.size - 10} more files`);
        }
      }
  
      const formatted = output.join('\n');
      const data = {
        sessionId: sessionId || undefined,
        timeRange: since,
        workspace,
        achievements: uniqueHighlights.slice(-5),
        nextSteps: [],
        stats: {
          checkpoints: memories.length,
          workAreas: Array.from(workAreas),
          branches: Array.from(gitBranches),
          files: Array.from(activeFiles).slice(0, 10)
        }
      } as const;
      return buildToolContent('session-summary', formatted, data as any, format);
      
    } catch (error) {
      return {
        content: [
          {
            type: 'text',
            text: `❌ Summary failed: ${error instanceof Error ? error.message : String(error)}`
          }
        ]
      };
    }
  }

• archive/src/tools/session.ts:455-485 (schema)

  The JSON schema definition for the 'summarize_session' tool, specifying input parameters: sessionId (optional), depth ('highlights' or 'full'), workspace, since (time range), and format (output mode). Includes detailed descriptions for MCP tool registration.

  {
    name: 'summarize_session',
    description: 'ALWAYS summarize before ending work sessions. Use when user says "done for today" or asks about accomplishments. Creates shareable progress reports. Essential for handoffs and documentation.',
    inputSchema: {
      type: 'object',
      properties: {
        sessionId: {
          type: 'string',
          description: 'Specific session to summarize (optional)'
        },
        depth: {
          type: 'string',
          enum: ['highlights', 'full'],
          description: 'Summary depth: highlights=key points only, full=detailed timeline'
        },
        workspace: {
          type: 'string',
          description: 'Workspace name or path (e.g., "coa-goldfish-mcp" or "C:\\source\\COA Goldfish MCP"). Will be normalized automatically.'
        },
        since: {
          type: 'string',
          description: 'Time range for summary when no sessionId (default: "1d")'
        },
        format: {
          type: 'string',
          enum: ['plain', 'emoji', 'json', 'dual'],
          description: 'Output format override (defaults to env GOLDFISH_OUTPUT_MODE or dual)'
        }
      }
    }
  }