TOYBOX MCP Server

Instructions

Implementation Reference

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

  Main handler function that orchestrates listing artifacts: gets active repo, lists from service, generates URLs, formats output.
  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)

  Type definition for the result returned by listArtifacts tool.
  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 the MCP server's tool list: defines 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)

  Dispatch handler in MCP server's CallToolRequest that invokes the listArtifacts function.
  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)

  ArtifactService method that scans the artifacts directory, extracts metadata from each .tsx file, 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() ); }