Saltar al contenido principal

Integración del servidor MCP

docStatic incluye un servidor integrado del Protocolo de Contexto de Modelos (MCP) que permite a los asistentes de IA acceder a tu documentación y comprenderla. Esto proporciona asistencia inteligente para la edición, la búsqueda y el análisis de contenidos.

Descripción general​

El servidor MCP conecta a los asistentes de IA directamente con su documentación de docStatic a través del punto final GraphQL de TinaCMS, lo que les permite:

  • Buscar contenido en la documentación mediante consultas en lenguaje natural
  • Recuperar documentos específicos por ruta o criterios
  • Analizar los patrones de uso de los componentes MDX
  • Comprender la estructura de los documentos y los metadatos
  • Proporcionar asistencia contextual basada en su contenido real

Requisitos previos​

  • Node.js 22.0 o superior, la misma versión que requiere el propio docStatic
  • Un servidor de desarrollo de docStatic en ejecución (npm run dev)
  • Punto final GraphQL de TinaCMS disponible en [localhost](http://localhost:4001/graphql)

Configuración​

1. Instalar las dependencias del servidor MCP​

Desde el directorio principal de docStatic:

npm run mcp:install

Esto instala las dependencias necesarias del servidor MCP en el subdirectorio mcp-server.

2. Compilar el servidor MCP​

npm run mcp:build

Esto compila el código TypeScript del servidor MCP a JavaScript.

3. Iniciar el servidor de desarrollo de docStatic​

El servidor MCP requiere que tu sitio docStatic esté en funcionamiento:

npm run dev

Esto inicia:

  • Docusaurus en [http://localhost:3000](http://localhost:3000`)
  • El panel de administración de TinaCMS en [localhost](http://localhost:3000/admin)
  • El punto final de GraphQL en [localhost](http://localhost:4001/graphql)

4. Ejecutar el servidor MCP​

En una terminal aparte:

npm run mcp:start

Para el desarrollo con reinicio automático ante cambios:

npm run mcp:dev

Herramientas disponibles​

El servidor MCP proporciona varias herramientas que pueden utilizar los asistentes de IA:

Búsqueda de documentos​

  • `search_documents`: Buscar documentos mediante palabras clave
  • `get_document`: Recuperar un documento específico por ruta
  • `list_all_documents`: Obtener los metadatos de todos los documentos

Análisis de contenido​

  • `get_documents_by_tag`: Filtra documentos por etiquetas de taxonomía
  • `analyze_mdx_components`: Identifica los componentes MDX utilizados en los documentos
  • `check_server_status`: Comprueba la conectividad con GraphQL

Configuración con Claude Desktop​

Para utilizar el servidor MCP con Claude Desktop, añade esta configuración a los ajustes de MCP de Claude Desktop:

{
  "mcpServers": {
    "docstatic": {
      "command": "node",
      "args": ["/absolute/path/to/docstatic/mcp-server/dist/server.js"],
      "cwd": "/absolute/path/to/docstatic"
    }
  }
}
Requisitos de trayectoria

Sustituye /absolute/path/to/docstatic por la ruta completa al directorio de tu proyecto docStatic. Tanto la ruta args como la ruta cwd deben ser rutas absolutas.

Comandos de desarrollo​

ComandoDescripciónnpm run mcp:installInstalar las dependencias del servidor MCPnpm run mcp:buildCompilar TypeScript a JavaScriptnpm run mcp:startIniciar el servidor MCP compiladonpm run mcp:devCompilar e iniciar en modo de desarrollo

Solución de problemas​

Problemas comunes​

«El servidor GraphQL no se está ejecutando»

  • Asegúrate de que npm run dev se está ejecutando en el directorio principal
  • Comprueba que se pueda acceder a [localhost](http://localhost:4001/graphql)
  • Comprueba que TinaCMS se haya iniciado por completo

«Conexión rechazada»

  • Confirma que el servidor de desarrollo está en ejecución
  • Comprueba si el puerto 4001 está disponible
  • Verifica que la configuración del cortafuegos no esté bloqueando la conexión

«Documento no encontrado»

  • Utiliza rutas relativas como installation.mdx, en lugar de /docs/installation.mdx
  • Asegúrate de que el documento existe en el directorio docs/
  • Comprueba que el archivo tenga el frontmatter MDX adecuado

Comprobación de la conectividad​

Prueba directamente el punto final de GraphQL:

curl -X POST http://localhost:4001/graphql \
  -H "Content-Type: application/json" \
  -d '{"query":"{ __typename }"}'

Respuesta esperada:

{"data":{"__typename":"Query"}}

Comprobación de los registros del servidor MCP​

El servidor MCP envía sus registros a stderr. Si utilizas Claude Desktop, comprueba los registros de Claude Desktop en busca de mensajes de error procedentes del servidor MCP.

Ventajas para el flujo de trabajo de documentación​

Con la integración de MCP, los asistentes de IA pueden:

  1. Comprender la estructura de tu contenido - Acceder a la taxonomía completa y a la jerarquía de documentos
  2. Ofrecer sugerencias precisas - Basar las recomendaciones en sus patrones de documentación reales
  3. Ayudar a mantener la coherencia - Identificar dónde deben utilizarse contenidos o componentes similares
  4. Agilizar la edición - Encontrar rápidamente contenido relacionado y sugerir mejoras
  5. Analizar patrones: identificar componentes de uso frecuente y lagunas de contenido

Arquitectura​

docStatic Project
├── docs/               # Your MDX documentation files
├── mcp-server/         # MCP server implementation
│   ├── src/server.ts   # Main server logic
│   ├── package.json    # MCP-specific dependencies
│   └── dist/           # Compiled JavaScript
└── tina/               # TinaCMS configuration
    └── config.jsx      # GraphQL schema definition

El servidor MCP actúa como puente entre los asistentes de IA y tu contenido de docStatic, proporcionando acceso estructurado a la documentación a través de la API GraphQL existente de TinaCMS.

Próximos pasos​

Tras configurar el servidor MCP:

  1. Prueba la integración con tu asistente de IA
  2. Explora las capacidades de búsqueda en la documentación
  3. Utiliza herramientas de análisis de contenido para comprender los patrones de tu documentación
  4. Aprovecha la asistencia de IA para los flujos de trabajo de creación y edición de contenido

Para obtener información detallada sobre la implementación del servidor MCP, consulta la página Detalles de la implementación del servidor MCP.