apifable

Lee la especificación. Entiende la API. Integra con confianza.

Inglés | 繁體中文

Descripción general

apifable es un servidor MCP que ayuda a la IA a integrar APIs de forma más fluida en proyectos frontend de TypeScript. Facilita la exploración de la estructura de la API, la búsqueda de endpoints y la generación de tipos de TypeScript, proporcionando a tu agente de IA el contexto que necesita para escribir código de integración preciso.

Related MCP server: openapi-mcp-proxy

✨ Características

• 📦 Contexto de API listo para IA — proporciona a la IA la estructura que necesita para entender y trabajar con tu API

• 📘 Soporte para OpenAPI 3.0 / 3.1 — funciona con especificaciones estándar como una fuente de verdad fiable

• 🤖 Servidor MCP para agentes de IA — conéctalo a Claude, Cursor y Windsurf

• 🔍 Herramientas de exploración de API — navega por endpoints, busca por palabras clave e inspecciona detalles completos de peticiones/respuestas

• 🏷️ Generación de tipos de TypeScript — genera definiciones de tipos de TypeScript listas para usar en código frontend

Primeros pasos

Instalación

Ejecuta apifable init para configurar la configuración de tu proyecto:

npx apifable@latest init

Esto crea apifable.config.json en la raíz de tu proyecto. El archivo de configuración debe ser enviado al control de versiones para que la ruta de la especificación se comparta con tu equipo.

Después de que el comando se inicie, puedes elegir entre Archivo manual y URL remota.

1. Archivo manual

Usa este modo si tu especificación OpenAPI ya reside en el proyecto, o si quieres gestionar las actualizaciones de la especificación tú mismo.

init te pedirá la ruta del archivo local, como openapi.yaml.

Luego debes colocar tu especificación OpenAPI en esa ruta manualmente. Cuando la API del backend cambie, también deberás actualizar ese archivo manualmente.

2. URL remota

Usa este modo si tu especificación OpenAPI está disponible desde una URL remota estable, como el endpoint de especificación OpenAPI proporcionado por la documentación de tu API de backend.

init primero te pedirá la URL remota, como https://api.example.com/openapi.yaml, y luego te pedirá la ruta de salida local, como ./openapi.yaml.

[!NOTE] En este modo, init también añade automáticamente la ruta de la especificación local descargada a .gitignore, porque el archivo está destinado a ser actualizado desde la fuente remota.

Luego puedes ejecutar el siguiente comando para descargar la especificación OpenAPI desde la URL remota a tu ruta local (spec.url → spec.path). Siempre que la especificación cambie, simplemente ejecútalo de nuevo para actualizar:

npx apifable@latest fetch

Cabeceras

Para cabeceras no sensibles que pueden compartirse con tu equipo, añade spec.headers a apifable.config.json:

{
  "spec": {
    "path": "openapi.yaml",
    "url": "https://example.com/openapi.yaml",
    "headers": {
      "X-Api-Version": "2"
    }
  }
}

Cabeceras de autenticación (Tokens secretos)

Si la descarga de la especificación OpenAPI remota requiere autenticación (API privada), almacena las cabeceras secretas en .apifable/auth.json. Este archivo no debe ser enviado al control de versiones:

{
  "headers": {
    "Authorization": "Bearer YOUR_SECRET_TOKEN"
  }
}

Tanto apifable.config.json como .apifable/auth.json soportan la sintaxis ${ENV_VAR} en los valores de las cabeceras.

{
  "headers": {
    "Authorization": "Bearer ${MY_API_KEY}"
  }
}

Prioridad de cabeceras (de mayor a menor)

1. Cabeceras de .apifable/auth.json (sobrescribe claves con el mismo nombre)

2. spec.headers de apifable.config.json

Claude Code

Añade lo siguiente a tu .mcp.json:

{
  "mcpServers": {
    "apifable": {
      "command": "npx",
      "args": ["-y", "apifable@latest", "mcp"]
    }
  }
}

Para otros agentes de IA como Cursor y Windsurf, puedes seguir el mismo enfoque para configurar apifable como un servidor MCP.

Uso

Aquí tienes algunos ejemplos de prompts que puedes usar para explorar APIs y construir funcionalidades.

Explorar la API

List all APIs

Show me APIs related to posts

List APIs under the Post tag

Show me the API details for post comments

Show me the API details for GET /posts/{id}/comments

Show me the API details for postComments

Construir una funcionalidad

Implement the post comments feature

Post page: src/pages/posts/[id].tsx

Related APIs:
- GET /posts/{id}/comments (list post comments)
- POST /posts/{id}/comments (create a post comment)

[!TIP] Al escribir un prompt para construir una funcionalidad, incluye contexto relevante: rutas de página, ubicaciones de componentes, APIs relacionadas y cualquier patrón o ejemplo a seguir.

Guía para agentes de IA

Añade lo siguiente al archivo AGENTS.md de tu proyecto para ayudar a los agentes de IA a usar apifable de manera más efectiva:

## API Integration (apifable)

- Always use `get_endpoint` to verify the exact path, method, and parameters before writing integration code. Never assume.
- When presenting endpoint list data from apifable tools, display exactly these columns in order: `Method` (Uppercase), `Path`, `Summary`. Keep all values verbatim, including summary prefixes like `[ 32 - 001 ]`. Do not omit, rename, paraphrase, or add extra columns.
- When saving generated types, store them under `src/types/` and name files by domain (e.g., `src/types/auth.ts`, `src/types/user.ts`), not by OpenAPI tag names.

Lo anterior es un punto de partida recomendado. Siéntete libre de ajustar las columnas de la lista de endpoints y la ruta de la carpeta de tipos para que coincidan con tu proyecto.

Referencia de herramientas MCP

get_spec_info

Devuelve el título, versión, descripción, servidores y todas las etiquetas de la API con sus recuentos de endpoints. Empieza aquí para entender la forma de una especificación desconocida.

list_endpoints_by_tag

Entradas:

• tag (string): El nombre de la etiqueta por la que filtrar

• limit (number, opcional): Máximo de endpoints a devolver

• offset (number, opcional): Número de endpoints a saltar (por defecto: 0)

Devuelve todos los endpoints que pertenecen a la etiqueta dada. La respuesta incluye los campos total, offset y hasMore para la paginación. Incluye una advertencia cuando los resultados superan los 30 elementos y no se especifica un limit.

search_endpoints

Entradas:

• query (string): Palabra clave a buscar

• tag (string, opcional): Restringir la búsqueda a una etiqueta específica

• limit (number, opcional): Máximo de resultados a devolver (por defecto: 10)

Búsqueda por palabra clave a través de operationId, path, summary y description. Los resultados se clasifican por relevancia. Si no se encuentran coincidencias exactas, recurre automáticamente a la búsqueda difusa. La respuesta incluye un campo matchType ("exact" o "fuzzy"); los resultados difusos también incluyen un campo score por resultado.

get_endpoint

Entradas (elige una):

• method (string) + path (string): Método HTTP y ruta del endpoint (ej. get + /users/{id})

• operationId (string): ID de la operación (ej. listUsers)

Devuelve el objeto completo del endpoint, incluyendo parámetros, requestBody y respuestas, con los $ref de componentes internos soportados resueltos en línea.

search_schemas

Entradas:

• query (string): Palabra clave a buscar

• limit (number, opcional): Máximo de resultados a devolver (por defecto: 10)

Búsqueda por palabra clave a través del nombre del esquema y la descripción. Los resultados se clasifican por relevancia. Si no se encuentran coincidencias exactas, recurre automáticamente a la búsqueda difusa. La respuesta incluye un campo matchType ("exact" o "fuzzy"); los resultados difusos también incluyen un campo score por resultado. Los resultados vacíos también pueden incluir un campo message con orientación para el siguiente paso.

get_schema

Entradas:

• name (string): Nombre del esquema de components/schemas

Devuelve el esquema completo con los $ref de componentes internos soportados resueltos.

get_types

Entradas (elige un modo):

• schemas (string[]): Array de nombres de esquemas de components/schemas

• method (string) + path (string): Método HTTP y ruta del endpoint

• operationId (string): ID de la operación (ej. listUsers)

Genera declaraciones de TypeScript autocontenidas como texto de código. En el modo endpoint, sigue los $ref de componentes internos soportados antes de recopilar las dependencias del esquema. Incluye automáticamente dependencias transitivas y no incluye sentencias de importación.

Reglas de modo:

• Usa exactamente un modo por llamada: schemas, method + path, o operationId

• No mezcles modos en la misma llamada

Limitaciones

• No se soportan los $ref externos (ej. referencias a otros archivos o URLs).

• No se soporta OpenAPI 2.0 (Swagger). Solo se soportan las especificaciones OpenAPI 3.0 y 3.1.

Patrocinio

Si crees que este paquete te ha ayudado, considera convertirte en patrocinador para apoyar mi trabajo~ y tu avatar será visible en mis proyectos principales.

Créditos

• @reapi/mcp-openapi — por la inspiración inicial

Licencia

LICENCIA MIT

Historial de estrellas