Rust Docs MCP Server

Rust Docs MCP Server

⭐ Gosta deste projeto? Por favor, marque o repositório com estrela no GitHub para mostrar seu apoio e ficar atualizado! ⭐

Motivação

Assistentes de codificação modernos com IA (como Cursor, Cline, Roo Code, etc.) são excelentes em entender a estrutura e a sintaxe do código, mas muitas vezes têm dificuldade com os detalhes de bibliotecas e frameworks em rápida evolução, especialmente em ecossistemas como Rust, onde crates são atualizados com frequência. O corte nos dados de treinamento significa que eles podem não ter conhecimento das APIs mais recentes, levando a sugestões de código incorretas ou desatualizadas.

Este servidor MCP resolve esse desafio fornecendo uma fonte de conhecimento focada e atualizada para um crate Rust específico. Ao executar uma instância deste servidor para um crate (por exemplo, serde, tokio, reqwest), você dá ao seu assistente de codificação com LLM uma ferramenta (query_rust_docs) que ele pode usar antes de escrever código relacionado a esse crate.

Quando instruído a usar esta ferramenta, o LLM pode fazer perguntas específicas sobre a API ou o uso do crate e receber respostas derivadas diretamente da documentação atual. Isso melhora significativamente a precisão e a relevância do código gerado, reduzindo a necessidade de correção manual e acelerando o desenvolvimento.

Múltiplas instâncias deste servidor podem ser executadas simultaneamente, permitindo que o assistente LLM acesse a documentação de vários crates diferentes durante uma sessão de codificação.

Este servidor busca a documentação de um crate Rust especificado, gera embeddings para o conteúdo e fornece uma ferramenta MCP para responder perguntas sobre o crate com base no contexto da documentação.

Recursos

• Documentação Direcionada: Foca em um único crate Rust por instância do servidor.
• Suporte a Recursos: Permite especificar recursos necessários do crate para a geração da documentação.
• Busca Semântica: Usa o modelo text-embedding-3-small da OpenAI para encontrar as seções de documentação mais relevantes para uma determinada pergunta.
• Resumo com LLM: Utiliza o modelo gpt-4o-mini-2024-07-18 da OpenAI para gerar respostas concisas com base apenas no contexto da documentação recuperada.
• Cache: Armazena em cache o conteúdo da documentação gerada e os embeddings no diretório de dados XDG do usuário (~/.local/share/rustdocs-mcp-server/ ou similar) com base no crate, versão e recursos solicitados para acelerar execuções subsequentes.
• Integração MCP: Executa como um servidor MCP padrão via stdio, expondo ferramentas e recursos.

Pré-requisitos

• Chave da API OpenAI: Necessária para gerar embeddings e resumir respostas. O servidor espera que esta chave esteja disponível na variável de ambiente OPENAI_API_KEY. (O servidor também requer acesso à rede para baixar dependências do crate e interagir com a API da OpenAI).

Instalação

A maneira recomendada de instalar é baixar o binário pré-compilado para o seu sistema operacional na página de Releases do GitHub.

1. Vá para a página de Releases.
2. Baixe o arquivo apropriado (.zip para Windows, .tar.gz para Linux/macOS) para o seu sistema.
3. Extraia o binário rustdocs_mcp_server (ou rustdocs_mcp_server.exe).
4. Coloque o binário em um diretório incluído na variável de ambiente PATH do seu sistema (por exemplo, /usr/local/bin, ~/bin).

Compilando a partir do Código Fonte (Alternativa)

Se preferir compilar a partir do código fonte, você precisará do Rust Toolchain instalado.

1. Clone o repositório:

   git clone https://github.com/Govcraft/rust-docs-mcp-server.git
   cd rust-docs-mcp-server
   

2. Compile o servidor:

   cargo build --release
   

Uso

Nota Importante para Crates Novos:

Ao usar o servidor com um crate pela primeira vez (ou com uma nova versão/conjunto de recursos), ele precisa baixar a documentação e gerar embeddings. Esse processo pode levar algum tempo, especialmente para crates com documentação extensa, e requer uma conexão ativa com a internet e uma chave da API OpenAI.

Recomenda-se executar o servidor uma vez diretamente do seu terminal para qualquer nova configuração de crate antes de adicioná-lo ao seu assistente de codificação com IA (como Roo Code, Cursor, etc.). Isso permite que a geração inicial de embeddings e o cache sejam concluídos. Assim que você vir as mensagens de inicialização do servidor indicando que ele está pronto (por exemplo, "MCP Server listening on stdio"), você pode desligá-lo (Ctrl+C). Execuções subsequentes, incluindo aquelas iniciadas pelo seu assistente de codificação, usarão os dados em cache e iniciarão muito mais rápido.

Executando o Servidor

O servidor é iniciado a partir da linha de comando e requer a Especificação do ID do Pacote para o crate alvo. Esta especificação segue o formato usado pelo Cargo (por exemplo, crate_name, crate_name@version_req). Para obter os detalhes completos da especificação, consulte man cargo-pkgid ou a documentação do Cargo.

Opcionalmente, você pode especificar os recursos necessários do crate usando o sinalizador -F ou --features, seguido por uma lista separada por vírgulas de recursos. Isso é necessário para crates que exigem que recursos específicos sejam habilitados para que o cargo doc seja bem-sucedido (por exemplo, crates que exigem um recurso de tempo de execução como async-stripe).

# Set the API key (replace with your actual key)
export OPENAI_API_KEY="sk-..."

# Example: Run server for the latest 1.x version of serde
rustdocs_mcp_server "serde@^1.0"

# Example: Run server for a specific version of reqwest
rustdocs_mcp_server "reqwest@0.12.0"

# Example: Run server for the latest version of tokio
rustdocs_mcp_server tokio

# Example: Run server for async-stripe, enabling a required runtime feature
rustdocs_mcp_server "async-stripe@0.40" -F runtime-tokio-hyper-rustls

# Example: Run server for another crate with multiple features
rustdocs_mcp_server "some-crate@1.2" --features feat1,feat2

Na primeira execução para uma versão específica do crate e conjunto de recursos, o servidor irá:

1. Baixar a documentação do crate usando cargo doc (com os recursos especificados).
2. Analisar a documentação HTML.
3. Gerar embeddings para o conteúdo da documentação usando a API da OpenAI (isso pode levar algum tempo e gerar custos, embora normalmente apenas frações de um centavo de dólar para a maioria dos crates; até mesmo um crate grande como async-stripe com mais de 5000 páginas de documentação custou apenas US$ 0,18 para a geração de embeddings durante os testes).
4. Armazenar em cache o conteúdo da documentação e os embeddings para que o custo não seja incorrido novamente.
5. Iniciar o servidor MCP.

Execuções subsequentes para a mesma versão do crate e conjunto de recursos carregarão os dados do cache, tornando a inicialização muito mais rápida.

Interação MCP

O servidor se comunica usando o Model Context Protocol por meio de entrada/saída padrão (stdio). Ele expõe o seguinte:

• Ferramenta: query_rust_docs

  • Descrição: Consulta a documentação do crate Rust específico para o qual o servidor foi iniciado, usando busca semântica e resumo com LLM.
  • Esquema de Entrada:

    {
      "type": "object",
      "properties": {
        "question": {
          "type": "string",
          "description": "The specific question about the crate's API or usage."
        }
      },
      "required": ["question"]
    }
    

  • Saída: Uma resposta em texto contendo a resposta gerada pelo LLM com base no contexto da documentação relevante, prefixada com From <crate_name> docs:.
  • Exemplo de Chamada MCP:

    {
      "jsonrpc": "2.0",
      "method": "callTool",
      "params": {
        "tool_name": "query_rust_docs",
        "arguments": {
          "question": "How do I make a simple GET request with reqwest?"
        }
      },
      "id": 1
    }
    

• Recurso: crate://<crate_name>

  • Descrição: Fornece o nome do crate Rust para o qual esta instância do servidor está configurada.
  • URI: crate://<crate_name> (por exemplo, crate://serde, crate://reqwest)
  • Conteúdo: Texto simples contendo o nome do crate.

• Registro: O servidor envia logs informativos (mensagens de inicialização, etapas de processamento de consultas) de volta ao cliente MCP por meio de notificações logging/message.

Exemplo de Configuração de Cliente (Roo Code)

Você pode configurar clientes MCP como o Roo Code para executar múltiplas instâncias deste servidor, cada uma direcionada a um crate diferente. Aqui está um exemplo de trecho para o arquivo mcp_settings.json do Roo Code, configurando servidores para reqwest e async-stripe (observe o argumento de recursos adicionado para async-stripe):

{
  "mcpServers": {
    "rust-docs-reqwest": {
      "command": "/path/to/your/rustdocs_mcp_server",
      "args": [
        "reqwest@0.12"
      ],
      "env": {
        "OPENAI_API_KEY": "YOUR_OPENAI_API_KEY_HERE"
      },
      "disabled": false,
      "alwaysAllow": []
    },
    "rust-docs-async-stripe": {
      "command": "rustdocs_mcp_server",
      "args": [
        "async-stripe@0.40",
        "-F",
        " runtime-tokio-hyper-rustls"
      ],
      "env": {
        "OPENAI_API_KEY": "YOUR_OPENAI_API_KEY_HERE"
      },
      "disabled": false,
      "alwaysAllow": []
    }
  }
}

Nota:

• Substitua /path/to/your/rustdocs_mcp_server pelo caminho real para o binário compilado no seu sistema se ele não estiver no seu PATH.
• Substitua YOUR_OPENAI_API_KEY_HERE pela sua chave real da API OpenAI.
• As chaves (rust-docs-reqwest, rust-docs-async-stripe) são nomes arbitrários que você escolhe para identificar as instâncias do servidor dentro do Roo Code.

Exemplo de Configuração de Cliente (Claude Desktop)

Para usuários do Claude Desktop, você pode configurar o servidor nas configurações do MCP. Aqui está um exemplo configurando servidores para serde e async-stripe:

{
  "mcpServers": {
    "rust-docs-serde": {
      "command": "/path/to/your/rustdocs_mcp_server",
      "args": [
        "serde@^1.0"
      ]
    },
    "rust-docs-async-stripe-rt": {
      "command": "rustdocs_mcp_server",
      "args": [
        "async-stripe@0.40",
        "-F",
        "runtime-tokio-hyper-rustls"
      ]
    }
  }
}

Nota:

• Certifique-se de que rustdocs_mcp_server esteja no PATH do seu sistema ou forneça o caminho completo (por exemplo, /path/to/your/rustdocs_mcp_server).
• As chaves (rust-docs-serde, rust-docs-async-stripe-rt) são nomes arbitrários que você escolhe para identificar as instâncias do servidor.
• Lembre-se de definir a variável de ambiente OPENAI_API_KEY onde o Claude Desktop possa acessá-la (isso pode ser em todo o sistema ou por meio de como você inicia o Claude Desktop). A configuração MCP do Claude Desktop pode não suportar diretamente a definição de variáveis de ambiente por servidor como o Roo Code.
• O exemplo mostra como adicionar o argumento -F para crates como async-stripe que exigem recursos específicos.

Cache

• Localização: A documentação e os embeddings em cache são armazenados no diretório de dados XDG, normalmente em ~/.local/share/rustdocs-mcp-server/<crate_name>/<sanitized_version_req>/<features_hash>/embeddings.bin. O sanitized_version_req é derivado do requisito de versão, e features_hash é um hash que representa a combinação específica de recursos solicitados na inicialização. Isso garante que diferentes conjuntos de recursos sejam armazenados em cache separadamente.
• Formato: Os dados são armazenados em cache usando serialização bincode.
• Regeneração: Se o arquivo de cache estiver ausente, corrompido ou não puder ser decodificado, o servidor regenerará automaticamente a documentação e os embeddings.

Como Funciona

1. Inicialização: Analisa a especificação do crate e os recursos opcionais da linha de comando usando clap.
2. Verificação de Cache: Procura um arquivo de cache pré-existente para o crate, requisito de versão e conjunto de recursos específicos.
3. Geração de Documentação (se houver falta de cache):
   • Cria um projeto Rust temporário dependendo apenas do crate alvo, habilitando os recursos especificados no seu Cargo.toml.
   • Executa cargo doc usando a API da biblioteca cargo para gerar documentação HTML no diretório temporário.
   • Localiza dinamicamente o diretório de saída correto dentro de target/doc procurando o subdiretório que contém index.html.
4. Extração de Conteúdo (se houver falta de cache):
   • Percorre os arquivos HTML gerados dentro do diretório de documentação localizado.
   • Usa o crate scraper para analisar cada arquivo HTML e extrair o conteúdo de texto da área de conteúdo principal (<section id="main-content">).
5. Geração de Embeddings (se houver falta de cache):
   • Usa o crate async-openai e tiktoken-rs para gerar embeddings para cada trecho de documento extraído usando o modelo text-embedding-3-small.
   • Calcula o custo estimado com base no número de tokens processados.
6. Cache (se houver falta de cache): Salva o conteúdo do documento extraído e seus embeddings correspondentes no arquivo de cache (o caminho inclui o hash dos recursos) usando bincode.
7. Inicialização do Servidor: Inicializa o RustDocsServer com os documentos e embeddings carregados/gerados.
8. Serviço MCP: Inicia o servidor MCP usando rmcp via stdio.
9. Tratamento de Consultas (ferramenta query_rust_docs):
   • Gera um embedding para a pergunta do usuário.
   • Calcula a similaridade de cosseno entre o embedding da pergunta e todos os embeddings de documentos em cache.
   • Identifica o trecho de documento com a maior similaridade.
   • Envia a pergunta do usuário e o conteúdo do trecho de documento com melhor correspondência para o modelo gpt-4o-mini-2024-07-18 por meio da API da OpenAI.
   • O LLM é instruído a responder à pergunta com base apenas no contexto fornecido.
   • Retorna a resposta do LLM ao cliente MCP.

Licença

Este projeto está licenciado sob a Licença MIT.

Copyright (c) 2025 Govcraft

Patrocinador

Govcraft é uma loja de uma pessoa só—sem apoio corporativo, sem investidores, apenas eu construindo ferramentas úteis. Se este projeto ajudar você, patrocinar mantém o trabalho em andamento.