docs-mcp: Instructions file for Codex

AGENTS.md — Developer and Agent Guide

This document describes the architecture, conventions, and patterns you need to know when working on docs-mcp.

Project Overview

docs-mcp is an MCP server (stdio transport) that provides AI agents with structured access to the Rust crate ecosystem. It is built with:

• rmcp 0.16 — MCP server framework with #[tool] / #[tool_router] / #[tool_handler] macros
• tokio — async runtime (multi-thread)
• reqwest + reqwest-middleware — HTTP with rate limiting
• serde_json — all rustdoc parsing works against serde_json::Value trees
• zstd — docs.rs serves rustdoc JSON as .json.zst compressed files

Data Sources

1. crates.io sparse index (sparse_index/) — https://index.crates.io/{prefix}/{name} — one line of NDJSON per version. Used for feature flags, MSRV, dep counts. Fast and no rate limit.
2. crates.io REST API (cratesio/) — https://crates.io/api/v1/crates/{name} — richer metadata (download counts, full version history, dependency details). Rate-limited to 1 req/s.
3. docs.rs rustdoc JSON (docsrs/) — https://docs.rs/crate/{name}/{version}/json — full API structure. Served as .json.zst. This is the most data-intensive source and is aggressively cached.

Key Types

Rustdoc JSON (format version 57)

These field types differ from naive assumptions — see src/docsrs/types.rs:

Field	Type	Notes
RustdocJson.root	serde_json::Value	Integer in JSON (e.g. 98), not a string
Item.id	serde_json::Value	Integer
Item.attrs	Vec<serde_json::Value>	Each attr is {"other": "#[cfg(...)]"} — use Item::attr_strings()
Item.links	HashMap<String, serde_json::Value>	Values are integer item IDs
PathEntry.kind	String	"enum", "function", "struct", etc.

AppState (src/tools/mod.rs)

Shared across all tool handlers. Contains:

• client: reqwest_middleware::ClientWithMiddleware — rate-limited HTTP client
• cache: Arc<Cache> — disk cache
• resolve_version(name, version_hint) — resolves None to latest stable via sparse index