SpEKS CLI & MCP Toolchain
in productionThe developer-facing half of the SpEKS platform: inspektor scaffolds and validates a project before it can fail, speks drives the spec API and GitOps sync, and an MCP server exposes the same validated operations to AI agents — so an assistant can scaffold and check an app without being handed a shell.
problem
A platform is only self-service if the path onto it is obvious. The control plane and GitOps registry worked, but getting an app ready still meant knowing which files the platform expected, how the spec was shaped, and which of a dozen conventions applied — knowledge that lived with one engineer. Every misconfigured project surfaced as a failed deploy rather than a failed check, which is the most expensive place to find out. The gap was not capability, it was the distance between a developer opening an editor and a valid project existing.
approach
Move every failure as early as possible and give the same operations to whoever — or whatever — is doing the work.
- Scaffold instead of document. inspektor init generates a working project for six app types — streamlit, shiny, nextjs, python with FastAPI/Flask/Django subtypes, dash, and gradio — with the spec, container, and CI wiring already correct. Conventions are executable rather than written down, and inspektor reset regenerates that boilerplate from current templates so projects do not drift as the platform moves.
- Fail at the keyboard, not in the cluster. validate, lint, and doctor form a ladder from project structure to deep spec checking to environment diagnosis. lint can auto-fix. Running them is a second-long local loop, so the class of error that used to reach a deploy now cannot leave the working directory.
- One client for the whole spec lifecycle. The speks CLI covers specs, versions, instances, and bindings through to approval workflows, batch operations, GitOps sync, and security scanning — with layered config from file, SPEKS_* environment, and flags, so the same commands work on a laptop and in CI without a wrapper script.
- The agent gets tools, not a shell. inspektor mcp serve exposes six typed tools over the Model Context Protocol — validate, lint, doctor, init, reset, get_version. An assistant in Claude Code can scaffold and check a project through the same validated paths a human uses, with no arbitrary execution and nothing new to keep in sync, because the MCP surface and the CLI are one binary.
outcome
Starting a new scientific app is a single command that produces something the platform already accepts, and the feedback that used to arrive from a failed pipeline now arrives before the first commit. Because the agent-facing surface is the same binary as the human-facing one, AI assistance became a way onto the platform rather than another thing to review — the tools stayed the single source of what "valid" means.
$ inspektor validate✓ .speks/spec.yaml: Found✓ Dockerfile: Found✓ docker-compose.yml: Found✓ .gitlab-ci.yml: Found✓ Makefile: Found✓ .speks/variables.env: Found✓ .speks/environments/staging.yaml: Found✓ .speks/environments/production.yaml: Found✓ app_name: Present✓ version: Present✓ team: Present✓ display_name: Present✗ description: Missing or empty → Add description field to configuration✓ app_name pattern: Valid format✓ container.image: Present✓ container.resources.memory_request: Valid format✓ container.resources.memory_limit: Valid format✓ container.resources.cpu_request: Valid format✓ container.resources.cpu_limit: Valid format✓ container.env.APP_VERSION: Present✓ network.port: Valid port✓ access.groups: Present✓ Multi-stage build: Multi-stage build detected✓ Non-root user: Non-root USER instruction found✓ HEALTHCHECK: HEALTHCHECK instruction found✓ EXPOSE: EXPOSE instruction found✓ Platform specification: Platform specified in FROM✓ app_name format: Valid format✓ Prefix convention: Valid Streamlit prefix: st-✓ Directory name: Matches app_name✓ Port convention: Matches Streamlit default: 8501✓ SpEKS template include: SpEKS CI template included✓ SPEKS_APP_NAME variable: SPEKS_APP_NAME defined⚠ Pipeline structure: No standard pipeline jobs or stages detected → Add standard stages (validate, build, deploy) or extend SpEKS jobs (.speks-deploy-staging, .build-image)✓ Environment override production.yaml: production.yaml is a valid ShinyProxySpec override✓ Environment override staging.yaml[0m: staging.yaml is a valid ShinyProxySpec override✗ Label: acme.io/label-a: Value is the placeholder "FIXME" → inspektor label set 'acme.io/label-a=<value>'✗ Label: acme.io/label-b: Value is the placeholder "FIXME" → inspektor label set 'acme.io/label-b=<value>'✓ Label: acme.io/label-c: Present⚠ Label: acme.io/label-d: Recommended label-d label is missing → inspektor label set 'acme.io/label-d=keyword1,keyword2'Score: 35/40 checks passedValidation complete: 35/40 checks passedError: validation incomplete$ inspektor doctor✓ Docker installed: Docker is installed✓ Docker running: Docker daemon is running✓ Port consistency: All files use the same port: 8501✓ Best practices: No common anti-patterns detected✓ Resource limits: Resource limits are reasonable✓ Template version: References SpEKS CI templates✓ CI_TEMPLATE_REF default: CI_TEMPLATE_REF has default value: latestScore: 7/7 checks passedDiagnostics complete: 7/7 checks passed$ inspektor init --type streamlit --name st-flow-qc✓ scaffold .speks/spec.yaml · Dockerfile · CI$ inspektor validate✓ structure entrypoint · port · healthcheck✓ lint spec.yaml OK · 0 errors✓ doctor docker reachable · base image current$ speks spec create -f .speks/spec.yaml --team team-bioinfo✓ created st-flow-qc v1.0.0◍ sync gitops · registry reconciling✓ live https://apps.mbbg.internal/st-flow-qc{
"mcpServers": {
"inspektor": {
"command": "inspektor",
"args": ["mcp", "serve"]
}
}
}screens
- inspektor validate output
- MCP tools in Claude Code