mcp-rustdoc 2.0.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 kieled
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,391 @@
+# mcp-rustdoc
+
+An MCP server that gives AI assistants deep access to the Rust ecosystem. It scrapes docs.rs with surgical DOM extraction (cheerio) and queries the crates.io API, exposing six tools that cover everything from high-level crate overviews to individual method signatures, feature gates, trait impls, and code examples.
+
+## Tools
+
+| Tool | What it returns |
+|---|---|
+| `get_crate_metadata` | Version, features, default features, optional/required deps, links (crates.io API) |
+| `get_crate_brief` | One-shot bundle: metadata + overview + re-exports + module list + focused module items |
+| `lookup_crate_docs` | Crate overview documentation, version, sections, re-exports |
+| `get_crate_items` | Items in a module with types, feature gates, and descriptions |
+| `lookup_crate_item` | Item detail: signature, docs, methods, variants, optionally trait impls + examples |
+| `search_crate` | Ranked symbol search (exact > prefix > substring) with canonical paths |
+
+Every tool accepts an optional `version` parameter to pin a specific crate version instead of `latest`.
+
+## Install
+
+No clone needed. Just configure your AI coding assistant with `npx`:
+
+```
+npx -y mcp-rustdoc
+```
+
+### Claude Code
+
+```bash
+claude mcp add mcp-rustdoc -- npx -y mcp-rustdoc
+```
+
+Or add to your project's `.mcp.json`:
+
+```json
+{
+  "mcpServers": {
+    "mcp-rustdoc": {
+      "type": "stdio",
+      "command": "npx",
+      "args": ["-y", "mcp-rustdoc"]
+    }
+  }
+}
+```
+
+### Gemini CLI
+
+Add to `~/.gemini/settings.json` (global) or `.gemini/settings.json` (project):
+
+```json
+{
+  "mcpServers": {
+    "mcp-rustdoc": {
+      "command": "npx",
+      "args": ["-y", "mcp-rustdoc"]
+    }
+  }
+}
+```
+
+### OpenAI Codex CLI
+
+```bash
+codex mcp add mcp-rustdoc -- npx -y mcp-rustdoc
+```
+
+Or add to `~/.codex/config.toml`:
+
+```toml
+[mcp_servers.mcp-rustdoc]
+command = "npx"
+args = ["-y", "mcp-rustdoc"]
+```
+
+### Claude Desktop
+
+Add to your `claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "mcp-rustdoc": {
+      "command": "npx",
+      "args": ["-y", "mcp-rustdoc"]
+    }
+  }
+}
+```
+
+### MCP Inspector (testing)
+
+```bash
+npx @modelcontextprotocol/inspector -- npx -y mcp-rustdoc
+```
+
+---
+
+## Development
+
+```bash
+git clone https://github.com/kieled/mcp-rustdoc.git
+cd mcp-rustdoc
+bun install
+```
+
+### Run with bun (no build step)
+
+```bash
+bun run dev
+```
+
+### Build with Vite and run with Node.js
+
+```bash
+bun run build     # vite build → dist/index.js (single bundled ESM file)
+node dist/index.js
+```
+
+### Build with tsc
+
+```bash
+bun run build:tsc  # tsc → dist/ (one .js per source file)
+node dist/index.js
+```
+
+### Type check only
+
+```bash
+bun run typecheck  # tsc --noEmit
+```
+
+### Publish
+
+```bash
+npm publish        # runs vite build via prepublishOnly, then publishes
+```
+
+---
+
+## Tool reference
+
+### `get_crate_metadata`
+
+Fetches structured metadata from the crates.io API.
+
+| Parameter | Type | Required | Description |
+|---|---|---|---|
+| `crateName` | string | yes | Crate name |
+| `version` | string | no | Pinned version |
+
+Returns: version, description, links (docs/repo/crates.io), license, download count, full feature list with activations, optional deps (feature-gated), required deps.
+
+```
+> get_crate_metadata({ crateName: "tokio" })
+
+# tokio v1.49.0
+
+An event-driven, non-blocking I/O platform for writing asynchronous applications...
+
+## Links
+  docs: https://docs.rs/tokio
+  repo: https://github.com/tokio-rs/tokio
+  license: MIT
+  downloads: 312,456,789
+
+## Features
+  default = [macros, rt-multi-thread]
+  fs = []
+  full = [fs, io-util, io-std, macros, net, ...]
+  io-util = [bytes]
+  ...
+
+## Optional Dependencies
+  bytes ^1 (feature-gated)
+  ...
+```
+
+---
+
+### `get_crate_brief`
+
+Single call to bootstrap context for a crate. Combines metadata, overview docs, re-exports, module list, and optionally expands focused modules.
+
+| Parameter | Type | Required | Description |
+|---|---|---|---|
+| `crateName` | string | yes | Crate name |
+| `version` | string | no | Pinned version |
+| `focusModules` | string | no | Comma-separated modules to expand (e.g. `"sync,task"`) |
+
+```
+> get_crate_brief({ crateName: "tokio", focusModules: "sync,task" })
+
+# tokio v1.49.0
+...
+## Features
+  default = [macros, rt-multi-thread]
+  all: bytes, fs, full, io-std, io-util, ...
+
+## Overview
+[truncated crate doc]
+
+## Re-exports
+  pub use task::spawn;
+  ...
+
+## Modules
+  fs  io  macros  net  runtime  signal  sync  task  time
+
+## Focus: tokio::sync
+  [struct] Barrier — ...
+  [struct] Mutex [sync] — ...
+  [struct] Notify [sync] — ...
+  ...
+
+## Focus: tokio::task
+  [fn] spawn — ...
+  [struct] JoinHandle — ...
+  ...
+```
+
+---
+
+### `lookup_crate_docs`
+
+Fetches the main documentation page for a crate.
+
+| Parameter | Type | Required | Description |
+|---|---|---|---|
+| `crateName` | string | yes | Crate name |
+| `version` | string | no | Pinned version |
+
+Returns: crate version, overview documentation text, re-exports, and section list with item counts.
+
+---
+
+### `get_crate_items`
+
+Lists all public items in a crate root or specific module.
+
+| Parameter | Type | Required | Description |
+|---|---|---|---|
+| `crateName` | string | yes | Crate name |
+| `modulePath` | string | no | Dot-separated path (e.g. `"sync"`, `"io.util"`) |
+| `itemType` | enum | no | Filter: `mod` `struct` `enum` `trait` `fn` `macro` `type` `constant` `static` `union` `attr` `derive` |
+| `version` | string | no | Pinned version |
+
+Each item includes its type, name, feature gate (if any), and short description.
+
+```
+> get_crate_items({ crateName: "tokio", modulePath: "sync", itemType: "struct" })
+
+# Items in tokio::sync [struct]
+  [struct] Barrier — ...
+  [struct] Mutex [feature: sync] — ...
+  [struct] Notify [feature: sync] — ...
+  [struct] OwnedMutexGuard [feature: sync] — ...
+  ...
+```
+
+---
+
+### `lookup_crate_item`
+
+Retrieves full documentation for a single item.
+
+| Parameter | Type | Required | Description |
+|---|---|---|---|
+| `crateName` | string | yes | Crate name |
+| `itemType` | enum | yes | Item type (see `get_crate_items`) |
+| `itemName` | string | yes | Item name (e.g. `"Mutex"`, `"spawn"`) |
+| `modulePath` | string | no | Dot-separated module path |
+| `version` | string | no | Pinned version |
+| `includeImpls` | boolean | no | Include trait implementation list |
+| `includeExamples` | boolean | no | Include code examples |
+
+Returns: feature gate (if any), type signature, documentation text, methods list, enum variants, required/provided trait methods. Optionally includes trait implementations and code examples.
+
+```
+> lookup_crate_item({
+    crateName: "tokio",
+    itemType: "struct",
+    itemName: "Mutex",
+    modulePath: "sync",
+    includeImpls: true
+  })
+
+# struct tokio::sync::Mutex
+> Available on crate feature `sync` only.
+
+## Signature
+pub struct Mutex<T: ?Sized> { ... }
+
+## Documentation
+An asynchronous Mutex...
+
+## Methods (12)
+  pub fn new(t: T) -> Mutex<T>
+  pub fn lock(&self) -> impl Future<Output = MutexGuard<'_, T>>
+  pub fn try_lock(&self) -> Result<MutexGuard<'_, T>, TryLockError>
+  ...
+
+## Trait Implementations (15)
+  impl<T: ?Sized + Debug> Debug for Mutex<T>
+  impl<T> Default for Mutex<T>
+  impl<T> From<T> for Mutex<T>
+  impl<T: ?Sized> Send for Mutex<T>
+  impl<T: ?Sized> Sync for Mutex<T>
+  ...
+```
+
+---
+
+### `search_crate`
+
+Searches all items in a crate by name. Results are ranked: exact match on the bare item name scores highest, then prefix matches, then substring matches.
+
+| Parameter | Type | Required | Description |
+|---|---|---|---|
+| `crateName` | string | yes | Crate name |
+| `query` | string | yes | Search query (case-insensitive) |
+| `version` | string | no | Pinned version |
+
+```
+> search_crate({ crateName: "tokio", query: "Mutex" })
+
+# "Mutex" in tokio — 6 matches
+
+[struct] tokio::sync::Mutex
+[struct] tokio::sync::MutexGuard
+[struct] tokio::sync::OwnedMutexGuard
+[struct] tokio::sync::MappedMutexGuard
+[enum] tokio::sync::TryLockError
+...
+```
+
+---
+
+## Recommended workflows
+
+### Exploring a new crate
+
+1. `get_crate_brief` with `focusModules` targeting the modules you care about
+2. `search_crate` to find specific types or functions
+3. `lookup_crate_item` for detailed signatures and docs
+
+### Understanding feature flags
+
+1. `get_crate_metadata` to see all features and their activations
+2. `get_crate_items` to see which items require which features
+
+### Finding the right type
+
+1. `search_crate` with a keyword
+2. `lookup_crate_item` with `includeImpls: true` to see what traits it implements
+3. `lookup_crate_item` on referenced types to chase cross-links
+
+---
+
+## Architecture
+
+```
+src/
+  index.ts              Entry point — registers tools + prompt, starts stdio server
+  lib.ts                Shared: URL builders, HTTP/DOM helpers, crates.io API, extractors
+  types/
+    html-to-text.d.ts   Type declarations for html-to-text
+  tools/
+    shared.ts           Shared Zod schemas (itemTypeEnum, versionParam)
+    lookup-docs.ts      lookup_crate_docs
+    get-items.ts        get_crate_items
+    lookup-item.ts      lookup_crate_item
+    search.ts           search_crate
+    crate-metadata.ts   get_crate_metadata
+    crate-brief.ts      get_crate_brief
+```
+
+### Data sources
+
+- **docs.rs** — HTML pages parsed with cheerio for surgical DOM extraction (only the elements needed, not full-page conversion)
+- **crates.io API** — JSON endpoints for metadata, features, and dependencies
+
+### Design decisions
+
+- **cheerio over full-page text conversion** — Extracts only specific DOM elements (`.item-decl`, `.top-doc`, `.code-header`, `.stab.portability`) to minimize token usage
+- **Ranked search** — `all.html` contains every public item; scoring by exact/prefix/substring gives better results than flat substring matching
+- **Version parameter everywhere** — Agents working on projects with pinned dependencies need to read docs for specific versions
+- **Optional sections** — `includeImpls` and `includeExamples` default to off so the base response stays compact; agents opt in when they need more detail
+
+## License
+
+MIT

package/dist/index.js

@@ -0,0 +1,576 @@
+#!/usr/bin/env node
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { z } from "zod";
+import axios from "axios";
+import { load } from "cheerio";
+import { convert } from "html-to-text";
+const DOCS_BASE = "https://docs.rs";
+const CRATES_IO = "https://crates.io/api/v1";
+const USER_AGENT = "mcp-rust-docs/2.0.0";
+const MAX_DOC_LENGTH = 6e3;
+const MAX_SEARCH_RESULTS = 100;
+const SECTION_TO_TYPE = {
+  modules: "mod",
+  structs: "struct",
+  enums: "enum",
+  traits: "trait",
+  functions: "fn",
+  macros: "macro",
+  types: "type",
+  constants: "constant",
+  statics: "static",
+  unions: "union",
+  attributes: "attr",
+  derives: "derive",
+  reexports: "reexport"
+};
+const TYPE_FILE_PREFIX = {
+  struct: "struct.",
+  enum: "enum.",
+  trait: "trait.",
+  fn: "fn.",
+  macro: "macro.",
+  type: "type.",
+  constant: "constant.",
+  static: "static.",
+  union: "union.",
+  attr: "attr.",
+  derive: "derive."
+};
+function crateSlug(name) {
+  return name.replace(/-/g, "_");
+}
+function docsUrl(crate, path = "index.html", version = "latest") {
+  return `${DOCS_BASE}/${crate}/${version}/${crateSlug(crate)}/${path}`;
+}
+function modToUrlPrefix(modulePath) {
+  return modulePath ? modulePath.replace(/\./g, "/") + "/" : "";
+}
+function modToRustPrefix(modulePath) {
+  return modulePath ? modulePath.replace(/\./g, "::") + "::" : "";
+}
+async function fetchDom(url) {
+  const { data } = await axios.get(url, { timeout: 15e3 });
+  return load(data);
+}
+function cleanHtml(html) {
+  return convert(html, {
+    wordwrap: 120,
+    selectors: [
+      { selector: "a", options: { ignoreHref: true } },
+      { selector: "img", format: "skip" }
+    ]
+  }).trim();
+}
+function truncate(text, max) {
+  return text.length > max ? text.slice(0, max) + "\n\n[…truncated]" : text;
+}
+function textResult(text) {
+  return { content: [{ type: "text", text }] };
+}
+function errorResult(msg) {
+  return { content: [{ type: "text", text: `Error: ${msg}` }], isError: true };
+}
+const cratesIoHeaders = { "User-Agent": USER_AGENT };
+async function fetchCrateInfo(name) {
+  const { data } = await axios.get(`${CRATES_IO}/crates/${name}`, {
+    headers: cratesIoHeaders,
+    timeout: 1e4
+  });
+  const c = data.crate;
+  return {
+    name: c.name,
+    version: c.max_stable_version || c.max_version,
+    description: c.description,
+    documentation: c.documentation,
+    repository: c.repository,
+    downloads: c.downloads
+  };
+}
+async function fetchCrateVersionInfo(name, version) {
+  const { data } = await axios.get(`${CRATES_IO}/crates/${name}/${version}`, {
+    headers: cratesIoHeaders,
+    timeout: 1e4
+  });
+  const v = data.version;
+  const features = v.features ?? {};
+  return {
+    num: v.num,
+    features,
+    defaultFeatures: features["default"] ?? [],
+    yanked: v.yanked,
+    license: v.license
+  };
+}
+async function fetchCrateDeps(name, version) {
+  const { data } = await axios.get(`${CRATES_IO}/crates/${name}/${version}/dependencies`, {
+    headers: cratesIoHeaders,
+    timeout: 1e4
+  });
+  return (data.dependencies ?? []).map((d) => ({
+    name: d.crate_id,
+    req: d.req,
+    optional: d.optional,
+    kind: d.kind,
+    features: d.features ?? []
+  }));
+}
+function extractItemFeatureGate($) {
+  const gate = $(".item-info .stab.portability").first().text().trim();
+  return gate || null;
+}
+function extractExamples($) {
+  const examples = [];
+  $("div.example-wrap pre.rust").each((_, el) => {
+    const code = $(el).text().trim();
+    if (code) examples.push(code);
+  });
+  return examples;
+}
+function extractTraitImpls($) {
+  const impls = [];
+  $("#trait-implementations-list > details > summary h3.code-header").each((_, el) => {
+    impls.push($(el).text().trim());
+  });
+  return impls;
+}
+function extractReExports($) {
+  const reexports = [];
+  $("h2#reexports").next("dl.item-table").find("dt code").each((_, el) => {
+    reexports.push($(el).text().trim());
+  });
+  return reexports;
+}
+const itemTypeEnum = z.enum([
+  "mod",
+  "struct",
+  "enum",
+  "trait",
+  "fn",
+  "macro",
+  "type",
+  "constant",
+  "static",
+  "union",
+  "attr",
+  "derive"
+]);
+const versionParam = z.string().optional().describe('Crate version (e.g. "1.49.0"). Defaults to latest.');
+function register$5(server2) {
+  server2.tool(
+    "lookup_crate_docs",
+    "Fetch the main documentation for a Rust crate. Returns overview, version, sections, and re-exports.",
+    {
+      crateName: z.string().describe('Crate name (e.g. "tokio", "serde-json")'),
+      version: versionParam
+    },
+    // @ts-expect-error — MCP SDK deep type instantiation with Zod schemas
+    async ({ crateName, version }) => {
+      try {
+        const ver = version ?? "latest";
+        const url = docsUrl(crateName, "index.html", ver);
+        const $ = await fetchDom(url);
+        const pageVersion = $(".sidebar-crate .version").text().trim() || ver;
+        const doc = truncate(
+          cleanHtml($("details.toggle.top-doc").html() ?? ""),
+          MAX_DOC_LENGTH
+        );
+        const sections = [];
+        $("h2.section-header").each((_, el) => {
+          const id = $(el).attr("id") ?? "";
+          const count = $(el).next("dl.item-table").find("dt").length;
+          if (id && count) sections.push(`  ${$(el).text().trim()} (${count})`);
+        });
+        const reexports = extractReExports($);
+        const parts = [`# ${crateName} v${pageVersion}`, url, "", doc];
+        if (reexports.length) {
+          parts.push("", "## Re-exports", ...reexports.map((r) => `  ${r}`));
+        }
+        parts.push("", "## Sections", ...sections);
+        return textResult(parts.join("\n"));
+      } catch (e) {
+        return errorResult(`Could not fetch docs for "${crateName}". ${e.message}`);
+      }
+    }
+  );
+}
+function register$4(server2) {
+  server2.tool(
+    "get_crate_items",
+    "List public items in a crate root or module. Returns names, types, feature gates, and short descriptions.",
+    {
+      crateName: z.string().describe("Crate name"),
+      modulePath: z.string().optional().describe('Dot-separated module path (e.g. "sync", "io.util"). Omit for crate root.'),
+      itemType: itemTypeEnum.optional().describe("Filter results to a single item type"),
+      version: versionParam
+    },
+    async ({ crateName, modulePath, itemType, version }) => {
+      try {
+        const ver = version ?? "latest";
+        const url = docsUrl(crateName, `${modToUrlPrefix(modulePath)}index.html`, ver);
+        const $ = await fetchDom(url);
+        const lines = [];
+        $("h2.section-header").each((_, h2) => {
+          const sectionId = $(h2).attr("id") ?? "";
+          const type = SECTION_TO_TYPE[sectionId] ?? sectionId;
+          if (itemType && type !== itemType) return;
+          $(h2).next("dl.item-table").find("dt").each((_2, dt) => {
+            const $dt = $(dt);
+            const name = $dt.find("a").first().text().trim();
+            const desc = $dt.next("dd").text().trim();
+            const gate = $dt.find(".stab.portability code").first().text().trim();
+            if (!name) return;
+            const tag = gate ? ` [feature: ${gate}]` : "";
+            lines.push(`[${type}] ${name}${tag} — ${desc}`);
+          });
+        });
+        const label = modulePath ? `${crateName}::${modulePath.replace(/\./g, "::")}` : crateName;
+        if (!lines.length) {
+          return textResult(
+            `No items found in ${label}${itemType ? ` (type: ${itemType})` : ""}.`
+          );
+        }
+        return textResult(
+          [`# Items in ${label}${itemType ? ` [${itemType}]` : ""}`, url, "", ...lines].join("\n")
+        );
+      } catch (e) {
+        return errorResult(`Could not list items. ${e.message}`);
+      }
+    }
+  );
+}
+function register$3(server2) {
+  server2.tool(
+    "lookup_crate_item",
+    "Get detailed documentation for a specific item. Returns signature, docs, feature gate, methods, trait impls, and optionally examples.",
+    {
+      crateName: z.string().describe("Crate name"),
+      itemType: itemTypeEnum.describe("Item type"),
+      itemName: z.string().describe('Item name (e.g. "Mutex", "spawn", "Serialize")'),
+      modulePath: z.string().optional().describe('Dot-separated module path (e.g. "sync"). Omit if at crate root.'),
+      version: versionParam,
+      includeExamples: z.boolean().optional().describe("Include code examples from the docs. Default: false."),
+      includeImpls: z.boolean().optional().describe("Include trait implementation list. Default: false.")
+    },
+    // @ts-expect-error — MCP SDK deep type instantiation with Zod schemas
+    async ({ crateName, itemType, itemName, modulePath, version, includeExamples, includeImpls }) => {
+      try {
+        const ver = version ?? "latest";
+        const prefix = modToUrlPrefix(modulePath);
+        const page = itemType === "mod" ? `${prefix}${itemName}/index.html` : `${prefix}${TYPE_FILE_PREFIX[itemType] ?? `${itemType}.`}${itemName}.html`;
+        const url = docsUrl(crateName, page, ver);
+        const $ = await fetchDom(url);
+        const fullName = `${crateName}::${modToRustPrefix(modulePath)}${itemName}`;
+        const decl = $("pre.rust.item-decl").text().trim();
+        const featureGate = extractItemFeatureGate($);
+        const doc = truncate(
+          cleanHtml($("details.toggle.top-doc").html() ?? ""),
+          MAX_DOC_LENGTH
+        );
+        const methods = [];
+        $("#implementations-list section.method h4.code-header").each((_, el) => {
+          methods.push($(el).text().trim());
+        });
+        const required = [];
+        $("h2#required-methods").first().nextUntil("h2").find("section h4.code-header").each((_, el) => {
+          required.push($(el).text().trim());
+        });
+        const provided = [];
+        $("h2#provided-methods").first().nextUntil("h2").find("section h4.code-header").each((_, el) => {
+          provided.push($(el).text().trim());
+        });
+        const variants = [];
+        $("section.variant h3.code-header, div.variant h3.code-header").each((_, el) => {
+          variants.push($(el).text().trim());
+        });
+        const parts = [`# ${itemType} ${fullName}`, url, ""];
+        if (featureGate) parts.push(`> ${featureGate}`, "");
+        if (decl) parts.push("## Signature", "```rust", decl, "```", "");
+        if (doc) parts.push("## Documentation", doc, "");
+        if (variants.length)
+          parts.push(`## Variants (${variants.length})`, ...variants.map((v) => `  ${v}`), "");
+        if (required.length)
+          parts.push(
+            `## Required Methods (${required.length})`,
+            ...required.map((m) => `  ${m}`),
+            ""
+          );
+        if (provided.length)
+          parts.push(
+            `## Provided Methods (${provided.length})`,
+            ...provided.map((m) => `  ${m}`),
+            ""
+          );
+        if (methods.length)
+          parts.push(`## Methods (${methods.length})`, ...methods.map((m) => `  ${m}`), "");
+        if (includeImpls) {
+          const impls = extractTraitImpls($);
+          if (impls.length) {
+            parts.push(`## Trait Implementations (${impls.length})`, ...impls.map((i) => `  ${i}`), "");
+          }
+        }
+        if (includeExamples) {
+          const examples = extractExamples($);
+          if (examples.length) {
+            parts.push(`## Examples (${examples.length})`);
+            examples.forEach((ex, i) => {
+              parts.push(`### Example ${i + 1}`, "```rust", ex, "```", "");
+            });
+          }
+        }
+        return textResult(parts.join("\n"));
+      } catch (e) {
+        return errorResult(
+          `Could not fetch ${itemType} "${itemName}". ${e.message}`
+        );
+      }
+    }
+  );
+}
+function scoreMatch(name, query) {
+  const lower = name.toLowerCase();
+  const q = query.toLowerCase();
+  const bareName = lower.includes("::") ? lower.split("::").pop() : lower;
+  if (bareName === q) return 100;
+  if (lower === q) return 95;
+  if (bareName.startsWith(q)) return 60;
+  if (lower.startsWith(q)) return 55;
+  if (lower.includes(q)) return 20;
+  return 0;
+}
+function register$2(server2) {
+  server2.tool(
+    "search_crate",
+    "Search for items by name within a Rust crate. Returns ranked results with canonical paths and item types.",
+    {
+      crateName: z.string().describe("Crate name"),
+      query: z.string().describe("Search query (matched against item names)"),
+      version: versionParam
+    },
+    async ({ crateName, query, version }) => {
+      try {
+        const ver = version ?? "latest";
+        const url = docsUrl(crateName, "all.html", ver);
+        const $ = await fetchDom(url);
+        const hits = [];
+        $("h3").each((_, h3) => {
+          const rawId = $(h3).attr("id") ?? "";
+          const type = SECTION_TO_TYPE[rawId] ?? rawId;
+          $(h3).next("ul.all-items").find("li a").each((_2, a) => {
+            const name = $(a).text().trim();
+            const href = $(a).attr("href") ?? "";
+            const score = scoreMatch(name, query);
+            if (score > 0) hits.push({ type, name, href, score });
+          });
+        });
+        if (!hits.length) return textResult(`No matches for "${query}" in ${crateName}.`);
+        hits.sort((a, b) => b.score - a.score || a.name.localeCompare(b.name));
+        const capped = hits.slice(0, MAX_SEARCH_RESULTS);
+        const lines = capped.map((h) => {
+          const canonical = `${crateName}::${h.name.replace(/::/g, "::")}`;
+          return `[${h.type}] ${canonical}`;
+        });
+        const overflow = hits.length > MAX_SEARCH_RESULTS ? ` (showing first ${MAX_SEARCH_RESULTS})` : "";
+        return textResult(
+          [`# "${query}" in ${crateName} — ${hits.length} matches${overflow}`, "", ...lines].join(
+            "\n"
+          )
+        );
+      } catch (e) {
+        return errorResult(`Could not search "${crateName}". ${e.message}`);
+      }
+    }
+  );
+}
+function register$1(server2) {
+  server2.tool(
+    "get_crate_metadata",
+    "Get crate metadata from crates.io: version, features, default features, optional dependencies, and links.",
+    {
+      crateName: z.string().describe("Crate name"),
+      version: versionParam
+    },
+    async ({ crateName, version }) => {
+      try {
+        const info = await fetchCrateInfo(crateName);
+        const ver = version ?? info.version;
+        const [versionInfo, deps] = await Promise.all([
+          fetchCrateVersionInfo(crateName, ver),
+          fetchCrateDeps(crateName, ver)
+        ]);
+        const parts = [
+          `# ${info.name} v${versionInfo.num}`,
+          "",
+          `${info.description}`,
+          "",
+          "## Links"
+        ];
+        if (info.documentation) parts.push(`  docs: ${info.documentation}`);
+        if (info.repository) parts.push(`  repo: ${info.repository}`);
+        parts.push(`  crates.io: https://crates.io/crates/${info.name}`);
+        parts.push(`  license: ${versionInfo.license}`);
+        parts.push(`  downloads: ${info.downloads.toLocaleString()}`);
+        const { features, defaultFeatures } = versionInfo;
+        parts.push("", "## Features");
+        parts.push(`  default = [${defaultFeatures.join(", ")}]`);
+        const featureNames = Object.keys(features).filter((f) => f !== "default").sort();
+        for (const name of featureNames) {
+          const activates = features[name];
+          const tag = activates.length ? ` = [${activates.join(", ")}]` : "";
+          parts.push(`  ${name}${tag}`);
+        }
+        const optionalDeps = deps.filter((d) => d.optional && d.kind === "normal");
+        if (optionalDeps.length) {
+          parts.push("", "## Optional Dependencies");
+          for (const dep of optionalDeps) {
+            parts.push(`  ${dep.name} ${dep.req} (feature-gated)`);
+          }
+        }
+        const requiredDeps = deps.filter((d) => !d.optional && d.kind === "normal");
+        if (requiredDeps.length) {
+          parts.push("", "## Required Dependencies");
+          for (const dep of requiredDeps) {
+            parts.push(`  ${dep.name} ${dep.req}`);
+          }
+        }
+        if (versionInfo.yanked) {
+          parts.push("", "> WARNING: This version has been yanked.");
+        }
+        return textResult(parts.join("\n"));
+      } catch (e) {
+        return errorResult(`Could not fetch metadata for "${crateName}". ${e.message}`);
+      }
+    }
+  );
+}
+function register(server2) {
+  server2.tool(
+    "get_crate_brief",
+    "Bundle call: fetches crate metadata, overview docs, module list, re-exports, and optionally items from focused modules — all in one shot.",
+    {
+      crateName: z.string().describe("Crate name"),
+      version: versionParam,
+      focusModules: z.string().optional().describe('Comma-separated module names to expand (e.g. "sync,task,io"). Omit for overview only.')
+    },
+    async ({ crateName, version, focusModules }) => {
+      try {
+        const info = await fetchCrateInfo(crateName);
+        const ver = version ?? info.version;
+        const versionInfo = await fetchCrateVersionInfo(crateName, ver);
+        const rootUrl = docsUrl(crateName, "index.html", ver);
+        const $ = await fetchDom(rootUrl);
+        const doc = truncate(cleanHtml($("details.toggle.top-doc").html() ?? ""), 3e3);
+        const reexports = extractReExports($);
+        const itemsBySection = {};
+        $("h2.section-header").each((_, h2) => {
+          const sectionId = $(h2).attr("id") ?? "";
+          const type = SECTION_TO_TYPE[sectionId] ?? sectionId;
+          const items = [];
+          $(h2).next("dl.item-table").find("dt").each((_2, dt) => {
+            const $dt = $(dt);
+            const name = $dt.find("a").first().text().trim();
+            const gate = $dt.find(".stab.portability code").first().text().trim();
+            if (name) {
+              items.push(gate ? `${name} [${gate}]` : name);
+            }
+          });
+          if (items.length) itemsBySection[type] = items;
+        });
+        const parts = [
+          `# ${info.name} v${versionInfo.num}`,
+          rootUrl,
+          "",
+          info.description,
+          "",
+          `license: ${versionInfo.license} | downloads: ${info.downloads.toLocaleString()}`
+        ];
+        if (info.repository) parts.push(`repo: ${info.repository}`);
+        const { defaultFeatures, features } = versionInfo;
+        parts.push(
+          "",
+          "## Features",
+          `  default = [${defaultFeatures.join(", ")}]`,
+          `  all: ${Object.keys(features).filter((f) => f !== "default").sort().join(", ")}`
+        );
+        if (doc) parts.push("", "## Overview", doc);
+        if (reexports.length) {
+          parts.push("", "## Re-exports", ...reexports.map((r) => `  ${r}`));
+        }
+        if (itemsBySection["mod"]) {
+          parts.push("", "## Modules", ...itemsBySection["mod"].map((m) => `  ${m}`));
+        }
+        for (const [type, items] of Object.entries(itemsBySection)) {
+          if (type === "mod" || type === "reexport") continue;
+          parts.push("", `## ${type} (${items.length})`, ...items.map((i) => `  ${i}`));
+        }
+        if (focusModules) {
+          const modules = focusModules.split(",").map((m) => m.trim()).filter(Boolean);
+          for (const mod of modules) {
+            try {
+              const modUrl = docsUrl(crateName, `${modToUrlPrefix(mod)}index.html`, ver);
+              const $mod = await fetchDom(modUrl);
+              parts.push("", `## Focus: ${crateName}::${mod.replace(/\./g, "::")}`, modUrl);
+              $mod("h2.section-header").each((_, h2) => {
+                const sectionId = $mod(h2).attr("id") ?? "";
+                const type = SECTION_TO_TYPE[sectionId] ?? sectionId;
+                $mod(h2).next("dl.item-table").find("dt").each((_2, dt) => {
+                  const $dt = $mod(dt);
+                  const name = $dt.find("a").first().text().trim();
+                  const desc = $dt.next("dd").text().trim();
+                  const gate = $dt.find(".stab.portability code").first().text().trim();
+                  if (!name) return;
+                  const tag = gate ? ` [${gate}]` : "";
+                  parts.push(`  [${type}] ${name}${tag} — ${desc}`);
+                });
+              });
+            } catch {
+              parts.push("", `## Focus: ${mod}`, `  (module not found)`);
+            }
+          }
+        }
+        return textResult(parts.join("\n"));
+      } catch (e) {
+        return errorResult(`Could not fetch brief for "${crateName}". ${e.message}`);
+      }
+    }
+  );
+}
+console.log = (...args) => console.error(...args);
+const server = new McpServer({ name: "rust-docs", version: "2.0.0" });
+register$5(server);
+register$4(server);
+register$3(server);
+register$2(server);
+register$1(server);
+register(server);
+server.prompt(
+  "lookup_crate_docs",
+  { crateName: z.string().describe("Crate name") },
+  ({ crateName }) => ({
+    messages: [
+      {
+        role: "user",
+        content: {
+          type: "text",
+          text: [
+            `Analyze the documentation for the Rust crate '${crateName}'. Focus on:`,
+            "1. Main purpose and features",
+            "2. Key types and functions",
+            "3. Common usage patterns",
+            "4. Important notes or warnings",
+            "5. Latest version"
+          ].join("\n")
+        }
+      }
+    ]
+  })
+);
+async function main() {
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+}
+main().catch((e) => {
+  console.error("Failed to start server:", e);
+  process.exit(1);
+});

package/package.json

@@ -0,0 +1,56 @@
+{
+  "name": "mcp-rustdoc",
+  "version": "2.0.0",
+  "type": "module",
+  "description": "MCP server for fetching and browsing Rust crate documentation from docs.rs and crates.io",
+  "main": "dist/index.js",
+  "bin": {
+    "mcp-rustdoc": "dist/index.js"
+  },
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "dev": "bun run src/index.ts",
+    "build": "vite build",
+    "build:tsc": "tsc",
+    "start": "node dist/index.js",
+    "typecheck": "tsc --noEmit",
+    "prepublishOnly": "vite build"
+  },
+  "keywords": [
+    "mcp",
+    "rust",
+    "docs.rs",
+    "crates.io",
+    "documentation",
+    "model-context-protocol",
+    "rustdoc",
+    "ai",
+    "llm"
+  ],
+  "author": "",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/kieled/mcp-rustdoc.git"
+  },
+  "homepage": "https://github.com/kieled/mcp-rustdoc#readme",
+  "engines": {
+    "node": ">=18"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.6.1",
+    "axios": "^1.6.0",
+    "cheerio": "^1.0.0",
+    "html-to-text": "^9.0.5",
+    "zod": "^3.23.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "typescript": "^5.7.0",
+    "vite": "^6.0.0"
+  }
+}