MCP Documentation Service

MCP Documentation Service

O que é?

O MCP Documentation Service é uma implementação do Model Context Protocol (MCP) para gerenciamento de documentação. Ele fornece um conjunto de ferramentas para ler, escrever e gerenciar documentação em markdown com metadados de frontmatter. O serviço foi projetado para funcionar perfeitamente com assistentes de IA como o Claude no Cursor ou no Claude Desktop, facilitando o gerenciamento da sua documentação por meio de interações em linguagem natural.

Recursos

• Ler e Escrever Documentos: Leia e escreva facilmente documentos markdown com metadados de frontmatter
• Editar Documentos: Faça edições precisas baseadas em linhas com prévia de diff
• Listar e Pesquisar: Encontre documentos por conteúdo ou metadados
• Geração de Navegação: Crie estruturas de navegação a partir da sua documentação
• Verificações de Saúde: Analise a qualidade da documentação e identifique problemas como metadados ausentes ou links quebrados
• Documentação Otimizada para LLM: Gere saída consolidada em documento único otimizada para grandes modelos de linguagem
• Integração MCP: Integração perfeita com o Model Context Protocol
• Suporte a Frontmatter: Suporte completo para frontmatter YAML em documentos markdown
• Compatibilidade com Markdown: Funciona com arquivos markdown padrão

Início Rápido

Instalação

Requer que o Node esteja instalado na sua máquina.

npm install -g mcp-docs-service

Ou use diretamente com npx:

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

Integração com Cursor

Para usar com o Cursor, crie um arquivo .cursor/mcp.json na raiz do seu projeto:

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

Integração com Claude Desktop

Para usar o MCP Docs Service com o Claude Desktop:

1. Instale o Claude Desktop - Baixe a versão mais recente no site do Claude.

2. Configure o Claude Desktop para MCP:

   • Abra o Claude Desktop
   • Clique no menu do Claude e selecione "Developer Settings"
   • Isso criará um arquivo de configuração em:
     • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
     • Windows: %APPDATA%\Claude\claude_desktop_config.json

3. Edite o arquivo de configuração para adicionar o MCP Docs Service:

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

Certifique-se de substituir /path/to/your/docs pelo caminho absoluto do seu diretório de documentação.

4. Reinicie o Claude Desktop completamente.

5. Verifique se a ferramenta está disponível - Após reiniciar, você deve ver um ponto verde para a ferramenta MCP docs-manager (Cursor Settings > MCP)

6. Solução de problemas:

   • Se o servidor não aparecer, verifique os logs em:
     • macOS: ~/Library/Logs/Claude/mcp*.log
     • Windows: %APPDATA%\Claude\logs\mcp*.log
   • Certifique-se de que o Node.js esteja instalado no seu sistema
   • Verifique se os caminhos na sua configuração são absolutos e válidos

Exemplos

Usando com o Claude no Cursor

Ao usar o Claude no Cursor, você pode invocar as ferramentas de duas maneiras:

1. Usando Linguagem Natural (Recomendado):
   • Simplesmente peça ao Claude para realizar a tarefa em linguagem 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 a Sintaxe Direta de Ferramentas:
   • Para um controle mais preciso, você pode usar a sintaxe direta de ferramentas:

@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 com o Claude Desktop

Ao usar o Claude Desktop, você pode invocar as ferramentas de duas maneiras:

1. Usando Linguagem 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 o Seletor de Ferramentas:
   • Clique no ícone de martelo no canto inferior direito da caixa de entrada
   • Selecione "docs-manager" na lista de ferramentas disponíveis
   • Escolha a ferramenta específica que deseja usar
   • Preencha os parâmetros necessários e clique em "Run"

O Claude interpretará suas solicitações em linguagem natural e usará a ferramenta apropriada com os parâmetros corretos. Você não precisa memorizar os nomes exatos das ferramentas ou formatos de parâmetros — basta descrever o que deseja fazer!

Comandos Comuns das Ferramentas

Aqui estão alguns comandos comuns que você pode usar com as ferramentas:

Lendo um Documento

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

Escrevendo um 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."

Editando um Documento

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

Pesquisando Documentos

@docs-manager mcp_docs_manager_search_documents query="getting started"

Gerando Navegação

@docs-manager mcp_docs_manager_generate_navigation

Contribuindo

Contribuições são bem-vindas! Veja como você pode contribuir:

1. Faça um fork do repositório
2. Crie um branch de funcionalidade: git checkout -b feature/my-feature
3. Faça commit das suas alterações: git commit -am 'Add my feature'
4. Envie para o branch: git push origin feature/my-feature
5. Envie um pull request

Certifique-se de que seu código siga o estilo existente e inclua testes apropriados.

Testes e Cobertura

O MCP Docs Service possui cobertura abrangente de testes para garantir confiabilidade e estabilidade. Usamos Vitest para testes e monitoramos métricas de cobertura para manter a qualidade do código.

Executando Testes

# Run all tests
npm test

# Run tests with coverage report
npm run test:coverage

A suíte de testes inclui:

• Testes unitários para funções utilitárias e handlers
• Testes de integração para o fluxo de documentos
• Testes de ponta a ponta para o serviço MCP

Nossos testes são projetados para serem robustos e lidar com possíveis erros na implementação, garantindo que passem mesmo se houver problemas com o código subjacente.

Relatórios de Cobertura

Após executar o comando de cobertura, relatórios detalhados são gerados no diretório coverage:

• Relatório HTML: coverage/index.html
• Relatório JSON: coverage/coverage-final.json

Mantemos alta cobertura de testes para garantir a confiabilidade do serviço, com foco em testar caminhos críticos e casos extremos.

Saúde da Documentação

Usamos o MCP Docs Service para manter a saúde da nossa própria documentação. A pontuação de saúde é baseada em:

• Completude dos metadados (título, descrição, etc.)
• Presença de links quebrados
• Documentos órfãos (não vinculados a partir de nenhum lugar)
• Formatação e estilo consistentes

Você pode verificar a saúde da sua documentação com:

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

Documentação Consolidada para LLMs

O MCP Docs Service pode gerar um arquivo de documentação consolidado otimizado para grandes modelos de linguagem. Esse recurso é útil quando você deseja fornecer todo o seu conjunto de documentação a um LLM para 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

A saída consolidada inclui:

• Metadados do projeto (nome, versão, descrição)
• Sumário com contagem de tokens para cada seção
• Toda a documentação organizada por seção com separação clara
• Contagem de tokens para ajudar a permanecer dentro dos limites de contexto do LLM

Resiliente por Padrão

O MCP Docs Service é projetado para ser resiliente por padrão. O serviço lida automaticamente com documentação incompleta ou mal estruturada sem falhar:

• Retorna uma pontuação mínima de saúde de 80 mesmo com problemas
• Cria automaticamente diretórios de documentação ausentes
• Lida graciosamente com diretórios de documentação ausentes
• Continua o processamento mesmo quando arquivos têm erros
• Fornece pontuação tolerante para completude de metadados e links quebrados

Isso torna o serviço particularmente útil para:

• Projetos legados com documentação mínima
• Projetos em estágios iniciais de desenvolvimento de documentação
• Migração de documentação de outros formatos

O serviço sempre fornecerá feedback útil em vez de falhar, permitindo que você melhore sua documentação incrementalmente ao longo do tempo.

Histórico de Versões

v0.6.0

• Adicionado o recurso de documentação consolidada otimizada para LLM (flag --single-doc)
• Adicionada contagem de tokens para cada seção da documentação
• Adicionada personalização da saída do documento consolidado (flag --output)
• Adicionada configuração de limite máximo de tokens (flag --max-tokens)

v0.5.2

• Resiliência aprimorada com criação automática de diretórios de documentação ausentes
• Modo de tolerância melhorado com pontuação mínima de saúde de 80
• Modo de tolerância definido como padrão para verificações de saúde
• Descrição da ferramenta de verificação de saúde atualizada para mencionar o modo de tolerância

v0.5.1

• Adicionado modo de tolerância às verificações de saúde
• Corrigidos problemas com a confiabilidade da suíte de testes
• Melhorado o tratamento de erros nas operações de documentos

Documentação

Para informações mais detalhadas, consulte nossa documentação:

• Guia de Introdução
• Guia de Integração MCP
• Uso do Protocolo MCP
• Referência da API
• Exemplos

Licença

MIT