TOYBOX MCP Server

Instructions

Implementation Reference

• src/handlers/list.ts:23-89 (handler)

  Main handler function for list_artifacts tool that gets active repo, lists artifacts using service, generates URLs and formatted message

  export async function listArtifacts(): Promise<ListArtifactsResult> {
    const configService = new ConfigService();
    
    log.info('Starting artifact listing');
    
    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) {
        return {
          success: false,
          artifacts: [],
          galleryUrl: '',
          totalCount: 0,
          error: 'No active TOYBOX repository found. Please run initialize_toybox first or set an active repository.',
        };
      }
  
      const localPath = activeRepo.localPath;
      log.info('Using TOYBOX at path', { localPath });
      
      // Update last used timestamp
      await configService.touchRepository(activeRepo.name);
  
      // Step 2: Initialize services
      const artifactService = new ArtifactService(localPath);
  
      // Step 3: List all artifacts
      log.info('Scanning for artifacts');
      const artifactList = await artifactService.listArtifacts();
  
      // Step 4: Generate URLs for each artifact
      const baseUrl = activeRepo.publishedUrl || `https://example.github.io/${activeRepo.name}`;
      
      const artifactsWithUrls = artifactList.map(artifact => ({
        id: artifact.id,
        metadata: artifact.metadata,
        url: artifactService.generateArtifactUrl(artifact.id, baseUrl),
        standaloneUrl: `${baseUrl}/standalone/${artifact.id}`,
      }));
  
      // Step 5: Group by folders if any
      const groupedArtifacts = groupArtifactsByFolder(artifactsWithUrls);
  
      return {
        success: true,
        artifacts: artifactsWithUrls,
        galleryUrl: baseUrl,
        totalCount: artifactsWithUrls.length,
        message: formatArtifactsList(groupedArtifacts, baseUrl),
      };
  
    } catch (error) {
      const errorMessage = error instanceof Error ? error.message : String(error);
      
      return {
        success: false,
        artifacts: [],
        galleryUrl: '',
        totalCount: 0,
        error: `Failed to list artifacts: ${errorMessage}`,
      };
    }
  }

• src/handlers/list.ts:6-18 (schema)

  Output type definition for list_artifacts result

  export interface ListArtifactsResult {
    success: boolean;
    artifacts: Array<{
      id: string;
      metadata: ArtifactMetadata;
      url: string;
      standaloneUrl: string;
    }>;
    galleryUrl: string;
    totalCount: number;
    message?: string;
    error?: string;
  }

• src/index.ts:159-166 (registration)

  Tool registration in ListToolsRequestHandler, defining name, description, and empty input schema

  {
    name: 'list_artifacts',
    description: 'List all published artifacts in your TOYBOX',
    inputSchema: {
      type: 'object',
      properties: {},
    },
  },

• src/index.ts:251-263 (registration)

  Tool execution handler in CallToolRequestSchema switch statement

  case 'list_artifacts': {
    log.info('Executing list_artifacts');
    const result = await listArtifacts();
    log.info('list_artifacts completed', { artifactCount: result.artifacts?.length || 0 });
    return {
      content: [
        {
          type: 'text',
          text: JSON.stringify(result, null, 2),
        },
      ],
    };
  }

• src/services/artifacts.ts:118-153 (helper)

  Helper method in ArtifactService that scans the artifacts directory, extracts metadata from .tsx files, and returns sorted list

  async listArtifacts(): Promise<Array<{ id: string; metadata: ArtifactMetadata; filePath: string }>> {
    const artifactsDir = path.join(this.repoPath, 'src', 'artifacts');
    
    if (!await fs.pathExists(artifactsDir)) {
      return [];
    }
    
    const artifactFiles = await glob('*.tsx', { cwd: artifactsDir });
    const artifacts: Array<{ id: string; metadata: ArtifactMetadata; filePath: string }> = [];
    
    for (const file of artifactFiles) {
      const filePath = path.join(artifactsDir, file);
      const artifactId = path.basename(file, '.tsx');
      
      // Skip .gitkeep and other non-artifact files
      if (artifactId.startsWith('.') || artifactId === 'index') {
        continue;
      }
      
      try {
        const metadata = await this.extractMetadata(filePath);
        artifacts.push({
          id: artifactId,
          metadata,
          filePath,
        });
      } catch (error) {
        log.error('Failed to read metadata from file', { file, error });
        // Continue with other files
      }
    }
    
    return artifacts.sort((a, b) => 
      new Date(b.metadata.updatedAt).getTime() - new Date(a.metadata.updatedAt).getTime()
    );
  }