Skip to main content
Glama

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

oss-docs sync (sparse git, ~5 s when nothing changed) or oss-docs pull (weekly pre-built index, ~19 MB gz)

Tools

list_projects, list_versions, search_docs, read_chunks, get_page_outline, whats_new

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 stdio

The 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-mcp

Antigravity / agy

agy mcp add oss-docs -- uv --directory /path/to/oss-docs-mcp run oss-docs-mcp

Claude 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/mcp

Step-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 / source instead.

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 tools

Licensing

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 tools
get_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

    A3.9/5.0

    Scored across 6 tools

    Disambiguation5/5

    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.

    Naming Consistency4/5

    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.

    Tool Count5/5

    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.

    Completeness4/5

    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

    ActivityNo data
    ResponsivenessOutdated data

    Related MCP Connectors

    Related MCP Servers