cloud-ark / cloud-ark/kubeplus
Add a RAG MCP server for KubePlus documentation, for use with kagent agents
- Dominant language
- Go
- Stars
- 756
- Forks
- 95
- Avg merge
- 1d 14h
- Merged PRs (30d)
- 7
Description
### Summary
Agents built on kagent currently connect to KubePlus via a basic MCP server exposing
imperative tools (kubectl-metrics, etc.). This issue proposes adding a second,
retrieval-focused MCP server that lets an agent ground its answers in KubePlus's own
docs and example manifests, rather than relying on model memory alone.
### Motivation
- kagent supports attaching multiple `ToolServer` resources to a single `Agent`, so
tools and retrieval can be cleanly separated instead of overloading one server.
- KubePlus's docs/example set (README, Operator-FAQ, getting-started, multitenancy
examples, etc.) is small enough to index locally without an external embedding API,
making it usable in offline/minikube classroom and CI environments.
- This gives students and adopters an agent that can answer "how do I configure X in
KubePlus" questions with citations back to the actual repo files, not just
general LLM knowledge.
### Proposed approach
1. **Ingest** (`ingest.py`): clone `cloud-ark/kubeplus`, walk `.md` docs and
`.yaml`/`.yml` example manifests (skip `vendor/`), chunk (~250 words, 50-word
overlap), fit a `TfidfVectorizer`, and persist to `index.pkl`.
- No embedding model download required — keeps it usable offline in minikube.
2. **Serve** (`rag_server.py`): a FastMCP server exposing one tool,
`search_kubeplus_docs(query, top_k)`, doing cosine-similarity lookup over the
saved index and returning `{source, score, text}` per match.
3. **Wire into kagent**: register the server as its own `ToolServer` CR and attach it
to the `Agent` alongside the existing tools `ToolServer`, e.g.:
```yaml
apiVersion: kagent.dev/v1alpha1
kind: ToolServer
metadata:
name: kubeplus-rag
spec:
stdio:
command: python
args: ["rag_server.py"]
workingDir: /path/to/kubeplus_rag
---
apiVersion: kagent.dev/v1alpha1
kind: Agent
metadata:
name: kubeplus-agent
spec:
tools:
- toolServer: your-existing-tools-server
- toolServer: kubeplus-rag
```
### Tasks
- [ ] Add `ingest.py` / `rag_server.py` (prototype attached/linked below)
- [ ] Decide on re-index trigger: manual re-run vs. scheduled job vs. git webhook
- [ ] Evaluate retrieval quality on a fixed set of test questions (multitenancy,
cross-ns-deps, storage isolation, etc.)
- [ ] Document the two-`ToolServer` pattern in the kagent + KubePlus integration docs
- [ ] (Stretch) swap TF-IDF for real embeddings (local sentence-transformers or an
embedding API) once past prototype stage
### Acceptance criteria
- A kagent `Agent` can be configured with both the existing tools `ToolServer` and
`kubeplus-rag`, and correctly calls `search_kubeplus_docs` when asked
KubePlus-specific questions.
- Retrieval returns relevant chunks (source file + score) for a documented set of
sample queries.
- Setup works fully offline against a local minikube cluster, with no external API
dependency for embeddings.
### Related
- Builds on the existing KubePlus MCP server work (kubectl-metrics wrapper,
kubeconfig security boundary, init-container plugin fetching).
- Complements the multi-tenant kagent isolation issues (cross-ns-deps annotation,
Agent Sandbox interoperability).
Contributor guide
Research direction
Start by reviewing the existing KubePlus MCP server and the proposed ToolServer and Agent YAML. Then examine the prototype for ingest.py and rag_server.py, and assess indexing the named Markdown and YAML sources offline. Done means both ToolServers can be attached to an Agent, search_kubeplus_docs returns relevant sources and scores for fixed sample queries, and the integration pattern is documented.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- kubernetes, python, scikit-learn
- Domain
- ai, devops, documentation
- Issue type
- Feature
- Difficulty
- 5/5
- Estimated time
- Over a week
- Activity status
- Active
- Clarity
- Mostly clear
- Newbie friendliness
- 35/100