API de Fastly: especificación OpenAPI
Este repositorio contiene una especificación completa y no oficial de OpenAPI 3.0 para la API de Fastly , creada mediante ingeniería inversa de la documentación pública de la API. Ofrece documentación significativamente mejorada en comparación con la documentación web oficial, con descripciones detalladas, ejemplos y esquemas estructurados optimizados tanto para desarrolladores humanos como para agentes de IA.
Componentes clave
Este proyecto proporciona tres recursos clave para trabajar con la API de Fastly:
- Especificación completa de OpenAPI (
fastly-openapi.yaml ): un esquema integral de OpenAPI 3.0 para todos los puntos finales de API de Fastly - Especificación optimizada para IA (
fastly-openapi-mcp.yaml ): un subconjunto optimizado para el consumo de agentes de IA - Servidor de protocolo de contexto de modelo (
fastly-mcp-server/ ): una implementación de servidor MCP que permite que los modelos de IA interactúen con Fastly a través de un protocolo estandarizado
Servidor MCP para la integración de IA
El repositorio incluye un servidor completo de Protocolo de Contexto de Modelo (MCP) para Fastly, disponible en NPM:
# Install globally
npm install -g fastly-mcp-server
# Or run directly
npx fastly-mcp-server run
Este servidor MCP permite a los asistentes y agentes de IA:
- Interactúe con los servicios de Fastly a través del lenguaje natural
- Administrar configuraciones de CDN, configuraciones de almacenamiento en caché y funciones de seguridad
- Realizar la depuración de contenido, la recopilación de estadísticas y la implementación de servicios.
- Acceda a todas las funciones principales de Fastly a través de una interfaz estandarizada
Consulte el directorio fastly-mcp-server para obtener ejemplos de uso detallados y opciones de configuración.
Descargo de responsabilidad
Esta es una especificación no oficial y Fastly no la avala, respalda ni garantiza. Puede estar incompleta o contener imprecisiones. La especificación se proporciona "tal cual", sin garantía de ningún tipo.
Características
- Esquema completo de OpenAPI 3.0 para la API CDN de Fastly
- Documentación mejorada que supera la documentación web oficial en claridad y detalle.
- Esquemas optimizados para IA diseñados específicamente para el consumo por parte de grandes modelos de lenguaje y agentes de IA
- Descripciones detalladas de puntos finales con contexto operativo y ejemplos
- Definiciones de esquema completas para todos los objetos de solicitud y respuesta
- Compatibilidad con todas las principales funcionalidades de la API de Fastly:
- Gestión de servicios
- Configuración del dominio
- Gestión de backend
- Manipulación de VCL
- Controles de caché
- Operaciones de purga
- Diccionarios Edge
- Seguridad WAF
- Puntos finales de registro
- Estadísticas y métricas
- Computación en el borde
Presupuesto
Este repositorio contiene dos especificaciones OpenAPI:
fastly-openapi.yaml
La especificación completa de la API de Fastly, que contiene todos los puntos finales, parámetros y esquemas. Esta especificación:
- Proporciona documentación más completa y estructurada que los documentos web oficiales.
- Incluye descripciones detalladas que explican el contexto de uso, no solo los parámetros.
- Contiene ejemplos consistentes para todas las operaciones y esquemas de datos.
- Es útil para la documentación completa de API y la generación de clientes.
fastly-openapi-mcp.yaml
Un subconjunto simplificado de la API, optimizado específicamente para la interacción con agentes de IA. Esta especificación:
- Contiene solo los puntos finales utilizados con más frecuencia para tareas comunes de Fastly
- Se centra en las operaciones principales necesarias para la gestión diaria.
- Mantiene descripciones detalladas y ejemplos optimizados para la comprensión de IA.
- Prioriza los puntos finales que son más útiles en las interfaces conversacionales
- Sigue una organización basada en tareas que coincide con los flujos de trabajo de los usuarios comunes.
- Reduce el consumo de tokens para contextos de IA mientras maximiza la utilidad
La versión MCP es ideal para la integración con asistentes y herramientas de IA que necesitan interactuar con Fastly a través de interfaces de lenguaje natural.
Uso
Visualización de la documentación
Puede generar documentación interactiva a partir de estas especificaciones utilizando herramientas como:
Ejemplos:
# For the complete API
npx @redocly/cli preview-docs fastly-openapi.yaml
# For the AI-optimized subset
npx @redocly/cli preview-docs fastly-openapi-mcp.yaml
Validación
Para validar las especificaciones:
# For the complete API
npx @stoplight/spectral-cli lint fastly-openapi.yaml
# Or use swagger-cli
npx swagger-cli validate fastly-openapi.yaml
# For the AI-optimized subset
npx @stoplight/spectral-cli lint fastly-openapi-mcp.yaml
Generación de código
Estas especificaciones se pueden utilizar con generadores de código OpenAPI para crear bibliotecas de cliente en varios lenguajes de programación:
# For the complete API
npx @openapitools/openapi-generator-cli generate -i fastly-openapi.yaml -g javascript -o ./client
# For the AI-optimized subset
npx @openapitools/openapi-generator-cli generate -i fastly-openapi-mcp.yaml -g javascript -o ./client-mcp
Preparación del agente
Ambas especificaciones están diseñadas para ser compatibles con agentes, es decir, optimizadas para su uso con agentes y herramientas de IA. Siguen las mejores prácticas para la legibilidad por máquina:
- Descripciones detalladas de operaciones con mayor densidad de información que los documentos oficiales
- Patrones de nombres consistentes en todos los puntos finales relacionados
- Documentación completa del esquema con descripciones detalladas de las propiedades
- Ejemplos para todas las operaciones y componentes del esquema
- Referencias y relaciones entre componentes correctamente estructuradas
La versión MCP lleva la preparación del agente aún más lejos con:
- Selección curada de puntos finales de alto valor para tareas comunes
- Organización orientada a tareas alineada con las intenciones del usuario
- Descripciones mejoradas centradas en contextos conversacionales
- Eliminación de puntos finales especializados que rara vez aparecen en el uso diario
- Optimizado para reducir el consumo de tokens en contextos de IA
Para conocer casos de uso específicos de la especificación MCP, consulte subset.md , que describe las tareas conversacionales comunes y los flujos de trabajo de API correspondientes.
Uso del servidor MCP
Para utilizar el servidor MCP con la configuración de su asistente de IA:
Bollo (Recomendado)
{
"mcpServers": {
"fastly api": {
"command": "bunx",
"args": ["fastly-mcp-server@latest", "run"],
"env": {
"API_KEY_APIKEYAUTH": "your-fastly-api-key"
}
}
}
}
Node.js
{
"mcpServers": {
"fastly": {
"command": "npx",
"args": ["-y", "fastly-mcp-server@latest", "run"],
"env": {
"API_KEY_APIKEYAUTH": "your-fastly-api-key"
}
}
}
}
Nota : Bun es el entorno de ejecución preferido para fastly-mcp-server debido a su rendimiento superior y tiempo de inicio.
Consulte la documentación de fastly-mcp-server para obtener más detalles sobre la configuración y el uso.
Recursos