TOYBOX MCP Server

Instructions

Implementation Reference

• src/handlers/config.ts:20-105 (handler)

  Main handler function that implements the update_config tool: finds the local TOYBOX repo, updates config file via ArtifactService, commits and pushes Git changes, returns success result with summary.

  export async function updateConfig(configUpdates: Partial<ToyboxConfig>): Promise<UpdateConfigResult> {
    try {
      // Step 1: Find local TOYBOX repository
      log.info('Looking for local TOYBOX repository');
      const localPath = await findToyboxRepository();
      
      if (!localPath) {
        return {
          success: false,
          config: {} as ToyboxConfig,
          error: 'No TOYBOX repository found. Please run initialize_toybox first.',
        };
      }
  
      log.info('Found TOYBOX at path', { localPath });
  
      // Step 2: Initialize services
      const gitService = new GitService(localPath);
      const artifactService = new ArtifactService(localPath);
  
      // Step 3: Read current configuration
      const currentConfig = await artifactService.readConfig();
      
      // Step 4: Update configuration
      log.info('Updating configuration');
      await artifactService.updateConfig(configUpdates);
      
      // Step 5: Read updated configuration
      const updatedConfig = await artifactService.readConfig();
  
      // Step 6: Commit changes if there are any
      log.info('Committing configuration changes');
      
      // Pull latest changes first
      try {
        await gitService.pull();
      } catch (error) {
        log.warn('Could not pull changes, proceeding with local state');
      }
  
      // Stage configuration file
      await gitService.addFiles(['TOYBOX_CONFIG.json']);
  
      // Check if there are changes to commit
      const hasChanges = await gitService.hasUncommittedChanges();
      if (hasChanges) {
        const commitMessage = `feat: Update TOYBOX configuration\\n\\n` +
                             `Configuration changes:\\n` +
                             Object.entries(configUpdates)
                               .map(([key, value]) => `- ${key}: ${JSON.stringify(value)}`)
                               .join('\\n');
  
        await gitService.commit(commitMessage);
        await gitService.push();
      }
  
      // Step 7: Format changes summary
      const changes = Object.entries(configUpdates)
        .filter(([key, value]) => currentConfig[key as keyof ToyboxConfig] !== value)
        .map(([key, value]) => `• ${key}: ${JSON.stringify(currentConfig[key as keyof ToyboxConfig])} → ${JSON.stringify(value)}`)
        .join('\\n');
  
      return {
        success: true,
        config: updatedConfig,
        message: `✅ TOYBOX configuration updated successfully!\\n\\n` +
                 `Changes:\\n${changes || 'No changes detected'}\\n\\n` +
                 `Current configuration:\\n` +
                 `• Title: ${updatedConfig.title}\\n` +
                 `• Description: ${updatedConfig.description}\\n` +
                 `• Theme: ${updatedConfig.theme}\\n` +
                 `• Layout: ${updatedConfig.layout}\\n` +
                 `• Show Footer: ${updatedConfig.showFooter}\\n\\n` +
                 `Your changes will be visible on the next site deployment.`,
      };
  
    } catch (error) {
      const errorMessage = error instanceof Error ? error.message : String(error);
      
      return {
        success: false,
        config: {} as ToyboxConfig,
        error: `Failed to update configuration: ${errorMessage}`,
      };
    }
  }

• src/index.ts:168-186 (registration)

  Tool registration in ListToolsRequestSchema handler, defining name, description, and input schema.

    name: 'update_config',
    description: 'Update TOYBOX configuration (title, theme, layout, etc.)',
    inputSchema: {
      type: 'object',
      properties: {
        config: {
          type: 'object',
          properties: {
            title: { type: 'string' },
            description: { type: 'string' },
            theme: { type: 'string', enum: ['auto', 'light', 'dark'] },
            layout: { type: 'string', enum: ['grid', 'list'] },
            showFooter: { type: 'boolean' },
          },
        },
      },
      required: ['config'],
    },
  },

• src/index.ts:265-278 (registration)

  Dispatch handler in CallToolRequestSchema switch statement that invokes the updateConfig function.

  case 'update_config': {
    const { config } = args as { config: Record<string, unknown> };
    log.info('Executing update_config', { config });
    const result = await updateConfig(config);
    log.info('update_config completed', { result });
    return {
      content: [
        {
          type: 'text',
          text: JSON.stringify(result, null, 2),
        },
      ],
    };
  }

• src/handlers/config.ts:10-15 (schema)

  Type definition for the output/result of the updateConfig function.

  export interface UpdateConfigResult {
    success: boolean;
    config: ToyboxConfig;
    message?: string;
    error?: string;
  }

• src/services/artifacts.ts:189-215 (helper)

  ArtifactService method called by the handler to persist config updates to TOYBOX_CONFIG.json file.

  async updateConfig(config: Partial<ToyboxConfig>): Promise<void> {
    const configPath = path.join(this.repoPath, 'TOYBOX_CONFIG.json');
    
    let existingConfig: ToyboxConfig = {
      title: 'My TOYBOX',
      description: 'A collection of my creative artifacts',
      theme: 'auto',
      layout: 'grid',
      showFooter: true,
    };
    
    // Read existing config if it exists
    if (await fs.pathExists(configPath)) {
      try {
        const configContent = await readFile(configPath, 'utf8');
        existingConfig = { ...existingConfig, ...JSON.parse(configContent) };
      } catch (error) {
        log.warn('Failed to read existing config, using defaults');
      }
    }
    
    // Merge with new config
    const updatedConfig = { ...existingConfig, ...config };
    
    // Write updated config
    await writeFile(configPath, JSON.stringify(updatedConfig, null, 2), 'utf8');
  }