Skip to main content
Glama
README.md
# 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/`](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`](https://github.com/villadalmine/k8s-docs-mcp) (Kubernetes docs and
canonical manifests), [`study-cybercirujas`](https://github.com/villadalmine/study-cybercirujas)
(certification syllabi) and `rag-tutor` (books + GraphRAG). Milestones: [ROADMAP.md](ROADMAP.md).

## Quickstart

```bash
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).

## Connect it

**Claude Code**
```bash
claude mcp add -s user oss-docs -- uv --directory /path/to/oss-docs-mcp run oss-docs-mcp
```

**Antigravity / agy**
```bash
agy mcp add oss-docs -- uv --directory /path/to/oss-docs-mcp run oss-docs-mcp
```

**Claude Desktop / Cursor / any stdio client**
```json
{ "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)**
```bash
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](docs/INTEGRATIONS.md).
Server deployment with systemd + Open WebUI configured as code (and small-model lessons): [docs/DEPLOY-SERVER.md](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)

```text
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

```yaml
# 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](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/`](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`](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

```text
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.

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