Read Docs MCP

Permite que los agentes de IA accedan y comprendan la documentación de paquetes de repositorios locales o

GitHub
7
Prueba este MCPPatrocinado

Documentación

read-docs-mcp

Un servidor del Protocolo de Contexto de Modelos (MCP) que permite a los agentes de IA acceder y comprender la documentación de paquetes a través de una interfaz estructurada.

Características

  • Genera automáticamente herramientas MCP a partir de la estructura de documentación
  • Soporta múltiples módulos de documentación (hooks, componentes, utilidades, etc.)
  • Patrones de nomenclatura configurables para archivos de documentación y carpetas de módulos
  • Proporciona acceso a listados, resúmenes y documentación detallada
  • Generación dinámica de herramientas basada en módulos configurados
  • Recurso alternativo a package.json para información de versión
  • Ruta de documentación personalizable
  • Capacidad de búsqueda difusa para encontrar archivos por palabra clave con priorización inteligente

Modos de Uso Duales

Este servidor MCP tiene dos modos de uso distintos:

  1. Modo Lectura de Documentación (read-docs-{name}): Cuando se proporcionan tanto name como git-repo-path, el servidor funciona como un lector de documentos para el repositorio especificado, generando herramientas para acceder a la documentación.

  2. Modo Creación de Documentación (create-read-docs): Cuando no se proporciona información del repositorio, el servidor funciona como una guía para crear la estructura de documentación, proporcionando instrucciones sobre cómo configurar los archivos de documentación.

Configuración

El MCP soporta los siguientes argumentos de línea de comandos:

  • --name: Nombre del paquete/biblioteca (requerido para el Modo Lectura de Documentación)
  • --git-repo-path: Ruta al repositorio git (http o ssh) (requerido para el Modo Lectura de Documentación)
    • Si no se proporciona, el servidor MCP solo proporcionará instrucciones de construcción
  • --personal-token: Token de acceso personal para autenticación git (opcional)
    • Recomendado para repositorios privados
    • Soporta GitHub, GitLab, Bitbucket y alojamiento git genérico
  • --branch: Rama desde la que leer la documentación
    • Predeterminado: main
  • --docs-path: Ruta a la carpeta de documentación
    • Predeterminado: docs
  • --clone-location: Ruta para clonar el repositorio git
    • Predeterminado: {directorio de inicio del sistema operativo}/.temp-repo
  • --mode: Modo de operación para el servidor MCP
    • Opciones: normal (predeterminado), two-step
    • Consulte la sección Modos de Operación para más detalles
  • --include-src: Incluir capacidad de lectura de código fuente (opcional)
    • Establezca en true para habilitar la lectura de archivos fuente del repositorio
    • Predeterminado: false
    • Cuando está habilitado, añade una herramienta para leer archivos de código fuente para obtener detalles adicionales de implementación

Nota Importante sobre Autenticación Git

Este MCP requiere la clonación directa del repositorio git de destino. Debe asegurarse de tener acceso adecuado al repositorio antes de usar esta herramienta. Para repositorios privados, tiene varias opciones de autenticación:

  1. Uso de Token de Acceso Personal (Recomendado): Pase su token de acceso personal usando el argumento --personal-token. Este es el método más confiable y funciona con todos los principales proveedores de alojamiento git.
  2. Claves SSH: Configure claves SSH en su máquina local para URLs SSH
  3. Almacenamiento de Credenciales Git: Configure el almacenamiento de credenciales Git en su máquina para URLs HTTPS

Uso de Token de Acceso Personal:

# With HTTPS URL
npx -y read-docs-mcp --name=MyDocs --git-repo-path=https://github.com/user/private-repo --personal-token=your_personal_access_token_here

# With SSH URL (automatically converted to HTTPS)
npx -y read-docs-mcp --name=MyDocs --git-repo-path=git@gitlab.service-hub.tech:frontend/private-repo.git --personal-token=your_personal_access_token_here

El MCP soporta tokens de acceso personal tanto para URLs HTTPS como SSH:

URLs HTTPS:

  • GitHub: Usa el token directamente en la URL HTTPS
  • GitLab (incluido el autoalojado): Usa el formato OAuth2 con el token
  • Bitbucket: Usa el formato token-auth
  • Alojamiento Git Genérico: Usa el formato OAuth2 (estilo GitLab)

URLs SSH: Cuando se proporciona un token personal, las URLs SSH se convierten automáticamente a HTTPS con autenticación adecuada:

  • SSH: git@gitlab.service-hub.tech:frontend/repo.git
  • HTTPS: https://oauth2:token@gitlab.service-hub.tech/frontend/repo.git

Sin autenticación adecuada, el MCP fallará al clonar repositorios privados.

Modos de Operación

Puede especificar diferentes modos al ejecutar el servidor MCP usando el argumento --mode:

Modo Normal (predeterminado)

npx -y read-docs-mcp --name=MyDocs --git-repo-path=https://github.com/user/repo
# or explicitly:
npx -y read-docs-mcp --name=MyDocs --git-repo-path=https://github.com/user/repo --mode=normal

En modo normal, el servidor crea herramientas individuales para cada módulo y operación (por ejemplo, get-hooks-list, get-hooks-details, get-components-list, etc.).

Modo de Dos Pasos

npx -y read-docs-mcp --name=MyDocs --git-repo-path=https://github.com/user/repo --mode=two-step

En modo de dos pasos, en lugar de crear herramientas individuales para cada módulo, el servidor crea estas 5 herramientas genéricas:

  1. get-overview - Obtener resumen del proyecto (igual que en modo normal)
  2. get-overall-list - Obtener una lista de todos los módulos disponibles
  3. get-module-overview - Obtener resumen de un módulo específico (toma el nombre del módulo como parámetro)
  4. get-module-list - Obtener lista de elementos en un módulo específico (toma el nombre del módulo como parámetro)
  5. get-module-detail - Obtener detalles de un elemento específico en un módulo (toma el módulo y el nombre del elemento como parámetros)

Este enfoque reduce significativamente el número total de herramientas cuando tiene muchos módulos, haciendo que el servidor MCP sea más eficiente y fácil de gestionar.

Configuración en Cursor

Para usar este MCP en Cursor, añada la siguiente configuración a su configuración de Cursor:

Modo Lectura de Documentación (Mac/Linux)

{
  "mcpServers": {
    "read-docs-{name}": {
      "command": "npx",
      "args": [
        "-y",
        "read-docs-mcp",
        "--git-repo-path=https://github.com/user/repo",
        "--name=YourLibName"
      ]
    }
  }
}

Modo Lectura de Documentación con Acceso a Código Fuente (Mac/Linux)

{
  "mcpServers": {
    "read-docs-{name}": {
      "command": "npx",
      "args": [
        "-y",
        "read-docs-mcp",
        "--git-repo-path=https://github.com/user/repo",
        "--name=YourLibName",
        "--include-src=true"
      ]
    }
  }
}

Modo Creación de Documentación (Mac/Linux)

{
  "mcpServers": {
    "create-read-docs": {
      "command": "npx",
      "args": ["-y", "read-docs-mcp"]
    }
  }
}

Modo Lectura de Documentación (Windows)

{
  "mcpServers": {
    "read-docs-{name}": {
      "command": "cmd",
      "args": [
        "/c",
        "npx",
        "-y",
        "read-docs-mcp",
        "--git-repo-path=https://github.com/user/repo",
        "--name=YourLibName"
      ]
    }
  }
}

Modo Lectura de Documentación con Acceso a Código Fuente (Windows)

{
  "mcpServers": {
    "read-docs-{name}": {
      "command": "cmd",
      "args": [
        "/c",
        "npx",
        "-y",
        "read-docs-mcp",
        "--git-repo-path=https://github.com/user/repo",
        "--name=YourLibName",
        "--include-src=true"
      ]
    }
  }
}

Modo Creación de Documentación (Windows)

{
  "mcpServers": {
    "create-read-docs": {
      "command": "cmd",
      "args": ["/c", "npx", "-y", "read-docs-mcp"]
    }
  }
}

Ruta de Documentación Personalizada

Si desea especificar un directorio de documentación personalizado:

{
  "mcpServers": {
    "read-docs-{name}": {
      "command": "npx",
      "args": [
        "-y",
        "read-docs-mcp",
        "--git-repo-path=https://github.com/user/repo",
        "--name=YourLibName",
        "--docs-path=documentation"
      ]
    }
  }
}

Configuración del Modo de Dos Pasos

Para usar el modo de dos pasos para mayor eficiencia con conjuntos de documentación grandes:

{
  "mcpServers": {
    "read-docs-{name}": {
      "command": "npx",
      "args": [
        "-y",
        "read-docs-mcp",
        "--git-repo-path=https://github.com/user/repo",
        "--name=YourLibName",
        "--mode=two-step"
      ]
    }
  }
}

Repositorio Privado con Token Personal

Para acceder a repositorios privados usando un token de acceso personal:

{
  "mcpServers": {
    "read-docs-{name}": {
      "command": "npx",
      "args": [
        "-y",
        "read-docs-mcp",
        "--git-repo-path=https://github.com/user/private-repo",
        "--name=YourLibName",
        "--personal-token=your_personal_access_token_here"
      ]
    }
  }
}

GitLab Autoalojado con URL SSH

Para instancias de GitLab autoalojadas usando URLs SSH:

{
  "mcpServers": {
    "read-docs-{name}": {
      "command": "npx",
      "args": [
        "-y",
        "read-docs-mcp",
        "--git-repo-path=git@gitlab.some-host.com:some-group/your-repo.git",
        "--name=YourLibName",
        "--personal-token=your_gitlab_access_token_here"
      ]
    }
  }
}

Nota de Seguridad: Almacene su token de acceso personal de forma segura. Considere usar variables de entorno en lugar de codificar el token en su configuración.

Estructura de Documentación

El servidor MCP espera la siguiente estructura para el Modo Lectura de Documentación:

repository/
├── docs/ (configurable)
│   ├── read-docs-mcp.json
│   ├── hooks/
│   │   ├── read-module-docs-mcp.json
│   │   ├── list.md
│   │   ├── overview.md
│   │   ├── use-state.md
│   │   └── ...
│   ├── components/
│   │   ├── read-module-docs-mcp.json
│   │   └── ...
│   └── ...
└── package.json

Configuración Principal: read-docs-mcp.json

{
  "name": "SomeLibrary",
  "description": "A library for some purpose",
  "version": "1.0.1",
  "moduleList": ["hooks", "components", "directives", "utils"],
  "fileName": "overview.md",
  "moduleFolderNamingPattern": "kebab"
}
  • name, description: Usados en la construcción del servidor MCP
  • version: Si no se proporciona, recurre a la versión en package.json, o por defecto a "0.1.0"
  • moduleList: Lista de módulos de documentación; si no se proporciona, se usan todas las carpetas en el directorio de documentación
  • fileName: El archivo a usar para el resumen. Si no se proporciona, por defecto es "overview.md"
  • moduleFolderNamingPattern: Patrón de nomenclatura para carpetas de módulos. Puede ser "kebab", "camel", "snake", "pascal" u "original". El predeterminado es "kebab"

Reglas de Patrones de Nomenclatura

Los siguientes patrones de nomenclatura son compatibles para carpetas de módulos y archivos de detalle:

  • kebab-case (predeterminado): Las palabras están en minúsculas y separadas por guiones

    • Ejemplo: "form-control", "use-state", "data-table"

  • camelCase: La primera palabra está en minúsculas, las palabras siguientes están capitalizadas sin separadores

    • Ejemplo: "formControl", "useState", "dataTable"

  • snake_case: Las palabras están en minúsculas y separadas por guiones bajos

    • Ejemplo: "form_control", "use_state", "data_table"

  • PascalCase: Cada palabra está capitalizada sin separadores

    • Ejemplo: "FormControl", "UseState", "DataTable"

  • original: Usa el nombre exactamente como se proporciona en moduleList, sin conversión

    • Ejemplo: Los nombres en moduleList se usarán tal cual para los nombres de directorios

Configuración del Módulo: read-module-docs-mcp.json

{
  "get-all": {
    "name": "get-hook-list",
    "description": "Get a list of hooks",
    "fileName": "list.md"
  },
  "get-details": {
    "name": "get-hook-details",
    "description": "Get details of a hook",
    "paramDescription": "A hook name",
    "namingPattern": "kebab"
  },
  "get-overview": {
    "name": "get-hook-overview",
    "description": "Get an overview of the hook module",
    "fileName": "overview.md"
  }
}

Trabajo con Agentes

Uso del Modo Lectura de Documentación

Cuando haya configurado el servidor MCP con un repositorio, puede usarlo para explorar documentación:

Using the read-docs-{YourLibName} MCP, I'd like to explore the documentation for {YourLibName}. Can you:

1. Get an overview of the available modules
2. Show me the list of hooks available
3. Provide details on a specific hook
4. Give me an overview of the components module

Uso del Modo Creación de Documentación

Cuando use el servidor MCP sin un repositorio, puede pedir ayuda para crear documentación:

Using the create-read-docs MCP, I need to create documentation for my library that can be used with read-docs-mcp.
Can you help me set up the required structure and files?

Ejemplos de Prompts para el Modo Lectura de Documentación

Explorando Documentación de Paquetes

Using the read-docs-{PackageName} MCP, I'd like to explore the documentation for [Package Name]. Can you:

1. Get an overview of the available modules
2. Show me the list of hooks available
3. Provide details on the useAuth hook
4. Give me an overview of the components module

I'm particularly interested in understanding how authentication works in this library.

Aprendiendo a Usar un Componente

Using the read-docs-{PackageName} MCP, I need to implement a form with validation using the [Package Name] library. Please:

1. Show me the available components
2. Get details on the Form component
3. Get details on the Input component
4. Explain how to use form validation with these components

If there are any code examples in the documentation, please highlight those.

Encontrando Documentación con Búsqueda Difusa

Using the read-docs-{PackageName} MCP, I'm looking for documentation about authentication in the library. Can you:

1. Use fuzzy search to find all files related to "auth"
2. Based on the search results, get the details for the most relevant authentication documentation
3. Show me how to implement authentication using the library

The fuzzy search should help us quickly locate the relevant documentation files.

Leyendo Código Fuente para Detalles de Implementación

Using the read-docs-{PackageName} MCP (configured with --include-src=true), I need to understand how the useAuth hook is implemented. Please:

1. First, get the documentation details for the useAuth hook
2. Based on the documentation, read the source code file for useAuth to understand the implementation
3. Explain how the authentication flow works based on both the documentation and source code

Remember to prioritize the documentation first, then use source code only for additional implementation details.

Ejemplos de Prompts para el Modo Creación de Documentación

Using the create-read-docs MCP, I need to set up documentation for my React component library. Can you help me create the folder structure and necessary configuration files?

Using the create-read-docs MCP, I've started creating documentation for my utility functions. How should I structure the detailed documentation for individual utility functions?

Herramientas

Herramientas del Modo Lectura de Documentación

El MCP genera dinámicamente herramientas basadas en la estructura de documentación y el modo de operación. Todas las herramientas tienen el prefijo del nombre del paquete para evitar conflictos cuando se usan múltiples instancias de read-docs-mcp.

Herramientas del Modo Normal

En modo normal, para cada módulo en moduleList, se pueden generar hasta tres herramientas, más una herramienta opcional de lectura de archivos fuente:

{name}-get-[module]-list

Obtener una lista de todos los elementos en el módulo.

Parámetros:

  • Ninguno

Devuelve:

  • Contenido del archivo de lista (predeterminado: list.md)

{name}-get-[module]-details

Obtener detalles sobre un elemento específico en el módulo.

Parámetros:

  • name (string): Nombre del elemento para obtener detalles

Devuelve:

  • Contenido del archivo de detalles, nombrado según el namingPattern (predeterminado es kebab-case)

{name}-get-[module]-overview

Obtener un resumen del módulo.

Parámetros:

  • Ninguno

Devuelve:

  • Contenido del archivo de resumen (predeterminado: overview.md)

{name}-fuzzy-search

Buscar archivos por palabra clave con priorización inteligente.

Parámetros:

  • keyword (string): La palabra clave para buscar en nombres de archivos y contenido

Devuelve:

  • Lista formateada de archivos coincidentes con la siguiente prioridad:
    1. Coincidencia exacta en el nombre del archivo
    2. Coincidencia parcial en el nombre del archivo
    3. Coincidencia exacta en el contenido del archivo
    4. Coincidencia parcial en el contenido del archivo

Los resultados se formatean como:

type: module
name: someModule

o

type: detail
name: someDetail
module: someModule

Herramientas del Modo de Dos Pasos

En modo de dos pasos, el MCP genera 5 herramientas genéricas en lugar de herramientas individuales para cada módulo, más una herramienta opcional de lectura de archivos fuente:

{name}-get-overview

Obtener resumen del proyecto.

Parámetros:

  • Ninguno

Devuelve:

  • Contenido del archivo de resumen principal

{name}-get-overall-list

Obtener una lista de todos los módulos disponibles.

Parámetros:

  • Ninguno

Devuelve:

  • Lista de todos los módulos disponibles en la documentación

{name}-get-module-overview

Obtener un resumen de un módulo específico.

Parámetros:

  • module (string): Nombre del módulo

Devuelve:

  • Contenido del archivo de resumen del módulo

{name}-get-module-list

Obtener una lista de elementos en un módulo específico.

Parámetros:

  • module (string): Nombre del módulo

Devuelve:

  • Contenido del archivo de lista del módulo

{name}-get-module-detail

Obtener detalles de un elemento específico en un módulo.

Parámetros:

  • module (string): Nombre del módulo
  • name (string): Nombre del elemento para obtener detalles

Devuelve:

  • Contenido del archivo de detalles del elemento

{name}-fuzzy-search

Buscar archivos por palabra clave con priorización inteligente.

Parámetros:

  • keyword (string): La palabra clave para buscar en nombres de archivos y contenido

Devuelve:

  • Lista formateada de archivos coincidentes con el mismo sistema de prioridad y formato descrito en la sección del Modo Normal anterior

{name}-read-source-file

Leer el contenido de archivos de código fuente. Nota: Esta herramienta solo está disponible cuando se usa el parámetro --include-src=true durante la inicialización del servidor.

Parámetros:

  • filePath (string): La ruta relativa al archivo fuente dentro del repositorio del proyecto (por ejemplo, 'src/components/Button.tsx', 'lib/utils.js')

Devuelve:

  • Contenido del archivo fuente con verificaciones de seguridad para asegurar que el acceso está restringido al directorio del proyecto

Importante: Esta herramienta solo debe usarse después de consultar la documentación primero. La documentación debe ser su fuente principal de información. Solo lea el código fuente cuando necesite detalles adicionales de implementación o ejemplos que no estén cubiertos en la documentación.

Herramientas del Modo Creación de Documentación

El MCP proporciona una sola herramienta para ayudar con la creación de documentación:

get-create-docs-instructions

Obtener instrucciones detalladas para crear la estructura de documentación.

Parámetros:

  • Ninguno

Devuelve:

  • Instrucciones detalladas sobre cómo configurar archivos de documentación y estructura

Creación de documentación para el modo de lectura de documentación

Puedes crear manualmente la estructura de documentación o usar el modo de creación de documentación para obtener orientación. Sigue estos pasos para crear documentación que pueda ser accedida por el modo de lectura de documentación:

Paso 1: Crear el archivo de configuración principal

Crea un archivo read-docs-mcp.json en tu directorio de documentación:

{
  "name": "YourLibrary",
  "description": "Description of your library",
  "version": "1.0.0",
  "moduleList": ["hooks", "components", "utils"],
  "moduleFolderNamingPattern": "kebab"
}

El moduleFolderNamingPattern determina cómo se convertirán los nombres de tus carpetas de módulos. Por ejemplo, si tu moduleList contiene ["FormControl", "useHooks"] y eliges el patrón "kebab", las carpetas se crearán como form-control/ y use-hooks/.

Paso 2: Crear directorios y configuraciones de módulos

Para cada módulo, crea un directorio y un archivo read-module-docs-mcp.json:

{
  "get-all": {
    "name": "get-component-list",
    "description": "Get a list of components",
    "fileName": "list.md"
  },
  "get-details": {
    "name": "get-component-details",
    "description": "Get details of a component",
    "paramDescription": "A component name",
    "namingPattern": "kebab"
  },
  "get-overview": {
    "name": "get-component-overview",
    "description": "Get an overview of components",
    "fileName": "overview.md"
  }
}

Nota: Los nombres reales de las herramientas generadas tendrán como prefijo el nombre de tu paquete. Por ejemplo, si el nombre de tu paquete es "MyLibrary", las herramientas se llamarán MyLibrary-get-component-list, MyLibrary-get-component-details, etc.

Paso 3: Crear archivos de documentación

Crea los archivos markdown necesarios:

  • list.md - Lista de todos los elementos del módulo
  • overview.md - Resumen del módulo
  • Archivos de detalle individuales (por ejemplo, button.md, input.md, etc.)

Licencia

MIT