Saltar al contenido principal

Implementación del servidor MCP de docStatic

Un servidor Model Context Protocol (MCP) que proporciona a los asistentes de IA acceso estructurado a su documentación de docStatic a través del punto de conexión GraphQL de TinaCMS.

Descripción general​

Este servidor MCP se conecta a su punto de conexión GraphQL local de TinaCMS (http://localhost:4001/graphql) y proporciona herramientas para:

  • Buscar contenido en la documentación
  • Recuperar documentos específicos
  • Listar todos los documentos disponibles
  • Filtrar documentos por etiquetas
  • Analizar el uso de componentes MDX
  • Verificar la conectividad del servidor

Configuración​

1. Instalar dependencias​

Desde el directorio principal de docStatic:

npm install
# Esto instalará automáticamente las dependencias del servidor MCP a través del hook postinstall

O manualmente:

cd mcp-server
npm install

2. Compilar el servidor​

npm run mcp:build

3. Iniciar el servidor de desarrollo de docStatic​

El servidor MCP requiere que el punto de conexión GraphQL de TinaCMS esté en ejecución:

npm run dev

Esto inicia TinaCMS con Docusaurus en:

4. Ejecutar el servidor MCP​

En una terminal separada:

npm run mcp:start

Herramientas disponibles​

search_documents​

Busca en la documentación usando palabras clave.

Parámetros:

  • query (requerido): Término de búsqueda
  • limit (opcional): Número máximo de resultados (predeterminado: 20)

Ejemplo:

{
  "query": "installation",
  "limit": 10
}

get_document​

Recupera un documento específico por su ruta.

Parámetros:

  • path (requerido): Ruta relativa al documento

Ejemplo:

{
  "path": "installation.mdx"
}

list_all_documents​

Obtiene una lista de todos los documentos disponibles con sus metadatos.

get_documents_by_tag​

Filtra documentos por una etiqueta específica.

Parámetros:

  • tag (requerido): Etiqueta para filtrar

Ejemplo:

{
  "tag": "software_content-management-systems_tinacms"
}

analyze_mdx_components​

Analiza qué componentes MDX se usan en un documento.

Parámetros:

  • path (requerido): Ruta relativa al documento

check_server_status​

Verifica la conectividad del servidor GraphQL.

Uso con Claude Desktop​

Agregue esta configuración a los ajustes MCP de Claude Desktop:

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

Desarrollo​

Modo de vigilancia​

Para el desarrollo activo, use el modo de vigilancia para recompilar automáticamente al detectar cambios:

cd mcp-server
npm run watch

Compilación y ejecución manual​

npm run mcp:build  # Compilar TypeScript
npm run mcp:start  # Iniciar el servidor

Desarrollo con reinicio automático​

npm run mcp:dev    # Compilar e iniciar en un solo comando

Solución de problemas​

Problemas comunes

"GraphQL server is not running"

"Connection refused"

  • Verifique que TinaCMS haya iniciado correctamente
  • Compruebe si el puerto 4001 está bloqueado por un firewall

"Document not found"

  • Asegúrese de que el documento exista en el directorio docs/
  • Use rutas relativas como installation.mdx, no /docs/installation.mdx

Probar el servidor​

Pruebe la conectividad GraphQL:

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

Arquitectura​

La arquitectura del servidor MCP:

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

El servidor MCP:

  1. Se conecta al punto de conexión GraphQL de TinaCMS
  2. Ejecuta consultas GraphQL para obtener datos de los documentos
  3. Proporciona respuestas estructuradas a través del protocolo MCP
  4. Gestiona los casos de error y los problemas de conectividad

Integración con asistentes de IA​

Capacidades de los asistentes de IA

Este servidor MCP permite a los asistentes de IA:

  • Comprender la estructura de su documentación
  • Buscar temas o conceptos específicos
  • Acceder al contenido completo de los documentos
  • Analizar los patrones de uso de componentes MDX
  • Proporcionar asistencia contextual basada en su documentación real

El servidor comprende el formato específico de docStatic, incluidos:

  • Metadatos del encabezado (frontmatter)
  • Uso de componentes MDX (<Admonition>, <Figure>, etc.)
  • Estructura jerárquica de etiquetas
  • Estados del flujo de trabajo de TinaCMS