🦀 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

bash

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):

bash

# 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 build
arm64 - Latest ARM64 build

🚀 Usage

Starting the Server

Using npm or Bun

bash

# Production mode
npm start
# or
bun start

# Development mode with hot reload
npm run dev
# or
bun run dev

Using Executable

bash

# 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:

json

{
  "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:

json

{
  "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:

json

{
  "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:

json

{
  "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:

json

[
  {
    "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:

sql

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:

json

{
  "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:

bash

# 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:

json

{
  "mcpServers": {
    "rust-docs": {
      "command": "node",
      "args": ["/path/to/mcp-docsrs/dist/index.js"]
    }
  }
}

Or using the executable:

json

{
  "mcpServers": {
    "rust-docs": {
      "command": "/path/to/mcp-docsrs"
    }
  }
}

Or using Docker:

json

{
  "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

bash

# 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

bash

# 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:

bash

# 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

text

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, install libstdc++ with: apk add libstdc++

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

1. Fork the repository

2. Create your feature branch (git checkout -b feature/amazing-feature)

3. Commit your changes (git commit -m 'Add some amazing feature')

4. Push to the branch (git push origin feature/amazing-feature)

5. 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

Report Bug • Request Feature

Mcp Docsrs

Documentation

🦀 MCP Rust Docs Server

✨ Features

📦 Installation

Using Bun

Using Pre-built Executables

Linux

macOS

Windows

Using Docker

🚀 Usage

Starting the Server

Using npm or Bun

Using Executable

🛠️ Available Tools

lookup_crate_docs

lookup_item_docs

search_crates

📊 Resources

cache://stats

cache://entries?limit={limit}&offset={offset}

cache://query?sql={sql}

cache://config

⚙️ Configuration

🔌 MCP Configuration

🏗️ Building

Prerequisites

Build Commands

Build Output

👨‍💻 Development

Development Workflow

Testing

Test Output

Project Structure

📝 Notes

🤝 Contributing

🙏 Acknowledgments

📄 License

Similar MCP

Metmuseum Mcp

Mcp Server Aws Sso

Mcp Ipfs

Liveblocks Mcp Server

Trending MCP

Playwright Mcp

Serena

Mcp Playwright

Mcp Server Cloudflare

Metmuseum Mcp

Mcp Server Aws Sso

Mcp Ipfs

Liveblocks Mcp Server

Playwright Mcp

Serena

Mcp Playwright

Mcp Server Cloudflare

`lookup_crate_docs`

`lookup_item_docs`

`search_crates`

`cache://stats`

`cache://entries?limit={limit}&offset={offset}`

`cache://query?sql={sql}`

`cache://config`