TOYBOX MCP Server

Instructions

Implementation Reference

• src/handlers/publish.ts:11-169 (handler)

  The main handler function `publishArtifact` that executes the tool logic: gets active repo, validates artifact code, generates ID and file content, saves/updates artifact, commits and pushes changes to GitHub, returns success/error with URL.

  export async function publishArtifact(params: PublishArtifactParams): Promise<PublishResult> {
    const { code, metadata } = params;
    const configService = new ConfigService();
  
    log.info('Starting artifact publication', { title: metadata.title, type: metadata.type });
  
    try {
      // Step 1: Get active TOYBOX repository from config
      log.debug('Looking for active TOYBOX repository...');
      log.info('Looking for active TOYBOX repository');
      const activeRepo = await configService.getActiveRepository();
      
      if (!activeRepo) {
        log.error('No active TOYBOX repository found');
        return {
          success: false,
          artifactId: '',
          artifactUrl: '',
          error: 'No active TOYBOX repository found. Please run initialize_toybox first or set an active repository.',
        };
      }
  
      const localPath = activeRepo.localPath;
      log.info('Using TOYBOX repository', { localPath, repoName: activeRepo.name });
      log.info('Using TOYBOX at path', { localPath });
      
      // Update last used timestamp
      await configService.touchRepository(activeRepo.name);
  
      // Step 2: Initialize services
      const gitService = new GitService(localPath);
      const artifactService = new ArtifactService(localPath);
  
      // Step 3: Validate artifact code
      log.debug('Validating artifact code...');
      log.info('Validating artifact code');
      const validation = artifactService.validateArtifactCode(code);
      if (!validation.valid) {
        log.error('Code validation failed', { issues: validation.issues });
        return {
          success: false,
          artifactId: '',
          artifactUrl: '',
          error: `Code validation failed: ${validation.issues.join(', ')}`,
        };
      }
  
      // Step 4: Generate artifact ID and check for conflicts
      const artifactId = artifactService.generateArtifactId(metadata.slug);
      log.info('Generated artifact ID', { artifactId, slug: metadata.slug, title: metadata.title });
      log.info('Generated artifact ID', { artifactId });
  
      // Step 5: Generate artifact file content
      const artifactContent = artifactService.generateArtifactFile(code, metadata);
  
      // Step 6: Pull latest changes to avoid conflicts
      log.debug('Pulling latest changes...');
      log.info('Pulling latest changes');
      try {
        await gitService.pull();
        log.debug('Successfully pulled latest changes');
      } catch (error) {
        log.warn('Could not pull changes, proceeding with local state', { error: error instanceof Error ? error.message : String(error) });
        log.warn('Could not pull changes, proceeding with local state');
      }
  
      // Step 7: Save artifact to filesystem
      log.debug('Saving artifact...');
      log.info('Saving artifact');
      let filePath: string;
      try {
        filePath = await artifactService.saveArtifact(artifactId, artifactContent);
        log.info('Artifact saved successfully', { filePath });
      } catch (error) {
        // If artifact exists, try updating it instead
        if (error instanceof Error && error.message.includes('already exists')) {
          log.info('Artifact exists, updating...', { artifactId });
          log.info('Artifact exists, updating');
          filePath = await artifactService.updateArtifact(artifactId, artifactContent);
          log.info('Artifact updated successfully', { filePath });
        } else {
          throw error;
        }
      }
  
      // Step 8: Stage changes
      log.debug('Staging changes...');
      log.info('Staging changes');
      const relativePath = path.relative(localPath, filePath);
      await gitService.addFiles([relativePath]);
      log.debug('Files staged', { stagedFiles: [relativePath] });
  
      // Step 9: Check if there are changes to commit
      const hasChanges = await gitService.hasUncommittedChanges();
      if (!hasChanges) {
        log.warn('No changes detected, artifact may already be up to date');
        return {
          success: false,
          artifactId,
          artifactUrl: '',
          error: 'No changes detected. Artifact may already be up to date.',
        };
      }
  
      // Step 10: Commit changes
      const commitMessages = [
        `feat: Add/update artifact "${metadata.title}"`,
        `- Type: ${metadata.type}
  - Tags: ${metadata.tags?.join(', ') || 'none'}${metadata.description ? `\n- Description: ${metadata.description}` : ''}
  - Created: ${metadata.createdAt}
  - Updated: ${metadata.updatedAt}`
      ];
  
      log.debug('Committing changes...', { commitMessages });
      log.info('Committing changes');
      await gitService.commit(commitMessages);
      log.info('Changes committed successfully');
  
      // Step 11: Push to GitHub
      log.debug('Pushing to GitHub...');
      log.info('Pushing to GitHub');
      await gitService.push();
      log.info('Changes pushed to GitHub successfully');
  
      // Step 12: Get published URL
      const baseUrl = activeRepo.publishedUrl || `https://example.github.io/${activeRepo.name}`;
      const artifactUrl = artifactService.generateArtifactUrl(artifactId, baseUrl);
      
      log.info('Artifact published successfully', { 
        artifactId, 
        artifactUrl, 
        baseUrl,
        title: metadata.title 
      });
  
      return {
        success: true,
        artifactId,
        artifactUrl,
        message: `✅ Artifact published successfully!\n\n` +
                 `Title: ${metadata.title}\n` +
                 `ID: ${artifactId}\n` +
                 `URL: ${artifactUrl}\n` +
                 `Gallery: ${baseUrl}\n\n` +
                 `Your artifact is now live! It may take a few minutes for GitHub Pages to update.`,
      };
  
    } catch (error) {
      const errorMessage = error instanceof Error ? error.message : String(error);
      log.error('Failed to publish artifact', { error: errorMessage, title: metadata.title });
      
      return {
        success: false,
        artifactId: '',
        artifactUrl: '',
        error: `Failed to publish artifact: ${errorMessage}`,
      };
    }
  }

• src/types.ts:44-49 (schema)

  Zod schema `PublishArtifactParamsSchema` defining input validation for the tool (code and metadata), plus related `PublishArtifactParams` type.

  export const PublishArtifactParamsSchema = z.object({
    code: z.string(),
    metadata: ArtifactMetadataSchema,
  });
  
  export type PublishArtifactParams = z.infer<typeof PublishArtifactParamsSchema>;

• src/index.ts:128-158 (registration)

  Tool registration in `ListToolsRequestSchema` handler: defines `publish_artifact` tool name, description, and inputSchema (JSON schema mirroring the Zod schema).

  {
    name: 'publish_artifact',
    description: 'Publish a new artifact to your TOYBOX. Artifacts are uniquely identified by a slug-based ID with UUID suffix.',
    inputSchema: {
      type: 'object',
      properties: {
        code: {
          type: 'string',
          description: 'The React component code for the artifact (do not include React import - uses new JSX transform)',
        },
        metadata: {
          type: 'object',
          properties: {
            title: { type: 'string', description: 'Display title for the artifact (can include any characters, emojis, etc.)' },
            slug: { 
              type: 'string', 
              description: 'URL-friendly identifier in lowercase kebab-case (e.g., "my-component", "todo-app"). Only lowercase letters, numbers, and hyphens allowed.',
            },
            description: { type: 'string', description: 'Optional description' },
            type: { type: 'string', enum: ['react', 'svg', 'mermaid'], description: 'Artifact type' },
            tags: { type: 'array', items: { type: 'string' }, description: 'Optional tags' },
            folder: { type: 'string', description: 'Optional folder grouping' },
            createdAt: { type: 'string', description: 'ISO date string' },
            updatedAt: { type: 'string', description: 'ISO date string' },
          },
          required: ['title', 'slug', 'type', 'createdAt', 'updatedAt'],
        },
      },
      required: ['code', 'metadata'],
    },
  },

• src/index.ts:236-249 (registration)

  Tool execution routing in `CallToolRequestSchema` handler: switch case for 'publish_artifact' that parses args with schema and calls `publishArtifact` handler.

  case 'publish_artifact': {
    const params = PublishArtifactParamsSchema.parse(args);
    log.info('Executing publish_artifact', { title: params.metadata.title });
    const result = await publishArtifact(params);
    log.info('publish_artifact completed', { result });
    return {
      content: [
        {
          type: 'text',
          text: JSON.stringify(result, null, 2),
        },
      ],
    };
  }

• src/index.ts:16-16 (registration)

  Import statement for the `publishArtifact` handler from './handlers/publish.js'.

  import { publishArtifact } from './handlers/publish.js';