api_spec_list

Instructions

Implementation Reference

• src/tools/api-spec.ts:181-216 (handler)

  The handler for the 'api_spec_list' tool. Registered via server.tool() with an empty schema (no input parameters). Calls storage.listSpecs() and returns the list of imported API specs as JSON, or a message if none exist. Handles errors gracefully.

  server.tool(
    'api_spec_list',
    'Lista todos los specs de API importados. Úsalo para descubrir qué APIs están disponibles.',
    {},
    async () => {
      try {
        const items = await storage.listSpecs()
  
        if (items.length === 0) {
          return {
            content: [
              {
                type: 'text' as const,
                text: 'No hay specs importados. Usa api_import para importar uno.',
              },
            ],
          }
        }
  
        return {
          content: [
            {
              type: 'text' as const,
              text: JSON.stringify(items, null, 2),
            },
          ],
        }
      } catch (error) {
        const message = error instanceof Error ? error.message : String(error)
        return {
          content: [{ type: 'text' as const, text: `Error: ${message}` }],
          isError: true,
        }
      }
    },
  )

• src/tools/api-spec.ts:181-216 (registration)

  Registration of the 'api_spec_list' tool on the MCP server via server.tool(). The function registerApiSpecTools (line 50) is called from src/server.ts (line 65) with the server and storage instances.

  server.tool(
    'api_spec_list',
    'Lista todos los specs de API importados. Úsalo para descubrir qué APIs están disponibles.',
    {},
    async () => {
      try {
        const items = await storage.listSpecs()
  
        if (items.length === 0) {
          return {
            content: [
              {
                type: 'text' as const,
                text: 'No hay specs importados. Usa api_import para importar uno.',
              },
            ],
          }
        }
  
        return {
          content: [
            {
              type: 'text' as const,
              text: JSON.stringify(items, null, 2),
            },
          ],
        }
      } catch (error) {
        const message = error instanceof Error ? error.message : String(error)
        return {
          content: [{ type: 'text' as const, text: `Error: ${message}` }],
          isError: true,
        }
      }
    },
  )

• src/lib/storage.ts:504-520 (helper)

  The storage helper that powers the handler. listSpecs() reads all JSON files from the specs directory, parses each as an ApiSpec, and maps them to ApiSpecListItem objects containing name, source, endpointCount, and version.

  async listSpecs(): Promise<ApiSpecListItem[]> {
    await this.ensureDir('specs')
    const files = await this.listJsonFiles(this.specsDir)
  
    const allSpecs = await Promise.all(
      files.map((file) => this.readJson<ApiSpec>(join(this.specsDir, file))),
    )
  
    return allSpecs
      .filter((spec): spec is ApiSpec => spec !== null)
      .map((spec) => ({
        name: spec.name,
        source: spec.source,
        endpointCount: spec.endpoints.length,
        version: spec.version,
      }))
  }

• src/lib/types.ts:145-150 (schema)

  The ApiSpecListItem interface defining the return shape: name (string), source (string), endpointCount (number), and optional version (string). This is the schema for items returned by api_spec_list.

  export interface ApiSpecListItem {
    name: string
    source: string
    endpointCount: number
    version?: string
  }