rust-cargo-docs-rag-mcp is an MCP (Model Context Protocol) server that provides tools for Rust crate documentation lookup. It allows LLMs to look up documentation for Rust crates they are unfamiliar with. This README focuses on how to build, version, release, and install the project using two common paths: 1. pkgx (build/install locally from source) 2. Docker image (published to GitHub Container R
Add this skill
npx mdskills install promptexecution/cratedocs-mcpComprehensive MCP server for Rust crate documentation with excellent multi-deployment support
1# Rust Cargo Docs RAG MCP23`rust-cargo-docs-rag-mcp` is an MCP (Model Context Protocol) server that provides tools for Rust crate documentation lookup. It allows LLMs to look up documentation for Rust crates they are unfamiliar with.45This README focuses on how to build, version, release, and install the project using two common paths:61. pkgx (build/install locally from source)72. Docker image (published to GitHub Container Registry — GHCR)89---1011## Release / Versioning workflow (maintainers)1213```bash14git clone https://github.com/promptexecution/rust-cargo-docs-rag-mcp.git15cd rust-cargo-docs-rag-mcp16cargo build --release17cargo install --path .18# Or install the pkgx-managed binary and check its version19just install-pkgx20```2122### Installing with pkgx2324The repository includes a mini [pkgx pantry](./pkgx) so you can build and run the CLI through `pkgx` without touching your global toolchain:2526```bash27git clone https://github.com/promptexecution/rust-cargo-docs-rag-mcp.git28cd rust-cargo-docs-rag-mcp29export PKGX_PANTRY_PATH=$PWD/pkgx30export PKGX_PANTRY_DIR=$PWD/pkgx # pkgx^2 compatibility31pkgx cratedocs version32```3334`pkgx` will download the tagged source tarball, compile `cratedocs` with the required Rust toolchain, and cache the result for subsequent runs. Once you're ready to upstream this package to the central [pkgx pantry](https://github.com/pkgxdev/pantry), copy `pkgx/projects/github.com/promptexecution/rust-cargo-docs-rag-mcp/package.yml` into a new PR there.3536## Running the Server37This repository is wired to Cocogitto via `cog.toml`. Typical flow to create a release:38391. Install Cocogitto (once)40 ```bash41 cargo install cocogitto42 ```43442. Bump the version / create the tag from main (on your machine):45 ```bash46 git checkout main47 git pull origin main48 cog bump patch49 # or `cog bump minor` / `cog bump major`50 ```5152 - `cog bump` runs the pre_bump_hooks/post_bump_hooks defined in `cog.toml`.53 - This will update Cargo.toml, Cargo.lock and CHANGELOG.md, and create a signed tag `vX.Y.Z`.54553. Push commit + tag to GitHub:56 ```bash57 git push --follow-tags origin main58 ```5960When the tag is pushed, the `Release & Publish (GHCR)` workflow will run:61- It builds multi-arch (amd64/arm64) Docker images with Docker Buildx and pushes them to GHCR at:62 - ghcr.io/<org_or_user>/rust-cargo-docs-rag-mcp:<tag>63 - ghcr.io/<org_or_user>/rust-cargo-docs-rag-mcp:latest64- It creates a GitHub Release for that tag and uploads the release binary (target/release/cratedocs) as an asset.6566Repository requirements:67- Ensure GitHub Actions has permission to publish packages (Packages / Container registry). The release workflow uses the repository's GITHUB_TOKEN and sets packages: write in workflow permissions.68- Ensure `main` is the branch you want `cog` to operate from (cog.toml has branch_whitelist = ["main"] by default).6970---7172## Install / Run — Docker (recommended for consumers)7374Prebuilt images are published to GitHub Container Registry (GHCR) on release tags.7576Pull the image (replace OWNER with the GH org or username that owns the repo; tags look like v0.3.1):77```bash78docker pull ghcr.io/promptexecution/rust-cargo-docs-rag-mcp:latest79# or a specific version:80docker pull ghcr.io/promptexecution/rust-cargo-docs-rag-mcp:v0.3.181```8283Run the container in HTTP mode (default):84```bash85docker run --rm -p 8080:8080 ghcr.io/promptexecution/rust-cargo-docs-rag-mcp:latest86```8788Run in stdio mode:89```bash90docker run --rm -e CRATEDOCS_MODE=stdio -i ghcr.io/promptexecution/rust-cargo-docs-rag-mcp:latest91```9293### Using Docker9495You can also build and run the server in an Alpine-based container. Prebuilt images are automatically published to GHCR via [`.github/workflows/docker.yml`](.github/workflows/docker.yml):9697```bash98docker pull ghcr.io/promptexecution/rust-cargo-docs-rag-mcp:latest99```100101To build locally (useful before pushing to another registry):102103```bash104# Build the image (adjust the tag to match your registry)105docker build -t promptexecution/rust-cargo-docs-rag-mcp .106107# Run HTTP/SSE mode on port 8080108docker run --rm -p 8080:8080 promptexecution/rust-cargo-docs-rag-mcp109```110111Configuration is controlled through environment variables:112- `CRATEDOCS_MODE` (default `http`): switch to `stdio` to expose the stdio MCP server113- `CRATEDOCS_ADDRESS` (default `0.0.0.0:8080`): bind the HTTP server to a specific interface/port114- `CRATEDOCS_DEBUG` (default `false`): set to `true` to enable verbose logging in HTTP mode115116All additional arguments appended to `docker run ... -- <args>` are forwarded to the underlying `cratedocs` process.117118### Directly Testing Documentation Tools119### Environment Variables120121- `CRATEDOCS_MODE` (default: `http`) — set to `stdio` to run the stdio MCP server122- `CRATEDOCS_ADDRESS` (default: `0.0.0.0:8080`) — bind address for HTTP mode123- `CRATEDOCS_DEBUG` (default: `false`) — set to `true` to enable debug logging124125### Passing custom arguments126127You can also pass custom arguments directly to the `cratedocs` binary:128```bash129docker run --rm -p 3000:3000 ghcr.io/promptexecution/rust-cargo-docs-rag-mcp:latest \130 http --address 0.0.0.0:3000 --debug131```132133---134135## Install / Run — pkgx (local build from source)136137[pkgx](https://pkgx.dev) is a universal package manager that can build and run this project without requiring a system-wide Rust installation:138139```bash140# Install using pkgx (automatically handles Rust dependencies)141pkgx install142143# Or build directly with pkgx144pkgx +rust +cargo cargo build --release145146# Run without installing147pkgx +rust +cargo cargo run --bin cratedocs -- stdio148```149150The project includes a `package.yml` file for pkgx integration, making it easy to build and test across different environments.151152---153154## Install / Run — Cargo (standard Rust toolchain)155156```bash157git clone https://github.com/promptexecution/rust-cargo-docs-rag-mcp.git158cd rust-cargo-docs-rag-mcp159cargo build --release160cargo install --path .161```162163After installation, you can run:164```bash165# STDIN/STDOUT mode166cratedocs stdio167168# HTTP/SSE mode169cratedocs http --address 127.0.0.1:8080170171# With debug logging172cratedocs http --address 127.0.0.1:8080 --debug173```174175---176177## Features178179- **Lookup crate documentation**: Get general documentation for a Rust crate180- **Search crates**: Search for crates on crates.io based on keywords181- **Lookup item documentation**: Get documentation for a specific item (e.g., struct, function, trait) within a crate182- **List crate items**: Enumerate all items in a crate with optional filtering183184---185186## Available Tools187188The server provides the following tools via the MCP protocol:189190### 1. `lookup_crate`191192Retrieves documentation for a specified Rust crate.193194Parameters:195- `crate_name` (required): The name of the crate to look up196- `version` (optional): The version of the crate (defaults to latest)197198Example:199```json200{201 "name": "lookup_crate",202 "arguments": {203 "crate_name": "tokio",204 "version": "1.28.0"205 }206}207```208209### 2. `search_crates`210211Searches for Rust crates on crates.io.212213Parameters:214- `query` (required): The search query215- `limit` (optional): Maximum number of results to return (defaults to 10, max 100)216217Example:218```json219{220 "name": "search_crates",221 "arguments": {222 "query": "async runtime",223 "limit": 5224 }225}226```227228### 3. `lookup_item`229230Retrieves documentation for a specific item in a crate.231232Parameters:233- `crate_name` (required): The name of the crate234- `item_path` (required): Path to the item (e.g., 'std::vec::Vec')235- `version` (optional): The version of the crate (defaults to latest)236237Example:238```json239{240 "name": "lookup_item",241 "arguments": {242 "crate_name": "serde",243 "item_path": "serde::Deserialize",244 "version": "1.0.160"245 }246}247```248249### 4. `list_crate_items`250251Enumerates all items in a specified Rust crate and version, optionally filtering by item type, visibility, or module path.252253Parameters:254- `crate_name` (required): The name of the crate255- `version` (required): The version of the crate256- `item_type` (optional): Filter by item type (struct, enum, trait, fn, macro, mod)257- `visibility` (optional): Filter by visibility (pub, private)258- `module` (optional): Filter by module path (e.g., serde::de)259260Example:261```json262{263 "name": "list_crate_items",264 "arguments": {265 "crate_name": "serde",266 "version": "1.0.0",267 "item_type": "struct"268 }269}270```271272---273274## Testing Tools Directly275276You can directly test the documentation tools from the command line without starting a server:277278```bash279# Get help for the test command280cargo run --bin cratedocs test --tool help281282# Enumerate crate items283cargo run --bin cratedocs test --tool list_crate_items --crate-name serde --version 1.0.0 --item-type struct284285# Look up crate documentation286cargo run --bin cratedocs test --tool lookup_crate --crate-name tokio287288# Look up item documentation289cargo run --bin cratedocs test --tool lookup_item --crate-name tokio --item-path sync::mpsc::Sender290291# Search for crates292cargo run --bin cratedocs test --tool search_crates --query logger --limit 5293294# Output in different formats (markdown, text, json)295cargo run --bin cratedocs test --tool search_crates --query logger --format json296297# Summarize output (strip LICENSE and VERSION sections, limit tokens)298cargo run --bin cratedocs test --tool lookup_crate --crate-name tokio --tldr --max_tokens 48000299```300301---302303## MCP Protocol Integration304305This server implements the Model Context Protocol (MCP) which allows it to be easily integrated with LLM clients that support the protocol. For more information about MCP, visit [the MCP repository](https://github.com/modelcontextprotocol/mcp).306307### VSCode MCP, RooCode local example308309```bash310# compile & install cratedocs in ~/.cargo/bin311cargo install --path .312```313314in `mcp_settings.json`:315```json316{317 "mcpServers":{318 "rust-crate-local": {319 "command": "cratedocs",320 "args": [321 "stdio"322 ]323 }324 }325}326```327328### VSCode MCP, RooCode hosted example329330```json331{332 "mcpServers":{333 "rust-crate-docs": {334 "command": "bunx",335 "args": [336 "-y",337 "mcp-remote@latest",338 "http://127.0.0.1:3000/sse?sessionId=",339 "--allow-http",340 "--transport sse-only",341 "--debug"342 ]343 }344 }345}346```347348### Using Docker with MCP349350You can use the Docker image directly in your MCP configuration:351352```json353{354 "mcpServers": {355 "rust-crate-docs-docker": {356 "command": "docker",357 "args": [358 "run",359 "--rm",360 "-i",361 "ghcr.io/promptexecution/rust-cargo-docs-rag-mcp:latest",362 "stdio"363 ]364 }365 }366}367```368369Or if you want to run the HTTP/SSE server in Docker and connect via mcp-remote:370371```bash372# Start the HTTP server in Docker373docker run --rm -p 8080:8080 ghcr.io/promptexecution/rust-cargo-docs-rag-mcp:latest374```375376Then in `mcp_settings.json`:377```json378{379 "mcpServers": {380 "rust-crate-docs-docker-http": {381 "command": "bunx",382 "args": [383 "-y",384 "mcp-remote@latest",385 "http://localhost:8080/sse",386 "--allow-http",387 "--transport", "sse-only"388 ]389 }390 }391}392```393394### Using pkgx with MCP395396If you have [pkgx](https://pkgx.dev) installed, you can run the server without a system-wide Rust installation:397398```json399{400 "mcpServers": {401 "rust-crate-docs-pkgx": {402 "command": "pkgx",403 "args": [404 "+rust",405 "+cargo",406 "cargo",407 "run",408 "--manifest-path",409 "/path/to/rust-cargo-docs-rag-mcp/Cargo.toml",410 "--bin",411 "cratedocs",412 "--",413 "stdio"414 ]415 }416 }417}418```419420Or use pkgx to install and run directly:421422```bash423# Clone and install with pkgx424git clone https://github.com/promptexecution/rust-cargo-docs-rag-mcp.git425cd rust-cargo-docs-rag-mcp426pkgx +rust +cargo cargo install --path .427```428429Then reference it normally in `mcp_settings.json`:430```json431{432 "mcpServers": {433 "rust-crate-docs": {434 "command": "cratedocs",435 "args": ["stdio"]436 }437 }438}439```440441442## Implementation Notes443444- The server includes a caching mechanism to prevent redundant API calls for the same documentation445- It interfaces with docs.rs for crate documentation and crates.io for search functionality446- Results are returned as plain text/HTML content that can be parsed and presented by the client447448---449450## Versioning & Releases451452For detailed versioning and release instructions (including the Cocogitto workflow), see the **Release / Versioning workflow (maintainers)** section above.453454This repository includes a [`cog.toml`](./cog.toml) profile wired to [`scripts/set-version.sh`](./scripts/set-version.sh) so [Cocogitto](https://github.com/cocogitto/cocogitto) can bump the crate version and regenerate the changelog automatically.455456Typical release flow:4571. `cargo install cocogitto` (once)4582. `cog bump minor` (or `patch`/`major`) – this updates `Cargo.toml`, `Cargo.lock`, and `CHANGELOG.md`4593. Review the generated changelog, run tests, and push the resulting tag/commit460461See [`CHANGELOG.md`](./CHANGELOG.md) for the latest published versions.462463## License464465MIT License466467## Attribution & Linkback Request468469This fork builds on the original [`d6e/cratedocs-mcp`](https://github.com/d6e/cratedocs-mcp) work by:470- wiring the crate-documentation helpers into a full MCP server with both `stdio` and HTTP/SSE launch modes471- documenting the new unified CLI, RooCode/VSCode integration examples, and the `list_crate_items` tool surface472- adding guidance on testing individual tools directly from the CLI plus notes on caching and output formatting473474If you decide to keep these changes upstream, could you please add a short linkback to [`promptexecution/rust-cargo-docs-rag-mcp`](https://github.com/promptexecution/rust-cargo-docs-rag-mcp) in your README? That attribution helps other developers understand where this MCP-focused variant originated and makes it easier for them to follow improvements across both projects.475
Full transparency — inspect the skill content before installing.