MCP Documentation Service

MCP Documentation Service

¿Qué es?

MCP Documentation Service es una implementación del Model Context Protocol (MCP) para la gestión de documentación. Proporciona un conjunto de herramientas para leer, escribir y gestionar documentación en markdown con metadatos frontmatter. El servicio está diseñado para funcionar sin problemas con asistentes de IA como Claude en Cursor o Claude Desktop, facilitando la gestión de tu documentación mediante interacciones en lenguaje natural.

Características

• Leer y escribir documentos: Lee y escribe fácilmente documentos markdown con metadatos frontmatter
• Editar documentos: Realiza ediciones precisas basadas en líneas con vista previa de diferencias
• Listar y buscar: Encuentra documentos por contenido o metadatos
• Generación de navegación: Crea estructuras de navegación a partir de tu documentación
• Comprobaciones de salud: Analiza la calidad de la documentación e identifica problemas como metadatos faltantes o enlaces rotos
• Documentación optimizada para LLM: Genera salida consolidada en un solo documento optimizada para modelos de lenguaje grandes
• Integración MCP: Integración perfecta con el Model Context Protocol
• Soporte de frontmatter: Soporte completo para frontmatter YAML en documentos markdown
• Compatibilidad con Markdown: Funciona con archivos markdown estándar

Inicio Rápido

Instalación

Requiere que Node esté instalado en tu máquina.

npm install -g mcp-docs-service

O úsalo directamente con npx:

npx mcp-docs-service /path/to/docs

Integración con Cursor

Para usarlo con Cursor, crea un archivo .cursor/mcp.json en la raíz de tu proyecto:

{
  "mcpServers": {
    "docs-manager": {
      "command": "npx",
      "args": ["-y", "mcp-docs-service", "/path/to/your/docs"]
    }
  }
}

Integración con Claude Desktop

Para usar MCP Docs Service con Claude Desktop:

1. Instala Claude Desktop: Descarga la última versión desde el sitio web de Claude.

2. Configura Claude Desktop para MCP:

   • Abre Claude Desktop
   • Haz clic en el menú de Claude y selecciona "Developer Settings"
   • Esto creará un archivo de configuración en:
     • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
     • Windows: %APPDATA%\Claude\claude_desktop_config.json

3. Edita el archivo de configuración para añadir MCP Docs Service:

{
  "mcpServers": {
    "docs-manager": {
      "command": "npx",
      "args": ["-y", "mcp-docs-service", "/path/to/your/docs"]
      "env": {
        "MCP_NPX_WRAPPER": true
      }
    }
  }
}

Asegúrate de reemplazar /path/to/your/docs con la ruta absoluta a tu directorio de documentación.

4. Reinicia Claude Desktop por completo.

5. Verifica que la herramienta esté disponible: Después de reiniciar, deberías ver un punto verde para la herramienta MCP docs-manager (Cursor Settings > MCP)

6. Solución de problemas:

   • Si el servidor no aparece, revisa los registros en:
     • macOS: ~/Library/Logs/Claude/mcp*.log
     • Windows: %APPDATA%\Claude\logs\mcp*.log
   • Asegúrate de que Node.js esté instalado en tu sistema
   • Verifica que las rutas en tu configuración sean absolutas y válidas

Ejemplos

Usando con Claude en Cursor

Cuando uses Claude en Cursor, puedes invocar las herramientas de dos maneras:

1. Usando lenguaje natural (recomendado):
   • Simplemente pídele a Claude que realice la tarea en lenguaje natural:

Can you search my documentation for anything related to "getting started"?

Please list all the markdown files in my docs directory.

Could you check if there are any issues with my documentation?

2. Usando sintaxis directa de herramientas:
   • Para un control más preciso, puedes usar la sintaxis directa de herramientas:

@docs-manager mcp_docs_manager_read_document path=docs/getting-started.md

@docs-manager mcp_docs_manager_list_documents recursive=true

@docs-manager mcp_docs_manager_check_documentation_health

Usando con Claude Desktop

Cuando uses Claude Desktop, puedes invocar las herramientas de dos maneras:

1. Usando lenguaje natural (recomendado):

Can you read the README.md file for me?

Please find all documents that mention "API" in my documentation.

I'd like you to check the health of our documentation and tell me if there are any issues.

2. Usando el selector de herramientas:
   • Haz clic en el icono de martillo en la esquina inferior derecha del cuadro de entrada
   • Selecciona "docs-manager" de la lista de herramientas disponibles
   • Elige la herramienta específica que quieras usar
   • Completa los parámetros requeridos y haz clic en "Run"

Claude interpretará tus solicitudes en lenguaje natural y usará la herramienta adecuada con los parámetros correctos. No necesitas recordar los nombres exactos de las herramientas ni los formatos de los parámetros: ¡solo describe lo que quieres hacer!

Comandos comunes de herramientas

Aquí tienes algunos comandos comunes que puedes usar con las herramientas:

Leer un documento

@docs-manager mcp_docs_manager_read_document path=docs/getting-started.md

Escribir un documento

@docs-manager mcp_docs_manager_write_document path=docs/new-document.md content="---
title: New Document
description: A new document created with MCP Docs Service
---

# New Document

This is a new document created with MCP Docs Service."

Editar un documento

@docs-manager mcp_docs_manager_edit_document path=README.md edits=[{"oldText":"# Documentation", "newText":"# Project Documentation"}]

Buscar documentos

@docs-manager mcp_docs_manager_search_documents query="getting started"

Generar navegación

@docs-manager mcp_docs_manager_generate_navigation

Contribuciones

¡Las contribuciones son bienvenidas! Así es como puedes contribuir:

1. Haz un fork del repositorio
2. Crea una rama de características: git checkout -b feature/my-feature
3. Haz commit de tus cambios: git commit -am 'Add my feature'
4. Haz push a la rama: git push origin feature/my-feature
5. Envía un pull request

Asegúrate de que tu código siga el estilo existente e incluya las pruebas adecuadas.

Pruebas y cobertura

MCP Docs Service tiene una cobertura de pruebas completa para garantizar fiabilidad y estabilidad. Usamos Vitest para las pruebas y realizamos seguimiento de las métricas de cobertura para mantener la calidad del código.

Ejecutar las pruebas

# Run all tests
npm test

# Run tests with coverage report
npm run test:coverage

El conjunto de pruebas incluye:

• Pruebas unitarias para funciones utilitarias y manejadores
• Pruebas de integración para el flujo de documentos
• Pruebas de extremo a extremo para el servicio MCP

Nuestras pruebas están diseñadas para ser robustas y manejar posibles errores en la implementación, asegurando que pasen incluso si hay problemas con el código subyacente.

Informes de cobertura

Después de ejecutar el comando de cobertura, se generan informes detallados en el directorio coverage:

• Informe HTML: coverage/index.html
• Informe JSON: coverage/coverage-final.json

Mantenemos una alta cobertura de pruebas para garantizar la fiabilidad del servicio, con un enfoque en probar rutas críticas y casos límite.

Salud de la documentación

Usamos MCP Docs Service para mantener la salud de nuestra propia documentación. La puntuación de salud se basa en:

• Integridad de los metadatos (título, descripción, etc.)
• Presencia de enlaces rotos
• Documentos huérfanos (no enlazados desde ningún lugar)
• Formato y estilo consistentes

Puedes comprobar la salud de tu documentación con:

npx mcp-docs-service --health-check /path/to/docs

Documentación consolidada para LLM

MCP Docs Service puede generar un archivo de documentación consolidado optimizado para modelos de lenguaje grandes. Esta función es útil cuando quieres proporcionar todo tu conjunto de documentación a un LLM como contexto:

# Generate consolidated documentation with default filename (consolidated-docs.md)
npx mcp-docs-service --single-doc /path/to/docs

# Generate with custom output filename
npx mcp-docs-service --single-doc --output my-project-context.md /path/to/docs

# Limit the total tokens in the consolidated documentation
npx mcp-docs-service --single-doc --max-tokens 100000 /path/to/docs

La salida consolidada incluye:

• Metadatos del proyecto (nombre, versión, descripción)
• Tabla de contenidos con recuento de tokens para cada sección
• Toda la documentación organizada por secciones con separación clara
• Recuento de tokens para ayudar a mantenerse dentro de los límites de contexto del LLM

Resiliente por defecto

MCP Docs Service está diseñado para ser resiliente por defecto. El servicio maneja automáticamente documentación incompleta o mal estructurada sin fallar:

• Devuelve una puntuación de salud mínima de 80 incluso con problemas
• Crea automáticamente los directorios de documentación faltantes
• Maneja correctamente los directorios de documentación inexistentes
• Continúa procesando incluso cuando los archivos tienen errores
• Proporciona una puntuación flexible para la integridad de metadatos y enlaces rotos

Esto hace que el servicio sea particularmente útil para:

• Proyectos heredados con documentación mínima
• Proyectos en etapas tempranas de desarrollo de documentación
• Al migrar documentación desde otros formatos

El servicio siempre proporcionará comentarios útiles en lugar de fallar, permitiéndote mejorar tu documentación de forma incremental con el tiempo.

Historial de versiones

v0.6.0

• Se añadió la función de documentación consolidada optimizada para LLM (bandera --single-doc)
• Se añadió el recuento de tokens para cada sección de documentación
• Se añadió la personalización de la salida del documento consolidado (bandera --output)
• Se añadió la configuración del límite máximo de tokens (bandera --max-tokens)

v0.5.2

• Resiliencia mejorada mediante la creación automática de directorios de documentación faltantes
• Modo de tolerancia mejorado con una puntuación de salud mínima de 80
• El modo de tolerancia ahora es el predeterminado para las comprobaciones de salud
• Se actualizó la descripción de la herramienta de comprobación de salud para mencionar el modo de tolerancia

v0.5.1

• Se añadió el modo de tolerancia a las comprobaciones de salud
• Se corrigieron problemas con la fiabilidad del conjunto de pruebas
• Se mejoró el manejo de errores en las operaciones de documentos

Documentación

Para obtener información más detallada, consulta nuestra documentación:

• Guía de inicio
• Guía de integración MCP
• Uso del protocolo MCP
• Referencia de la API
• Ejemplos

Licencia

MIT