Rust Docs MCP Server

Consulta la documentación más reciente de los crates de Rust.

Documentación

Rust Docs MCP Server

⭐ ¿Te gusta este proyecto? ¡Por favor da una estrella al repositorio en GitHub para mostrar tu apoyo y mantenerte al día! ⭐

Motivación

Los asistentes de codificación modernos impulsados por IA (como Cursor, Cline, Roo Code, etc.) son excelentes para comprender la estructura y sintaxis del código, pero a menudo tienen dificultades con los detalles de bibliotecas y frameworks que evolucionan rápidamente, especialmente en ecosistemas como Rust donde los crates se actualizan con frecuencia. El corte en sus datos de entrenamiento significa que pueden carecer de conocimiento sobre las APIs más recientes, lo que genera sugerencias de código incorrectas o desactualizadas.

Este servidor MCP aborda este desafío proporcionando una fuente de conocimiento enfocada y actualizada para un crate específico de Rust. Al ejecutar una instancia de este servidor para un crate (p. ej., serde, tokio, reqwest), le das a tu asistente de codificación LLM una herramienta (query_rust_docs) que puede usar antes de escribir código relacionado con ese crate.

Cuando se le indica que use esta herramienta, el LLM puede hacer preguntas específicas sobre la API o el uso del crate y recibir respuestas derivadas directamente de la documentación actual. Esto mejora significativamente la precisión y relevancia del código generado, reduciendo la necesidad de corrección manual y acelerando el desarrollo.

Se pueden ejecutar varias instancias de este servidor simultáneamente, lo que permite al asistente LLM acceder a la documentación de varios crates diferentes durante una sesión de codificación.

Este servidor obtiene la documentación de un crate específico de Rust, genera embeddings para el contenido y proporciona una herramienta MCP para responder preguntas sobre el crate basándose en el contexto de la documentación.

Características

Documentación específica: Se centra en un solo crate de Rust por instancia del servidor.
Soporte de características: Permite especificar las características requeridas del crate para la generación de documentación.
Búsqueda semántica: Utiliza el modelo text-embedding-3-small de OpenAI para encontrar las secciones de documentación más relevantes para una pregunta determinada.
Resumen con LLM: Aprovecha el modelo gpt-4o-mini-2024-07-18 de OpenAI para generar respuestas concisas basadas solo en el contexto de documentación recuperado.
Caché: Almacena en caché el contenido de documentación generado y los embeddings en el directorio de datos XDG del usuario (~/.local/share/rustdocs-mcp-server/ o similar) según el crate, la versión y las características solicitadas para acelerar los lanzamientos posteriores.
Integración MCP: Se ejecuta como un servidor MCP estándar sobre stdio, exponiendo herramientas y recursos.

Requisitos previos

Clave de API de OpenAI: Necesaria para generar embeddings y resumir respuestas. El servidor espera que esta clave esté disponible en la variable de entorno OPENAI_API_KEY. (El servidor también requiere acceso a la red para descargar las dependencias del crate e interactuar con la API de OpenAI).

Instalación

La forma recomendada de instalar es descargar el binario precompilado para tu sistema operativo desde la página de Releases de GitHub.

Ve a la página de Releases.
Descarga el archivo apropiado (.zip para Windows, .tar.gz para Linux/macOS) para tu sistema.
Extrae el binario rustdocs_mcp_server (o rustdocs_mcp_server.exe).
Coloca el binario en un directorio incluido en la variable de entorno PATH de tu sistema (p. ej., /usr/local/bin, ~/bin).

Compilar desde el código fuente (Alternativa)

Si prefieres compilar desde el código fuente, necesitarás tener instalado el Rust Toolchain.

Clona el repositorio:

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

Compila el servidor:
```
cargo build --release
```

Uso

Nota importante para crates nuevos:

Cuando uses el servidor con un crate por primera vez (o con una nueva versión/conjunto de características), necesitará descargar la documentación y generar embeddings. Este proceso puede llevar algún tiempo, especialmente para crates con documentación extensa, y requiere una conexión a internet activa y una clave de API de OpenAI.

Se recomienda ejecutar el servidor una vez directamente desde tu línea de comandos para cualquier configuración de crate nuevo antes de agregarlo a tu asistente de codificación IA (como Roo Code, Cursor, etc.). Esto permite que se complete la generación inicial de embeddings y el caché. Una vez que veas los mensajes de inicio del servidor que indican que está listo (p. ej., "MCP Server listening on stdio"), puedes apagarlo (Ctrl+C). Los lanzamientos posteriores, incluidos los iniciados por tu asistente de codificación, usarán los datos en caché y arrancarán mucho más rápido.

Ejecutar el servidor

El servidor se lanza desde la línea de comandos y requiere la Especificación de ID de Paquete para el crate objetivo. Esta especificación sigue el formato utilizado por Cargo (p. ej., crate_name, crate_name@version_req). Para los detalles completos de la especificación, consulta man cargo-pkgid o la documentación de Cargo.

Opcionalmente, puedes especificar las características requeridas del crate usando la bandera -F o --features, seguida de una lista de características separadas por comas. Esto es necesario para crates que requieren características específicas habilitadas para que cargo doc tenga éxito (p. ej., crates que requieren una característica de runtime 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

En la primera ejecución para una versión de crate específica y conjunto de características, el servidor hará lo siguiente:

Descargará la documentación del crate usando cargo doc (con las características especificadas).
Analizará el HTML de la documentación.
Generará embeddings para el contenido de la documentación usando la API de OpenAI (esto puede llevar tiempo y generar costos, aunque normalmente solo fracciones de un centavo de dólar para la mayoría de los crates; incluso un crate grande como async-stripe con más de 5000 páginas de documentación costó solo $0.18 USD para la generación de embeddings durante las pruebas).
Almacenará en caché el contenido de la documentación y los embeddings para que el costo no se incurra nuevamente.
Iniciará el servidor MCP.

Las ejecuciones posteriores para la misma versión de crate y conjunto de características cargarán los datos desde el caché, haciendo que el inicio sea mucho más rápido.

Interacción MCP

El servidor se comunica usando el Protocolo de Contexto de Modelo (MCP) sobre entrada/salida estándar (stdio). Expone lo siguiente:

Herramienta: query_rust_docs

Descripción: Consulta la documentación del crate específico de Rust para el cual se inició el servidor, usando búsqueda semántica y resumen con LLM.

Esquema de entrada:

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

Salida: Una respuesta de texto que contiene la respuesta generada por el LLM basada en el contexto de documentación relevante, precedida por From <crate_name> docs:.

Ejemplo de llamada 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>
- Descripción: Proporciona el nombre del crate de Rust para el cual esta instancia del servidor está configurada.
- URI: crate://<crate_name> (p. ej., crate://serde, crate://reqwest)
- Contenido: Texto plano que contiene el nombre del crate.
Registro (Logging): El servidor envía registros informativos (mensajes de inicio, pasos de procesamiento de consultas) de vuelta al cliente MCP a través de notificaciones logging/message.

Ejemplo de configuración de cliente (Roo Code)

Puedes configurar clientes MCP como Roo Code para ejecutar múltiples instancias de este servidor, cada una dirigida a un crate diferente. Aquí hay un ejemplo de fragmento para el archivo mcp_settings.json de Roo Code, configurando servidores para reqwest y async-stripe (observa el argumento de características agregado 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:

Reemplaza /path/to/your/rustdocs_mcp_server con la ruta real al binario compilado en tu sistema si no está en tu PATH.
Reemplaza YOUR_OPENAI_API_KEY_HERE con tu clave real de API de OpenAI.
Las claves (rust-docs-reqwest, rust-docs-async-stripe) son nombres arbitrarios que eliges para identificar las instancias del servidor dentro de Roo Code.

Ejemplo de configuración de cliente (Claude Desktop)

Para usuarios de Claude Desktop, puedes configurar el servidor en la configuración de MCP. Aquí hay un ejemplo que configura servidores para serde y 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:

Asegúrate de que rustdocs_mcp_server esté en el PATH de tu sistema o proporciona la ruta completa (p. ej., /path/to/your/rustdocs_mcp_server).
Las claves (rust-docs-serde, rust-docs-async-stripe-rt) son nombres arbitrarios que eliges para identificar las instancias del servidor.
Recuerda configurar la variable de entorno OPENAI_API_KEY donde Claude Desktop pueda acceder a ella (esto podría ser en todo el sistema o mediante la forma en que lanzas Claude Desktop). La configuración MCP de Claude Desktop podría no soportar directamente configurar variables de entorno por servidor como Roo Code.
El ejemplo muestra cómo agregar el argumento -F para crates como async-stripe que requieren características específicas.

Caché

Ubicación: La documentación y los embeddings en caché se almacenan en el directorio de datos XDG, típicamente bajo ~/.local/share/rustdocs-mcp-server/<crate_name>/<sanitized_version_req>/<features_hash>/embeddings.bin. El sanitized_version_req se deriva del requisito de versión, y features_hash es un hash que representa la combinación específica de características solicitadas al inicio. Esto asegura que los diferentes conjuntos de características se almacenen en caché por separado.
Formato: Los datos se almacenan en caché usando serialización bincode.
Regeneración: Si el archivo de caché falta, está corrupto o no se puede decodificar, el servidor regenerará automáticamente la documentación y los embeddings.

Cómo funciona

Inicialización: Analiza la especificación del crate y las características opcionales desde la línea de comandos usando clap.
Verificación de caché: Busca un archivo de caché preexistente para el crate, requisito de versión y conjunto de características específicos.
Generación de documentación (si no hay caché):
- Crea un proyecto Rust temporal que depende solo del crate objetivo, habilitando las características especificadas en su Cargo.toml.
- Ejecuta cargo doc usando la API de la biblioteca cargo para generar documentación HTML en el directorio temporal.
- Localiza dinámicamente el directorio de salida correcto dentro de target/doc al buscar el subdirectorio que contiene index.html.
Extracción de contenido (si no hay caché):
- Recorre los archivos HTML generados dentro del directorio de documentación localizado.
- Usa el crate scraper para analizar cada archivo HTML y extraer el contenido de texto del área de contenido principal (<section id="main-content">).
Generación de embeddings (si no hay caché):
- Usa el crate async-openai y tiktoken-rs para generar embeddings para cada fragmento de documento extraído usando el modelo text-embedding-3-small.
- Calcula el costo estimado según la cantidad de tokens procesados.
Caché (si no hay caché): Guarda el contenido del documento extraído y sus embeddings correspondientes en el archivo de caché (la ruta incluye el hash de características) usando bincode.
Inicio del servidor: Inicializa el RustDocsServer con los documentos y embeddings cargados/generados.
Servicio MCP: Inicia el servidor MCP usando rmcp sobre stdio.
Manejo de consultas (herramienta query_rust_docs):
- Genera un embedding para la pregunta del usuario.
- Calcula la similitud coseno entre el embedding de la pregunta y todos los embeddings de documentos en caché.
- Identifica el fragmento de documento con la mayor similitud.
- Envía la pregunta del usuario y el contenido del fragmento de documento que mejor coincide al modelo gpt-4o-mini-2024-07-18 a través de la API de OpenAI.
- Se le indica al LLM que responda la pregunta basándose solo en el contexto proporcionado.
- Devuelve la respuesta del LLM al cliente MCP.

Licencia

Este proyecto está licenciado bajo la Licencia MIT.

Patrocinio

Govcraft es un negocio de una sola persona: sin respaldo corporativo, sin inversores, solo yo construyendo herramientas útiles. Si este proyecto te ayuda, patrocinar mantiene el trabajo en marcha.