DocsetMCP

DocsetMCP

Acesse sua documentação local do Dash diretamente de assistentes de IA 🚀

DocsetMCP é um servidor Model Context Protocol (MCP) que integra perfeitamente seus docsets locais do Dash com assistentes de IA como Claude, permitindo acesso instantâneo à documentação offline sem sair da sua conversa.

📋 Sumário

• Por que DocsetMCP?
• Início Rápido
• Recursos
• Pré-requisitos
• Instalação
• Configuração
• Exemplos de Uso
• Ferramentas Disponíveis
• Solução de Problemas
• Desenvolvimento
• Contribuição
• Licença

Por que DocsetMCP?

• 📚 Documentação Instantânea: Sem alternar de contexto, sem buscas na web. Vá direto para a documentação na sua conversa com IA
• 🔒 Local e Privado: Trabalhe com arquivos de docset na sua máquina
• ⚡ Extremamente Rápido: Cache otimizado e consultas diretas ao banco de dados
• 🎯 Resultados Precisos: Obtenha exatamente o que você precisa com filtros inteligentes

Início Rápido

{
  "mcpServers": {
    "docsetmcp": {
      "command": "uvx",
      "args": ["docsetmcp"]
    }
  }
}

Adicione à sua configuração MCP e reinicie o cliente MCP. Depois, tente perguntar algo como "Encontre a documentação do AppIntent"

✨ Recursos

Pesquisa de Documentação

• Suporte a Múltiplos Docsets: Pesquise em mais de 165 docsets suportados, incluindo Apple, NodeJS, Python e outros
• Filtro por Linguagem: Direcione linguagens de programação específicas dentro dos docsets
• Pesquisa por Nome: Retorna apenas entradas onde os termos de busca correspondem aos nomes dos itens para resultados precisos
• Classificação Inteligente: Resultados classificados por tipo de correspondência (exata > prefixo > substring) e ordenação dinâmica por tipo
• Orientação de Contêineres: Entradas de frameworks e classes mostram notas de drilldown para explorar membros

Acesso a Cheatsheets

• Referência Rápida: Acesso instantâneo a Git, Vim, Docker e mais de 40 outros cheatsheets
• Correspondência Difusa: Encontre cheatsheets mesmo com nomes parciais
• Navegação por Categoria: Explore comandos por categoria dentro de cada cheatsheet
• Busca Interna: Consulte comandos específicos dentro de qualquer cheatsheet

Desempenho e Integração

• Cache Eficiente: Cache em memória para consultas repetidas
• Acesso Direto ao Banco de Dados: Sem servidores intermediários ou APIs
• Universal: Funciona com Claude Desktop, Cursor, VS Code e qualquer cliente compatível com MCP
• Descoberta de Frameworks: Liste todos os frameworks/tipos disponíveis em qualquer docset
• Orientação de Contêineres: Notas automáticas de drilldown para frameworks e classes com membros

📦 Docsets Suportados

DocsetMCP suporta mais de 165 docsets, incluindo:

Use list_available_docsets para ver todos os docsets instalados no seu sistema.

Pré-requisitos

• macOS (Dash é exclusivo para Mac)
• Dash com os docsets desejados baixados
• Python 3.10 ou superior
• Gerenciador de pacotes UV (Como Instalar)
• Um assistente de IA que suporte MCP (Claude Desktop, Claude Code CLI, Cursor IDE, etc.)

Configuração

Locais Personalizados de Docset

Por padrão, o DocsetMCP procura docsets nos diretórios padrão do Dash:

• Docsets: ~/Library/Application Support/Dash/DocSets
• Cheatsheets: ~/Library/Application Support/Dash/Cheat Sheets

Você pode personalizar esses locais usando:

Variáveis de Ambiente

# Set custom docset directory
export DOCSET_PATH="/path/to/your/docsets"

# Set custom cheatsheet directory  
export CHEATSHEET_PATH="/path/to/your/cheatsheets"

# Run with custom paths
docsetmcp

Argumentos de Linha de Comando

# Test with custom docset path
docsetmcp --docset-path "/path/to/your/docsets" --list-docsets

# Test with custom cheatsheet path
docsetmcp --cheatsheet-path "/path/to/your/cheatsheets" --test-connection

# Use both custom paths
docsetmcp --docset-path "/custom/docsets" --cheatsheet-path "/custom/cheatsheets"

# Use additional search paths (searches multiple locations)
docsetmcp --additional-docset-paths "/extra/docsets" "/more/docsets"
docsetmcp --additional-cheatsheet-paths "/extra/cheatsheets" "/more/cheatsheets"

Ordem de Prioridade:

1. Argumentos de CLI (maior prioridade)
2. Variáveis de ambiente
3. Locais padrão do Dash (menor prioridade)

Caminhos de Pesquisa Adicionais:

As opções --additional-docset-paths e --additional-cheatsheet-paths permitem que o DocsetMCP pesquise em vários locais além do caminho principal. Isso é útil quando:

• Você tem docsets em vários diretórios
• Você deseja incluir docsets de terceiros ou personalizados
• Você está compartilhando docsets entre diferentes ferramentas

O DocsetMCP descobrirá e configurará automaticamente os docsets encontrados nesses caminhos adicionais.

Configuração do Cliente MCP

Escolha seu cliente MCP abaixo para instruções específicas de configuração:

{
  "mcpServers": {
    "docsetmcp": {
      "command": "uvx",
      "args": ["docsetmcp"]
    }
  }
}

{
  "mcpServers": {
    "docsetmcp": {
      "command": "uvx",
      "args": ["docsetmcp"],
      "env": {
        "DOCSET_PATH": "/path/to/your/docsets",
        "CHEATSHEET_PATH": "/path/to/your/cheatsheets"
      }
    }
  }
}

# For current project
claude mcp add docsetmcp "uvx docsetmcp"

# For all projects
claude mcp add --scope user docsetmcp "uvx docsetmcp"

{
  "mcpServers": {
    "docsetmcp": {
      "command": "uvx",
      "args": ["docsetmcp"]
    }
  }
}

Instalação

Nenhuma Instalação Necessária (Recomendado)

Se o seu cliente MCP suporta uvx, nenhuma instalação é necessária! O pacote será baixado e executado automaticamente quando necessário. Consulte as seções Início Rápido ou Configuração.

Instalação Manual

Se você preferir instalar localmente ou se o seu cliente MCP não suportar uvx:

pip install docsetmcp

Em seguida, use docsetmcp em vez de uvx docsetmcp na sua configuração.

Instalação para Desenvolvimento

1. Clone e instale:

   git clone https://github.com/codybrom/docsetmcp.git
   cd docsetmcp
   pip install -e .
   

2. Execute os testes (opcional):

   # Install test dependencies
   pip install pytest pytest-cov pytest-xdist
   
   # Run basic tests
   pytest tests/test_docsets.py::TestDocsets::test_yaml_structure -v
   
   # Run quick tests (structure + existence checks)
   pytest tests/ -k "yaml_structure or test_docset_exists" -v
   
   # Run full test suite (all docsets)
   pytest tests/ -v
   
   # Run with coverage
   pytest tests/ --cov=docsetmcp --cov-report=html -v
   
   # Validate all local cheatsheets work (integration test)
   python scripts/validate_cheatsheets.py
   

Exemplos de Uso

Depois de configurado, você pode pedir ao seu assistente de IA para pesquisar documentação naturalmente:

🍎 Desenvolvimento iOS/macOS

"Search for URLSession documentation"
"Show me how to use AppIntent in SwiftUI"
"Find CarPlay framework documentation"  # Returns framework + related entries with drilldown notes
"Search for CPListTemplate class"       # Returns specific CarPlay class
"Find NSPredicate examples"

🌐 Desenvolvimento Web

"Look up Express.js middleware documentation"
"Search React hooks in the React docset"
"Find CSS flexbox properties"

🛠️ DevOps e Terminal

"Search git rebase commands in the Git cheatsheet"
"Show Docker compose syntax from the cheatsheet"
"Find bash array manipulation commands"

📊 Ciência de Dados

"Search pandas DataFrame methods"
"Look up NumPy array broadcasting"
"Find matplotlib pyplot functions"

Uso Avançado

# Search specific docset with language filter
"Use search_docs for 'URLSession' in the apple_api_reference docset with Swift language"

# Explore framework members using drilldown guidance
"Search for 'SwiftData' then follow the drilldown note to see all members"

# List all available tools
"What frameworks are available in the nodejs docset?"

# Browse cheatsheet categories
"Show all categories in the vim cheatsheet"

Fluxo de Descoberta

O DocsetMCP foi projetado para pesquisas baseadas em nome, não em palavras-chave. Siga este fluxo:

1. Comece com Ferramentas de Descoberta

# Find what languages are available
"List all available programming languages"

# Find docsets for your language
"Show me all Python docsets"

# See what types are available in a docset
"List all types in the apple_api_reference docset for Swift"

# Browse entries by type with letter filters
"Show me all Classes starting with 'UI' in apple_api_reference for Swift"

2. Depois Pesquise por Nomes Exatos

# Once you know exact names, search for them
"Search for UIViewController in apple_api_reference with Swift"
"Find readFile documentation in nodejs docset"
"Show me the CarPlay framework documentation"

3. Use Notas de Drilldown

Quando você encontrar tipos de contêiner (frameworks, classes), siga a orientação de drilldown:

# Container entry will show: "contains 42 additional members - use search_docs('ContainerName', max_results=50)"
"Search for SwiftData in apple_api_reference with max_results=50"

Como Funciona

1. Suporte a Múltiplos Formatos: Lida com o formato de cache da Apple e compressão tarix
2. Acesso Direto ao Banco de Dados: Consulta os bancos SQLite do Dash para buscas rápidas
3. Correspondência por Nome: Retorna apenas entradas onde os termos de busca correspondem aos nomes dos itens (sem falsos positivos)
4. Classificação Inteligente: Prioriza correspondências exatas, depois prefixos, depois substrings
5. Ordenação Dinâmica por Tipo: Usa arquivos de configuração do docset para priorização inteligente de resultados
6. Detecção de Contêineres: Detecta automaticamente frameworks/classes com membros e fornece orientação de exploração
7. Extração Inteligente: Descomprime o JSON DocC da Apple ou extrai HTML de arquivos tarix
8. Formatação Markdown: Converte documentação em Markdown legível

Ferramentas Disponíveis

O DocsetMCP fornece onze ferramentas poderosas para acessar sua documentação:

🔍 search_docs

Pesquise e extraia documentação de qualquer docset.

📋 search_cheatsheet

Pesquise cheatsheets do Dash para referência rápida de comandos.

📚 list_available_docsets

Liste todos os docsets instalados do Dash com suas linguagens suportadas.

📝 list_available_cheatsheets

Liste todos os cheatsheets disponíveis do Dash que podem ser pesquisados.

🏗️ list_frameworks

Liste frameworks/tipos dentro de um docset específico.

🌍 list_languages

Descubra todas as linguagens de programação com documentação disponível.

📖 list_docsets_by_language

Encontre todos os docsets que suportam uma linguagem de programação específica.

🏷️ list_types

Liste todos os tipos disponíveis (Classe, Protocolo, Função, etc.) em um docset/linguagem.

📋 list_entries

Liste entradas filtradas por tipo e prefixo de nome opcional.

📂 list_cheatsheet_categories

Liste todas as categorias dentro de um cheatsheet específico.

📄 fetch_cheatsheet

Obtenha o conteúdo completo do cheatsheet (recomendado para acesso abrangente).

Solução de Problemas

Desenvolvimento

Compilando a partir do código-fonte

# Clone the repository
git clone https://github.com/codybrom/docsetmcp.git
cd docsetmcp

# Install in development mode
pip install -e .

# Install all development dependencies
pip install -r requirements.txt

# Set up pre-commit hooks
pre-commit install

Testes

# Run basic structure tests
pytest tests/test_docsets.py::TestDocsets::test_yaml_structure -v

# Run quick tests (structure + existence)
pytest tests/ -k "yaml_structure or test_docset_exists" -v

# Run full test suite (all docsets)
pytest tests/ -v

# Run with coverage
pytest tests/ --cov=docsetmcp --cov-report=html -v

# Run tests in parallel
pytest tests/ -n auto -v

# Validate cheatsheets
python scripts/validate_cheatsheets.py

Qualidade do Código

# Format Python code with Black
black docsetmcp/

# Format YAML files with yamlfix
yamlfix docsetmcp/docsets/*.yaml

# Run all pre-commit hooks
pre-commit run --all-files

# Run specific hook
pre-commit run yamlfix --all-files

# Run spell check (cspell installed automatically during setup)
npm run spell

Comandos CLI

# Test version
docsetmcp --version

# List available docsets
docsetmcp --list-docsets

# Test server startup
docsetmcp --test-connection

# Test with custom paths
docsetmcp --docset-path "/custom/path" --list-docsets

Compilando a Distribuição

# Build package
python setup.py sdist bdist_wheel

# Install from source
pip install .

Arquitetura

Componentes Principais

• docsetmcp/server.py: Implementação principal do servidor MCP usando FastMCP. Contém a classe DashExtractor que lida com:

  • Formato de cache da Apple (baseado em UUID SHA-1 com compressão brotli)
  • Formato Tarix (arquivos tar.gz)
  • Consultas ao banco de dados SQLite para busca de documentação
  • Conversão de HTML para Markdown

• docsetmcp/config_loader.py: Sistema de configuração que carrega configurações YAML para mais de 165 docsets suportados. Fornece padrões inteligentes e lida com formatos de configuração simples e complexos.

• docsetmcp/docsets/: Arquivos de configuração YAML para cada docset suportado, definindo:

  • Caminhos e formatos de docset
  • Variantes de idioma e filtros
  • Prioridades de tipo para resultados de busca

Detalhes-chave da Implementação

1. Suporte a Múltiplos Formatos: O servidor detecta e lida automaticamente com o formato de cache moderno da Apple (usando UUIDs baseados em SHA-1) e o formato de compressão tarix mais antigo, com base na configuração do docset.

2. Estratégia de Cache: A documentação extraída é armazenada em cache na memória (_fs_cache para formato Apple, _html_cache para tarix) para melhorar o desempenho em consultas repetidas.

3. Algoritmo de Busca: Usa consultas LIKE sem distinção de maiúsculas/minúsculas no banco de dados optimizedIndex.dsidx. Os resultados são classificados por tipo de correspondência (exata > prefixo > substring) e depois pela ordenação dinâmica de tipos dos arquivos de configuração do docset. Retorna apenas entradas onde o termo de busca corresponde ao nome do item.

4. Carregamento de Configuração: O ConfigLoader aplica padrões inteligentes, permitindo configurações YAML mínimas enquanto suporta substituições complexas quando necessário.

5. Detecção de Tipo de Contêiner: Entradas de framework, classe e módulo incluem automaticamente notas de aprofundamento quando contêm membros adicionais, orientando os usuários a buscar conteúdo mais específico.

Contribuindo

Recebemos contribuições com prazer! Veja como você pode ajudar:

Adicionando Suporte a Novos Docsets

1. Crie uma configuração YAML em docsetmcp/docsets/:

   # docsetmcp/docsets/my_docset.yaml
   name: My Docset
   description: Brief description of the docset
   docset_path: My_Docset/My_Docset.docset
   languages:
     - python
     - javascript
   

2. Teste sua configuração:

   pytest tests/test_docsets.py -k "my_docset" -v
   

3. Envie um pull request

Reportando Problemas

• 🐛 Relatórios de Bugs
• 💡 Solicitações de Recursos
• 📚 Problemas de Documentação

Diretrizes de Desenvolvimento

• Siga as diretrizes de estilo PEP 8
• Adicione testes para novos recursos
• Atualize a documentação conforme necessário
• Mantenha os commits focados e descritivos

Arquitetura Técnica

O DocsetMCP aproveita a estrutura interna do Dash para acesso eficiente à documentação:

• Suporte a Formatos: Lida tanto com o formato de cache moderno da Apple (baseado em UUID SHA-1 com compressão brotli) quanto com arquivos tarix tradicionais
• Estratégia de Cache: Cache em memória para consultas repetidas
• Acesso ao Banco de Dados: Consultas SQLite diretas aos índices otimizados do Dash
• Extração de Conteúdo: Extração inteligente com estratégias de fallback
• Sistema de Tipos: Type hints completos para melhor suporte a IDEs

Licença

Licença MIT - consulte o arquivo LICENSE para detalhes.

Agradecimentos

• Agradecimentos a Kapeli por criar o Dash
• Construído sobre o padrão Model Context Protocol
• Inspirado pela comunidade e ecossistema MCP