Provides search and review capabilities for Argo Applications, including application search, deployment inspection, and image and values grep across hundreds of public home-ops Kubernetes Git repositories.
Provides search and review capabilities for Flux HelmReleases, including chart search, deployment inspection, and image and values grep across hundreds of public home-ops Kubernetes Git repositories.
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., "@kubesearch-mcp search for cert-manager HelmReleases"
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.
An MCP server that lets an LLM search kubesearch.dev — a search engine over Flux HelmReleases and Argo Applications across hundreds of public "home-ops" Kubernetes Git repositories.
It reproduces all of kubesearch.dev's search modes as tools, and can temporarily clone a repo so the model can review its actual manifests.
Tool | kubesearch.dev equivalent | What it does |
|
| Find charts by name; see who deploys them, ranked by popularity. |
|
| One chart's deployments. |
|
| Container image repositories and the tags used in the wild. |
|
| Full-text grep across real-world Helm values for config examples. |
| — | Report the cached data's release date and row counts. |
All search tools are annotated read-only and return a typed structuredContent
payload alongside the equivalent text. They page with limit/offset and report
has_more, and their result ordering is global (matches are ranked across the whole
result set before the page is cut), so paging never repeats or skips an entry.
In the values view, value_paths accepts the paths printed in the summary view's
common_settings verbatim, array forms like route.hostnames[] included. A single
deployment whose config is too large for one response is always returned when it is
first on the page, so { repo, limit: 1 } reaches any deployment; larger ones later in
a page are reported individually via values_omitted and omitted_count.
KUBESEARCH_ENABLE_CLONE=false to disable)Tool | What it does |
| Temporarily clone a repo (indexed |
| List files in a clone (optional sub-path + glob). |
| Read a text file from a clone (binary refused, large files truncated). |
| Substring-search a clone's text files; returns |
| Delete a clone early (clones also auto-expire). |
Clones are sandboxed: shallow (--depth 1, blob-size filtered), run with git via
execFile (no shell) and a scrubbed environment, size/TTL/concurrency-capped, confined to
a per-clone temp dir, with path-traversal and symlink-escape protection. By default any
public host is allowed but private/loopback/link-local/metadata addresses are blocked (see
env vars below).
Lifecycle: a clone is kept while it's being used and auto-deleted after
KUBESEARCH_CLONE_TTL_MINUTES of inactivity (the timer resets on every access). Repeat
repo_clone calls for the same repo+branch are deduplicated to a single working copy and
(by default) refreshed with a shallow git fetch + hard reset to the latest commit, so a
long-lived clone never goes stale — set KUBESEARCH_CLONE_REFRESH_ON_CLONE=false to reuse
without pulling. Reads (repo_read_file/repo_grep/repo_list_files) are served from the
snapshot and do not pull, so an in-progress review stays stable; re-run repo_clone to pull.
Concurrent repo_clone calls for the same repo share a single git invocation, at most
KUBESEARCH_CLONE_MAX_CONCURRENT git subprocesses run at once, and clone directories
stranded by an ungraceful restart are reaped at startup.
Server-provided MCP prompts that chain the tools: kubesearch_compare_deployments,
kubesearch_adopt_chart, kubesearch_find_config_examples, kubesearch_pick_image, and
(when cloning is enabled) kubesearch_review_repo.
kubesearch.dev has no live API; it publishes its index as SQLite databases on the
whazor/k8s-at-home-search GitHub
releases (a new date-tagged release daily). This server downloads and caches those
databases locally and queries them with SQL — fast, offline-capable, and identical to
what the website shows. Two complementary databases are used and joined on the YAML
file URL:
repos.db (~7 MB) — chart/release/repo metadata.
repos-extended.db (~37 MB) — the spec.values JSON (powers grep and image search).
Data is refreshed automatically when a newer daily release appears (see
KUBESEARCH_REFRESH_HOURS).
Related MCP server: K8s MCP Server
npm install
npm run buildAdd it to Claude Code:
claude mcp add kubesearch -- node /absolute/path/to/kubesearch-mcp/dist/index.jsOr in a Claude Desktop / MCP client config:
{
"mcpServers": {
"kubesearch": {
"command": "node",
"args": ["/absolute/path/to/kubesearch-mcp/dist/index.js"]
}
}
}The first call downloads the databases into the cache dir (a few seconds); subsequent runs reuse the cache.
The image defaults to the Streamable HTTP transport, which is what you want for a long-running server that MCP clients connect to over the network.
docker run -d --name kubesearch-mcp \
-p 3000:3000 \
-v kubesearch-data:/data \
-e GITHUB_TOKEN=ghp_xxx \
ghcr.io/perfectra1n/kubesearch-mcp:latestPublished tags: latest (default branch), vX.Y.Z and X.Y (releases), and
sha-<short> for a specific commit. To build it yourself instead, use
docker build -t kubesearch-mcp . and substitute that image name.
Mount /data as shown: it holds the cached databases, so without it every restart
re-downloads ~44 MB.
Or with Compose:
docker compose up -dThe container runs as the unprivileged
nodeuser (uid 1000) and writes cached databases and clones under/data. The named volume indocker-compose.ymlis writable out of the box. If you bind-mount a host directory instead, make it writable by uid 1000 (e.g.chown -R 1000:1000 ./data), orrepo_cloneand refreshes will fail with "Permission denied".
The MCP endpoint is http://<host>:3000/mcp. Two health endpoints are exposed:
GET /healthz — liveness. Always 200 while the process is up. This is what the
image's HEALTHCHECK uses, so a slow initial download can't get the container
restarted mid-download.
GET /readyz — readiness. 503 until a release is loaded, then 200. Use this for
Kubernetes readiness probes and load-balancer checks, so traffic isn't sent to a pod
whose first queries would fail.
Point an MCP client at it:
{
"mcpServers": {
"kubesearch": {
"type": "http",
"url": "http://localhost:3000/mcp",
"headers": { "Authorization": "Bearer <MCP_AUTH_TOKEN>" }
}
}
}(The Authorization header is only required when MCP_AUTH_TOKEN is set.)
The HTTP transport ships open. Out of the box there is no authentication, CORS is
*, and the image binds 0.0.0.0. That is fine on a trusted network or behind a
reverse proxy that authenticates for you; it is not fine on a public interface. Before
exposing the port beyond a network you control:
Variable | Default | What it does |
| (unset — auth off) | Require |
| (unset — any origin) | Comma-separated |
| (unset — any host) | Comma-separated |
|
| Refuse new sessions past this many concurrent ones. |
|
| Reject larger request bodies with 413. |
The server logs a warning at startup if it binds a non-loopback address with authentication disabled. Terminate TLS at a proxy; the server speaks plain HTTP.
If you prefer to have a client spawn the container per session:
docker run -i --rm -v kubesearch-data:/data -e MCP_TRANSPORT=stdio kubesearch-mcpAll configuration is via environment variables:
Variable | Default | Description |
|
|
|
|
| HTTP bind host (http transport). |
|
| HTTP listen port. |
| (unset — auth off) | If set, every HTTP request must send |
| (unset — any) |
|
| (unset — any) |
|
|
| Max HTTP request body size; larger bodies get 413. |
|
| Max concurrent HTTP sessions; further |
|
| Close an HTTP session after this long with no requests. |
|
| Minimum log severity to emit: |
|
| Where the SQLite databases are cached. |
|
| How often to check for a newer daily release. |
|
| Wall-clock limit for downloading one database. Downloads also abort after 30s with no data received. |
|
| Reject a database download larger than this. |
| (unset) | Lifts the GitHub API rate limit (60→5000/hr) used to resolve the latest release. Recommended. |
|
| Source repo for the databases (override only for forks/testing). |
|
| Enable the |
| (any) | Comma-separated host allowlist, e.g. |
|
| Permit cloning from private/loopback/link-local/metadata addresses (SSRF guard off). |
|
| Where ephemeral clones live. |
|
| Auto-delete a clone after this much inactivity (timer resets on each access). |
|
| On a repeat clone of the same repo, |
|
| Max concurrent cached clones (LRU-evicted). |
|
| Max |
|
| Reject/clean a clone whose tree exceeds this size. |
|
| Hard timeout for the |
mise pins the toolchain and owns the dev/release lifecycle, so every command below is the same one CI runs. One-time setup:
mise install # installs Node, lefthook, shellcheck; also installs the git hooksThen:
mise tasks # list every task with a description
mise run dev # run from source via tsx
mise run test # vitest (unit + offline integration against a fixture DB)
mise run lint # typecheck + prettier --check + shellcheck
mise run fmt # format in place with prettier
mise run build # bundle to dist/ with tsup
mise run ci # the full local gate: fmt-check, typecheck, test, build
mise run smoke # end-to-end against live upstream data (needs network)
mise run image # build the container image locallyThe underlying npm run <script> commands still work if you'd rather not use mise; mise
is a thin wrapper plus a pinned toolchain. Exact tool versions live in
.mise/config.toml with per-platform checksums in .mise/mise.lock, which CI enforces
via mise install --locked; package.json's engines.node records the minimum
supported runtime.
A lefthook pre-commit hook formats staged files with prettier
and re-stages them, and runs shellcheck on shell scripts. It deliberately doesn't run
tests or the typechecker — that's CI's job, so committing stays fast. mise install
wires the hook; lefthook install re-syncs it if needed.
Tests run fully offline against a small fixture database that mirrors the real schema.
They cover the domain logic, the download/refresh paths (with a stubbed fetch), the
HTTP transport end to end, and the tools themselves through an in-memory MCP client —
which means the SDK validates every response against its declared outputSchema. The
releaseKey/mergeHelmURL slug logic is ported verbatim from upstream and locked with
test vectors so generated /hr/<id> links match the real site.
typecheck and test run on every push and pull request, and the container image is
only published if they pass.
All data comes from kubesearch.dev /
whazor/k8s-at-home-search. To include
your own cluster, make the repo public and add the k8s-at-home or kubesearch GitHub
topic.
MIT
Get details for one chart by its kubesearch.dev release id (the id from kubesearch_search_releases, e.g. 'ghcr.io-home-operations-charts-mirror-cert-manager'). Three views, controlled by view:
summary (default): a compact digest of how the community configures the chart — the most commonly-set spec.values paths with their typical values, plus a couple of full example configs. Start here.
deployments: the paginated list of every repo deploying the chart (no values) — use it to find a repo to drill into.
values: the full parsed spec.values for selected deployments — narrow with repo and/or value_paths to fetch just the config (or subtree) you care about. This is the drill-down; prefer summary first.
Note: chart_source_url is the normalized kubesearch.dev grouping key, not necessarily the pullable chart. For chartRef/OCIRepository releases the real chart is in source_urls (group) and each deployment's source_url + source_tag; resolved_chart surfaces the true chart name when it differs from chart. Confirm by cloning the deployment's repo (repo_clone) and reading its OCIRepository source.yaml.
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | The release id / slug, e.g. 'ghcr.io-home-operations-charts-mirror-cert-manager'. | |
| top | No | `summary` view: number of common value paths to return. | |
| repo | No | `values` view: restrict to one repo (e.g. 'onedr0p/home-ops'). | |
| view | No | summary = community config digest (default); deployments = paginated repo list; values = full config drill-down. | summary |
| limit | No | Page size for `deployments`/`values` views. | |
| offset | No | Pagination offset for `deployments`/`values` views. | |
| examples | No | `summary` view: number of full example configs to include. | |
| value_paths | No | `values` view: only return these value-path subtrees, e.g. ['server.persistentVolume','server.retentionPeriod']. Paths from the summary view's common_settings work as-is, including array forms like 'route.hostnames[]'. |
| Name | Required | Description |
|---|---|---|
| id | Yes | |
| view | Yes | |
| chart | Yes | |
| shown | No | |
| offset | No | |
| has_more | No | |
| next_step | No | |
| top_repos | No | |
| deployments | No | |
| source_urls | Yes | |
| matched_repos | No | |
| omitted_count | No | |
| kubesearch_url | Yes | |
| resolved_chart | Yes | |
| values_summary | No | |
| chart_source_url | Yes | |
| deployment_count | Yes | |
| chart_source_ambiguous | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the readOnly/idempotent annotations, the description discloses that `chart_source_url` is normalized rather than pullable, that chartRef/OCIRepository releases have real chart info in `source_urls`, and that `resolved_chart` surfaces the true name. It also explains the pagination and view behaviors.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is structured with bullets, front-loaded with the core purpose, and each sentence adds value (view explanations, caveats, and cross-reference). It is long but earned.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With a rich schema (8 params, enums, defaults) and output schema present, the description covers the tool's complexity thoroughly: it explains all three views, the data nuances, and provides a workflow. Gaps like error handling are not needed given the structured data.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Although the schema already documents all 8 parameters (100% coverage), the description adds interpretive guidance—e.g., how `value_paths` from summary settings work as-is including array forms, and how `view` controls which parameters apply. It also gives a concrete id example. This exceeds baseline 3.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states 'Get details for one chart by its kubesearch.dev release id' with a clear verb and resource. It distinguishes from sibling tools by referencing `kubesearch_search_releases` for the id and describing three specific views (summary, deployments, values) that are unique to this tool.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It explicitly says 'Start here' for summary view, tells users to use deployments to find a repo to drill into, and describes values as the drill-down. It also directs users to `repo_clone` for confirmation, providing alternative navigation.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Full-text grep across the Helm spec.values of every indexed HelmRelease/Application (substring match). Great for finding real-world examples of a config key or value, e.g. 'cert-manager.io', 'nodeSelector', 'gatus'. Returns the matched key path, a snippet, and the source file. Mirrors the kubesearch.dev /grep search.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Max number of matching files to return. | |
| query | Yes | Substring to grep for in values (keys or values), e.g. 'cert-manager.io'. | |
| offset | No | Skip this many matches (results are ranked by repo stars). | |
| case_sensitive | No | Match case-sensitively. |
| Name | Required | Description |
|---|---|---|
| query | Yes | |
| shown | Yes | |
| offset | Yes | |
| results | Yes | |
| grep_url | Yes | |
| has_more | Yes | |
| total_files | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
The description discloses return format (matched key path, snippet, source file), scope (every indexed HelmRelease/Application), and matching semantics (substring match). Annotations already declare read-only and idempotent, so the description adds behavioral context without contradiction, though it omits potential edge cases like rate limits.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences, front-loaded with the action, containing concrete examples and essential return details. No redundant or filler content.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description is complete for a simple grep tool: it defines the target space, matching behavior, return structure, and an external reference. Combined with the detailed schema, annotations, and output schema, nothing critical is missing.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with clear descriptions for all four parameters, so the baseline is 3. The description provides concrete query examples ('cert-manager.io', 'nodeSelector') that illustrate usage, but it doesn't explain limit, offset, or case_sensitive beyond what the schema already offers.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states a specific action: full-text grep across the Helm spec.values of indexed HelmRelease/Application objects. It distinguishes itself from sibling tools (e.g., kubesearch_search_releases, repo_grep) by targeting values and returning key paths/snippets. The kubesearch.dev reference adds precise context.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It explicitly states the tool is useful for finding real-world examples of config keys/values, which gives clear usage context. However, it does not explicitly mention when not to use it or name alternatives, so it falls just short of a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search kubesearch.dev for container image repositories used across public home-ops clusters (substring match on the image repository, case-insensitive). Returns each matching image repository, the tags seen in the wild, how many deployments use it, and a few sample repos. Equivalent to the kubesearch.dev /image search.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Max number of image repositories to return. | |
| query | Yes | Image repository substring, e.g. 'cert-manager', 'ghcr.io/home-operations', 'postgres'. | |
| offset | No | Skip this many results (ranked by usage count). |
| Name | Required | Description |
|---|---|---|
| query | Yes | |
| shown | Yes | |
| offset | Yes | |
| results | Yes | |
| has_more | Yes | |
| image_url | Yes | |
| total_matches | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already cover read-only/idempotent behavior, so the description adds value by disclosing the search semantics (substring, case-insensitive), the data source (public home-ops clusters), and the exact return contents (repositories, tags, deployment counts, sample repos). This goes beyond the annotations and enriches the agent's understanding.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two focused sentences with no fluff. The first sentence front-loads the core action and scope, the second describes return values and equivalence. Every clause earns its place, making it easy to parse quickly.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the output schema exists, the description doesn't need to detail return types. It covers the essential context: what the tool does, what data it searches, matching behavior, and result granularity. With annotations handling safety and schema handling parameters, the description is complete for this tool's complexity.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100% with clear parameter descriptions, so the baseline is 3. The description adds extra meaning by explaining the query parameter's matching semantics ('substring match, case-insensitive') and what the results represent (tag counts, deployment usage, sample repos), which complements the schema without redundancy.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb ('Search') and resource ('container image repositories'), and adds key semantics like substring match and case-insensitivity. It clearly distinguishes from sibling tools (search_releases, grep_values) by focusing on image repositories, and even references the equivalent kubesearch.dev /image search.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description clearly states the context (searching image repos across public home-ops clusters) and the matching behavior. However, it lacks explicit 'when not to use' or alternative tool references, though sibling names make the distinction obvious. This is close to a 5 but missing an explicit exclusion.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search kubesearch.dev for Flux HelmReleases / Argo Applications by chart name (substring, case-insensitive). Mirrors the kubesearch.dev homepage search (e.g. 'cert-manager'). Results are grouped by chart source and ranked by how many public home-ops repos deploy them. Each result includes an id you can pass to kubesearch_get_release for full details, plus a kubesearch.dev link.
Note: chart_source_url is a NORMALIZED grouping key (it matches kubesearch.dev's /hr/<id> grouping and intentionally collapses related registries, e.g. all bjw-s variants into 'oci://ghcr.io/bjw-s-labs/charts/'). For chartRef/OCIRepository releases the actual pullable chart is in source_urls (group) and each repo's source_url (+ source_tag); resolved_chart flags when the real chart name differs from chart.
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | Max number of chart groups to return. | |
| query | Yes | Chart name or substring to search for, e.g. 'cert-manager', 'authentik', 'plex'. | |
| offset | No | Pagination offset into the ranked results. |
| Name | Required | Description |
|---|---|---|
| query | Yes | |
| shown | Yes | |
| offset | Yes | |
| results | Yes | |
| has_more | Yes | |
| search_url | Yes | |
| total_matches | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Goes far beyond the readOnly/idempotent annotations by disclosing substring/case-insensitive matching, grouping by chart source, ranking by public home-ops repo usage, normalization of chart_source_url, and the resolved_chart flag. This is rich behavioral context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two compact paragraphs with the core statement first and a clearly separated note on normalization. Every sentence earns its place, though the normalization note is dense and might be overwhelming at first glance.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the output schema and annotations, the description covers search semantics, result shape, grouping caveats, and the next-step tool to use. It provides enough detail for an agent to invoke correctly and interpret results properly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema covers all parameters at 100%, and the description adds real value by specifying substring/case-insensitive matching, giving query examples, and clarifying output grouping semantics. It does not add much for limit/offset, but the schema already handles those.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states it searches kubesearch.dev for Flux HelmReleases / Argo Applications by chart name substring, case-insensitively. It distinguishes itself from kubesearch_get_release by noting results include an id for full details, and from image/grep siblings by its chart-name scope.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Frame as 'mirrors the kubesearch.dev homepage search' with examples, and explicitly directs the agent to pass returned ids to kubesearch_get_release for full details. It does not enumerate when not to use it relative to image/grep tools, but the used context is unambiguous.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Report the freshness and size of the locally cached kubesearch.dev data: the release tag (date), when it was loaded, the cache directory, and row counts. Useful to confirm how current the search data is.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
| Name | Required | Description |
|---|---|---|
| tag | Yes | |
| cacheDir | Yes | |
| loadedAt | Yes | |
| helmReleases | Yes | |
| releaseFiles | Yes | |
| reposIndexed | Yes | |
| valueDocuments | Yes | |
| ociRepositories | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint and idempotentHint, so the safety profile is covered. The description adds value by disclosing exactly what status information is returned (release tag, load time, cache directory, row counts), which goes beyond the annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences with no filler. The first sentence front-loads the action and output fields; the second provides a succinct use case. Every word earns its place.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple read-only status tool with no parameters and an output schema, the description fully covers purpose, output content, and usage context. It is entirely adequate given the tool's low complexity and sibling context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With zero parameters, the baseline for parameter semantics is 4. The description correctly avoids inventing parameter details, and the input schema confirms no parameters exist, so nothing is missing.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool reports freshness and size of cached data, enumerating specific fields (release tag, load time, cache directory, row counts). This unambiguously distinguishes it from sibling search tools, which perform queries rather than status inspection.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It explicitly notes the tool is 'useful to confirm how current the search data is', giving a clear use case. However, it doesn't explicitly mention when not to use it or name alternatives, though sibling tools imply those are for searching, not status checking.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Delete a temporary clone created by repo_clone (frees disk before its TTL). Clones are also auto-deleted after inactivity, so this is optional but polite.
| Name | Required | Description | Default |
|---|---|---|---|
| handle | Yes | The clone handle from repo_clone. |
| Name | Required | Description |
|---|---|---|
| handle | Yes | |
| removed | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already provide idempotentHint=true and readOnlyHint=false. The description adds valuable lifecycle context: clones are temporary, have a TTL, and are auto-deleted. This goes beyond annotations to explain why the tool is optional, and does not contradict destructiveHint=false since the clone is temporary.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is two sentences, front-loaded with the action ('Delete a temporary clone'), and both sentences serve a purpose: the first states the action and rationale, the second clarifies optionality. No wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a single-parameter tool with an output schema and strong annotations, the description covers the purpose, usage context, and lifecycle behavior (TTL, auto-deletion). It is fully sufficient for an agent to decide when and why to invoke it.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100% with the parameter 'handle' described as 'The clone handle from repo_clone.' The tool description merely references this relationship without adding new meaning, so the schema carries the full semantic burden.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses the verb 'Delete' with a specific resource ('temporary clone created by repo_clone') and clearly distinguishes this from sibling tools like repo_clone, which creates clones. The qualifier 'temporary' adds necessary scope.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
It explicitly states when to use it (to free disk before TTL) and when not to (since clones auto-delete after inactivity, making it optional). The alternative is effectively doing nothing, which the description implies by calling it 'polite'.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Temporarily clone a public Git repository so you can review its actual files. Accepts an indexed home-ops repo name (e.g. 'onedr0p/home-ops' — resolved to its real clone URL and branch) or a full https Git URL. The clone is shallow, sandboxed, size/time-limited, and auto-deleted after a TTL. Returns a handle to use with repo_list_files, repo_read_file, and repo_grep, plus a curated file tree to get you started. Call repo_cleanup when done.
| Name | Required | Description | Default |
|---|---|---|---|
| repo | Yes | An indexed repo name like 'onedr0p/home-ops', or a full https:// Git URL. |
| Name | Required | Description |
|---|---|---|
| tree | Yes | |
| branch | Yes | |
| handle | Yes | |
| reused | Yes | |
| size_mb | Yes | |
| updated | Yes | |
| file_count | Yes | |
| resolved_url | Yes | |
| expires_in_minutes | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Beyond the annotations (readOnlyHint=false, destructiveHint=false), the description discloses key behaviors: shallow clone, sandboxed environment, size/time limits, auto-deletion after TTL, and the nature of the return value (handle and curated file tree). It also notes that the repo must be public and that indexed names resolve to real clone URL and branch, adding meaningful context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise yet thorough, with four sentences that each add value: purpose, input types and resolution, clone characteristics and TTL, and output/lifecycle. It is well-structured, front-loading the main action, and contains no wasted words.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a clone tool with one parameter and an output schema, the description covers all essential aspects: what it does, input format, behavioral constraints (shallow, sandboxed, time-limited), output (handle + curated tree), and follow-up action (cleanup). The output schema explains return values, so the description need not list them, and it still manages to be sufficiently complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema describes the 'repo' parameter as an indexed repo name or full https URL. The description adds value by explaining that indexed names are resolved to their real clone URL and branch, and gives a concrete example. This goes beyond the schema's coverage, so it earns a 4 rather than the baseline 3.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool clones a public Git repository to review files, with a specific verb ('clone') and resource ('repository'). It distinguishes itself from siblings by explaining it returns a handle for use with repo_list_files, repo_read_file, and repo_grep, making its role as an entry point unmistakable.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description indicates when to use it ('so you can review actual files') and provides lifecycle instructions ('Call repo_cleanup when done'), plus how to use the returned handle with sibling tools. It does not explicitly state alternatives or when not to use it, but the context is clear enough for an agent to select this tool over others.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search the text contents of a previously cloned repository (by handle) for a substring. Optionally restrict to files matching a glob. Returns file paths, line numbers, and matching lines. If truncated is set, narrow the search with a longer query or a glob rather than paging.
| Name | Required | Description | Default |
|---|---|---|---|
| glob | No | Optional glob filter, e.g. '**/*.yaml'. | |
| limit | No | Max number of matching lines to return. | |
| query | Yes | Substring to search for across the repo's text files. | |
| handle | Yes | The clone handle from repo_clone. | |
| case_sensitive | No | Match case-sensitively. |
| Name | Required | Description |
|---|---|---|
| query | Yes | |
| handle | Yes | |
| matches | Yes | |
| truncated | Yes | |
| total_matches | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already signal readOnly, idempotent, and closed-world behavior. The description adds valuable behavioral details: search scope ('text contents'), optional glob filtering, return format ('file paths, line numbers, and matching lines'), and truncation handling. This goes beyond annotation basics and helps the agent predict tool output.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Three sentences, all informative. The first sentence captures the core action, the second adds an optional parameter, and the third provides practical usage advice. No filler or repetition; front-loaded and efficient.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a search tool with output schema and rich annotations, the description covers key contextual aspects: prerequisite (cloned repository), optional filter, return format, and behavior on truncation. It doesn't mention case_sensitive or limit explicitly, but the schema fully documents those, and the truncation guidance substitutes for deeper pagination details.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema coverage is 100%, with each parameter including a description, so the baseline is 3. The description does not significantly expand on parameter meaning beyond what the schema provides—it only restates 'by handle' and 'glob' in narrative form. No new parameter-level insight is added.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description states a specific verb ('Search') and a specific resource ('text contents of a previously cloned repository'), immediately distinguishing it from sibling tools like repo_list_files (list files) and repo_read_file (read one file). It also specifies the output (file paths, line numbers, matching lines), making the tool's purpose unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies the prerequisite of a prior repo_clone operation via 'previously cloned repository (by handle)', and offers explicit guidance for handling truncated results: 'narrow the search with a longer query or a glob rather than paging.' It does not explicitly mention when to use this over kubesearch_grep_values, but given sibling list and context, the usage is clear enough.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List files in a previously cloned repository (by handle). Optionally scope to a sub-path and/or filter with a glob (e.g. '/*.yaml', 'kubernetes/'). Use the handle returned by repo_clone.
| Name | Required | Description | Default |
|---|---|---|---|
| glob | No | Optional glob filter applied to file paths, e.g. '**/*.yaml'. | |
| path | No | Sub-path within the repo to list (default: repo root). | . |
| handle | Yes | The clone handle from repo_clone. |
| Name | Required | Description |
|---|---|---|
| path | Yes | |
| handle | Yes | |
| entries | Yes | |
| truncated | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint and idempotentHint, covering the safety profile. The description adds useful behavioral context beyond annotations: the handle must come from repo_clone, and listing can be scoped via sub-path and glob. No contradictions.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, front-loaded with the core purpose, followed by optional parameters and a necessary prerequisite. Every phrase earns its place with no redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a simple list files tool with an output schema, the description covers the prerequisite (handle from repo_clone) and options (path, glob). It does not explicitly state whether the listing is recursive, but the glob pattern '**/*.yaml' implies recursive behavior, and the output schema likely clarifies return structure. No major gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 100%, with each parameter (handle, path, glob) fully described in the input schema. The description restates these options but adds no new semantic detail beyond examples already present in the schema, so baseline 3 is appropriate.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states a specific action and resource: 'List files in a previously cloned repository (by handle)'. This distinguishes it from sibling tools like repo_read_file and repo_grep, which operate on file contents. The optional path and glob filters are additional specificity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives a clear prerequisite via 'Use the handle returned by repo_clone' and explains optional scoping/filtering with path and glob. It does not explicitly name alternatives or when-not-to-use conditions, but the context is strong enough for an agent to understand when this tool applies.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Read a text file from a previously cloned repository (by handle and relative path). Binary files are refused and large files are truncated. Use the handle returned by repo_clone.
| Name | Required | Description | Default |
|---|---|---|---|
| path | Yes | Relative path to the file within the repo, e.g. 'kubernetes/apps/cert-manager/helmrelease.yaml'. | |
| handle | Yes | The clone handle from repo_clone. | |
| max_bytes | No | Max bytes to return. |
| Name | Required | Description |
|---|---|---|
| path | Yes | |
| bytes | Yes | |
| handle | Yes | |
| content | Yes | |
| truncated | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare read-only and idempotent hints. The description adds behavioral details about binary files being refused and large files being truncated, which goes beyond the structured annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Two sentences, front-loaded with the action, and each sentence earns its place without unnecessary elaboration.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
With a rich output schema and good annotations, the description covers the key prerequisites and constraints (prerequisite handle, binary refusal, truncation) sufficiently for an agent to use the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema covers 100% of parameters with descriptions. The description reinforces the handle's origin but doesn't add significant new semantic information beyond what the schema already provides.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool reads a text file from a cloned repository using a handle and relative path. It also mentions binary refusal and truncation, which distinguishes it from sibling tools like repo_list_files and repo_grep.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context: it works on previously cloned repos and instructs to use the handle from repo_clone. It doesn't explicitly name alternatives, but the usage context is unambiguous.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
v0.1.0kubesearch_get_releasekubesearch_grep_valueskubesearch_search_imageskubesearch_search_releaseskubesearch_statusrepo_cleanuprepo_clonerepo_greprepo_list_filesrepo_read_fileScored across 10 tools
Each tool has a clearly distinct purpose: the kubesearch_* tools search the index, while the repo_* tools operate on cloned repositories. Even the two grep tools are well-separated by scope (index-wide vs. within a clone).
The naming follows a consistent verb_noun pattern with a clear prefix distinction: kubesearch_search_releases, kubesearch_get_release, repo_clone, repo_list_files, etc. The two prefixes intentionally separate functional domains, and all names are descriptive and predictable.
10 tools is a well-scoped count for the server's purpose, covering both search and repository exploration without redundancy. Each tool earns its place in the set.
The tool surface provides end-to-end coverage: searching for releases and images, retrieving release details, grepping values, checking cache status, and drilling into real repositories with clone/list/read/grep/cleanup. No obvious dead ends or missing operations for the domain.
Code intelligence for LLMs. Analyze, search, and retrieve code from any public git repository.
Read and write KukGit repositories, files, issues and pull requests from an AI assistant.
Give your AI assistant access to real Helm chart data. No more hallucinated values.yaml files.
Fail-closed policy guardrails for AI agents running kubectl, terraform, helm, and argocd.
