Skip to content

Commit 9d6fc14

Browse files
njaypnjayp
committed
H4HIP: add mcp server
Signed-off-by: nick powell <[email protected]>
1 parent fcdf969 commit 9d6fc14

File tree

2 files changed

+222
-0
lines changed

2 files changed

+222
-0
lines changed

‎hips/README.md‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -35,3 +35,4 @@ restricted markdown format and can be found in the
3535
- [hip-0024: Improve the Helm Documentation](hip-0024.md)
3636
- [hip-0025: Better Support for Resource Creation Sequencing](hip-0025.md)
3737
- [hip:0026: H4HIP: Wasm plugin system](hip-0026.md)
38+
- [hip-0028: Add MCP Server to Helm CLI](hip-0028.md)

‎hips/hip-0028.md‎

Lines changed: 221 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,221 @@
1+
---
2+
hip: "0028"
3+
title: "Add MCP Server to Helm CLI"
4+
authors: [ "nick powell <[email protected]>" ]
5+
created: "2025-09-03"
6+
type: "feature"
7+
status: "draft"
8+
---
9+
10+
## Abstract
11+
12+
This HIP adds MCP (Model Context Protocol) support to Helm, letting AI assistants like Claude safely run read-only Helm commands. It's completely opt-in, only exposes read operations, and requires minimal implementation effort. The integration automatically converts Helm's Cobra commands into MCP tools, with command flags and arguments becoming the tool's input schema.
13+
14+
## Motivation
15+
16+
Developers are increasingly using AI assistants in their workflows. Currently, if an AI assistant needs to help with Helm operations, users must manually copy and paste terminal output. With MCP support, AI assistants can directly query Helm releases, check status, and explore charts without manual intervention.
17+
18+
## Specification
19+
20+
This HIP adds `helm mcp` commands that enable AI assistants to run safe, read-only Helm operations. Each allowed Helm command becomes an MCP tool, with the command's flags (like `--namespace`, `--all-namespaces`, `--output`) and arguments becoming the tool's input parameters that the AI assistant can use. Convenience commands, like `helm mcp claude enable`, provide a fast and easy opt-in user experience.
21+
22+
### MCP Command Tree
23+
24+
The integration adds the following command hierarchy under `helm mcp`:
25+
26+
```
27+
helm mcp
28+
├── start # Start MCP server on stdio
29+
├── tools # Export available MCP tools as JSON
30+
├── claude
31+
│ ├── enable # Enable Helm MCP in Claude Desktop
32+
│ ├── disable # Disable Helm MCP in Claude Desktop
33+
│ └── list # List MCP configurations in Claude Desktop
34+
└── vscode
35+
├── enable # Enable Helm MCP in VS Code
36+
├── disable # Disable Helm MCP in VS Code
37+
└── list # List MCP configurations in VS Code
38+
```
39+
40+
### Available MCP Tools
41+
42+
Once enabled, AI assistants will have access to the following Helm operations as MCP tools. This list is subject to change with the command tree. Each Helm command becomes an MCP tool, with its flags and arguments automatically converted to the tool's input schema:
43+
44+
| Tool Name | Helm Command | Description |
45+
|-----------|--------------|-------------|
46+
| `helm_list` | `helm list` | List releases in current namespace |
47+
| `helm_status` | `helm status` | Show the status of a named release |
48+
| `helm_history` | `helm history` | Fetch release history |
49+
| `helm_get_all` | `helm get all` | Download all information for a named release |
50+
| `helm_get_hooks` | `helm get hooks` | Download hooks for a named release |
51+
| `helm_get_manifest` | `helm get manifest` | Download the manifest for a named release |
52+
| `helm_get_metadata` | `helm get metadata` | Download metadata for a named release |
53+
| `helm_get_notes` | `helm get notes` | Download notes for a named release |
54+
| `helm_get_values` | `helm get values` | Download values for a named release |
55+
| `helm_show_all` | `helm show all` | Show all information of a chart |
56+
| `helm_show_chart` | `helm show chart` | Show the chart's metadata |
57+
| `helm_show_crds` | `helm show crds` | Show the chart's CRDs |
58+
| `helm_show_readme` | `helm show readme` | Show the chart's README |
59+
| `helm_show_values` | `helm show values` | Show the chart's default values |
60+
61+
The complete tool definitions with their schemas can be exported by running `helm mcp tools`.
62+
63+
## Rationale
64+
65+
The proposed design leverages Helm's existing Cobra command structure to automatically generate MCP tools. Each Cobra command becomes an MCP tool, with the command's flags and arguments becoming the tool's input schema - meaning Helm's existing CLI structure directly maps to the MCP interface without additional configuration. This approach minimizes code changes and maintenance burden while providing a natural mapping between CLI commands and MCP tools.
66+
67+
## Backwards compatibility
68+
69+
Helm will continue to function exactly as before for users who do not enable MCP support. The MCP feature is entirely opt-in and does not modify any existing Helm commands or behaviors.
70+
71+
## How to teach this
72+
73+
- Provide a quick start guide showing how to enable MCP in Claude Desktop or VS Code
74+
- Include examples demonstrating AI-assisted Helm workflows
75+
76+
### Example Usage
77+
78+
```bash
79+
# Enable for Claude Desktop
80+
helm mcp claude enable
81+
```
82+
```bash
83+
# Enable for VS Code
84+
helm mcp vscode enable
85+
```
86+
87+
Users can then ask their AI assistant questions like "What Helm releases are deployed?" or "Show me the nginx values" and the assistant will execute the appropriate commands and provide explanations.
88+
89+
## Reference Implementation
90+
91+
[PR #31221](https://github.com/helm/helm/pull/31221)
92+
93+
The implementation uses [Ophis](https://github.com/njayp/ophis), a Go library that automatically converts Cobra CLI commands into MCP servers. Each allowed Cobra command becomes an MCP tool, with the command's flags and arguments automatically becoming the tool's input parameters. The integration is added to `pkg/cmd/root.go`:
94+
95+
```go
96+
// mcp server commands
97+
ophis.Command(&ophis.Config{
98+
Filters: []ophis.Filter{
99+
ophis.AllowFilter([]string{
100+
"helm list",
101+
"helm status",
102+
"helm get",
103+
"helm history",
104+
"helm show",
105+
"helm search",
106+
}),
107+
},
108+
}),
109+
```
110+
111+
### Under the Hood
112+
113+
Ophis works by automatically analyzing a Cobra CLI's command structure and converting each allowed command into an MCP tool with a corresponding JSON schema. Here's how the transformation process works:
114+
115+
#### 1. Command Discovery and Filtering
116+
117+
When Ophis starts, it recursively traverses the entire Cobra command tree starting from the root command. For each command it encounters, it applies a series of filters to determine whether that command should be exposed as an MCP tool.
118+
119+
The default filters exclude:
120+
- Commands without a `Run` or `PreRun` function (non-executable commands)
121+
- Hidden commands (`cmd.Hidden = true`)
122+
- Built-in utility commands like `mcp`, `help`, and `completion`
123+
124+
For Helm, the integration uses an `AllowFilter` to explicitly whitelist only safe, read-only operations:
125+
126+
```go
127+
ophis.AllowFilter([]string{
128+
"helm list",
129+
"helm status",
130+
"helm get",
131+
"helm history",
132+
"helm show",
133+
"helm search",
134+
})
135+
```
136+
137+
#### 2. Tool Name Generation
138+
139+
Each allowed command is assigned a unique tool name by flattening the command path with underscores. For example:
140+
- `helm list` becomes `helm_list`
141+
- `helm get values` becomes `helm_get_values`
142+
- `helm search repo` becomes `helm_search_repo`
143+
144+
This naming scheme ensures each MCP tool has a unique, predictable identifier that maps directly back to the original CLI command.
145+
146+
#### 3. Schema Generation
147+
148+
Ophis automatically generates a JSON schema for each tool by analyzing the command's flags and arguments:
149+
150+
**Input Schema Structure:**
151+
```json
152+
{
153+
"type": "object",
154+
"properties": {
155+
"flags": {
156+
"type": "object",
157+
"properties": {
158+
// Individual flag schemas generated from cobra.Command.Flags()
159+
}
160+
},
161+
"args": {
162+
"type": "array",
163+
"items": {"type": "string"},
164+
"description": "Positional command line arguments\nUsage pattern: <extracted from cmd.Use>"
165+
}
166+
}
167+
}
168+
```
169+
170+
**Flag Schema Generation:**
171+
Ophis inspects each command's flag set and automatically generates appropriate JSON schema types:
172+
173+
- `bool` flags → `"type": "boolean"`
174+
- `int`/`uint` flags → `"type": "integer"`
175+
- `float` flags → `"type": "number"`
176+
- `string` flags → `"type": "string"`
177+
- `stringSlice` flags → `"type": "array", "items": {"type": "string"}`
178+
- `duration` flags → `"type": "string"` with regex pattern validation
179+
- `ip`/`ipNet` flags → `"type": "string"` with IP address patterns
180+
181+
Each flag's usage description becomes the schema's description field, and hidden flags are automatically excluded.
182+
183+
**Output Schema:**
184+
All tools share a consistent output schema:
185+
```json
186+
{
187+
"type": "object",
188+
"properties": {
189+
"stdout": {"type": "string"},
190+
"stderr": {"type": "string"},
191+
"exitCode": {"type": "integer"}
192+
}
193+
}
194+
```
195+
196+
#### 4. Command Execution
197+
198+
When an AI assistant invokes an MCP tool, Ophis handles the execution through a structured process:
199+
200+
1. **Argument Construction**: The MCP tool input is converted back to CLI arguments:
201+
- Tool name `helm_get_manifest` → command path `["get", "manifest"]`
202+
- Boolean flags: `{"all-namespaces": true}` → `["--all-namespaces"]`
203+
- Value flags: `{"output": "json"}` → `["--output", "json"]`
204+
- Array flags: `{"selector": ["app=web", "env=prod"]}` → `["--selector", "app=web", "--selector", "env=prod"]`
205+
- Positional args are appended directly
206+
207+
2. **Subprocess Execution**: Ophis executes the original CLI binary as a subprocess:
208+
```go
209+
cmd := exec.CommandContext(ctx, executablePath, args...)
210+
```
211+
212+
3. **Output Capture**: All stdout, stderr, and exit code information is captured and returned in the structured output format.
213+
214+
#### 5. Configuration Management
215+
216+
Ophis provides convenience commands for integrating with AI assistants:
217+
218+
- **`helm mcp claude enable`**: Automatically updates Claude Desktop's configuration file (`~/.config/claude-desktop/config.json`) to include the Helm MCP server
219+
- **`helm mcp vscode enable`**: Updates VS Code's settings to register the MCP server for Copilot integration
220+
- **`helm mcp tools`**: Exports all available tools and their schemas to `mcp-tools.json` for inspection
221+

0 commit comments

Comments
 (0)