kubespec.dev turns Kubernetes API specs into a searchable field tree and an MCP endpoint

A field-level index rather than a documentation mirror

Kubernetes Spec Explorer is a site that presents the Kubernetes API as something you can navigate rather than read. The live version is at kubespec.dev, and the first bullet in the README summarises the approach: a tree view of every field of all Kubernetes resources, with search.

That distinction matters. The official Kubernetes reference documentation is organised by API group and kind, and within a kind by field, which means the answer to what a specific field means is several clicks away and the same field name can appear in a dozen kinds with different meanings. A tree view of every field with search inverts that, so the question becomes a search box rather than a navigation exercise.

The second feature is a changelog of each kind and each project version, since Kubernetes v1.10. That is a different kind of question from what a field means: it answers when a field appeared, when it was deprecated, and what a given version's schema looked like. A project that supports several Kubernetes versions, or that needs to know when an API graduated to stable, needs exactly this.

The third is examples you can copy and modify, with links to official docs and other resources. The examples are stored as individual files per kind, which is the mechanism behind the whole site, and the third bullet is what makes the tool usable in practice rather than merely informative.

The primary language is TypeScript, the licence is MIT, and the project is hosted on Vercel, with a vercel.json in the repository root and Next.js in the package manifest.

The index is generated output, and that shapes everything

The repository layout makes the architecture clear. There is an index directory, a lib directory, an app directory, a scripts directory and a public directory, with next.config.ts and the Next.js config files at the root. The index is the substance.

The build script is build-index, which the package.json defines as node scripts/build-index.ts. That script is what fetches the API specifications and turns them into the tree data the site serves.

The critical detail for anyone reading the code is that the index is a checked-in artefact. The README's update instructions are explicit about it: you run the build script with a GitHub token, and then you create a pull request. The same applies to adding a new project of CRD specs, where you add an entry at the end of the list of projects in lib/projects.ts, run the build for that slug, and open a pull request.

So the data flow is: a spec source is resolved, the build script writes the index, a human reviews the diff and merges it, and the site serves the merged index. That review step is a feature, not an inconvenience, because an index that is regenerated on every deploy is an index that can change without anyone looking at it, and a wrong field name in a spec source would otherwise propagate silently.

Downloads are cached on disk in .cache/specs/, and the README says to delete that directory to force a re-download. That cache is what makes a full reindex affordable, and it is also why a stale index is possible if a spec source changes without the cache being cleared.

The versions and kinds in the site are therefore a snapshot with a human in the loop, and that is the honest characterisation of what you are querying.

Adding examples and links next to the changelog

The contribution guide for content is the most specific part of the README, and it explains how the site stays useful without a central content team.

Examples and links live next to the generated index of each project, with the same path structure as the changelog. A link file is at index/<project>/links/<apiVersion>/<Kind>.json, and the example given is index/kubernetes/links/apps/v1/Deployment.json, whose content is a JSON array of objects with a name and an href.

An example is a file at index/<project>/examples/<apiVersion>/<Kind>/<n>-<name>.md, one file per example, ordered by file name, with a title and a description in the frontmatter and the manifest in a yaml code block. The ordering rule is the sort key, and the numbered prefix is how you control it.

The reason this design is worth copying is the symmetry. Because the examples and links sit at the same paths as the generated changelog, there is exactly one place to look for a kind, and the browse view, the changelog view and the example view cannot drift apart. A site that keeps examples in a separate content directory with its own routing has to reconcile two structures; this one does not.

The frontmatter convention is also deliberate. A title and a description per example means the example can appear in a listing with a human-readable summary rather than only as a file to open, and the yaml block inside the markdown keeps the manifest copy-pasteable without any transformation.

An MCP server so agents can look up specs instead of guessing

The feature that distinguishes this project from a documentation mirror is the MCP server at https://kubespec.dev/mcp, with its own documentation page at kubespec.dev/docs/mcp.

The problem it addresses is concrete. A language model asked to write a Kubernetes manifest will produce a field name it half-remembers, and if the model has no way to check, the manifest fails at apply time with a validation error, or worse, applies with a silently different meaning. A coding agent that can query the spec tree gets the real field name, its real type and its real version history before it writes the YAML.

The fact that the README lists this as a headline feature rather than a footnote tells you where the maintainer thinks the value is. The site is useful to a human, but the MCP endpoint is what makes it useful to the agents that are writing the manifests.

The design point is that this is the same data, not a separate one. The tree the browser renders and the tree the agent queries come from the same generated index, so an agent that looks up a field gets the same answer a human would. That is a meaningful property, because a divergence between a documentation site and its API version is the classic way these things rot.

What the README does not document is the transport details, the authentication model, the rate limits, or which parts of the index are exposed to the MCP server. If you are going to point a fleet of agents at that endpoint, those are the questions to ask, and the MCP documentation page is where to look.

Running the site locally and rebuilding the index

The development setup is the standard pnpm flow. The README tells a contributor to clone the repo, run pnpm install, and then run pnpm dev, and the scripts section of the package manifest shows what those commands map to:

  "scripts": {
    "dev": "next dev",
    "build": "next build",
    "start": "next start",
    "lint": "eslint",
    "build-index": "node scripts/build-index.ts"
  },

So the local site is a standard Next.js development server with hot reloading, and the build and start scripts are the usual next build and next start. The repository uses pnpm, with a pnpm-lock.yaml and a pnpm-workspace.yaml at the root, and the packageManager field pins pnpm at 12.8.1.

The stack is current. Next is at 16.4.0, React and React DOM at 19.3.0, Tailwind at 4.3.3 with the PostCSS plugin, TypeScript at 7.0.2, and yaml at 2.9.1 as a runtime dependency, which is the parser used to read the manifests in the example files.

Rebuilding the index is a separate command from the site itself, and it needs a GitHub token because the build resolves versions and spec sources from GitHub. The README gives the command in the form GH_TOKEN=$(gh auth token) pnpm build-index, with a slug argument to update one specific project and no argument to update all of them, and a --full flag that re-resolves versions already present in the index, which is the option you want when a spec source has changed in place rather than when a new version has appeared.

The cache note completes the picture. Downloaded spec files are cached in .cache/specs/, and deleting that directory forces a re-download, so if you are chasing a stale result the cache is the first thing to clear.

Where kubespec.dev is the wrong tool

There are three clear boundaries, and the most important one is about what the data actually represents.

The index describes published API versions, not your cluster. It is a catalogue of the schemas that exist in Kubernetes releases and in the CRD projects it supports. It cannot tell you which fields a particular apiserver accepts, whether a CRD in your cluster has drifted from the upstream definition, or what the effective schema of an aggregated API server is. For that, you interrogate the cluster, with the API discovery endpoints or with kubectl explain against a live server, and those give you the truth for your environment rather than the published reference.

The second is the CRD coverage boundary. The README says the site supports popular CRDs and names Argo CD, cert-manager, Cilium, Flux, Istio, Karpenter and KEDA, and many more. For anything outside the indexed projects, the site is silent. And even inside those projects, the CRD schema depends on the version you installed, so a project indexed at one version does not describe your installation at another. A team running internal CRDs that are not in the list gets no benefit from this tool.

The third is that the site is a reference, not a workflow tool. It does not validate your manifests, it does not generate them, and it does not diff two versions of your own values. The examples are there to be copied and modified by hand, and the links are there to send you to the authoritative documentation. If your need is a linter, a policy engine or a schema validator in your CI pipeline, this is the wrong layer.

The alternative approach is the local one, and the difference in approach is instructive. Running kubectl explain against your own apiserver gives the truth about your cluster with no index to maintain and no staleness, at the cost of needing cluster access and of being slower to browse. The site gives a browsable, versioned, searchable catalogue that works with no cluster at all, which is why it pairs with an MCP server: an agent writing a manifest often has no cluster credentials and needs a reference, and the site is that reference with a lookup interface.

Editorial conclusion

Adopt kubespec.dev if you need a fast answer to what a field in a Kubernetes API actually is, how it changed between versions, or which CRD kinds exist, and if you want your coding agent to ask the same question over MCP rather than guessing. Do not adopt it as a source of truth for what your cluster accepts, since it documents published API versions rather than interrogating a live server, and do not expect it to replace kubectl explain or the official reference, which it links to. Verify first that the versions and kinds you care about are in the index, that the CRD projects you use are among the supported list including Argo CD, cert-manager, Cilium, Flux, Istio, Karpenter and KEDA, and that you understand the index is generated output, since updating it needs a GitHub token and a pull request.

Frequently asked questions

Official sources

1. aptakube/kubespec.dev on GitHub
2. Issues
3. License: MIT
4. Project website
5. README