Bucketeer Docs Local MCP Server

Bucketeer Docs Local MCP Server

Visão Geral

Este projeto fornece um servidor MCP (Model Context Protocol) para a documentação do Bucketeer. Ele oferece uma interface para pesquisar e recuperar conteúdo da documentação da plataforma de feature flags e experimentação do Bucketeer, permitindo que assistentes de IA forneçam informações precisas sobre os recursos e o uso do Bucketeer.

Configuração do Ambiente

Requisitos

• Node.js 18+
• npm

Etapas de Instalação

1. Clone o repositório:

git clone <repository-url>
cd bucketeer-docs-local-mcp-server

2. Instale as dependências:

npm install

3. Compile o projeto:

npm run build

4. Compile o índice de documentos:

npm run build:index

Iniciando o Servidor

npm start

Fontes de Documentos

O servidor busca e indexa automaticamente a documentação do repositório bucketeer-io/bucketeer-docs:

• Integração com o Repositório GitHub:

  • Busca automaticamente os arquivos .mdx do diretório docs/ e de todos os subdiretórios
  • Processa frontmatter e conteúdo markdown para indexação de busca otimizada
  • Armazena em cache o conteúdo usando hashes SHA e só atualiza quando os arquivos são modificados
  • Suporta travessia recursiva de diretórios para capturar todos os arquivos de documentação

• Indexação Inteligente:

  • Extrai palavras-chave de títulos, descrições, cabeçalhos e conteúdo
  • Constrói um índice pesquisável com pontuação de relevância baseada em correspondências de palavras-chave e busca de texto completo
  • Otimizado para a terminologia específica do Bucketeer (feature flags, experimentos, SDKs, targeting, etc.)
  • Lida com extração de frontmatter (título, descrição) de arquivos MDX

• Gerenciamento de Cache:

  • Os arquivos são armazenados em cache localmente no diretório files/docs/ como arquivos JSON
  • O índice de documentos é armazenado em files/index/document-index.json
  • O cache do GitHub é armazenado em files/docs/github_cache.json com detecção de alterações baseada em SHA
  • Use npm run build:index:force para forçar a reconstrução de todo o índice

Uso com npx

Configuração Inicial

1. Compile o índice de documentos:

npx @bucketeer/docs-local-mcp-server build-index

2. Use na sua configuração do MCP conforme mostrado na próxima seção.

Atualizando o Índice

Para atualizar o índice de documentação (por exemplo, quando houver nova documentação disponível):

npx @bucketeer/docs-local-mcp-server build-index --force

Configuração do Cursor e Claude Desktop

Configure o Servidor MCP adicionando o seguinte ao seu arquivo mcp.json ou claude_desktop_config.json, consultando a documentação do Cursor (https://docs.cursor.com/context/model-context-protocol#configuring-mcp-servers) e do Claude Desktop (https://modelcontextprotocol.io/quickstart/user):

Instalação Rápida com Deeplink do Cursor

Para usuários do Cursor, você pode instalar o servidor MCP com um único clique usando o deeplink abaixo:

Isso configurará automaticamente o servidor MCP nas configurações do seu Cursor. Após clicar no link, o Cursor solicitará que você instale o servidor.

Opção 1: Usando npx (Recomendado)

{
  "mcpServers": {
    "bucketeer-docs": {
      "type": "stdio",
      "command": "npx",
      "args": ["@bucketeer/docs-local-mcp-server"]
    }
  }
}

Opção 2: Usando instalação local

{
  "mcpServers": {
    "bucketeer-docs": {
      "type": "stdio",
      "command": "npm",
      "args": ["start", "--prefix", "/path/to/bucketeer-docs-local-mcp-server"]
    }
  }
}

Uso

Quando o servidor MCP estiver em execução, as seguintes ferramentas estarão disponíveis:

1. search_docs - Pesquisar Documentação do Bucketeer

• Parâmetro: query (string) - A consulta de pesquisa
• Parâmetro: limit (número, opcional) - Número máximo de resultados a retornar (padrão: 5)

Exemplo:

{
  "name": "search_docs",
  "arguments": {
    "query": "feature flags SDK integration",
    "limit": 5
  }
}

Resposta: Retorna um array de resultados de pesquisa com título, URL, caminho, descrição, trecho e pontuação de relevância.

2. get_document - Obter Conteúdo Específico do Documento

• Parâmetro: path (string) - Caminho do documento obtido nos resultados da pesquisa

Exemplo:

{
  "name": "get_document",
  "arguments": {
    "path": "getting-started/create-feature-flag"
  }
}

Resposta: Retorna o conteúdo completo do documento, incluindo título, descrição, URL e conteúdo markdown completo.

Comandos de Desenvolvimento

• npm run build - Compila arquivos TypeScript para o diretório dist/
• npm run build:index - Compila/atualiza o índice de documentos do repositório GitHub
• npm run build:index:force - Força a reconstrução de todo o índice (ignora o cache)
• npx @bucketeer/docs-local-mcp-server build-index - Compila o índice usando npx
• npx @bucketeer/docs-local-mcp-server build-index --force - Força a reconstrução do índice usando npx
• npm run dev:index - Compila e atualiza o índice em modo de desenvolvimento
• npm run dev - Compila e inicia o servidor em modo de desenvolvimento
• npm run lint - Executa a verificação de lint do Biome
• npm run lint:fix - Executa a verificação de lint do Biome e corrige erros de lint

Configuração

O servidor é configurado via src/config/index.ts:

• siteName: "Bucketeer"
• websiteUrl: "https://docs.bucketeer.io"
• githubRepo: "https://github.com/bucketeer-io/bucketeer-docs"
• docsDirectory: "docs" (diretório no repositório GitHub que contém a documentação)
• searchLimitDefault: 5 (número padrão de resultados de pesquisa)
• useGithubSource: true (sempre usa o GitHub como fonte)

Estrutura de Arquivos

files/
├── docs/           # Cached JSON files from GitHub repository
├── index/          # Document search index
│   └── document-index.json
└── [created automatically when building index]

Arquitetura

O servidor consiste em vários componentes principais:

1. GithubDocumentFetcher: Busca recursivamente os arquivos .mdx do repositório GitHub
2. IndexManager: Compila e gerencia o índice de documentos pesquisável
3. SearchService: Fornece funcionalidade de busca com correspondência de palavras-chave e busca de texto completo
4. Servidor MCP: Expõe ferramentas via Model Context Protocol

Licença

Apache License 2.0, consulte LICENSE.

Contribuindo

Adoraríamos ❤️ que você contribuísse para o Bucketeer e ajudasse a melhorá-lo! Qualquer pessoa pode usá-lo e aproveitá-lo!

Por favor, siga nosso guia de contribuição aqui.