COA Goldfish MCP

Instructions

Implementation Reference

• archive/src/tools/checkpoint-unified.ts:478-514 (handler)

  Main entry point for the 'checkpoint' tool. Infers the action (save, restore, search, timeline) from arguments and dispatches to the appropriate private handler method.

  async handleUnifiedCheckpoint(args: UnifiedCheckpointArgs): Promise<ToolResponse> {
    try {
      // Determine action - use provided action or infer from arguments
      const action = args.action || inferCheckpointAction(args);
      
      // Route to appropriate handler based on action
      switch (action) {
        case 'save':
          return this.handleSave(args);
        case 'restore':
          return this.handleRestore(args);
        case 'search':
          return this.handleSearch(args);
        case 'timeline':
          return this.handleTimeline(args);
        default:
          return {
            content: [
              {
                type: 'text',
                text: `❓ Unknown action: ${action}. Supported actions: save, restore, search, timeline`
              }
            ]
          };
      }
      
    } catch (error) {
      return {
        content: [
          {
            type: 'text',
            text: `❌ Error in checkpoint tool: ${error instanceof Error ? error.message : 'Unknown error'}`
          }
        ]
      };
    }
  }

• archive/src/tools/checkpoint-unified.ts:763-868 (schema)

  Defines the MCP tool schema for 'checkpoint' including name, description, and comprehensive inputSchema with all parameters for different actions (save, restore, search, timeline).

  static getToolSchema() {
    return {
      name: 'checkpoint',
      description: 'Save progress or restore session context. Use after completing tasks, before breaks, when resuming work, or asking "what was I working on?"',
      inputSchema: {
        type: 'object',
        properties: {
          action: {
            type: 'string',
            enum: ['save', 'restore', 'search', 'timeline'],
            description: 'Action to perform. Defaults to "restore" (most common). Use "save" with description to create checkpoint.'
          },
          
          // Save action properties
          description: {
            type: 'string',
            description: 'Checkpoint description (required for save action)'
          },
          highlights: {
            type: 'array',
            items: { type: 'string' },
            description: 'Key achievements or decisions to remember'
          },
          activeFiles: {
            type: 'array',
            items: { type: 'string' },
            description: 'Files currently being worked on'
          },
          gitBranch: {
            type: 'string',
            description: 'Current git branch (auto-detected if not provided)'
          },
          workContext: {
            type: 'string',
            description: 'What you\'re working on or next steps'
          },
          sessionId: {
            type: 'string',
            description: 'Session identifier (auto-generated if not provided)'
          },
          global: {
            type: 'boolean',
            description: 'Store as global checkpoint (visible across all workspaces)',
            default: false
          },
          
          // Restore action properties
          checkpointId: {
            type: 'string',
            description: 'Specific checkpoint ID to restore'
          },
          depth: {
            type: 'string',
            enum: ['minimal', 'highlights', 'full'],
            description: 'Restoration depth',
            default: 'highlights'
          },
          mode: {
            type: 'string',
            enum: ['latest', 'specific', 'search'],
            description: 'Restoration mode',
            default: 'latest'
          },
          
          // Search action properties
          query: {
            type: 'string',
            description: 'Search query for finding specific checkpoints'
          },
          since: {
            type: 'string',
            description: 'Time range for search (e.g., "24h", "1week")'
          },
          limit: {
            type: 'number',
            description: 'Maximum number of results to return',
            default: 10
          },
          
          // Timeline action properties
          range: {
            type: 'string',
            description: 'Time range for timeline: "1h", "24h", "7d", "30d"',
            default: '7d'
          },
          format: {
            type: 'string',
            enum: ['compact', 'detailed'],
            description: 'Timeline display format',
            default: 'compact'
          },
          
          // Common properties
          workspace: {
            type: 'string',
            description: 'Target workspace (path or name)'
          },
          outputFormat: {
            type: 'string',
            enum: ['plain', 'emoji', 'json', 'dual'],
            description: 'Output format override'
          }
        }
      }
    };
  }

• archive/src/index.ts:116-117 (registration)

  Registers the 'checkpoint' tool handler in the MCP server's CallToolRequestSchema handler by dispatching to UnifiedCheckpointTool.handleUnifiedCheckpoint

  case 'checkpoint':
    return await this.unifiedCheckpointTool.handleUnifiedCheckpoint(args as any);

• archive/src/index.ts:87-88 (registration)

  Registers the 'checkpoint' tool schema in the MCP server's ListToolsRequestSchema response

  // Unified checkpoint tool (replaces checkpoint, restore_session, and search functionality)
  UnifiedCheckpointTool.getToolSchema(),

• archive/src/tools/checkpoint-unified.ts:49-72 (helper)

  Helper function that intelligently infers the checkpoint action based on provided arguments, enabling flexible usage without explicit action specification.

  function inferCheckpointAction(args: UnifiedCheckpointArgs): 'save' | 'restore' | 'search' | 'timeline' {
    // If we have description, it's a save (checkpoint creation)
    if (args.description) {
      return 'save';
    }
    
    // If we have query, it's a search
    if (args.query) {
      return 'search';
    }
    
    // If we have range, it's a timeline
    if (args.range) {
      return 'timeline';
    }
    
    // If we have checkpointId or depth specified, it's a restore
    if (args.checkpointId || args.depth || args.mode) {
      return 'restore';
    }
    
    // Default to restore (most common operation)
    return 'restore';
  }