一个用于KubeAid管理的Kubernetes集群的MCP服务器。 将其接入Claude Code、Claude Desktop、Cursor或任何兼容MCP的客户端， 即可提出诸如*"哪些应用不同步？"、"为什么kube-prometheus降级了？"或"同步cert-manager应用"*等问题——模型通过调用此服务器的工具来回答，这些工具通过您自己的kubeconfig凭据与您的集群通信。
基于官方@modelcontextprotocol/sdk和@kubernetes/client-node用TypeScript构建。
作者： Deep Poharkar
KubeAid以GitOps方式运行集群：每个应用都是从你的kubeaid-config仓库生成的ArgoCD Application，并且默认禁用自动同步——Git与集群之间的漂移是正常的，需要等待有意的同步。通用的Kubernetes助手不理解这种工作流。此服务器理解：
ArgoCD Application CR是一等公民：同步状态、健康状态、失败条件和漂移资源只需一次工具调用即可获取。
同步被建模为KubeAid中明确的"立即部署"决策——通过选择加入的标志进行门控，支持dry_run，并且绝不允许在你标记为受保护的上下文中执行。
捆绑的提示词编码了KubeAid的操作习惯：同步前先审查漂移，在kubeaid-config仓库中修复问题，而不是手动编辑集群。
Related MCP server: mcp-kubernetes-server
读取工具——始终注册：
工具 | 功能 |
| 服务器可以定位的Kubeconfig上下文，带有默认和写保护标志。 |
| 每个KubeAid管理的ArgoCD应用，包含同步状态、健康状态、修订版本和自动同步标志。支持 |
| 深入查看一个应用：来源、错误条件、漂移/不健康资源、上次同步结果、部署历史。 |
| 命名空间及其状态和年龄。 |
| 节点及其就绪状态、角色、kubelet版本、内部IP。 |
| 具有kubectl风格派生状态（CrashLoopBackOff等）、就绪计数、重启次数、节点、年龄的Pod。 |
| 每个容器的状态和上次崩溃详情、条件，以及Pod的近期事件。 |
| 尾部容器日志； |
| 部署及其就绪/最新/可用计数。 |
| 近期事件，可选仅警告，按命名空间或集群范围。 |
| 按apiVersion/kind/name描述任何资源——包括CRD，如 |
写入工具——仅在KUBEAID_MCP_ALLOW_WRITES=true时注册：
工具 | 说明 |
| 触发ArgoCD同步（KubeAid的"部署"操作）。支持 |
| 设置部署的副本数。 |
| 滚动重启部署/有状态集/守护进程集。 |
| 删除卡住的Pod，以便其控制器替换它。 |
每个工具都接受可选的context参数，以便从单个服务器进程定位kubeconfig中的任何集群。
提示词在客户端中作为斜杠命令/菜单项出现，并使用上述工具引导模型完成工作流：
提示词 | 工作流 |
| 对降级/不同步的应用进行根因分析：条件 → 资源 → Pod日志 → 建议。 |
| 列出所有漂移的应用，评估每个待处理同步的风险，然后询问后再同步任何内容。 |
| 扫描节点、应用、Pod和警告事件；按严重程度报告发现。 |
需要Node.js 20+。
git clone <your-repo-url> kubeaid-mcp
cd kubeaid-mcp
npm install
npm run buildclaude mcp add kubeaid -- node "$(pwd)/dist/index.js"默认只读。要在保持生产环境不可触碰的同时启用写入：
claude mcp add kubeaid \
-e KUBEAID_MCP_ALLOW_WRITES=true \
-e KUBEAID_MCP_PROTECTED_CONTEXTS=prod-cluster-1,prod-cluster-2 \
-- node "$(pwd)/dist/index.js"启用设置 → 开发者 → 本地MCP服务器，然后添加到该页面打开的配置文件中：
{
"mcpServers": {
"kubeaid": {
"command": "node",
"args": ["/absolute/path/to/kubeaid-mcp/dist/index.js"],
"env": {
"KUBEAID_MCP_ALLOW_WRITES": "true",
"KUBEAID_MCP_PROTECTED_CONTEXTS": "prod-cluster-1"
}
}
}
}之后完全退出并重新打开应用。
所有配置都是环境变量，在启动时读取一次：
变量 | 默认值 | 含义 |
| client-node默认查找（ | Kubeconfig路径。 |
| 跟随当前上下文实时变化 | 固定默认上下文。未设置时， |
|
| 保存ArgoCD的 |
|
| 是否注册变更工具。 |
| 无 | 逗号分隔的上下文，即使启用了写入，也拒绝所有变更调用。 |
三个独立的层：
能力门控 — 禁用写入（默认）时，变更工具永远不会注册，因此模型甚至无法看到它们。
受保护的上下文 — 每个变更处理器都会根据KUBEAID_MCP_PROTECTED_CONTEXTS重新检查目标上下文，并拒绝受保护的上下文，无论模型要求什么。
客户端确认 — 工具带有MCP readOnlyHint/destructiveHint注释，因此行为良好的客户端会在风险调用前提示你。
服务器本身不持有任何凭据；它只能执行你的kubeconfig身份通过RBAC已被授权执行的操作。
npm run typecheck # strict TS, no emit
npm run build # compile to dist/
npm run smoke # spawn the server, MCP handshake, list tools + prompts
KUBEAID_MCP_ALLOW_WRITES=true npm run smoke # verify write tools register冒烟测试不需要集群——它通过stdio驱动原始JSON-RPC协议。
check_chart_updates：将部署的图表版本与上游KubeAid argocd-helm-charts目录进行比较。
密封秘密辅助工具：列出SealedSecret状态，标记失败的解封。
Prometheus/Alertmanager工具：从KubeAid附带的kube-prometheus堆栈中显示触发的警报。
MIT © 2026 Deep Poharkar
Full detail for one ArgoCD Application: Git/Helm sources, sync and health status, error conditions, the resources that are OutOfSync or unhealthy, last sync operation result and recent deploy history. Use this to diagnose why an app is Degraded or a sync failed.
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | Application name (as shown by list_argocd_apps). | |
| context | No | Kubeconfig context to target; omit for the server's default context. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds meaningful behavioral detail by enumerating what the tool returns: Git/Helm sources, sync/health status, error conditions, OutOfSync or unhealthy resources, last sync result, and deploy history. This goes beyond the annotations and helps set expectations for a diagnostic read operation.
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 with no wasted words. The first sentence front-loads the tool's purpose and enumerates its key outputs, while the second provides a concrete diagnostic use case. It is dense but easy to parse.
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 no output schema, the description compensates by listing the main content categories and a clear use case. It does not detail the exact return format or pagination behavior, but for a diagnostic read tool with two well-documented parameters, the provided information is sufficiently complete for an agent to select and invoke it 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?
Schema description coverage is 100%, and both parameters have clear descriptions in the schema: 'name' references list_argocd_apps, and 'context' explains default behavior. The tool description adds no additional parameter semantics, but the schema already carries the full burden, so a baseline score of 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 opens with 'Full detail for one ArgoCD Application' which clearly identifies the verb (provide/detail), the resource (ArgoCD Application), and singular scope. It distinguishes itself from siblings like list_argocd_apps by emphasizing 'one' application and from generic describe_resource by specifying ArgoCD-specific content.
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 explicitly states when to use the tool: 'Use this to diagnose why an app is Degraded or a sync failed.' This provides clear contextual guidance, though it does not explicitly mention when not to use it or name alternative tools such as describe_resource or get_events.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Deep-dive one pod: per-container state (waiting/termination reasons, last crash exit code), conditions and the pod's recent events.
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | Pod name. | |
| context | No | Kubeconfig context to target; omit for the server's default context. | |
| namespace | Yes | Namespace of the pod. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, so the read-only nature is covered. The description adds specific details about return content (per-container state, termination reasons, crash exit codes, conditions, events) which goes beyond annotations, providing useful behavioral transparency about what to expect from the tool.
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 a single, compact sentence that immediately states the purpose and lists the specific details returned. No filler or redundancy. Perfectly front-loaded.
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 read-only describe tool, the description covers what it returns (per-container state, reasons, exit codes, conditions, events) and the scope (one pod). Given the annotations already indicate read-only, this is sufficient. Slight gap: it doesn't mention the namespace/name parameters explicitly, but schema covers that.
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%, so all three parameters (namespace, name) are fully described in the schema. The description does not add extra parameter semantics beyond what the schema already provides, so it stays at the baseline of 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 performs a 'deep-dive' on a single pod, specifying per-container state, waiting/termination reasons, last crash exit code, conditions, and recent events. This is specific and distinguishes it from siblings like list_pods (which lists) and get_events (which retrieves events).
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 usage for in-depth pod inspection, but does not explicitly state when to use it over alternatives like describe_resource or get_events. No exclusion criteria are given, so the agent must infer when this is the right tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Fetch any Kubernetes resource (including CRDs like SealedSecret or Certificate) by apiVersion, kind and name. Returns the full object.
| Name | Required | Description | Default |
|---|---|---|---|
| kind | Yes | Resource kind, e.g. "Service", "SealedSecret". | |
| name | Yes | Resource name. | |
| context | No | Kubeconfig context to target; omit for the server's default context. | |
| namespace | No | Namespace; omit for cluster-scoped resources. | |
| api_version | No | apiVersion, e.g. "v1", "apps/v1", "bitnami.com/v1alpha1" (default "v1"). |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, so the description is not required to restate safety. It adds the behavioral detail that it 'Returns the full object', which is useful. The description does not introduce any contradictions with annotations, and it provides enough context beyond the structured fields (e.g., that it works with CRDs).
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 a single, front-loaded sentence that starts with the core purpose ('Fetch any Kubernetes resource') and then adds the essential qualifying detail about CRDs and required identifiers. There is zero wasted wording; every phrase 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?
Given the tool's general scope, the description is complete for an agent to understand its usage: it fetches any resource, returns the full object, and the schema provides all parameter details. It might have mentioned that it supports both namespaced and cluster-scoped resources, but the schema already clarifies this via the optional namespace field. The absence of an output schema is mitigated by the statement that it returns the full object, so no additional return-value documentation is needed.
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%, so the baseline is 3. The description adds extra meaning by noting that it works for CRDs and providing examples (SealedSecret, Certificate), which clarifies the expected kind values. It also highlights the interplay of apiVersion, kind, and name, reinforcing the required parameters beyond the schema's individual descriptions.
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 action ('Fetch'), the resource ('any Kubernetes resource'), and the key identifying parameters (apiVersion, kind, name). It explicitly includes CRDs like SealedSecret or Certificate, which distinguishes it from sibling tools that target specific resource types (e.g., describe_pod, describe_argocd_app). The purpose is unambiguous and stands out from the siblings.
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 it can be used for any resource, but it does not explicitly mention when to prefer this over the more specific describe tools (like describe_pod) or when not to use it. No alternatives or exclusions are stated, leaving the usage guidance somewhat implied rather than explicit.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Recent cluster events, newest last. Filter to one namespace and/or Warning-type events only.
| Name | Required | Description | Default |
|---|---|---|---|
| context | No | Kubeconfig context to target; omit for the server's default context. | |
| namespace | No | Namespace to inspect; omit for all namespaces. | |
| only_warnings | No | Return only Warning-type events. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, so the safety profile is covered. The description adds behavioral details like 'newest last' and the filtering capability, providing useful context beyond the schema. It does not contradict 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 concise sentences, front-loaded with the core purpose and then the filtering option. No wasted words, every part adds value.
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 tool is simple (read-only list with optional filters) and annotations cover safety. The description adequately explains purpose and filters; it might mention the output format (a list) but that is implied. It is complete enough for reliable invocation.
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%, so all parameters are documented in the schema. The description reinforces namespace and only_warnings usage but adds no new syntax or format details beyond what the schema provides. A 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 it retrieves recent cluster events, newest last, which is specific and distinct from sibling tools like list_pods or get_pod_logs. It mentions the resource (cluster events) and ordering, making it 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 provides clear guidance on filtering ('Filter to one namespace and/or Warning-type events only'), implying when to use it for scoped event lookup. It lacks explicit exclusions or alternatives, but the sibling context and the filter note make the use case clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Tail a container's logs. Set previous=true to read the prior (crashed) instance's logs — essential for CrashLoopBackOff.
| Name | Required | Description | Default |
|---|---|---|---|
| name | Yes | Pod name. | |
| lines | No | How many lines to tail (default 100). | |
| context | No | Kubeconfig context to target; omit for the server's default context. | |
| previous | No | Read logs from the previous, crashed container instance. | |
| container | No | Container name; required only for multi-container pods. | |
| namespace | Yes | Namespace of the pod. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already confirm read-only and non-destructive behavior; the description adds valuable context about the previous flag and its role in crash debugging. It does not cover streaming/pagination, but the annotations lower the bar and the added context is meaningful.
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, both necessary and directly informative. The first states the core action; the second gives a high-value usage tip without wasting 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?
With no output schema, the description and schema collectively provide enough for a logs tool: tailing behavior, line count, namespace/container targeting, and crash-instance option. Minor gap: no mention of output format, but that is generally implied and not critical for log retrieval.
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 100% of parameters, so the baseline is 3, but the description enriches the 'previous' parameter by explaining its purpose and relevance to CrashLoopBackOff, which goes beyond the schema's bare definition. No other parameters need extra explanation given the schema quality.
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?
Description uses specific verb 'Tail' and names the resource 'container's logs', with a clear distinction from sibling tools like describe_pod or get_events. It also adds meaningful scope by mentioning 'previous (crashed) instance's logs', making the tool's purpose 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 provides a clear context for using the previous flag ('essential for CrashLoopBackOff') and implies the tool is for reading logs. It does not explicitly compare to alternatives, but the log-specific context and sibling names make the usage clear enough.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List the ArgoCD Applications KubeAid manages in this cluster, with sync status (Synced/OutOfSync), health (Healthy/Degraded/...), deployed revision and whether auto-sync is on. KubeAid disables auto-sync by default, so OutOfSync apps are usually awaiting a deliberate sync. Start here for any GitOps question.
| Name | Required | Description | Default |
|---|---|---|---|
| context | No | Kubeconfig context to target; omit for the server's default context. | |
| project | No | Filter by ArgoCD project name. | |
| only_problems | No | Return only apps that are OutOfSync or not Healthy. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare this read-only and non-destructive (readOnlyHint=true, destructiveHint=false). The description adds valuable behavioral context: KubeAid disables auto-sync by default, so OutOfSync apps are typically awaiting a deliberate sync. It also discloses the return fields, which is useful given no output schema.
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 with no fluff. The first sentence fronts the action and resource, the second adds context, and the third gives usage direction. Every sentence 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 list tool with optional filters and no output schema, the description is complete enough. It lists the return fields (sync status, health, deployed revision, auto-sync), provides domain context, and gives usage guidance. Minor gaps like pagination are not critical for this tool.
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 covers all three parameters with descriptions (context, project, only_problems), so the description does not need to repeat them. It adds no extra parameter-level meaning beyond what the schema provides, so a baseline score of 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 uses a specific verb 'List' with the resource 'ArgoCD Applications' and scope 'KubeAid manages in this cluster', clearly distinguishing it from sibling tools like describe_argocd_app. It also lists the exact fields returned, making the tool's purpose 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?
Provides a clear directive 'Start here for any GitOps question', indicating this is the entry point for such queries. It also explains the auto-sync behavior to help interpret results, though it does not explicitly name alternatives like describe_argocd_app for app-specific details.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List the kubeconfig contexts (clusters) this server can target, including which one is the default and which are write-protected.
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint true and destructiveHint false, and the description does not contradict them. It adds useful behavioral context by specifying that output includes default and write-protected status and that the context list is limited to what this server can target.
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?
Single sentence, front-loaded with the verb and object, and every clause adds meaningful detail about scope and output contents. 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?
This is a simple, parameterless read-only listing tool. The description conveys what is listed, the scope limitation, and key output features (default and write-protected), which is sufficient for an agent to select and invoke it 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 is empty, so there are no parameters requiring clarification. With zero parameters, the description does not need to compensate for schema gaps, matching the baseline for parameter-less tools.
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?
Description uses a specific verb ('List') with a clear object ('kubeconfig contexts') and adds scope ('this server can target'). It is clearly distinct from the sibling node/pod/deployment tools.
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 clear context for when to use the tool: to see available target contexts, the default, and write-protected ones. It does not explicitly name alternatives or exclusions, but the sibling list makes its unique purpose evident.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List deployments with ready/up-to-date/available replica counts and age.
| Name | Required | Description | Default |
|---|---|---|---|
| context | No | Kubeconfig context to target; omit for the server's default context. | |
| namespace | No | Namespace to inspect; omit for all namespaces. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations mark readOnlyHint=true and destructiveHint=false, aligning with the non-mutating list operation. The description adds output details (replica counts, age) but no hidden behavior.
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, tightly packed with the operation's scope and returned fields; no filler.
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?
A read-only list tool with clear parameter coverage in the schema and adequate output guidance in prose. No output schema exists, but the listed fields are simple and the behavior is likely clear.
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 JSON Schema already describes both parameters (context, namespace) with 100% coverage. The description adds no new meaning beyond what the schema fields already say.
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?
Uses a specific verb ('List') and resource ('deployments'), with the scope of returned data (state, replica counts, age) stated. It does not explicitly distinguish itself from sibling list tools, but the resource type is named.
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?
Implies a read-only listing operation by context, but does not state when to choose it over alternatives or specify any exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List namespaces in the cluster with their status and age.
| Name | Required | Description | Default |
|---|---|---|---|
| context | No | Kubeconfig context to target; omit for the server's default context. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already mark the operation as read-only and non-destructive, which covers side effects. The description adds output details (status and age) but doesn't mention pagination, filters, or authentication caveats. Given the annotations carry the safety signal, a 3 for neutral value is appropriate.
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 a single, lean sentence that states the purpose and output aspects without any filler. It is front-loaded and entirely relevant, earning a top score.
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?
This is a simple read-only list operation. With annotations covering side effects and the schema documenting the only parameter, the description supplies enough context (status, age) and does not require deeper detail. The tool is complete for its purpose.
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 has full (100%) coverage for the single 'context' parameter with an explicit description, so the description does not need to repeat it. It adds no new parameter meaning beyond the schema, so baseline 3 applies.
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 lists namespaces in the cluster and includes status and age, which is specific and distinguishes it from sibling list tools (list_nodes, list_pods, etc.) that target other resource types.
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 establishes when to use the tool (when you need a list of namespaces) and given the resource in the name, no alternative is needed. However, it does not explicitly mention when not to use it or direct to siblings for other resources, but the context is unambiguous enough for a 4.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List cluster nodes with Ready status, roles, kubelet version and internal IP.
| Name | Required | Description | Default |
|---|---|---|---|
| context | No | Kubeconfig context to target; omit for the server's default context. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true. The description adds output detail (Ready, role, version, IP) but no additional behavioral boundaries beyond what annotations provide.
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?
One sentence, clear and directly informative; no redundancy with schema or annotations.
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 the tool's narrow scope (list nodes), the schema covers the only parameter; the description gives the returned fields, and the siblings provide related operations. Lacks an output schema, but optional for such outputs.
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 already provides full description of 'context' (the kubeconfig context; omit for server default). Description reinforces target semantics in readable terms, though plain schema would likely be enough.
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 specific verb 'list' with a specific resource ('cluster nodes') and includes the key result fields (Ready, role, kubelet version, internal IP), distinguishing it from node/pod listing tools.
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?
Clear context is given (list nodes), but no explicit when-to-use guidance or named alternatives; sibling names 'list_pods' and 'get_nodes' imply adjacent functions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
List pods with derived status (CrashLoopBackOff, ImagePullBackOff, Terminating, ...), ready count, restarts, node and age.
| Name | Required | Description | Default |
|---|---|---|---|
| context | No | Kubeconfig context to target; omit for the server's default context. | |
| namespace | No | Namespace to inspect; omit for all namespaces. |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Annotations already declare readOnlyHint=true and destructiveHint=false, and the description reinforces this read-only, safe behavior without contradiction. It adds value by disclosing the exact output fields (derived status, ready count, restarts, node, age), which helps the agent understand what information will be returned. This goes beyond the structured annotations by providing the output contract.
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 a single, well-structured sentence that begins with the primary action ('List pods') and then lists the key output fields in a scannable format. No words are wasted, and the most important information (what it does) is front-loaded. Excellent balance of brevity and information density.
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 straightforward read-only list operation, the description covers purpose, output fields, and the critical namespace scoping behavior (including the default). It does not mention pagination or limits, which might be a minor gap for large clusters, but the annotations and schema fill in the safety and parameter details. The description is complete for the tool's apparent simplicity.
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 covers 100% of parameters (context and namespace) with clear descriptions, providing a solid baseline. The description enriches the namespace parameter by explicitly stating that omitting it means 'all namespaces', which is not explicit in the schema. This extra semantic detail is valuable for correct usage.
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 it lists pods with derived status (CrashLoopBackOff, Terminating), ready count, restarts, node, and age. This specific verb+resource combo and the detailed output fields distinguish it from sibling tools like list_deployments or describe_pod. It immediately conveys the exact scope and differentiation.
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 usage by mentioning the namespace parameter behavior ('omit for all namespaces'), but does not explicitly state when to use this tool versus siblings like describe_pod or list_deployments. There is no explicit 'use this when' or alternative naming. The guidance is present but implicit, requiring the agent to infer the tool's position among its siblings.
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.0describe_argocd_appdescribe_poddescribe_resourceget_eventsget_pod_logslist_argocd_appslist_contextslist_deploymentslist_namespaceslist_nodeslist_podsScored across 11 tools
Each tool targets a distinct resource/action - nodes, events, ArgoCD apps, pods, deployments, generic resource fetch, contexts, namespaces - with no overlapping purposes. The list/describe pairs for pods and ArgoCD apps are clearly separated by summary vs. detail, and describe_resource is explicitly generic.
Naming follows a consistent verb_noun pattern: list_* for summary listings, describe_* for detailed views, and get_pod_logs as a specific action. Even though get_events uses 'get' instead of 'list', the pattern is predictable and readable, so deviation is minor and not confusing.
With 11 tools, the set is well-scoped for a Kubernetes diagnostic server. Each tool addresses a common troubleshooting need (node health, pod issues, logs, ArgoCD sync, deployments) without excess or missing core operations.
The surface covers the main diagnostic workflows: listing and describing nodes, pods, deployments, and ArgoCD apps; retrieving events and logs; fetching any resource via describe_resource; and listing contexts/namespaces. For a read-only troubleshooting tool, this is comprehensive with no critical dead ends.
MCP server for AI agents to plan, verify, and deploy Cloudflare-native apps.
The Google GKE MCP server is a managed Model Context Protocol server that provides AI applications with tools to manage Google Kubernetes Engine (GKE) clusters and Kubernetes resources. It exposes a structured, discoverable interface that allows AI agents to interact with GKE and Kubernetes APIs, enabling them to inspect cluster configurations, retrieve Kubernetes resource YAMLs, monitor operations like cluster upgrades, diagnose issues, and optimize costs—all without needing to parse text output or use complex kubectl commands.
MCP server for your apps' tools and custom tools, plus hosted AI agents and approval-gated workflows
MCP server for Argo RPG Platform — connects AI assistants to campaign data via OAuth2
