rs-docs

rs-docs is a CLI tool and library that fetches or reads rustdoc JSON and converts it to Markdown documentation. It can pull crate docs from docs.rs or process local rustdoc JSON files (plain, gzip, or zstd compressed).

Features

• Remote: Fetch rustdoc JSON from docs.rs by crate name and version
• Local: Read rustdoc JSON from disk (.json, .json.gz, .json.zst)
• Output formats: Single Markdown file, multiple files (one per item), or both
• Compression: Auto-detects or uses URL extension for gzip/zstd
• MCP server: Run as a Model Context Protocol server for AI tools (fetch docs, read index/file, search crates.io)

Requirements

• Rust (see Cargo.toml for required edition)

Installation

From the project root:

cargo build --release

The binary will be at target/release/rs-docs. Optionally install to your path:

cargo install --path .

Usage

rs-docs [OPTIONS] <SUBCOMMAND>

Options

Option	Short	Default	Description
--output-dir	-o	.	Directory to write output into
--format	-f	single	Output layout: single, multiple, or both

Subcommands

Remote (docs.rs)

rs-docs remote --package <CRATE> [--crate-version <VERSION>] [--target <TARGET>] [--format-version <N>]

• --package, -p: Crate name (e.g. clap, tokio)
• --crate-version: latest, semver like ~4, or exact version (default: latest)
• --target, -t: Target triple (optional)
• --format-version: Rustdoc JSON format version (optional)

Local

rs-docs local --input <PATH>

• --input, -i: Path to rustdoc JSON (.json, .json.gz, or .json.zst)

MCP server

rs-docs mcp [--output-dir <DIR>]

• Runs an MCP server on stdin/stdout. --output-dir (default: .) is used as the doc cache; fetched crates are written under <output-dir>/<pkg>_<target>_<version>.
• Format options (--format) are ignored when using mcp.

Examples

# Fetch latest clap docs and write a single markdown file to current directory
rs-docs remote -p clap

# Fetch tokio 1.x and write both single file and multiple files
rs-docs remote -p tokio --crate-version "~1" -f both

# Use a local rustdoc JSON file
rs-docs local -i ./target/doc/crate_name.json

# Output to a specific directory
rs-docs remote -p serde -o ./docs

# Run MCP server with cache in /tmp/rs-docs-cache (for Cursor/IDE MCP config)
rs-docs mcp -o /tmp/rs-docs-cache

Output

• Single (-f single): One file with full crate documentation (default).
• Multiple (-f multiple): One Markdown file per item plus readme.md and index.md.
• Both (-f both): Writes both layouts to the output directory.

MCP server

When run as rs-docs mcp, the binary acts as an MCP server that exposes:

• Tools: search_crates (search crates.io), fetch_docs (fetch and write crate docs to cache), get_index, get_file.
• Resources: Cached package docs via rs-docs://doc?pkg=...&target=...&version=...&path=....

Use search_crates first when the package name is uncertain. Cached output lives under --output-dir as <pkg>_<target>_<version>/.

Example Cursor MCP config (e.g. .cursor/mcp.json):

{
  "mcpServers": {
    "rs-docs": {
      "command": "/path/to/rs-docs",
      "args": ["mcp", "-o", "/tmp/rs-docs-cache"]
    }
  }
}

Replace /path/to/rs-docs with the path to your rs-docs binary (e.g. target/release/rs-docs or the result of cargo install --path .).

Library

The rs-docs crate can be used as a library:

• parse_remote(url) (async): Fetches rustdoc JSON from a URL (e.g. docs.rs), decompresses if needed, returns a rustdoc_types::Crate.
• parse_local(path): Reads a local file (.json, .json.gz, or .json.zst), decompresses if needed, returns a rustdoc_types::Crate.
• write_docs(crate_data, options): Converts a Crate to Markdown and writes to disk using transform::OutputOptions.
• mcp::run_server(outdir) (async): Runs the MCP server on stdin/stdout, using outdir as the doc cache.

See DEVELOPERS.md for the full layout and API.

License

MIT. See LICENSE for details.