Read Docs MCP

Permite que agentes de IA acessem e compreendam a documentação de pacotes de repositórios locais ou remotos.

GitHub
7
Experimente este MCPPatrocinado

Documentação

read-docs-mcp

Um servidor Model Context Protocol (MCP) que permite que agentes de IA acessem e compreendam a documentação de pacotes por meio de uma interface estruturada.

Recursos

  • Gera automaticamente ferramentas MCP a partir da estrutura da documentação
  • Suporta múltiplos módulos de documentação (hooks, componentes, utilitários, etc.)
  • Padrões de nomenclatura configuráveis para arquivos de documentação e pastas de módulos
  • Fornece acesso a listagem, visão geral e detalhes da documentação
  • Geração dinâmica de ferramentas com base nos módulos configurados
  • Recurso de fallback para package.json para informações de versão
  • Caminho de documentação personalizável
  • Capacidade de busca difusa para encontrar arquivos por palavra-chave com priorização inteligente

Modos de Uso Duplos

Este servidor MCP possui dois modos de uso distintos:

  1. Modo Leitura de Documentação (read-docs-{name}): Quando tanto name quanto git-repo-path são fornecidos, o servidor funciona como um leitor de documentos para o repositório especificado, gerando ferramentas para acessar a documentação.

  2. Modo Criação de Documentação (create-read-docs): Quando nenhuma informação de repositório é fornecida, o servidor funciona como um guia para criar a estrutura da documentação, fornecendo instruções sobre como configurar os arquivos de documentação.

Configuração

O MCP suporta os seguintes argumentos de linha de comando:

  • --name: Nome do pacote/biblioteca (obrigatório para o Modo Leitura de Documentação)
  • --git-repo-path: Caminho para o repositório git (http ou ssh) (obrigatório para o Modo Leitura de Documentação)
    • Se não for fornecido, o servidor MCP fornecerá apenas instruções de construção
  • --personal-token: Token de acesso pessoal para autenticação git (opcional)
    • Recomendado para repositórios privados
    • Suporta GitHub, GitLab, Bitbucket e hospedagem Git genérica
  • --branch: Branch de onde ler a documentação
    • Padrão: main
  • --docs-path: Caminho para a pasta de documentação
    • Padrão: docs
  • --clone-location: Caminho para clonar o repositório git
    • Padrão: {diretório home do usuário}/.temp-repo
  • --mode: Modo de operação do servidor MCP
  • --include-src: Incluir capacidade de leitura de código-fonte (opcional)
    • Defina como true para habilitar a leitura de arquivos de código-fonte do repositório
    • Padrão: false
    • Quando habilitado, adiciona uma ferramenta para ler arquivos de código-fonte para obter detalhes adicionais de implementação

Nota Importante sobre Autenticação Git

Este MCP requer a clonagem direta do repositório git de destino. Você deve garantir que tenha acesso adequado ao repositório antes de usar esta ferramenta. Para repositórios privados, você tem várias opções de autenticação:

  1. Usando Token de Acesso Pessoal (Recomendado): Passe seu token de acesso pessoal usando o argumento --personal-token. Este é o método mais confiável e funciona com todos os principais provedores de hospedagem Git.
  2. Chaves SSH: Configure chaves SSH em sua máquina local para URLs SSH
  3. Armazenamento de Credenciais Git: Configure o armazenamento de credenciais Git em sua máquina para URLs HTTPS

Usando Token de Acesso Pessoal:

# 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

O MCP suporta tokens de acesso pessoal para URLs HTTPS e SSH:

URLs HTTPS:

  • GitHub: Usa o token diretamente na URL HTTPS
  • GitLab (incluindo auto-hospedado): Usa o formato OAuth2 com o token
  • Bitbucket: Usa o formato token-auth
  • Hospedagem Git Genérica: Usa o formato OAuth2 (estilo GitLab)

URLs SSH: Quando um token pessoal é fornecido, URLs SSH são automaticamente convertidas para HTTPS com autenticação adequada:

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

Sem autenticação adequada, o MCP falhará ao clonar repositórios privados.

Modos de Operação

Você pode especificar diferentes modos ao executar o servidor MCP usando o argumento --mode:

Modo Normal (padrão)

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

No modo normal, o servidor cria ferramentas individuais para cada módulo e operação (ex.: get-hooks-list, get-hooks-details, get-components-list, etc.).

Modo de Duas Etapas

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

No modo de duas etapas, em vez de criar ferramentas individuais para cada módulo, o servidor cria estas 5 ferramentas genéricas:

  1. get-overview - Obter visão geral do projeto (igual ao modo normal)
  2. get-overall-list - Obter uma lista de todos os módulos disponíveis
  3. get-module-overview - Obter visão geral de um módulo específico (recebe o nome do módulo como parâmetro)
  4. get-module-list - Obter lista de itens em um módulo específico (recebe o nome do módulo como parâmetro)
  5. get-module-detail - Obter detalhes de um item específico em um módulo (recebe o módulo e o nome do item como parâmetros)

Esta abordagem reduz significativamente o número total de ferramentas quando você tem muitos módulos, tornando o servidor MCP mais eficiente e fácil de gerenciar.

Configuração no Cursor

Para usar este MCP no Cursor, adicione a seguinte configuração às configurações do Cursor:

Modo Leitura de Documentação (Mac/Linux)

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

Modo Leitura de Documentação com Acesso ao Código-Fonte (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 Criação de Documentação (Mac/Linux)

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

Modo Leitura de Documentação (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 Leitura de Documentação com Acesso ao Código-Fonte (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 Criação de Documentação (Windows)

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

Caminho Personalizado de Documentação

Se você quiser especificar um diretório de documentação 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"
      ]
    }
  }
}

Configuração do Modo de Duas Etapas

Para usar o modo de duas etapas para melhor eficiência com grandes conjuntos de documentação:

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

Repositório Privado com Token Pessoal

Para acessar repositórios privados usando um token de acesso pessoal:

{
  "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 Auto-Hospedado com URL SSH

Para instâncias GitLab auto-hospedadas 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 Segurança: Armazene seu token de acesso pessoal com segurança. Considere usar variáveis de ambiente em vez de codificar o token em sua configuração.

Estrutura da Documentação

O servidor MCP espera a seguinte estrutura para o Modo Leitura de Documentação:

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

Configuração 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 na construção do servidor MCP
  • version: Se não for fornecido, usa como fallback a versão no package.json, ou o padrão "0.1.0"
  • moduleList: Lista de módulos de documentação; se não for fornecida, todas as pastas no diretório de documentação são usadas
  • fileName: O arquivo a ser usado para a visão geral. Se não for fornecido, o padrão é "overview.md"
  • moduleFolderNamingPattern: Padrão de nomenclatura para pastas de módulos. Pode ser "kebab", "camel", "snake", "pascal" ou "original". O padrão é "kebab"

Regras de Padrão de Nomenclatura

Os seguintes padrões de nomenclatura são suportados para pastas de módulos e arquivos de detalhes:

  • kebab-case (padrão): Palavras em minúsculas e separadas por hífens

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

  • camelCase: Primeira palavra em minúsculas, palavras subsequentes capitalizadas sem separadores

    • Exemplo: "formControl", "useState", "dataTable"

  • snake_case: Palavras em minúsculas e separadas por sublinhados

    • Exemplo: "form_control", "use_state", "data_table"

  • PascalCase: Cada palavra capitalizada sem separadores

    • Exemplo: "FormControl", "UseState", "DataTable"

  • original: Usa o nome exatamente como fornecido na moduleList, sem conversão

    • Exemplo: Nomes na moduleList serão usados como estão para nomes de diretórios

Configuração do 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"
  }
}

Trabalhando com Agentes

Usando o Modo Leitura de Documentação

Quando você configurou o servidor MCP com um repositório, pode usá-lo para explorar a documentação:

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

Usando o Modo Criação de Documentação

Quando você usa o servidor MCP sem um repositório, pode pedir ajuda para criar documentação:

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?

Exemplos de Prompts para o Modo Leitura de Documentação

Explorando a Documentação do Pacote

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.

Aprendendo a Usar um 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 Documentação com Busca 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.

Lendo Código-Fonte para Detalhes de Implementação

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.

Exemplos de Prompts para o Modo Criação de Documentação

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?

Ferramentas

Ferramentas do Modo Leitura de Documentação

O MCP gera dinamicamente ferramentas com base na estrutura da documentação e no modo de operação. Todas as ferramentas são prefixadas com o nome do pacote para evitar conflitos quando múltiplas instâncias do read-docs-mcp são usadas.

Ferramentas do Modo Normal

No modo normal, para cada módulo no moduleList, até três ferramentas podem ser geradas, além de uma ferramenta opcional de leitura de arquivos de código-fonte:

{name}-get-[module]-list

Obter uma lista de todos os itens no módulo.

Parâmetros:

  • Nenhum

Retorna:

  • Conteúdo do arquivo de lista (padrão: list.md)

{name}-get-[module]-details

Obter detalhes sobre um item específico no módulo.

Parâmetros:

  • name (string): Nome do item para obter detalhes

Retorna:

  • Conteúdo do arquivo de detalhes, nomeado de acordo com o namingPattern (padrão é kebab-case)

{name}-get-[module]-overview

Obter uma visão geral do módulo.

Parâmetros:

  • Nenhum

Retorna:

  • Conteúdo do arquivo de visão geral (padrão: overview.md)

{name}-fuzzy-search

Buscar arquivos por palavra-chave com priorização inteligente.

Parâmetros:

  • keyword (string): A palavra-chave para buscar em nomes de arquivos e conteúdo

Retorna:

  • Lista formatada de arquivos correspondentes com a seguinte prioridade:
    1. Correspondência exata no nome do arquivo
    2. Correspondência parcial no nome do arquivo
    3. Correspondência exata no conteúdo do arquivo
    4. Correspondência parcial no conteúdo do arquivo

Os resultados são formatados como:

type: module
name: someModule

ou

type: detail
name: someDetail
module: someModule

Ferramentas do Modo de Duas Etapas

No modo de duas etapas, o MCP gera 5 ferramentas genéricas em vez de ferramentas individuais para cada módulo, além de uma ferramenta opcional de leitura de arquivos de código-fonte:

{name}-get-overview

Obter visão geral do projeto.

Parâmetros:

  • Nenhum

Retorna:

  • Conteúdo do arquivo de visão geral principal

{name}-get-overall-list

Obter uma lista de todos os módulos disponíveis.

Parâmetros:

  • Nenhum

Retorna:

  • Lista de todos os módulos disponíveis na documentação

{name}-get-module-overview

Obter uma visão geral de um módulo específico.

Parâmetros:

  • module (string): Nome do módulo

Retorna:

  • Conteúdo do arquivo de visão geral do módulo

{name}-get-module-list

Obter uma lista de itens em um módulo específico.

Parâmetros:

  • module (string): Nome do módulo

Retorna:

  • Conteúdo do arquivo de lista do módulo

{name}-get-module-detail

Obter detalhes de um item específico em um módulo.

Parâmetros:

  • module (string): Nome do módulo
  • name (string): Nome do item para obter detalhes

Retorna:

  • Conteúdo do arquivo de detalhes do item

{name}-fuzzy-search

Buscar arquivos por palavra-chave com priorização inteligente.

Parâmetros:

  • keyword (string): A palavra-chave para buscar em nomes de arquivos e conteúdo

Retorna:

  • Lista formatada de arquivos correspondentes com o mesmo sistema de prioridade e formato descrito na seção Modo Normal acima

{name}-read-source-file

Ler o conteúdo de arquivos de código-fonte. Nota: Esta ferramenta só está disponível quando o parâmetro --include-src=true é usado durante a inicialização do servidor.

Parâmetros:

  • filePath (string): O caminho relativo para o arquivo de código-fonte dentro do repositório do projeto (ex.: 'src/components/Button.tsx', 'lib/utils.js')

Retorna:

  • Conteúdo do arquivo de código-fonte com verificações de segurança para garantir que o acesso seja restrito ao diretório do projeto

Importante: Esta ferramenta só deve ser usada após consultar a documentação primeiro. A documentação deve ser sua fonte primária de informação. Leia o código-fonte apenas quando precisar de detalhes adicionais de implementação ou exemplos que não são cobertos na documentação.

Ferramentas do Modo Criação de Documentação

O MCP fornece uma única ferramenta para ajudar na criação de documentação:

get-create-docs-instructions

Obter instruções detalhadas para criar a estrutura da documentação.

Parâmetros:

  • Nenhum

Retorna:

  • Instruções detalhadas sobre como configurar arquivos de documentação e estrutura

Criando Documentação para o Modo de Leitura de Documentação

Você pode criar manualmente a estrutura de documentação ou usar o Modo de Criação de Documentação para obter orientação. Siga estes passos para criar documentação que possa ser acessada pelo Modo de Leitura de Documentação:

Passo 1: Crie o arquivo de configuração principal

Crie um arquivo read-docs-mcp.json no seu diretório de documentação:

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

O moduleFolderNamingPattern determina como os nomes das pastas dos seus módulos serão convertidos. Por exemplo, se o seu moduleList contém ["FormControl", "useHooks"] e você escolher o padrão "kebab", as pastas serão criadas como form-control/ e use-hooks/.

Passo 2: Crie diretórios e configurações dos módulos

Para cada módulo, crie um diretório e um arquivo 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"
  }
}

Observação: Os nomes reais das ferramentas geradas serão prefixados com o nome do seu pacote. Por exemplo, se o nome do seu pacote for "MyLibrary", as ferramentas serão nomeadas como MyLibrary-get-component-list, MyLibrary-get-component-details, etc.

Passo 3: Crie os arquivos de documentação

Crie os arquivos markdown necessários:

  • list.md - Lista de todos os itens no módulo
  • overview.md - Visão geral do módulo
  • Arquivos de detalhes individuais (por exemplo, button.md, input.md, etc.)

Licença

MIT