Iggy Docs MCP

MCP server for answering questions from the Apache Iggy documentation.

Serves two corpora to any MCP client, so an AI assistant answers Iggy questions from the project's own current material rather than from training data:

• the guides — the content/docs tree of apache/iggy-website, around seventy-five pages covering the server, every SDK, connectors, clustering, the CLI and the web UI. Keyed by site path (server/docker), linked to iggy.apache.org.

• the Rust API — the inline /// doc comments of the SDK and core crates in apache/iggy, read from rustdoc's JSON output. Keyed under api/ (api/iggy/clients/client/IggyClient), linked to docs.rs.

The two answer different questions — the guides say how Iggy is meant to be used, the Rust API says what is actually callable — so results are labelled with the half they came from, and list_docs and search_docs take a source argument (all, website, rust-api) to restrict to one.

Search is chunked BM25, with a small vocabulary bridge (container → docker, typescript → node, ssl → tls). Code blocks are first-class content: an SDK answer usually is the code block.

Each half is ranked on its own. BM25 normalises against average chunk length, and generated API items are uniformly shorter than prose, so one pooled average would penalise every guide chunk and flatter every API one. The two lists are then interleaved 2:1 in favour of prose — an explanation usually answers the question and a signature confirms it. A query that matches one half alone returns that half in full.

Distinct from the MCP server the Iggy project itself ships, which speaks the broker protocol to a running server. This one serves documentation and needs no server running.

Modelled on PolicyMCP, an MCP server for ASF policy documents: same layout, same tool surface, same conventions.

Corpus sources

Guides (apache/iggy-website)

Two modes, checked in this order:

1. Local checkout, when IGGY_DOCS_ROOT points at an iggy-website checkout (either the repo root or content/docs directly; the repo root resolves to content/docs, so blog posts and node_modules are never indexed). Files are read fresh on every call, so git pull is the refresh.

2. GitHub, otherwise: the docs tree is discovered via the GitHub API and fetched from raw files, cached in ~/.cache/iggy-doc-mcp/ for seven days.

Rust API (apache/iggy)

A second local root, IGGY_RUST_ROOT, pointing at an apache/iggy checkout. There is no GitHub mode: unlike the guides, these files are generated, and generating them needs the source tree.

Only the public API of the SDK and core crates is indexed — iggy, iggy_common, iggy_binary_protocol, overridable with IGGY_RUST_CRATES. That keeps the index in the hundreds of items rather than the tens of thousands a whole-workspace private-item index would produce, which matters because every extra short item competes with the guides in search.

Doc comments are read from rustdoc's JSON, which cargo writes to target/doc/<crate>.json:

cargo +nightly rustdoc -p iggy --lib -- -Z unstable-options --output-format json

Building is never implicit — a search must not trigger a Rust build — so:

• when the JSON is present it is parsed fresh on every call, exactly like the website checkout, and re-running cargo rustdoc is the refresh;

• refresh_docs runs the build explicitly, once per configured crate;

• when the JSON is absent the Rust corpus is simply empty and the guides answer alone. A configured IGGY_RUST_ROOT with nothing built under it says so rather than returning silently.

IGGY_RUST_DOC_JSON overrides where the <crate>.json files are looked for, if they are not under <root>/target/doc.

One wrinkle on the first build: it takes minutes, and some MCP clients cut a tool call off after 60 seconds, so refresh_docs may report a timeout while cargo carries on and finishes normally. Call list_docs afterwards to confirm — if the item count is in the hundreds, the build landed. Later refreshes return promptly, because cargo has nothing to redo.

Two caveats worth knowing. rustdoc's JSON format is explicitly unstable and renumbers on breaking changes; the parser handles both the current and previous spellings of the shapes it uses and warns when it meets a format_version outside its checked range, rather than silently rendering signatures as _. And --output-format json is nightly-only, though a stable toolchain will emit it under RUSTC_BOOTSTRAP=1 if you would rather not install one.

Related MCP server: Documentation Fetcher & RAG Search

Install

python3 -m venv .venv
. .venv/bin/activate
pip install -e .

Run

iggy-doc-mcp

For local development:

python -m iggy_doc_mcp.server

Test

pip install -e ".[dev]"
make check

Configure with Claude Desktop or Codex

On macOS the Claude Desktop config lives at ~/Library/Application Support/Claude/claude_desktop_config.json; create it if it is not there. Add the server, then quit and reopen Claude Desktop.

{
  "mcpServers": {
    "iggy-docs": {
      "command": "<path to IggyDocMCP>/.venv/bin/python",
      "args": ["-m", "iggy_doc_mcp.server"],
      "env": {
        "IGGY_DOCS_ROOT": "<path to iggy-website>",
        "IGGY_RUST_ROOT": "<path to iggy>"
      }
    }
  }
}

Omit IGGY_DOCS_ROOT to use the GitHub-fetched guides instead of a local checkout. Omit IGGY_RUST_ROOT to serve the guides alone.

Tools

• list_docs — every documentation page, organised by section, with word counts and corpus source; source restricts to one half.

• get_doc — full text of one page by key (e.g. server/docker, sdk/python/intro); unambiguous partial keys resolve automatically.

• search_docs — ranked keyword search across both halves, returning excerpts with their code blocks, each labelled Guide or Rust API and linked to iggy.apache.org or docs.rs; source restricts to one half.

• find_examples — search fenced code examples by topic and language, with source doc keys, headings and URLs.

• extract_code_snippets — inventory code fences for snippet verification work, filtered by language or doc key.

• get_related_docs — find pages related to a doc key using links, backlinks, shared section and shared terms.

• explain_doc_map — guided overview of the documentation sections, likely entry points for an audience or goal, and obvious top-level gaps.

• find_broken_links — local-checkout link scan for broken internal docs links and optional external URL checks.

• refresh_docs — re-fetch the GitHub guides, bypassing the seven-day cache (reporting git pull as the path when a local checkout is in use), and rebuild the Rust API corpus with cargo rustdoc.

Example questions

• What flags does the Iggy server need under Docker?

• How do I create a consumer group from Python?

• What is the exact signature of send_messages on the Rust client?

• Which errors can IggyClient::connect return?

• How do I enable TLS?

• How is message retention configured?

• Show me a TypeScript producer example.

Licence

Apache License 2.0. See LICENSE.

Disclaimer

This is an independent, third-party tool. It is not a release of, endorsed by, or affiliated with the Apache Software Foundation or the Apache Iggy project. Apache, Apache Iggy and Iggy are trademarks of the Apache Software Foundation.