README Documentation
🦀 MCP Rust Docs Server
A Model Context Protocol (MCP) server for fetching Rust crate documentation from docs.rs using the rustdoc JSON API
Features • Installation • Usage • Building • Development • Notes • Contributing • License
✨ Features
- 🚀 Fast Documentation Fetching - Direct access to rustdoc JSON API for comprehensive crate documentation
- 🔍 Item-Level Lookup - Query specific structs, functions, traits, and more within crates
- 💾 Smart Caching - Built-in LRU cache with SQLite backend for optimal performance
- 🎯 Version Support - Fetch docs for specific versions or use semver ranges
- 🖥️ Cross-Platform - Standalone executables for Linux, macOS, and Windows
- 📦 Zero Dependencies - Single executable with everything bundled
- 🔧 TypeScript - Full type safety with modern ES modules
- 🗜️ Compression Support - Automatic Zstd decompression for efficient data transfer
📦 Installation
Using Bun
bun install
bun run build:bytecode # or bun run build:all for all platforms
Using Pre-built Executables
Download the latest release for your platform from the Releases page:
Linux
- x64/AMD64 (GLIBC):
mcp-docsrs-linux-x64
- For Ubuntu, Debian, Fedora, etc. - ARM64 (GLIBC):
mcp-docsrs-linux-arm64
- For ARM64 systems, AWS Graviton - x64/AMD64 (MUSL):
mcp-docsrs-linux-x64-musl
- For Alpine Linux, Docker containers (requires libstdc++) - ARM64 (MUSL):
mcp-docsrs-linux-arm64-musl
- For Alpine on ARM64, minimal containers (requires libstdc++)
macOS
- Intel:
mcp-docsrs-darwin-x64
- For Intel-based Macs - Apple Silicon:
mcp-docsrs-darwin-arm64
- For M1/M2/M3 Macs
Windows
- x64:
mcp-docsrs-windows-x64.exe
- For 64-bit Windows
Using Docker
Pull and run the latest multi-arch image (supports both x64 and ARM64):
# Pull the latest image
docker pull ghcr.io/vexxvakan/mcp-docsrs:latest
# Run the server
docker run --rm -i ghcr.io/vexxvakan/mcp-docsrs:latest
# Run with custom configuration
docker run --rm -i ghcr.io/vexxvakan/mcp-docsrs:latest \
--cache-ttl 7200000 --max-cache-size 200
Available tags:
latest
- Latest stable release (multi-arch)v1.0.0
- Specific version (multi-arch)x64
- Latest x64/AMD64 buildarm64
- Latest ARM64 build
🚀 Usage
Starting the Server
Using npm or Bun
# Production mode
npm start
# or
bun start
# Development mode with hot reload
npm run dev
# or
bun run dev
Using Executable
# Show help
mcp-docsrs --help
# Run with default settings
mcp-docsrs
# Run with custom configuration
mcp-docsrs --cache-ttl 7200000 --max-cache-size 200
🛠️ Available Tools
lookup_crate_docs
Fetches comprehensive documentation for an entire Rust crate.
Parameters:
Parameter | Type | Required | Description |
---|---|---|---|
crateName | string | ✅ | Name of the Rust crate |
version | string | ❌ | Specific version or semver range (e.g., "1.0.0", "~4") |
target | string | ❌ | Target platform (e.g., "i686-pc-windows-msvc") |
formatVersion | string | ❌ | Rustdoc JSON format version |
Example:
{
"tool": "lookup_crate_docs",
"arguments": {
"crateName": "serde",
"version": "latest"
}
}
lookup_item_docs
Fetches documentation for a specific item within a crate.
Parameters:
Parameter | Type | Required | Description |
---|---|---|---|
crateName | string | ✅ | Name of the Rust crate |
itemPath | string | ✅ | Path to the item (e.g., "struct.MyStruct", "fn.my_function") |
version | string | ❌ | Specific version or semver range |
target | string | ❌ | Target platform |
Example:
{
"tool": "lookup_item_docs",
"arguments": {
"crateName": "tokio",
"itemPath": "runtime.Runtime"
}
}
search_crates
Search for Rust crates on crates.io with fuzzy/partial name matching.
Parameters:
Parameter | Type | Required | Description |
---|---|---|---|
query | string | ✅ | Search query for crate names (supports partial matches) |
limit | number | ❌ | Maximum number of results to return (default: 10) |
Example:
{
"tool": "search_crates",
"arguments": {
"query": "serde",
"limit": 5
}
}
📊 Resources
The server provides resources for querying and inspecting the cache database:
cache://stats
Returns cache statistics including total entries, size, and oldest entry.
Example:
{
"totalEntries": 42,
"totalSize": 1048576,
"oldestEntry": "2024-01-15T10:30:00.000Z"
}
cache://entries?limit={limit}&offset={offset}
Lists cached entries with metadata. Supports pagination.
Parameters:
limit
- Number of entries to return (default: 100)offset
- Number of entries to skip (default: 0)
Example:
[
{
"key": "serde/latest/x86_64-unknown-linux-gnu",
"timestamp": "2024-01-15T14:20:00.000Z",
"ttl": 3600000,
"expiresAt": "2024-01-15T15:20:00.000Z",
"size": 524288
}
]
cache://query?sql={sql}
Execute SQL queries on the cache database (SELECT queries only for safety).
Example:
cache://query?sql=SELECT key, timestamp FROM cache WHERE key LIKE '%tokio%' ORDER BY timestamp DESC
Note: SQL queries in the URI should be URL-encoded. The server will automatically decode them.
cache://config
Returns the current server configuration including all runtime parameters.
Example response:
{
"cacheTtl": 7200000,
"maxCacheSize": 200,
"requestTimeout": 30000,
"dbPath": "/Users/vexx/Repos/mcp-docsrs/.cache"
}
⚙️ Configuration
Configure the server using environment variables or command-line arguments:
Variable | CLI Flag | Default | Description |
---|---|---|---|
CACHE_TTL | --cache-ttl | 3600000 | Cache time-to-live in milliseconds |
MAX_CACHE_SIZE | --max-cache-size | 100 | Maximum number of cached entries |
REQUEST_TIMEOUT | --request-timeout | 30000 | HTTP request timeout in milliseconds |
DB_PATH | --db-path | :memory: | Path to SQLite database file (use :memory: for in-memory) |
Example:
# Environment variables
CACHE_TTL=7200000 MAX_CACHE_SIZE=200 npm start
# Command-line arguments (executable)
./mcp-docsrs --cache-ttl 7200000 --max-cache-size 200
# Use persistent database to cache documentation between sessions
./mcp-docsrs --db-path ~/.mcp-docsrs
# Or with environment variable
DB_PATH=~/.mcp-docsrs npm start
🔌 MCP Configuration
Add to your MCP configuration file:
{
"mcpServers": {
"rust-docs": {
"command": "node",
"args": ["/path/to/mcp-docsrs/dist/index.js"]
}
}
}
Or using the executable:
{
"mcpServers": {
"rust-docs": {
"command": "/path/to/mcp-docsrs"
}
}
}
Or using Docker:
{
"mcpServers": {
"rust-docs": {
"command": "docker",
"args": ["run", "--rm", "-i", "ghcr.io/vexxvakan/mcp-docsrs:latest"]
}
}
}
🏗️ Building
Prerequisites
- Bun v1.2.14 or later
- macOS, Linux, or Windows
Build Commands
# Build for current platform
bun run build
# Build with bytecode compilation (standalone, requires Bun runtime)
bun run build:bytecode
# Build for all platforms (7 targets, all with bytecode for fast startup)
bun run build:all
# Linux builds (GLIBC - standard)
bun run build:linux-x64 # Linux x64/AMD64
bun run build:linux-arm64 # Linux ARM64
# Linux builds (MUSL - for Alpine/containers)
bun run build:linux-x64-musl # Linux x64/AMD64 (Alpine)
bun run build:linux-arm64-musl # Linux ARM64 (Alpine)
# macOS builds
bun run build:darwin-x64 # macOS Intel
bun run build:darwin-arm64 # macOS Apple Silicon
# Windows build
bun run build:windows-x64 # Windows x64
Build Output
All executables are created in the dist/
directory with bytecode compilation for fast startup:
File | Platform | Type | Size |
---|---|---|---|
mcp-docsrs-linux-x64 | Linux x64/AMD64 | GLIBC + Bytecode | 99MB |
mcp-docsrs-linux-arm64 | Linux ARM64 | GLIBC + Bytecode | 93MB |
mcp-docsrs-linux-x64-musl | Linux x64/AMD64 | MUSL (static) + Bytecode | 92MB |
mcp-docsrs-linux-arm64-musl | Linux ARM64 | MUSL (static) + Bytecode | 88MB |
mcp-docsrs-darwin-x64 | macOS Intel | Bytecode | 64MB |
mcp-docsrs-darwin-arm64 | macOS Apple Silicon | Bytecode | 58MB |
mcp-docsrs-windows-x64.exe | Windows x64 | Bytecode | 113MB |
👨💻 Development
Development Workflow
# Install dependencies
bun install
# Run in development mode
bun run dev
# Run tests
bun test
# Lint code
bun run lint
# Type checking
bun run typecheck
# Check build sizes (updates README table)
bun run check:sizes # Run after building
Testing
The project includes comprehensive tests for all major components:
# Run all tests
bun test
# Run tests in watch mode
bun test --watch
# Run specific test file
bun test cache.test.ts
# Run tests with full error logging (including expected errors)
LOG_EXPECTED_ERRORS=true bun test
Test Output
Tests are configured to provide clean output by default:
- ✅ Expected errors (like
CrateNotFoundError
in 404 tests) show as green checkmarks:✓ Expected CrateNotFoundError thrown
- ❌ Unexpected errors are shown with full stack traces in red
- ℹ️ Info logs are shown to track test execution
This makes it easy to distinguish between:
- Tests that verify error handling (expected errors)
- Actual test failures (unexpected errors)
To see full error details for debugging, set LOG_EXPECTED_ERRORS=true
.
Project Structure
mcp-docsrs/
├── src/ # Source code
│ ├── cli.ts # CLI entry point with argument parsing
│ ├── index.ts # MCP server entry point
│ ├── server.ts # MCP server implementation with tool/resource handlers
│ ├── cache.ts # LRU cache with SQLite persistence
│ ├── docs-fetcher.ts # HTTP client for docs.rs JSON API
│ ├── rustdoc-parser.ts # Parser for rustdoc JSON format
│ ├── errors.ts # Custom error types and error handling
│ ├── types.ts # TypeScript types and Zod schemas
│ └── tools/ # MCP tool implementations
│ ├── index.ts # Tool exports and registration
│ ├── lookup-crate.ts # Fetch complete crate documentation
│ ├── lookup-item.ts # Fetch specific item documentation
│ └── search-crates.ts # Search crates on crates.io
├── test/ # Test files
│ ├── cache.test.ts # Cache functionality tests
│ ├── cache-status.test.ts # Cache status and metrics tests
│ ├── docs-fetcher.test.ts # API client tests
│ ├── integration.test.ts # End-to-end integration tests
│ ├── persistent-cache.test.ts # SQLite cache persistence tests
│ ├── rustdoc-parser.test.ts # JSON parser tests
│ └── search-crates.test.ts # Crate search tests
├── scripts/ # Development and testing scripts
│ ├── test-crates-search.ts # Manual crate search testing
│ ├── test-mcp.ts # MCP server testing
│ ├── test-persistent-cache.ts # Cache persistence testing
│ ├── test-resources.ts # Resource endpoint testing
│ └── test-zstd.ts # Zstandard compression testing
├── plans/ # Project planning documents
│ └── feature-recommendations.md # Future feature ideas
├── dist/ # Build output (platform executables)
├── .github/ # GitHub Actions workflows
│ ├── workflows/ # CI/CD pipeline definitions
│ └── ... # Various automation configs
├── CLAUDE.md # AI assistant instructions
├── README.md # Project documentation
├── LICENSE # Apache 2.0 license
├── package.json # Project dependencies and scripts
├── tsconfig.json # TypeScript configuration
├── biome.json # Code formatter/linter config
└── bun.lock # Bun package lock file
📝 Notes
- 📅 The rustdoc JSON feature on docs.rs started on 2025-05-23, so releases before that date won't have JSON available
- 🔄 The server automatically handles redirects and format version compatibility
- ⚡ Cached responses significantly improve performance for repeated lookups
- 📦 Built executables include all dependencies - no runtime installation required
- ⚠️ MUSL builds limitation: Due to a known Bun issue, MUSL builds are not fully static and require
libstdc++
to run. For Docker/Alpine deployments, installlibstdc++
with:apk add libstdc++
🤝 Contributing
Contributions are welcome! Please feel free to submit a Pull Request.
- Fork the repository
- Create your feature branch (
git checkout -b feature/amazing-feature
) - Commit your changes (
git commit -m 'Add some amazing feature'
) - Push to the branch (
git push origin feature/amazing-feature
) - Open a Pull Request
🙏 Acknowledgments
- docs.rs for providing the Rust documentation API
- Model Context Protocol for the MCP specification
- The Rust community for excellent documentation standards
📄 License
This project is licensed under the Apache License 2.0 - see the LICENSE file for details.
Made with ❤️ for the Rust community