Argo工作流的MCP
MCP(模型上下文协议)服务器 Argo工作流程,使像Claude这样的人工智能助手能够通过标准化工具与Argo工作流进行交互。
此服务器基于Argo v4,并希望您的信号量、互斥量和时间表是多个列表。
在v3.5或更早版本中使用它可能意味着你需要就此与它争论。
什么是MCP?
这 模型上下文协议 是一个开放标准,允许人工智能助手与外部工具和数据源安全交互。该服务器将Argo工作流操作作为MCP工具公开,使AI助手能够:
- 提交和管理工作流
- 监控工作流状态和日志
- 管理工作流模板和cron工作流
- 查询和操作工作流档案
- 可视化工作流程图
特性
连接模式
- 直接Kubernetes API -使用kubeconfig直接连接到Kubernetes API。最适合本地开发或未部署Argo Server时。
- Argo服务器 --通过Argo Server连接以获得全功能支持,包括工作流归档操作、大型工作流支持和集中身份验证。
运输方式
- 标准 (默认)--适用于Claude Desktop和Cursor等本地客户端
- HTTP/SSE --用于远程客户端连接
支持的MCP客户端
- 克劳德桌面版
- 光标
- 克劳德代码 (克劳德的CLI)
- 任何兼容MCP的客户端
安装
下载预构建的二进制文件
从下载最新版本 GitHub 发布 页面。```bash
Linux (amd64)
curl -Lo mcp-for-argo-workflows https://github.com/pipekit/mcp-for-argo-workflows/releases/latest/download/mcp-for-argo-workflows-linux-amd64
chmod +x mcp-for-argo-workflows
sudo mv mcp-for-argo-workflows /usr/local/bin/
macOS (Apple Silicon)
curl -Lo mcp-for-argo-workflows https://github.com/pipekit/mcp-for-argo-workflows/releases/latest/download/mcp-for-argo-workflows-darwin-arm64
chmod +x mcp-for-argo-workflows
sudo mv mcp-for-argo-workflows /usr/local/bin/
macOS (Intel)
curl -Lo mcp-for-argo-workflows https://github.com/pipekit/mcp-for-argo-workflows/releases/latest/download/mcp-for-argo-workflows-darwin-amd64
chmod +x mcp-for-argo-workflows
sudo mv mcp-for-argo-workflows /usr/local/bin/
### 从源代码构建```bash
# Clone the repository
git clone https://github.com/pipekit/mcp-for-argo-workflows.git
cd mcp-for-argo-workflows
# Build the binary
make build
# The binary is created at bin/mcp-for-argo-workflows
码头工人```bash
docker pull ghcr.io/pipekit/mcp-for-argo-workflows:latest
Run with kubeconfig mounted
docker run -v ~/.kube:/root/.kube ghcr.io/pipekit/mcp-for-argo-workflows:latest
## 快速开始
### Claude桌面配置
将以下内容添加到您的Claude Desktop配置中(`~/Library/Application Support/Claude/claude_desktop_config.json` 在macOS或 `%APPDATA%\Claude\claude_desktop_config.json` 在Windows上):
**使用Direct Kubernetes API:**```json
{
"mcpServers": {
"argo-workflows": {
"command": "/usr/local/bin/mcp-for-argo-workflows",
"args": ["--namespace", "argo"]
}
}
}
使用Argo服务器:```json
{
"mcpServers": {
"argo-workflows": {
"command": "/usr/local/bin/mcp-for-argo-workflows",
"args": [
"--argo-server", "argo-server.argo:2746",
"--namespace", "argo"
],
"env": {
"ARGO_TOKEN": "Bearer eyJhbGciOiJSUzI1NiIs..."
}
}
}
}
### Claude代码配置
添加到您的克劳德代码设置(`~/.claude.json`):```json
{
"mcpServers": {
"argo-workflows": {
"command": "/usr/local/bin/mcp-for-argo-workflows",
"args": ["--namespace", "argo"]
}
}
}
光标配置
添加到光标设置:```json
{
"mcp.servers": {
"argo-workflows": {
"command": "/usr/local/bin/mcp-for-argo-workflows",
"args": ["--namespace", "argo"]
}
}
}
## 配置
### 配置选项
|环境变量|CLI标志|默认值|描述|
|---------------------|----------|---------|-------------|
| `MCP_TRANSPORT` | `--transport` | `stdio` |MCP传输模式: `stdio` 或 `http` |
| `MCP_HTTP_ADDR` | `--http-addr` | `:8080` |HTTP侦听地址(使用HTTP传输时)|
| `ARGO_SERVER` | `--argo-server` || Argo服务器主机:端口(对于直接K8s API省略)|
| `ARGO_TOKEN` | `--argo-token` ||Argo服务器身份验证的承载令牌|
| `ARGO_NAMESPACE` | `--namespace` | `default` |操作的默认命名空间|
| `KUBECONFIG` | `--kubeconfig` || kubeconfig文件的路径。多个文件可以用操作系统路径列表分隔符连接(`:` 在Unix上, `;` 在Windows上),符合kubectl约定|
| | `--context` ||要使用的Kubeconfig上下文。默认为kubeconfig `current-context` (仅限CLI)|
| `ARGO_SECURE` | `--argo-secure` | `true` |连接Argo服务器时使用TLS|
| `ARGO_INSECURE_SKIP_VERIFY` | `--argo-insecure-skip-verify` | `false` |跳过TLS证书验证|
| `ARGO_HTTP1` | `--argo-http1` | `false` |Argo服务器使用HTTP/1.1(REST)而不是gRPC。当服务器位于不支持gRPC的反向代理(例如nginx ingress)后面时需要|
**优先:** CLI标志>环境变量>默认值
### 示例配置
#### 本地开发(直接K8s API)```bash
# Uses your current kubeconfig context
mcp-for-argo-workflows --namespace argo
# Pin to a specific context (e.g. when KUBECONFIG merges several clusters)
mcp-for-argo-workflows --context eks-internal --namespace argo
# Multiple kubeconfig files, kubectl-style (':' on Unix)
KUBECONFIG=~/.kube/configs/eks.yaml:~/.kube/configs/k3d.yaml \
mcp-for-argo-workflows --context k3d-pipeline-mono --namespace argo
启动时会记录活动上下文和集群,以便您确认
在运行任何工具之前,先将服务器绑定到集群。
具有令牌认证的Argo服务器```bash
export ARGO_TOKEN="Bearer $(kubectl get secret -n argo argo-server-token -o jsonpath='{.data.token}' | base64 -d)"
mcp-for-argo-workflows \
--argo-server argo-server.argo:2746 \
--namespace argo
#### 远程访问的HTTP传输```bash
mcp-for-argo-workflows \
--transport http \
--http-addr :8080 \
--namespace argo
端口转发Argo服务器```bash
In one terminal
kubectl port-forward svc/argo-server -n argo 2746:2746
In another terminal
mcp-for-argo-workflows \
--argo-server localhost:2746 \
--argo-insecure-skip-verify \
--namespace argo
#### 反向代理后面的Argo服务器(例如nginx入口)```bash
mcp-for-argo-workflows \
--argo-server argo-workflows.example.com:443 \
--argo-http1 \
--argo-token "Bearer dummy" \
--namespace argo
可用工具
工作流生命周期
| 工具 | 说明 |
|---|---|
submit_workflow |
从YAML清单提交工作流 |
list_workflows |
列出工作流,可选择按状态/标签进行筛选 |
get_workflow |
获取详细的工作流信息 |
delete_workflow |
删除工作流 |
logs_workflow |
获取工作流或pod日志 |
watch_workflow |
流式工作流状态更新 |
wait_workflow |
等待工作流完成 |
lint_workflow |
提交前验证工作流清单 |
流程控制
| 工具 | 说明 |
|---|---|
suspend_workflow |
暂停正在运行的工作流 |
resume_workflow |
恢复暂停的工作流 |
stop_workflow |
停止工作流(允许退出处理程序运行) |
terminate_workflow |
立即终止工作流 |
retry_workflow |
从失败的步骤重试失败的工作流 |
resubmit_workflow |
从现有工作流创建新工作流 |
可视化
| 工具 | 说明 |
|---|---|
render_workflow_graph |
将工作流渲染为Mermaid、ASCII、DOT或SVG图 |
render_manifest_graph |
无需提交即可从YAML预览工作流结构 |
工作流模板
| 工具 | 说明 |
|---|---|
list_workflow_templates |
在命名空间中列出工作流模板 |
get_workflow_template |
获取工作流模板详细信息 |
create_workflow_template |
从YAML创建工作流模板 |
delete_workflow_template |
删除工作流模板 |
集群工作流模板
| 工具 | 说明 |
|---|---|
list_cluster_workflow_templates |
列出集群范围的工作流模板 |
get_cluster_workflow_template |
获取集群工作流模板详细信息 |
create_cluster_workflow_template |
从YAML创建集群工作流模板 |
delete_cluster_workflow_template |
删除群集工作流模板 |
CronWorkflows
| 工具 | 说明 |
|---|---|
list_cron_workflows |
列出cron工作流(计划工作流) |
get_cron_workflow |
获取cron工作流详细信息,包括时间表 |
create_cron_workflow |
从YAML创建cron工作流 |
delete_cron_workflow |
删除cron工作流 |
suspend_cron_workflow |
暂停cron工作流的计划 |
resume_cron_workflow |
恢复暂停的cron工作流 |
存档工作流(仅Argo服务器)
| 工具 | 说明 |
|---|---|
delete_archived_workflow |
从存档中删除工作流 |
resubmit_archived_workflow |
重新提交已存档的工作流 |
retry_archived_workflow |
重试失败的存档工作流 |
> 注: 当通过Argo服务器连接时, list_workflows 和 get_workflow 自动包括存档的工作流。不需要为存档的工作流提供单独的列表/获取工具。
节点操作
| 工具 | 说明 |
|---|---|
get_workflow_node |
获取工作流中特定节点的详细信息 |
用法示例
提交工作流
询问Claude:“将此工作流提交到argo命名空间”```yaml
apiVersion: argoproj.io/v1alpha1
kind: Workflow
metadata:
generateName: hello-world-
spec:
entrypoint: main
templates:
- name: main
container:
image: alpine:latest
command: [echo, "Hello World"]
### 监控工作流
- “列出argo命名空间中所有正在运行的工作流”
- “显示工作流hello-world-bac123的日志”
- “等待工作流hello-world-bc123完成”
- “工作流hello-world-bac123的状态如何?”
### 流程控制
- “暂停工作流数据管道xyz”
- “恢复暂停的工作流”
- “从失败的工作流重试失败的工作流”
- “优雅地停止工作流”
### 可视化工作流程
- “显示工作流复合体dag-123的图表”
- “将此工作流YAML渲染为美人鱼图”
- “给我一个工作流程图的ASCII可视化”
### 管理模板
- “列出argo命名空间中的所有工作流模板”
- “根据此YAML创建工作流模板”
- “删除名为数据管道的工作流模板”
### 使用CronWorkflows
- “显示所有计划的工作流”
- “暂停每日备份cron工作流”
- “cron工作流夜间清理的时间表是什么?”
## 故障排除
### 连接问题
**“创建Argo客户端失败”**
- 验证你的kubeconfig是否有效: `kubectl cluster-info`
- 检查RBAC权限: `kubectl auth can-i list workflows`
- 对于Argo服务器,验证服务器是否可访问: `curl https://argo-server.argo:2746/api/v1/info`
**工作流存在时“未找到工作流”**
- 检查命名空间:工作流是命名空间范围的
- 验证标签选择器是否过滤
### 身份验证问题
**Argo服务器出现“未经授权”错误**
- 确保 `ARGO_TOKEN` 设置正确
- 代币可能会过期;必要时再生
- 检查令牌是否具有所需的RBAC权限
**令牌生成:**```bash
# For service account token
kubectl create token argo-server -n argo
# Or from a secret
kubectl get secret -n argo argo-server-token -o jsonpath='{.data.token}' | base64 -d
TLS问题
“证书验证失败”
对于具有自签名证书的开发/测试:```bash
mcp-for-argo-workflows --argo-insecure-skip-verify
> **警告:** 不要用 `--argo-insecure-skip-verify` 在生产中。
### 反向代理/gRPC问题
**nginx入口后出现“意外的内容类型text/html”或gRPC错误**
当您的Argo服务器位于不支持gRPC的反向代理后面时(例如,没有gRPC后端协议的nginx入口),请使用HTTP/1.1模式:```bash
mcp-for-argo-workflows --argo-http1 --argo-server argo.example.com:443
调试日志记录
服务器记录到stderr。有关详细输出,请检查MCP客户端日志中的stderr或手动运行:```bash
mcp-for-argo-workflows --namespace argo 2>&1 | tee debug.log
## 贡献
欢迎投稿!请随时提交问题和拉取请求。
### 开发设置```bash
# Clone the repository
git clone https://github.com/pipekit/mcp-for-argo-workflows.git
cd mcp-for-argo-workflows
# Install development tools
make tools
# Run all checks (fmt, vet, lint, test)
make all
# Run only tests
make test
# Run only linter
make lint
# Run E2E tests (requires Docker for testcontainers)
make test-e2e
代码风格
- 遵循标准Go惯例
- 使用
gofmt和goimports用于格式化 - 通过
golangci-lint检查
拉取请求流程
- 分叉存储库
- 创建要素分支
- 通过测试进行更改
- 确保
make all通过 - 提交拉取请求
许可证
Apache许可证2.0-请参阅 许可证 了解详情。
