Servidor MCP de Astro Docs

Un servidor MCP para proporcionar acceso a la documentación de Astro a los agentes de IA. Este servidor permite a los asistentes de IA consultar y consultar la documentación de Astro al ayudar a los usuarios con tareas relacionadas con Astro.

Este servidor MCP basado en TypeScript implementa un sistema de recuperación de documentación para Astro. Demuestra los conceptos básicos de MCP al proporcionar:

Recursos que representan secciones de la documentación de Astro con URI y metadatos
Herramientas para buscar documentación de Astro
Indicaciones para preguntas y tareas comunes de Astro

Características

Recursos

Enumere y acceda a la documentación de Astro mediante las URI astro-docs://
Cada sección del documento tiene un título, contenido y categoría.
Tipo MIME de texto simple para acceso simple al contenido

Herramientas

search_docs - Buscar documentación de Astro
- Toma una consulta de búsqueda como parámetro obligatorio
- Devuelve las secciones de documentación coincidentes

Indicaciones

explain_astro_islands - Obtenga explicaciones detalladas de la arquitectura de las Islas Astro
astro_project_setup - Guía para configurar un nuevo proyecto Astro
astro_vs_other_frameworks - Compara Astro con otros frameworks web

Estructura del proyecto

src/ - Código fuente del servidor MCP
- index.ts - Implementación del servidor MCP principal
- scripts/ - Scripts de ayuda para compilar y probar
  - build.js : script de compilación que transpila TypeScript y crea scripts de inicio
  - test-client.js : cliente de prueba para verificar la funcionalidad del servidor
bin/ - Scripts ejecutables generados
- astro-docs-mcp - Script de inicio principal para el servidor MCP
build/ - Archivos JavaScript compilados (generados)

Requisitos

Se requiere Node.js v16 o posterior
Se recomienda Node.js v20+ para una mejor compatibilidad
El servidor utiliza la sintaxis de los módulos ES
gestor de paquetes pnpm (preferible a npm)

Instalación

Instalación de dependencias

Instalar dependencias:

pnpm install

Construir el servidor:

pnpm run build

Para desarrollo con reconstrucción automática:

pnpm run watch

Ejecución del servidor

pnpm start
# OR directly
./bin/astro-docs-mcp

Configuración con Claude Desktop

Para utilizar con Claude Desktop, agregue la configuración del servidor:

En MacOS: ~/Library/Application Support/Claude/claude_desktop_config.json En Windows: %APPDATA%/Claude/claude_desktop_config.json

Importante: La configuración debe utilizar la ruta absoluta al script:

{
  "mcp_servers": [
    {
      "id": "astro-docs-mcp",
      "name": "Astro Docs",
      "command": "/full/absolute/path/to/astro-mcp/bin/astro-docs-mcp",
      "type": "built-in"
    }
  ]
}

Reemplace /full/absolute/path/to/astro-mcp/ con la ruta absoluta real a su directorio de instalación.

Por ejemplo, si el repositorio está en /Users/username/projects/astro-mcp , el comando sería:

"/Users/username/projects/astro-mcp/bin/astro-docs-mcp"

Depuración

Dado que los servidores MCP se comunican a través de stdio, la depuración puede ser complicada. Recomendamos usar el Inspector MCP , disponible como script de paquete:

pnpm run inspector

El Inspector proporcionará una URL para acceder a las herramientas de depuración en su navegador.

Pruebas

Se proporciona un cliente de prueba para verificar que el servidor funciona correctamente:

pnpm test
# OR directly
node src/scripts/test-client.js

Esto enviará varios comandos al servidor y mostrará las respuestas.

Solución de problemas

Si encuentra problemas con el servidor:

Problemas de ruta : El problema más común son las rutas incorrectas en la configuración. Asegúrese de lo siguiente:
- Estás utilizando una ruta absoluta al script en claude_desktop_config.json
- La ruta apunta a bin/astro-docs-mcp (no al script raíz)
- El directorio de compilación existe y contiene index.js ( ls -la build/ )
- Todos los scripts tienen permisos de ejecución.
Errores de "Módulo no encontrado" : si ve errores como Cannot find module '/build/index.js' , verifique:
- Que has ejecutado el paso de compilación ( pnpm run build )
- Que el script se esté ejecutando desde el directorio correcto
- Que se estén utilizando rutas absolutas para la ejecución del script
Versión de Node.js : Asegúrate de usar Node.js v16 o posterior. Para obtener mejores resultados, usa la versión 20 o superior.
node --version
Permisos de script : asegúrese de que los scripts tengan permisos de ejecución:
chmod +x bin/astro-docs-mcp src/scripts/build.js src/scripts/test-client.js
Problemas con la salida JSON : Los mensajes de depuración enviados a la salida estándar (stdout) confunden a Claude Desktop, ya que solo espera JSON válido. Nuestros scripts redirigen correctamente toda la salida de depuración a la salida estándar (stderr).

Uso con Claude Desktop

Instale el servidor siguiendo los pasos de instalación anteriores.
Configure Claude Desktop editando el archivo de configuración para incluir la ruta absoluta al script:
{ "mcp_servers": [ { "id": "astro-docs-mcp", "name": "Astro Docs", "command": "/full/absolute/path/to/astro-mcp/bin/astro-docs-mcp", "type": "built-in" } ] }
Reinicie Claude Desktop.
Ahora puedes interactuar con la documentación de Astro usando los siguientes comandos:
- list - Lista de las secciones de documentación de Astro disponibles
- search <query> - Buscar en la documentación de Astro
- read astro-docs:///<id> - Leer una sección específica de la documentación

Mejoras futuras

Obtenga documentación en tiempo real del sitio web de Astro
Añadir secciones de documentación más completas
Implementar soporte para control de versiones de documentación
Agregue ejemplos de código y fragmentos para patrones comunes de Astro

Astro Docs MCP Server

Integrations