Construyendo sitios de Astro con herramientas de IA

Los editores impulsados por IA y las herramientas de codificación agénticas generalmente tienen un buen conocimiento de las APIs principales y conceptos de Astro. Sin embargo, algunos pueden usar APIs más antiguas y podrían no estar al tanto de las nuevas características o cambios recientes en el framework.

Esta guía cubre cómo mejorar las herramientas de IA con conocimiento actualizado de Astro y proporciona mejores prácticas para construir sitios de Astro con asistencia de IA.

Servidor MCP de documentación de Astro

Puedes asegurarte de que tus herramientas de IA tengan conocimiento actualizado de Astro a través del servidor MCP (Model Context Protocol) de la documentación de Astro. Esto proporciona acceso en tiempo real a la última documentación, ayudando a las herramientas de IA a evitar recomendaciones desactualizadas y asegurando que entiendan las mejores prácticas actuales.

A diferencia de los modelos de IA entrenados en datos estáticos, el servidor MCP proporciona acceso a la última documentación de Astro. El servidor es gratuito, de código abierto y se ejecuta de forma remota sin tener que instalar nada localmente.

El servidor MCP de la documentación de Astro utiliza la API de kapa.ai para mantener un índice actualizado de la documentación de Astro.

Detalles del servidor

Nombre: Astro Docs
URL: https://mcp.docs.astro.build/mcp
Transporte: HTTP transmitible

Instalación

El proceso de configuración varía según tu herramienta de desarrollo de IA. Es posible que veas que algunas herramientas se refieren a los servidores MCP como conectores, adaptadores, extensiones o complementos (plugins).

Configuración manual

Muchas herramientas admiten un formato común de configuración JSON para servidores MCP. Si no hay instrucciones específicas para la herramienta elegida, es posible que puedas agregar el servidor MCP de la documentación de Astro incluyendo la siguiente configuración en los ajustes de MCP de tu herramienta:

HTTP transmitible
Proxy local

{
  "mcpServers": {
    "Astro docs": {
      "type": "http",
      "url": "https://mcp.docs.astro.build/mcp"
    }
  }
}

{
  "mcpServers": {
    "Astro docs": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://mcp.docs.astro.build/mcp"]
    }
  }
}

Claude Code CLI

Claude Code es una herramienta de programación basada en agentes que se ejecuta en la línea de comandos. Habilitar el servidor MCP de Astro Docs le permite acceder a la documentación más reciente mientras genera código de Astro.

Instala usando el comando de terminal:

claude mcp add --transport http astro-docs https://mcp.docs.astro.build/mcp

Más información sobre el uso de servidores MCP con Claude Code

Acción de GitHub de Claude Code

Claude Code también proporciona una acción de GitHub que se puede utilizar para ejecutar comandos en respuesta a eventos de GitHub. Habilitar el servidor MCP de la documentación de Astro le permite acceder a la última documentación mientras responde preguntas en los comentarios o genera código de Astro.

Puedes configurarlo para usar el servidor MCP de la documentación de Astro para acceder a la documentación agregando lo siguiente al archivo de flujo de trabajo:

# ...rest of your workflow configuration
- uses: anthropics/claude-code-action@beta
  with:
    anthropic_api_key: ${{ secrets.ANTHROPIC_API_KEY }}
    mcp_config: |
      {
        "mcpServers": {
          "astro-docs": {
            "type": "http",
            "url": "https://mcp.docs.astro.build/mcp"
          }
        }
      }
    allowed_tools: "mcp__astro-docs__search_astro_docs"

Más información sobre el uso de servidores MCP con la acción de GitHub de Claude Code

Codex CLI

Codex CLI es una herramienta de codificación de IA de línea de comandos que puede utilizar el servidor MCP de la documentación de Astro para acceder a la documentación mientras genera código de Astro.

Puedes configurar servidores MCP a nivel global en el archivo ~/.codex/config.toml, o en un archivo .codex/config.toml en la raíz del proyecto.

[mcp_servers.astro-docs]
command = "npx"
args = ["-y", "mcp-remote", "https://mcp.docs.astro.build/mcp"]

Más información sobre el uso de servidores MCP con Codex CLI

Cursor

Cursor es un editor de código con IA. Agregar el servidor MCP de Astro Docs le permite a Cursor acceder a la documentación de Astro más reciente mientras realiza tareas de desarrollo.

Instala haciendo clic en el botón de abajo:

Añadir a Cursor

Más información sobre el uso de servidores MCP con Cursor

Visual Studio Code

Visual Studio Code admite servidores MCP cuando se utiliza Copilot Chat. Agregar el servidor MCP de Astro Docs le permite a VS Code acceder a la documentación de Astro más reciente al responder preguntas o realizar tareas de programación.

Instala haciendo clic en el botón de abajo:

Añadir a VS Code

Más información sobre el uso de servidores MCP con VS Code

Warp

Warp (anteriormente Warp Terminal) es un entorno de desarrollo de agentes diseñado para programar con múltiples agentes de IA. Agregar el servidor MCP de Astro Docs le permite a Warp acceder a la documentación de Astro más reciente al responder preguntas o realizar tareas de programación.

Abre la configuración de tu Warp y ve a AI > MCP Servers > Manage MCP Servers.
Haz clic en “Add”.

Enter the following configuration. You can optionally configure the Astro MCP server to activate on startup using the start_on_launch flag:

{
  "mcpServers": {
    "Astro docs": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://mcp.docs.astro.build/mcp"],
      "env": {},
      "working_directory": null,
      "start_on_launch": true
    }
  }
}

Haz clic en “Save”.

Más información sobre el uso de servidores MCP con Warp

Claude.ai / Claude Desktop

Claude.ai es un asistente de IA de propósito general. Agregar el servidor MCP de Astro Docs le permite acceder a la documentación más reciente al responder preguntas sobre Astro o generar código de Astro.

Navega a los ajustes del conector de Claude.ai.
Haz clic en “Add custom connector”. Es posible que debas desplazarte hacia abajo para encontrar esta opción.
Introduce la URL del servidor: https://mcp.docs.astro.build/mcp.
Establece el nombre como “Astro docs”.

Más información sobre el uso de servidores MCP con Claude.ai

Windsurf

Windsurf es una herramienta de programación basada en agentes potenciada por IA, disponible como plugins de editor o como un editor independiente. Puede usar el servidor MCP de Astro Docs para acceder a la documentación mientras realiza tareas de programación.

Windsurf no admite HTTP transmitible, por lo que requiere una configuración de proxy local:

Abre ~/.codeium/windsurf/mcp_config.json en tu editor.

Añade la siguiente configuración a los ajustes de MCP de tu Windsurf:

{
  "mcpServers": {
    "Astro docs": {
      "command": "npx",
      "args": ["-y", "mcp-remote", "https://mcp.docs.astro.build/mcp"]
    }
  }
}

Guarda la configuración y reinicia Windsurf.

Más información sobre el uso de servidores MCP con Windsurf

Gemini CLI

Gemini CLI es una herramienta de codificación de IA de línea de comandos que puede utilizar el servidor MCP de la documentación de Astro para acceder a la documentación mientras genera código de Astro.

Puedes configurar servidores MCP a nivel global en el archivo ~/.gemini/settings.json, o en un archivo .gemini/settings.json en la raíz del proyecto.

{
  "mcpServers": {
    "Astro docs": {
      "httpUrl": "https://mcp.docs.astro.build/mcp",
    }
  }
}

Más información sobre el uso de servidores MCP con Gemini CLI

Google Antigravity

Google Antigravity es una plataforma de desarrollo basada en agentes.

Abre ~/.gemini/antigravity/mcp_config.json siguiendo la guía para conectar servidores MCP personalizados.

Add the following configuration to mcp_config.json:

{
  "mcpServers": {
    "astro-docs": {
      "serverUrl": "https://mcp.docs.astro.build/mcp"
    }
  }
}

Guarda el archivo y haz clic en “Refresh” en la pestaña “Manage MCPs”.

Zed

Zed admite servidores MCP al utilizar sus capacidades de IA. Puede usar el servidor MCP de Astro Docs para acceder a la documentación mientras realiza tareas de programación.

Abre ~/.config/zed/settings.json en tu editor.

Añade la siguiente configuración a los ajustes de MCP de tu Zed:

{
   "context_servers": {
     "Astro docs": {
       "settings": {},
       "enabled": true,
       "url": "https://mcp.docs.astro.build/mcp"
     }
   }
}

Guarda la configuración.

Más información sobre el uso de servidores MCP con Zed

ChatGPT

Consulta la documentación de MCP de OpenAI para obtener instrucciones de configuración específicas.

Raycast

Raycast puede conectarse a servidores MCP para mejorar sus capacidades de IA. Agregar el servidor MCP de la documentación de Astro permite a Raycast acceder a la última documentación de Astro al responder preguntas.

Instala haciendo clic en el botón de abajo:

Añadir a Raycast

Más información sobre el uso de servidores MCP con Raycast

Opencode AI

Opencode AI es una herramienta de codificación de IA de código abierto basada en terminal que puede usar el servidor MCP de la documentación de Astro para acceder a la documentación mientras genera código de Astro.

Puedes configurar los servidores MCP en tu archivo de configuración de Opencode, normalmente llamado opencode.json, ubicado en la raíz del proyecto o en tu directorio de configuración global (por ejemplo, ~/.config/opencode/opencode.json).

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "Astro docs": {
      "type": "remote",
      "url": "https://mcp.docs.astro.build/mcp",
      "enabled": true
    }
  }
}

Más información sobre el uso de Opencode AI

Agente de codificación de GitHub Copilot

GitHub Copilot se puede utilizar como un agente de codificación impulsado por GitHub Actions. Habilitar el servidor MCP de la documentación de Astro le permite acceder a la última documentación de Astro al responder preguntas o realizar tareas de codificación.

Puedes configurar el agente de codificación para usar el servidor MCP de la documentación de Astro para acceder a la documentación agregando lo siguiente a la configuración del agente de codificación de Copilot de tu repositorio, disponible en https://github.com/<your-org>/<your-repo>/settings/copilot/coding_agent:

{
  "mcpServers": {
    "astro-docs": {
      "type": "http",
      "url": "https://mcp.docs.astro.build/mcp",
      "tools": ["mcp__astro-docs__search_astro_docs"]
    }
  }
}

Aprende más sobre cómo extender el agente de codificación de GitHub Copilot con servidores MCP.

Uso

Una vez configurado, puedes hacer preguntas sobre Astro a tu herramienta de IA, y esta recuperará información directamente de la documentación más reciente. Los agentes de codificación podrán consultar la documentación más reciente al realizar tareas de codificación, y los chatbots podrán responder con precisión preguntas sobre las características, APIs y mejores prácticas de Astro.

Resolución de problemas

Si encuentras problemas:

Verifica que tu herramienta admita transporte HTTP transmitible.
Comprueba que la URL del servidor sea correcta: https://mcp.docs.astro.build/mcp.
Asegúrate de que tu herramienta tenga acceso adecuado a Internet.
Consulta la documentación de integración de MCP específica de tu herramienta.

Si sigues teniendo problemas, abre una incidencia en el repositorio del servidor MCP de documentación de Astro.

Soporte de IA en Discord

La misma tecnología que impulsa el servidor MCP de Astro también está disponible como un chatbot en el Discord de Astro para soporte de autoservicio. Visita el canal #support-ai para hacer preguntas sobre Astro o el código de tu proyecto en lenguaje natural. Tu conversación se organiza automáticamente en un hilo, y puedes hacer un número ilimitado de preguntas de seguimiento.

Las conversaciones con el chatbot son públicas y están sujetas a las mismas reglas del servidor en cuanto a lenguaje y comportamiento que el resto de nuestros canales, pero no son visitadas activamente por nuestros miembros voluntarios de soporte. Para obtener asistencia de la comunidad, crea un hilo en nuestro canal regular #support.

Modo en segundo plano

Añadido en: astro@7.0.0 Nuevo

Cuando se detecta un agente de codificación de IA, astro dev inicia automáticamente el servidor de desarrollo como un proceso independiente en segundo plano. Esto evita que el servidor de desarrollo bloquee la terminal del agente y le permite seguir trabajando mientras se ejecuta el servidor.

Se escribe un archivo de bloqueo (.astro/dev.json) cuando se inicia el servidor de desarrollo, registrando la URL, el puerto y el PID del servidor. Esto evita que se inicien servidores duplicados para el mismo proyecto.

Si no estás utilizando un agente de codificación de IA, astro dev se inicia en primer plano e imprime logs en la terminal.

Para desactivar el modo automático en segundo plano, establece la variable de entorno ASTRO_DEV_BACKGROUND antes de ejecutar astro dev:

ASTRO_DEV_BACKGROUND=0 astro dev

Consulta la referencia de la CLI para obtener la lista completa de flags y subcomandos de astro dev.

Endpoint de salud

El servidor de desarrollo expone un endpoint /_astro/status que devuelve {"ok": true} en formato JSON. Esto permite a los agentes y otras herramientas comprobar mediante programación si el servidor de desarrollo está listo para aceptar solicitudes. Este endpoint solo está disponible en el servidor de desarrollo y no existe en los builds de producción.

Consejos para el desarrollo de Astro impulsado por IA

Comienza con plantillas: En lugar de construir desde cero, pide a las herramientas de IA que comiencen con una plantilla de Astro existente o utilicen npm create astro@latest con una opción de plantilla.
Usa astro add para integraciones: Pide a las herramientas de IA que utilicen astro add para integraciones oficiales (por ejemplo, astro add tailwind, astro add react). Para otros paquetes, instálalos usando el comando de tu gestor de paquetes preferido en lugar de editar package.json directamente.
Verifica las APIs actuales: Las herramientas de IA pueden utilizar patrones obsoletos. Pídeles que comprueben la documentación más reciente, especialmente para características más nuevas como las sesiones y acciones. Esto también es importante para características que han experimentado cambios significativos desde su lanzamiento inicial, como las colecciones de contenido, o características previamente experimentales que ya no lo son.
Usa reglas de proyecto: Si tu herramienta de IA lo admite, configura reglas de proyecto para imponer mejores prácticas y estándares de codificación, como los enumerados anteriormente.

Contribuir Comunidad Patrocinar