Skip to main content
Glama
MyoungSoo7

k8s-traps

by MyoungSoo7
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Local

k8s-traps

Kubernetes manifest traps that pass the linters and still break production, packaged as a CLI and an MCP server so AI agents can check YAML before it ships.

Generic scanners (Kubescape, kube-linter, Trivy, Checkov) are good at baseline hygiene: resource limits, privileged containers, image tags. Use them. This project covers a different gap: configuration that is valid, lints clean, and fails silently. Each trap here comes from a real incident on a small production K3s cluster.

ID

Trap

Default severity

T01

Service-link env vars (<SVC>_PORT=tcp://…) collide with the app's own settings

high

T02

ServiceMonitor selects nothing (pod labels instead of Service labels, or an unnamed port)

high

T03

Namespace has workloads but no NetworkPolicy

medium

T04

ConfigMap/Secret mounted with subPath never updates

low

T05

Two hostnames route to the same backend (a dead route serves another app with 200)

medium

T06

Replicas only prefer to spread across nodes

medium

T07

Secret value written in plain text (the value is never echoed back)

high

Full explanations, including the incident behind each trap: docs/traps.md.

Scope and limits

  • Offline and read-only. It parses the YAML you give it and never contacts a cluster.

  • Judged from the input only. For example, T03 cannot see a NetworkPolicy that lives in another repo. Feed it a whole helm template render when you can.

  • Heuristics. T01's same-name rule and T07's name patterns can raise false positives. Each finding says what it is based on.

Related MCP server: k8s-aiops

CLI

pip install k8s-traps
helm template my-chart | k8s-traps            # stdin
k8s-traps manifests/ --fail-on medium         # files or directories; exit 1 at/above severity
k8s-traps deploy.yaml --json --trap T01 --trap T02
k8s-traps --list

MCP server

The stdio server exposes three read-only tools:

  • audit_manifests(manifests: list[str], traps?: list[str])

  • list_traps()

  • explain_trap(trap_id)

Claude Code:

claude mcp add k8s-traps -- k8s-traps-mcp

Generic MCP client config:

{ "mcpServers": { "k8s-traps": { "command": "k8s-traps-mcp" } } }

Without installing first (this is what the MCP Registry entry runs):

{ "mcpServers": { "k8s-traps": { "command": "uvx", "args": ["k8s-traps", "--mcp"] } } }

Development

python -m venv .venv && .venv/bin/pip install -e '.[test]'
.venv/bin/pytest
.venv/bin/python scripts/gen_docs.py   # after editing the catalog in traps.py

Every trap has at least one test that must flag it and one that must stay clean. New traps are welcome; please describe the real failure each one comes from.

한국어 요약

린터는 통과하는데 운영에서 조용히 깨지는 쿠버네티스 매니페스트 함정을 잡는 CLI와 MCP 서버입니다. AI 에이전트가 YAML을 배포하기 전에 이 서버에 물어볼 수 있습니다.

  • 함정 7개는 모두 실제 K3s 클러스터에서 겪은 장애에서 나왔습니다. 목록은 위 표에 있습니다.

  • 리소스 한도나 권한 같은 기본 점검은 Kubescape나 kube-linter 몫입니다. 이 도구는 그 도구들과 같이 쓰도록 만들었습니다.

  • 입력으로 받은 YAML만 오프라인으로 봅니다. 클러스터에는 접속하지 않습니다.

  • 비밀값을 찾아도 그 값은 출력에 절대 싣지 않습니다.

License

MIT

Available Tools

3 tools
audit_manifestsA
Read-onlyIdempotent

Check Kubernetes YAML for known production traps.

manifests: one or more YAML strings (multi-document --- is fine; helm template output works). traps: optional subset of trap ids such as ["T01", "T02"]; default runs all. Returns findings sorted by severity. Secret values are never echoed back.

ParametersJSON Schema
NameRequiredDescriptionDefault
trapsNo
manifestsYes

TDQS

A4.5/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, so the safety profile is covered. The description adds valuable behavioral details: results are sorted by severity, and secret values are never echoed back. These go beyond the annotations and reassure the agent about output handling and security.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is compact and well-organized: a one-line purpose, followed by parameter explanations, then output behavior. Every sentence adds useful information, and the most important scoping detail (trap subset selection) is clearly presented. There is no filler or repetition of schema fields.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a two-parameter read-only tool, the description covers input format, optional filtering, default behavior, output ordering, and a security guarantee. Without an output schema, slightly more detail about the shape of findings could help, but the sibling tools list_traps and explain_trap fill the surrounding context, and nothing essential is missing for correct invocation.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so the description carries full responsibility for parameter meaning. It clearly explains that manifests is one or more YAML strings and explicitly supports multi-document and helm template formats. It also clarifies that traps is an optional subset of trap IDs, with an example and the default-all behavior. Both parameters are meaningfully enriched.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific verb and resource: 'Check Kubernetes YAML for known production traps.' This clearly distinguishes the tool from siblings list_traps and explain_trap, which list and explain traps rather than auditing manifests. The function's scope, checking production-relevant pitfalls, is immediately understandable.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description gives practical usage context: manifests can be multi-document YAML and helm template output works, and traps can be restricted to a subset or left to run all. It does not explicitly state when to prefer this tool over list_traps or explain_trap, but the verb and resource make the intended use clear enough without requiring exclusions.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

explain_trapA
Read-onlyIdempotent

Explain one trap: what goes wrong, the incident it came from, and how to fix it.

ParametersJSON Schema
NameRequiredDescriptionDefault
trap_idYes

TDQS

A3.9/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint, idempotentHint, and destructiveHint, so the safety profile is covered. The description adds the expected content areas (problem, incident, fix) but does not disclose failure modes, invalid ID behavior, or any data-source caveats; the description is consistent with 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.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is one concise sentence with no filler. It front-loads the action and immediately lists the three key content components, making it easy for an agent to scan and act on.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a simple, read-only, single-parameter tool, the description covers the essential outcome well. It lacks an explicit mention of how to obtain a valid trap_id or what happens for unknown IDs, but these are minor gaps given the simple scope and helpful sibling names.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters2/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The schema provides only a bare 'trap_id' string with 0% description coverage, so the description carries the burden of explaining the parameter. It implies that trap_id selects one trap but does not specify where valid IDs come from, what format they take, or any relationship to list_traps.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description uses a specific verb ('Explain') and a precise resource ('one trap'), and it specifies the content delivered: what goes wrong, the originating incident, and the fix. This clearly distinguishes it from siblings like list_traps, which enumerates traps, and audit_manifests, which concerns manifests.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The phrase 'one trap' makes clear this is a single-item lookup rather than a listing or audit operation, which provides usable context against the sibling tools. However, it does not explicitly state when to prefer this over list_traps or audit_manifests, so the guidance is implied rather than fully articulated.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

list_trapsA
Read-onlyIdempotent

List every trap this server checks, with id, title and default severity.

ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

A4.5/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint=true, idempotentHint=true, and destructiveHint=false, so no side-effect warnings are needed. The description adds scoping ('every trap this server checks') and output-field details, which is useful context beyond the annotations; there is no contradiction.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

A single front-loaded sentence with no filler. The verb, resource scope, and key output fields are all stated immediately and efficiently.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a zero-parameter, read-only list tool with an output schema, the description is complete: it states exactly what is returned and the annotations cover the safety profile. No prerequisites, caveats, or hidden behaviors are missing.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The input schema has zero parameters, so the baseline is 4. The description therefore does not need to explain parameter meaning and instead clarifies what payload fields the caller can expect in the result.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description uses a specific verb ('List') with a clear resource ('every trap this server checks') and the returned fields (id, title, default severity). This distinguishes it from siblings like explain_trap, which would focus on a single trap, and audit_manifests, which targets manifests rather than traps.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The intended use case is clear: call this when you need to enumerate all traps the server checks. It does not explicitly name alternatives or say when not to use it, but the scope is obvious and no exclusions are needed for a parameterless list.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

  1. 3 tool updatesv0.1.0
    • First observedaudit_manifests
    • First observedexplain_trap
    • First observedlist_traps
Deploy Server
One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

TDQS

A4.4/5.0

Scored across 3 tools

Disambiguation5/5

Each tool serves a clearly distinct purpose: list_traps enumerates available checks, audit_manifests executes the checks, and explain_trap provides detailed breakdowns. There is no overlap or ambiguity between them.

Naming Consistency5/5

All tool names follow a consistent verb_noun pattern (list_traps, audit_manifests, explain_trap). The naming is predictable and immediately conveys the action and target.

Tool Count5/5

With only 3 tools, the server is tightly scoped but each tool is essential: discovery, execution, and explanation. This is an appropriate minimal set for a specialized trap-checking utility.

Completeness5/5

The domain is well-covered: users can enumerate available traps, run the audit, and understand any trap's rationale and fix. No obvious gaps remain for the server's stated purpose.

Maintenance

ActivityMaintained
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers