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:

Construir el servidor:

Para desarrollo con reconstrucción automática:

Ejecución del servidor

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:

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:

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:

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:

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

Solución de problemas

Si encuentra problemas con el servidor:

1. 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.

2. 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

3. 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

4. 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

5. 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

1. Instale el servidor siguiendo los pasos de instalación anteriores.

2. 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" } ] }

3. Reinicie Claude Desktop.

4. 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