oss-docs-mcp
Indexes the Istio documentation for releases 1.31 and 1.32, letting agents search, outline, and read Istio doc sections with version-pinned citations (public URL plus GitHub source at a specific commit), and compare what changed between releases.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@oss-docs-mcp search KServe 0.20 docs for autoscaling and show what changed in 0.21"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
oss-docs-mcp
Version-pinned, token-thrifty documentation RAG for open-source AI-infra / Kubernetes projects, served over MCP.
LLMs answer infra questions from stale, version-mixed training data, and web search burns
tokens on HTML, navigation and the wrong release. oss-docs-mcp indexes each project's
docs straight from its own git repository, keeps the last N releases side by side, and
gives agents a search → read workflow that returns only the sections they need, with an exact
citation (url + source pinned to the commit).
It is project-agnostic: adding a project = adding one YAML file in sources/.
Projects | KServe (0.19–0.21, next) · llm-d (0.9–1.0) · SGLang (v0.5.22, v0.5.23, next) · agentgateway (1.6.x, 1.7.x, main) · Agent Router / ex Envoy AI Gateway (1.0–1.2, next) · Kubeflow (master) · Envoy Gateway (v1.9, v1.10, next) · Gateway API Inference Extension (v1.6.2, next) · KEDA (2.20, 2.21) · vLLM (v0.32.0, v0.33.0) · LeaderWorkerSet (v0.11.1, v1.0.0) · Istio (1.31, 1.32) |
Index | SQLite FTS5 (BM25), single file (~119 MB for 12 projects / 31 versions), no GPU, no server |
Freshness |
|
Tools |
|
Sibling of k8s-docs-mcp (Kubernetes docs and
canonical manifests), study-cybercirujas
(certification syllabi) and rag-tutor (books + GraphRAG). Milestones: ROADMAP.md.
Quickstart
git clone https://github.com/villadalmine/oss-docs-mcp && cd oss-docs-mcp
uv sync
uv run oss-docs sources # list manifests
uv run oss-docs sync # fetch + index all (first run ~1 min)
uv run oss-docs search "prefill decode disaggregation" -p llm-d
uv run oss-docs read 30150 # full chunk with citation
uv run oss-docs outline kserve autoscaling -v 0.20
uv run oss-docs probe https://docs.example.io/ # which strategy fits a new site? drafts the YAML
uv run oss-docs whats-new llm-d # pages added/removed/moved/changed 0.10 → 1.0
uv run oss-docs pull # or: download the weekly pre-built index
uv run pytest -q # offline tests
uv run python scripts/smoke_mcp.py # end-to-end over MCP stdioThe checkouts under data/cache/ take about 1 GB; keep data/ on a real disk, not a small tmpfs. sync forces git over HTTP/1.1 because GitHub rejects the big blob fetches of a blobless sparse clone over HTTP/2 (HTTP 400).
Related MCP server: Documentation MCP Server
Connect it
Claude Code
claude mcp add -s user oss-docs -- uv --directory /path/to/oss-docs-mcp run oss-docs-mcpAntigravity / agy
agy mcp add oss-docs -- uv --directory /path/to/oss-docs-mcp run oss-docs-mcpClaude Desktop / Cursor / any stdio client
{ "mcpServers": { "oss-docs": { "command": "uv",
"args": ["--directory", "/path/to/oss-docs-mcp", "run", "oss-docs-mcp"] } } }HTTP (Open WebUI ≥ 0.6.31 native MCP, agentgateway, rag-tutor's gateway)
uv run oss-docs-mcp --transport streamable-http --host 0.0.0.0 --port 8765 # → http://host:8765/mcpStep-by-step for Claude Code, Antigravity / agy and Open WebUI with a local LLM (both verified
end to end): docs/INTEGRATIONS.md.
Server deployment with systemd + Open WebUI configured as code (and small-model lessons): docs/DEPLOY-SERVER.md.
Containers: podman compose -f deploy/compose.yaml up -d (oss-docs + Open WebUI). rag-tutor uses
this index as its 4th MCP source (see INTEGRATIONS §5).
Env vars: OSS_DOCS_HOME (data dir, default ./data), OSS_DOCS_SOURCES, OSS_DOCS_DB, OSS_DOCS_MAX_HITS,
OSS_DOCS_MAX_READ_TOKENS (caps for small-context local models; also --max-read-tokens).
How an agent uses it (cheap → expensive)
search_docs("LLMInferenceService scheduler", project="kserve")
→ [26253] kserve@0.21 · LLMInferenceService Configuration Guide › Router Specification › Scheduler Configuration (~560 tok)
https://kserve.github.io/website/docs/model-serving/generative-inference/llmisvc/llmisvc-configuration#scheduler-configuration
… snippet …
read_chunks([26253]) → full section + url + source pinned to commit
get_page_outline("kserve", "llmisvc-configuration") → navigate long pages by section
search_docs(..., version="0.19") → answer for the release the user actually runs
whats_new("kserve") → what changed 0.20 → 0.21 (upgrade planning)Measured (scripts/token_benchmark.py, search + read top-2, tokens ≈ chars/4):
question | oss-docs-mcp | full page (markdown) | live page (HTML) |
LLMInferenceService scheduler prefix cache routing | 1.7k | 2.1k | 21.4k |
autoscaling KEDA ScaledObject | 1.5k | 5.0k | 40.3k |
prefill decode disaggregation EPP | 1.4k | 3.6k | 14.2k |
precise prefix cache aware routing kv events | 1.4k | 10.7k | 40.8k |
So 10–30× fewer tokens than fetching the page, 1.2–7.8× fewer than a perfect HTML→markdown fetch, and always the right version.
Adding a project
# sources/<id>.yaml (id must match the file name)
id: kserve
name: KServe
license: Apache-2.0
categories: [ai-serving, kubernetes]
git:
repo: https://github.com/kserve/website
ref: main
docs_dirs: [docs] # branch / git_tags modes
exclude: [reference/controlplane-client/*]
versions:
mode: docusaurus # docusaurus | git_tags | version_dirs | branch
keep: 3 # releases kept indexed (older ones are pruned)
include_current: true # also index unreleased docs on `ref`
url:
docs_base: https://kserve.github.io/website/docs/
style: docusaurus # docusaurus | hugo | mkdocs | mintlify | plain
# content_root: content/docs # map URLs from a fixed site dir (keeps section/version in the URL)Which mode? See docs/STRATEGIES.md. Short version: docs in git with
versions.json → docusaurus; docs folder in the code repo, released by tag → git_tags;
versions as sibling dirs (e.g. agentgateway content/docs/<section>/{latest,1.6.x,main}) →
version_dirs; single rolling site (e.g. Kubeflow) → branch.
Let probe decide: oss-docs probe <docs-url|github-url> [--write] inspects the site
(llms.txt, llms-full.txt, sitemap, GitHub links) and the candidate repos (Docusaurus,
Hugo, MkDocs, Mintlify, version dirs, release tags), ranks the strategies with reasons and
drafts sources/<id>.yaml. It picks the right mode for the first 6 projects; for the 5 added
later it found the right repo but the draft needed manual review (version dirs without a
latest release dir, docs_dir other than docs/, versioned site URLs) — see STRATEGIES.
No repo? strategy: llms_full | llms_txt | crawl (crawl4ai, optional extra) index the latest
snapshot of any site with the same chunks and citations — examples in docs/examples/.
Hugo sites that single-source their pages ({{< reuse "…" >}} + {{< version include-if=… >}}
/ {{< conditional-text … >}}) are resolved per version and section via the hugo: block — see
sources/agentgateway.yaml.
Metadata kept per chunk
project, version, kind (release/current), is_latest, ref, commit_sha, commit_date,
page path, public url + #anchor, source_url (GitHub blob at the commit), title,
description, heading path, token estimate, page and version content hashes (incremental sync).
Chunk ids change when a version is re-indexed: treat them as session-scoped handles, and cite the
url/sourceinstead.
Layout
sources/ one YAML per project (the versioned "what")
src/oss_docs_mcp/
fetchers/git.py shallow + blobless + sparse checkouts, release tags
pipeline.py versions → docsets → parse → incremental (re)index + prune
markdown.py frontmatter, MDX/Docusaurus/Hugo cleanup (fences untouched), chunking
urls.py path → public URL per framework
hugo.py Hugo include shortcodes + version/section conditionals
probe.py strategy discovery for a new site/repo
fetchers/web.py llms-full.txt / llms.txt / crawl4ai (polite, robots.txt)
store.py SQLite FTS5, version-aware search
render.py compact citation-first output (shared by MCP + CLI)
server.py / cli.py MCP server / `oss-docs` CLI
scripts/ smoke_mcp.py, token_benchmark.py
deploy/ compose.yaml (+ Open WebUI), systemd unit, container entrypoint
Containerfile non-root image serving streamable HTTP on :8765/mcp
docs/STRATEGIES.md acquisition strategy ADR + evaluation of scraping toolsLicensing
Code: Apache-2.0. Indexed docs keep their upstream license (recorded per project); every answer carries its source link. Check a project's docs license before redistributing a pre-built index.
Available Tools
6 toolsget_page_outlineB
Section outline of one doc page: chunk ids, headings and token sizes.
Args:
project: project id.
page: repo path, URL, or part of it / of the title (e.g. 'autoscaling').
version: default latest.
Inputs: page (required), project (required), version. Returns: result
list_projectsA
List indexed projects with their latest version, indexed versions and categories.
Inputs: no named parameters. Returns: result
list_versionsA
List indexed versions of a project with commit, date and size.
Args:
project: project id from list_projects (e.g. 'kserve', 'llm-d').
Inputs: project (required). Returns: result
read_chunksA
Return the full text of selected chunks (from search_docs / get_page_outline) with citations.
Args:
ids: chunk ids exactly as shown in [brackets] by search_docs / get_page_outline (never invent ids).
max_tokens: approximate budget; chunks beyond it are listed but not returned.
Inputs: ids (required), max_tokens. Returns: result
search_docsA
Keyword (BM25) search over official docs. Returns compact pointers, not full text.
Args:
query: English keywords, e.g. 'InferenceService autoscaling' or 'prefix cache aware routing'.
project: restrict to one project id from list_projects (recommended). Omit to search the latest docs of all projects.
version: ONLY if the user asked for a specific release; omit it otherwise (= latest).
Unknown versions fall back to latest with a note.
limit: max hits (default 5).
Inputs: query (required), limit, project, version. Returns: result
whats_newA
Docs pages added / removed / changed between two indexed versions (upgrade planning).
Args:
project: project id.
old_version: older version (default: the release before new_version).
new_version: newer version (default: latest release). Use 'next' / 'main' for unreleased docs.
limit: max pages listed per category.
Inputs: project (required), limit, new_version, old_version. Returns: result
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 6 tools
Each tool has a distinct role in a clear workflow: list projects/versions, search docs, inspect page structure, read chunk text, and compare versions. Search_docs, get_page_outline, and read_chunks all concern documentation content, but their descriptions make the progression from discovery to outline to full text unambiguous.
All names use consistent snake_case, and most follow a readable verb_noun pattern such as list_projects, search_docs, and read_chunks. The only minor deviation is whats_new, which is still understandable but not structurally aligned with the rest.
Six tools is well-scoped for a documentation search and retrieval server. Each tool occupies a distinct step in the workflow, and there are no obviously redundant or missing helper tools.
The surface covers project/version discovery, keyword search, page outlining, full-chunk retrieval, and cross-version change tracking, which covers the core documentation workflow well. A direct page-listing or full-page retrieval tool would close a minor discovery gap, but agents can work around it via search and outlines.
Maintenance
Related MCP Connectors
Versioned documentation registry and semantic search for AI tools and coding assistants.
One place for every AI agent's pages and docs: versioned links to share, search and update.
Provide your AI coding tools with token-efficient access to up-to-date technical documentation for…
A cited wiki of your GitHub repo: search, read pages, find symbols and ask, with line citations.
Related MCP Servers
- AlicenseAqualityDmaintenanceProvides LLMs with real-time access to up-to-date documentation from PyPI, npm, crates.io, GoDocs, DockerHub, GitHub, and GCP, preventing outdated code generation and API hallucinations.2737 PyPI14MIT
- FlicenseNot gradedqualityDmaintenanceEnables AI agents to search and query documentation from git repositories using hybrid search and structured metadata queries.1-
- AlicenseNot gradedqualityDmaintenanceProvides real-time, version-pinned documentation from 57+ AI/ML libraries to LLMs, preventing hallucinated APIs by fetching current docs and changelogs directly from GitHub.10 npmMIT
- AlicenseNot gradedqualityBmaintenanceEnables AI agents to search and ask questions across versioned service documentation, retrieve documents and diffs, and find related docs with cited answers over Streamable HTTP, SSE, or stdio.296 npmMIT