ArgoCD MCP服务器

使用Rust构建的ArgoCD健壮、优化的模型上下文协议（MCP）服务器。该服务器使AI助手能够通过标准化的MCP工具与ArgoCD API进行交互。

特性

优化响应格式：响应经过优化，以最大限度地减少上下文窗口的使用，同时提供基本信息
稳健的错误处理：全面的错误处理，包含详细的错误消息和优雅的降级
完整的测试覆盖范围：60多项与模拟ArgoCD API服务器的集成测试
标准运输：使用stdio传输与MCP客户端无缝集成
类型安全：采用Rust构建，确保类型安全和性能
版本兼容性：支持ArgoCD v1.0+，并记录了高级功能的要求

ArgoCD版本兼容性

功能	最低版本	状态
核心工具（列表、获取、树、日志、清单、元数据）	ArgoCD v1.0+	✅ 完全支持
list_resource_events	ArgoCD v1.0+	✅ 完全支持
sync_application	ArgoCD v1.0+	✅ 完全支持
回滚_应用程序	ArgoCD v1.0+	✅ 完全支持
server_side_diff	ArgoCD v2.5+	⚠️ 版本特定
get_application_sync_windows	ArgoCD v2.6+	⚠️ 版本特定

备注：如果您的ArgoCD实例不支持特定版本的功能，则将返回404错误。这是预期的行为，并记录在每个工具的描述中。

工具

`list_applications`

列出具有可选过滤器的ArgoCD应用程序，返回详细信息。

论据：

name （可选）：按应用程序名称筛选
projects （可选）：按项目名称筛选（字符串数组）
selector （可选）：用于筛选应用程序的标签选择器（例如，“env=prod”）
repo （可选）：按存储库URL筛选
app_namespace （可选）：按应用程序命名空间筛选

退货： 优化的应用程序摘要包括：

应用程序名称和命名空间
项目
存储库URL和目标修订
目标服务器和命名空间
同步和健康状态
自动同步配置

`list_application_names`

仅列出ArgoCD应用程序的名称。 高度优化，最大限度地减少上下文使用 -非常适合查找名称和自动纠正应用程序名称中的拼写错误。

论据：

projects （可选）：按项目名称筛选（字符串数组）
selector （可选）：用于筛选应用程序的标签选择器（例如，“env=prod”）
repo （可选）：按存储库URL筛选
app_namespace （可选）：按应用程序命名空间筛选

退货： 一个简单的字符串形式的应用程序名称列表。

使用案例：

获取所有应用程序名称的快速列表
验证应用程序是否存在
当用户键入的应用程序名称不正确时，自动纠正拼写错误
最小的上下文窗口使用率（比完整的应用程序详细信息小约95%）

`get_application`

按名称获取特定ArgoCD应用程序的详细信息。返回全面的应用程序详细信息，包括源存储库、目标集群、同步状态、运行状况和同步策略配置。

论据：

name （必填）：应用程序名称
app_namespace （可选）：应用程序的命名空间
project （可选）：项目标识符
refresh （可选）：刷新模式-“正常”或“硬”以强制从存储库刷新
resource_version （可选）：用于乐观并发的资源版本

退货： 优化的详细信息包括：

应用程序名称、命名空间和项目
创建时间戳和标签
源存储库详细信息（URL、路径/图表、目标修订版）
目标集群和命名空间
同步状态和修订
健康状态和消息
同步策略配置（自动同步、修剪、自愈设置）

使用案例：

获取特定应用程序的全面详细信息
检查应用程序的当前同步和运行状况
审查应用程序配置和来源
检查同步策略设置
从存储库强制刷新应用程序状态
使用详细的状态信息排除应用程序问题

输出示例：

Application: guestbook

Namespace: argocd
Project: default
Created: 2025-01-01T10:00:00Z

Source:
  Repository: https://github.com/argoproj/argocd-example-apps
  Path: guestbook
  Target Revision: HEAD

Destination:
  Server: https://kubernetes.default.svc
  Namespace: default

Status:
  Sync Status: Synced
  Sync Revision: abc123def456
  Health Status: Healthy
  Health Message: All resources are healthy

Sync Policy:
  Auto Sync: Enabled
  Auto Prune: true
  Self Heal: true

Labels:
  env: production
  team: platform

注：使用 refresh: "hard" 参数强制从存储库中完全刷新应用程序状态，这在需要最新信息时非常有用。

`server_side_diff`

使用模拟运行应用程序为ArgoCD应用程序执行服务器端差异计算。这将在dryrun模式下执行服务器端应用操作，并将预测状态与实时状态进行比较。

论据：

app_name （必填）：应用程序名称
app_namespace （可选）：应用程序的命名空间
project （可选）：项目标识符
target_manifests （可选）：用于比较的目标清单（YAML/JSON字符串数组）

退货： 优化的资源摘要显示：

资源名称、种类和命名空间
修改状态（布尔值表示是否存在差异）
修改资源的差异摘要
按修改/同步状态分组

使用案例：

检查应用程序是否存在配置偏差
同步前预览更改
验证准入控制器是否会接受更改
确定哪些特定资源存在差异
在不执行实际同步的情况下，将实时状态与目标状态进行比较

输出示例：

Server-Side Diff for application 'guestbook'
Total resources: 3, Modified: 1, In sync: 2

Modified Resources:
1. guestbook-ui (Deployment) in namespace 'default'
   Status: Resource has differences between live and target state

In Sync Resources:
1. guestbook-ui (Service) in namespace 'default'
2. redis-master (Deployment) in namespace 'default'

注：服务器端差异是一个测试版功能（自ArgoCD v2.10.0起可用）。通过在计算中引入Kubernetes准入控制器，它提供了更准确的差异结果。

`resource_tree`

获取ArgoCD应用程序的分层资源树。返回应用程序管理的所有Kubernetes资源的全面视图，包括它们的关系、健康状态和元数据。

论据：

application_name （必填）：应用程序名称
namespace （可选）：按资源命名空间筛选
name （可选）：按资源名称筛选
version （可选）：按资源版本筛选
group （可选）：按资源组筛选
kind （可选）：按资源类型筛选（例如“部署”、“服务”）
app_namespace （可选）：应用程序的命名空间
project （可选）：项目标识符

退货： 优化摘要包括：

资源总数
孤儿资源计数
按类型分组的资源（部署、服务、Pod等）
健康状况总结（健康、恶化、进展等）
包含详细信息的示例资源（最多10个）

使用案例：

可视化应用程序资源层次结构
检查所有资源的运行状况
识别不受应用程序管理的孤立资源
了解资源关系（父子关系）
按类型或命名空间筛选资源
解决部署问题
监控应用程序状态

输出示例：

Resource Tree for application 'guestbook'
Total resources: 5
Orphaned resources: 0

Resources by Kind:
  Deployment: 2
  Service: 2
  Pod: 1

Health Summary:
  Healthy: 4
  Progressing: 1

Sample Resources (showing up to 10):
1. guestbook-ui (Deployment) in namespace 'default' - Health: Healthy
   Images: gcr.io/heptio-images/ks-guestbook-demo:0.2
2. guestbook-ui (Service) in namespace 'default' - Health: Healthy - 1 parent(s)
3. redis-master (Deployment) in namespace 'default' - Health: Healthy
   Images: redis:6.2
4. redis-master (Service) in namespace 'default' - Health: Healthy - 1 parent(s)
5. guestbook-ui-7d87c5c5 (Pod) in namespace 'default' - Health: Progressing - 1 parent(s)

筛选器示例：

按类型筛选以仅查看部署：

{
  "application_name": "my-app",
  "kind": "Deployment"
}

按命名空间和类型筛选：

{
  "application_name": "my-app",
  "namespace": "production",
  "kind": "Service"
}

`list_resource_events`

列出ArgoCD应用程序或应用程序中特定资源的Kubernetes事件。返回全面的事件信息，包括类型（正常/警告）、原因、消息、时间戳和涉及的对象。提供对应用程序生命周期、部署和问题的见解。

论据：

application_name （必填）：应用程序名称
resource_namespace （可选）：按资源命名空间筛选
resource_name （可选）：按资源名称筛选
resource_uid （可选）：按资源UID筛选
app_namespace （可选）：应用程序的命名空间
project （可选）：项目标识符

退货： 优化摘要包括：

事件总数
按类型分组的事件（正常、警告）
按原因分组的事件
个人活动详情（最多显示20个最近的活动）
事件元数据：原因、消息、时间戳、涉及的对象、源组件

使用案例：

解决应用程序部署问题
监控应用程序生命周期事件
调查吊舱故障和调度问题
跟踪资源扩展和更新
审核配置更改
调试映像拉取错误或资源限制
随时间监控应用程序运行状况

输出示例：

Events for application 'guestbook'
Total events: 15

Events by Type:
  Normal: 10
  Warning: 5

Events by Reason:
  ScalingReplicaSet: 3
  Started: 4
  Pulled: 3
  FailedScheduling: 2
  BackOff: 3

Recent Events (showing up to 20):

1. [Normal] ScalingReplicaSet - Deployment/guestbook-ui
   Message: Scaled up replica set guestbook-ui-abc to 3
   Count: 5
   First: 2025-01-01T10:00:00Z | Last: 2025-01-01T10:05:00Z
   Source: deployment-controller

2. [Normal] Started - Pod/guestbook-ui-abc-12345
   Message: Started container guestbook
   First: 2025-01-01T10:10:00Z
   Source: kubelet

3. [Warning] FailedScheduling - Pod/guestbook-ui-abc-67890
   Message: 0/5 nodes are available: insufficient cpu
   Count: 10
   First: 2025-01-01T10:15:00Z | Last: 2025-01-01T10:20:00Z
   Source: default-scheduler

... and 12 more events (total: 15)

筛选器示例：

获取特定资源的所有事件：

{
  "application_name": "my-app",
  "resource_namespace": "production",
  "resource_name": "my-deployment"
}

按UID获取特定资源的事件：

{
  "application_name": "my-app",
  "resource_uid": "abc-123-def-456"
}

注：事件受Kubernetes的时间限制（通常保留1小时），并提供最新的故障排除活动。

`pod_logs`

通过智能错误/警告过滤和日志级别分析从ArgoCD应用程序中的Pod获取容器日志。对于部署故障排除、崩溃调查和监控应用程序行为至关重要。

论据：

application_name （必填）：应用程序名称
namespace （可选）：Pod命名空间
pod_name （可选）：Pod名称（如果没有提供，请使用kind和resource_name）
container （可选）：容器名称（默认为第一个容器）
since_seconds （可选）：显示N秒前以来的日志
tail_lines （可选）：从末尾开始的行数（默认值：100，以提高上下文效率）
previous （可选）：显示以前的容器日志（如果重新启动）
filter （可选）：服务器端文本过滤器
kind （可选）：资源类型（例如，“部署”、“状态集”）
group （可选）：资源组
resource_name （可选）：资源名称（pod_name的替代品）
app_namespace （可选）：应用程序命名空间
project （可选）：项目标识符
errors_only （可选）： 筛选器仅显示错误和潜在问题 （客户端，建议用于LLM上下文）

退货： 智能分析包括：

日志行总数
错误、警告和潜在问题计数
按级别分组的日志（致命、错误、警告、信息、调试）
带有时间戳和视觉指示器的单个日志条目
优化的有用提示

主要特点：

智能日志级别检测：从日志内容中自动检测致命、错误、警告、信息、调试级别
潜在问题检测：识别超出显式日志级别的问题（异常、超时、恐慌、崩溃、权限错误等）
错误筛选：使用 errors_only: true 仅显示错误和警告（保存LLM上下文）
上下文优化：默认尾部为100行，可防止上下文溢出
视觉指示器：用于快速识别问题的表情符号指示器(💀 致命的，❌ 错误，⚠️ 警告，ℹ️ 信息，🐛 调试）
NDJSON解析：处理ArgoCD的流式日志格式

使用案例：

排除吊舱碰撞和故障
调查部署问题
实时监控应用程序错误
调试连接和超时问题
查找应用程序故障的根本原因
分析日志模式和趋势

输出示例：

Pod Logs for application 'my-app'
Pod: my-app-7d87c5c5-abc12
Container: app
Tail Lines: 100

Total lines: 50

🔍 Filtered to show errors and potential issues only

📊 Log Analysis:
  ❌ Errors: 3
  ⚠️  Warnings: 2
  🔍 Potential Issues: 5

Logs by Level:
  ERROR: 3
  WARNING: 2

📝 Log Entries (showing 5):
────────────────────────────────────────────────────────────────────────────────
❌ [2025-01-01T10:15:30Z] ERROR:
   Failed to connect to database: connection timeout

⚠️  [2025-01-01T10:15:35Z] WARNING:
   Retrying connection (attempt 2/5)

❌ [2025-01-01T10:15:40Z] ERROR:
   Connection failed again: unable to resolve hostname

❌ [2025-01-01T10:15:45Z] ERROR:
   Max retries exceeded, giving up

⚠️  [2025-01-01T10:15:50Z] WARNING:
   Service degraded due to database unavailability
────────────────────────────────────────────────────────────────────────────────

💡 Tip: Increase 'tail_lines' to see more logs or use 'since_seconds' for time-based filtering

筛选器示例：

获取所有日志（未筛选）：

{
  "application_name": "my-app",
  "pod_name": "my-app-pod",
  "tail_lines": 100
}

仅获取错误和警告（建议用于故障排除）：

{
  "application_name": "my-app",
  "pod_name": "my-app-pod",
  "errors_only": true
}

从特定容器获取日志：

{
  "application_name": "my-app",
  "pod_name": "my-app-pod",
  "container": "sidecar",
  "tail_lines": 50
}

获取5分钟前以来的日志：

{
  "application_name": "my-app",
  "pod_name": "my-app-pod",
  "since_seconds": 300
}

获取部署日志（自动选择pod）：

{
  "application_name": "my-app",
  "kind": "Deployment",
  "resource_name": "my-deployment",
  "errors_only": true
}

检测到的问题模式： 该工具使用以下关键字自动检测潜在问题：

错误级别：致命、严重、错误、错误
警告级别：警告，警告
异常：异常、恐慌、崩溃
失败：失败、超时、无法、无法
访问问题：拒绝、拒绝、拒绝许可

性能提示：

使用 errors_only: true 将上下文使用率降低70-90%
默认 tail_lines: 100 在细节和上下文效率之间取得平衡
使用 since_seconds 用于时间范围的故障排除
合并 filter （服务器端） errors_only （客户端）实现最高效率

`revision_metadata`

获取ArgoCD应用程序特定版本的元数据（作者、日期、消息、标签）。返回提交信息，包括作者、时间戳、提交消息、关联的Git标签和签名验证状态。可用于跟踪更改、审核部署和了解修订历史。

论据：

application_name （必填）：应用程序名称
revision （必填）：修订/提交哈希
app_namespace （可选）：应用程序命名空间
project （可选）：项目标识符
source_index （可选）：源索引（适用于多源应用）
version_id （可选）：来自历史数据的版本ID（适用于多源应用程序）

退货： 优化摘要包括：

修订的作者和日期
简短而完整的提交消息
标签和相关标签的数量
签名状态（已签名/未签名）和摘要

使用案例：

跟踪更改和审核部署
了解修订历史并提交详细信息
验证提交的作者身份和完整性
识别修订版的相关Git标签
与特定代码版本相关的调试问题

输出示例：

Revision Metadata for application 'guestbook' at revision 'abc123def456'

Author: John Doe 
Date: 2025-10-27T10:30:00Z

Commit Message:
  feat: Add new feature

Full Message:
  feat: Add new feature

  This commit introduces a brand new feature to the application.

Tags (2):
  - v1.2.0
  - release-candidate

Signature Status: Valid signature

`get_application_sync_windows`

获取ArgoCD应用程序的同步窗口。返回已配置的同步窗口列表，包括其计划、持续时间和受影响的应用程序/命名空间/集群。有助于了解应用程序何时可以同步或何时被阻止同步。

论据：

application_name （必填）：应用程序名称
app_namespace （可选）：应用程序命名空间
project （可选）：项目标识符

退货： 优化摘要包括：

同步窗口总数
每个同步窗口的详细信息：

- kind：同步窗口的类型（例如，“允许”、“拒绝”） - schedule：窗口的Cron时间表 - duration：窗口持续时间（例如“1小时”、“30米”） - applications：受窗口影响的应用程序名称列表 - namespaces：受窗口影响的命名空间列表 - clusters：受窗口影响的群集URL列表 - manual_sync_enabled：窗口期间是否允许手动同步 - start_time：窗口的开始时间（RFC3339格式） - end_time：窗口结束时间（RFC3339格式）

使用案例：

确定何时允许或拒绝应用程序同步
确定维护窗口或停电期
了解哪些应用程序、命名空间或集群受到特定同步策略的影响
在窗口期间验证手动同步权限

输出示例：

Sync Windows for application 'my-app' (2 total):

1. Kind: allow
   Schedule: 0 0 * * *
   Duration: 1h
   Start Time: 2025-01-01T00:00:00Z
   End Time: 2025-01-01T01:00:00Z
   Manual Sync Enabled: true
   Applications: guestbook, helm-app
   Namespaces: default, staging
   Clusters: https://kubernetes.default.svc

2. Kind: deny
   Schedule: 0 2 * * *
   Duration: 30m
   Start Time: 2025-01-01T02:00:00Z
   End Time: 2025-01-01T02:30:00Z
   Manual Sync Enabled: false
   Applications: backend-api
   Namespaces: backend-prod

`sync_application`

将ArgoCD应用程序同步到Git中的目标状态。此操作部署或更新应用程序资源，以匹配Git存储库中定义的资源。 注意：这是一个写操作，在只读模式下被阻止。

论据：

application_name （必填）：要同步的应用程序的名称
revision （可选）：要同步的特定修订（默认为应用规范中的目标修订）
dry_run （可选）：如果为true，则预览同步而不实际执行（默认值：false）
prune （可选）：是否修剪Git中不再定义的资源（默认值：false）
force （可选）：使用强制应用覆盖任何冲突（默认值：false）
resources （可选）：要同步的特定资源（如果未指定，则同步所有资源）
sync_options （可选）：同步选项数组（例如，\[“Validate=false”，“CreateNamespace=true”\]）
retry （可选）：重试配置（限制、回退持续时间、回退最大持续时间、退避因素）
app_namespace （可选）：应用程序命名空间
project （可选）：项目标识符

退货： 优化摘要包括：

应用程序名称
手术是否为模拟手术
当前同步状态和同步后的修订
同步后的当前运行状况
已同步到的目标修订
是否启用修剪/强制
已应用的同步选项
已同步的资源数量（如果是部分同步）

使用案例：

从Git部署新的应用程序版本
更新应用程序配置
修复配置漂移
使用模拟运行模式预览更改
仅同步特定资源（部分同步）
强制同步以覆盖冲突
用西梅清理废弃资源

输出示例：

Sync Completed for application 'guestbook'

Target Revision: HEAD
Current Sync Revision: abc123def456

Status:
  Sync Status: Synced
  Health Status: Progressing

Configuration:
  Dry Run: false
  Prune Enabled: false
  Force Enabled: false
  Resources Synced: all

✅ Sync completed successfully.
    Monitor the application to ensure it reaches the desired state.

使用示例：

基本同步：

{
  "application_name": "guestbook"
}

模拟运行以预览更改：

{
  "application_name": "guestbook",
  "dry_run": true
}

同步到特定版本：

{
  "application_name": "guestbook",
  "revision": "v1.2.3"
}

与修剪同步：

{
  "application_name": "guestbook",
  "prune": true
}

仅同步特定资源：

{
  "application_name": "guestbook",
  "resources": [
    {
      "group": "apps",
      "kind": "Deployment",
      "name": "guestbook-ui",
      "namespace": "default"
    }
  ]
}

与选项同步：

{
  "application_name": "guestbook",
  "sync_options": ["Validate=false", "CreateNamespace=true"]
}

常用同步选项：

Validate=false -跳过kubectl验证
CreateNamespace=true -如果命名空间不存在，则创建命名空间
PruneLast=true -在所有其他资源同步后修剪资源
ApplyOutOfSyncOnly=true -仅应用不同步的资源
ServerSideApply=true -使用服务器端应用程序
Replace=true -使用替换而不是应用

最佳实践：

始终先进行试运行：预览同步 dry_run: true 在执行之前，尤其是在生产中
同步后的监视器：观察应用程序以确保其达到所需状态
用力要小心：只有在理解其含义时才能使用武力
小心梅干：修剪会删除资源-确保您知道将删除哪些资源
对大型应用程序使用选择性同步：当您只需要更新某些组件时，同步特定资源
适当配置重试：对不可靠的环境使用重试配置
检查同步窗口：在同步之前，请验证应用程序是否不在被阻止的同步窗口中

只读模式： 此工具是一种写入操作 在只读模式下被阻止。如果您在以下情况下尝试使用它，您将收到错误 ARGOCD_READ_ONLY=true.

看 docs/sync_application.md 有关详细文档、高级示例和所有同步选项。

`get_application_history`

获取ArgoCD应用程序的部署历史记录。返回包含历史ID、修订、时间戳和启动器信息的所有部署的列表。 对于回滚操作至关重要。

论据：

application_name （必填）：应用程序名称
app_namespace （可选）：应用程序的命名空间
project （可选）：项目标识符

退货： 优化摘要包括：

部署总数
历史条目（最多20个最新条目，按最新条目排序）：

- 历史ID（回滚时需要） - Git修订版（缩短显示，JSON中的完整哈希） - 部署时间戳 - 部署持续时间（如果可用） - 谁发起（用户名或“自动”） - 源代码存储库和路径/图表 - 目标修订（分支/标签） - 当前部署标记(👉) - 自动化部署指标(🤖)

使用案例：

获取回滚操作的历史ID （最关键-要求 rollback_application)
审核部署并跟踪谁部署了什么
了解部署时间表和进度
识别自动化部署与手动部署
跨部署跟踪源更改
通过与特定部署关联来解决问题
验证当前部署状态

输出示例：

📜 Deployment History for 'guestbook'
════════════════════════════════════════════════════════════════════════════════

Total deployments: 5

────────────────────────────────────────────────────────────────────────────────

👉 1. History ID: 5 (Current)
   Revision: ghi789jk (ghi789jkl012345678901234567890123456)
   Deployed: 2025-01-05T10:30:00Z
   Duration: from 2025-01-05T10:29:00Z to 2025-01-05T10:30:00Z
   Initiated by: john.doe
   Repository: https://github.com/argoproj/argocd-example-apps
   Path: guestbook
   Target Revision: v2.0

────────────────────────────────────────────────────────────────────────────────

   2. History ID: 4
   Revision: def456ab (def456abc789012345678901234567890123)
   Deployed: 2025-01-04T14:30:00Z
   Initiated by: Automated 🤖
   Repository: https://github.com/argoproj/argocd-example-apps
   Path: guestbook
   Target Revision: main

────────────────────────────────────────────────────────────────────────────────

💡 Tips:
   - Use the History ID with 'rollback_application' to revert to a previous version
   - Current deployment is marked with 👉
   - 🤖 indicates automated deployments

回滚工作流：

1. get_application_history(application_name: "my-app")
   → Get history IDs and find the version to rollback to

2. rollback_application(application_name: "my-app", id: 4)
   → Rollback to history ID 4 from step 1

看 docs/get_application_history.md 获取详细的文档、工作流程和示例。

`refresh_application`

从Git存储库刷新ArgoCD应用程序。强制ArgoCD重新获取清单并重新计算同步状态。 这是一个只读操作 这不会修改集群状态，只会更新ArgoCD的缓存视图。

论据：

application_name （必填）：应用程序名称
refresh_type （可选）：“正常”或“硬”（默认：“硬”）

- “正常”：从缓存中定期刷新 - “hard”：强制从Git存储库刷新

app_namespace （可选）：应用程序的命名空间
project （可选）：项目标识符

退货： 前后对比显示：

将状态（之前/之后）与更改指示器同步
健康状态（之前/之后），带变化指示器
如果更改，则同步修订（之前/之后）
存储库URL和目标修订
变化的总结
视觉指示器(🔄 对于改变，✓ 不变）

使用案例：

解决过时的同步状态 （最常见的-修复“卡住”的应用程序）
推送到Git后更新ArgoCD
对未更新的应用程序进行故障排除
验证是否检测到配置更改
修复缓存问题
预同步验证
检测新的Git提交

输出示例：

🔄 Refreshed Application 'guestbook'
════════════════════════════════════════════════════════════════════════════════

Refresh Type: hard
Repository: https://github.com/argoproj/argocd-example-apps
Target Revision: HEAD

────────────────────────────────────────────────────────────────────────────────

📊 Status Comparison:

🔄  Sync Status:
   Before: OutOfSync
   After:  Synced
   ➜ Changed!

✓  Health Status:
   Before: Healthy
   After:  Healthy
   ➜ No change

────────────────────────────────────────────────────────────────────────────────

✅ Refresh completed - Application state was updated

Changes detected in: sync status

💡 Tips:
   - Refresh does not modify cluster resources, only ArgoCD's cache
   - Use 'hard' refresh to force re-fetch from Git repository
   - If sync status changed to 'OutOfSync', use 'sync_application' to deploy

常见场景：

Git推送后：强制ArgoCD检测新的提交

   {
     "application_name": "my-app",
     "refresh_type": "hard"
   }

卡住的应用程序：修复出现冻结的应用程序

   {
     "application_name": "stuck-app",
     "refresh_type": "hard"
   }

部署前检查：同步前刷新

   1. refresh_application → Get latest from Git
   2. Check if OutOfSync
   3. sync_application → Deploy if needed

重要提示：

只读操作：从不修改群集资源
随时都可以安全运行：仅更新ArgoCD的缓存
不是部署：刷新≠同步（使用 sync_application 部署）
以只读模式可用：可以在以下情况下使用 ARGOCD_READ_ONLY=true

看 docs/refresh_application.md 了解详细的文档、工作流程和故障排除方案。

`get_resource`

从ArgoCD应用程序获取特定的Kubernetes资源。返回详细的资源清单，包括元数据、规范和状态。

论据：

application_name （必填）：应用程序名称
resource_name （必填）：要检索的特定资源的名称
version （必需）：Kubernetes API版本（例如“v1”、“apps/v1”）
kind （必填）：资源类型（例如，“Pod”、“Service”、“Deployment”）
namespace （可选）：资源的命名空间
group （可选）：API组（核心资源为空，部署为“应用程序”等）
app_namespace （可选）：ArgoCD应用程序的命名空间
project （可选）：ArgoCD项目标识符

退货： 优化摘要包括：

资源标识（名称、种类、版本、组、命名空间）
包含解析元数据（标签、注释、创建时间、状态）的清单摘要
完整清单（显示前50行，如果截断，请注明）

使用案例：

检查特定pod、部署、服务或其他Kubernetes资源的当前状态
查看资源配置详细信息
验证资源状态和运行状况
使用特定资源解决问题
检查资源标签、注释和元数据

输出示例：

Resource: nginx-deployment (Deployment)
Application: production-app
Version: v1
Group: apps
Namespace: production

Manifest Summary:
  API Version: apps/v1
  Kind: Deployment
  Name: nginx-deployment
  Namespace: production
  Labels (3):
    app: nginx
    env: production
    version: 1.0
  Annotations Count: 2
  Created: 2025-01-01T00:00:00Z
  Status: 3/3 replicas ready

📄 Full Manifest:
────────────────────────────────────────────────────────────────────────────────
apiVersion: apps/v1
kind: Deployment
metadata:
  name: nginx-deployment
  namespace: production
...

看 docs/get_resource.md 查看详细的文档和示例。

`patch_resource`

使用JSON补丁、合并补丁或战略合并补丁格式对ArgoCD应用程序中的Kubernetes资源进行补丁。 注意：这是一个写操作，在只读模式下被阻止。

论据：

application_name （必填）：应用程序名称
resource_name （必填）：要修补的资源的名称
version （必需）：Kubernetes API版本（例如“v1”、“apps/v1”）
kind （必需）：资源类型（例如，“部署”、“服务”、“ConfigMap”）
patch （必填）：补丁内容为JSON字符串
namespace （可选）：资源的命名空间
group （可选）：API组（对于核心资源为空）
patch_type （可选）：补丁策略类型（json补丁、合并补丁、策略合并补丁）
app_namespace （可选）：ArgoCD应用程序的命名空间
project （可选）：ArgoCD项目标识符

退货： 优化摘要包括：

补丁确认和资源识别
使用解析的元数据更新清单摘要
完整更新的清单（显示前50行）

使用案例：

通过更新副本计数来扩展部署
更新部署中的容器映像
添加或修改标签和注释
更新Pod中的环境变量
修改ConfigMap或机密数据
更改资源限制和请求
更新服务端口或选择器

常见补丁类型：

application/json-patch+json：用于精确操作的RFC 6902 JSON补丁
application/merge-patch+json：RFC 7396用于简单合并的合并补丁
application/strategic-merge-patch+json：Kubernetes战略合并（默认，推荐）

示例-规模部署：

{
  "application_name": "backend-app",
  "namespace": "production",
  "resource_name": "api-deployment",
  "version": "v1",
  "group": "apps",
  "kind": "Deployment",
  "patch": "{\"spec\": {\"replicas\": 5}}",
  "patch_type": "application/merge-patch+json"
}

输出示例：

✅ Patched Resource: api-deployment (Deployment)
Application: production-app
Version: v1
Group: apps
Namespace: production

Updated Manifest Summary:
  API Version: apps/v1
  Kind: Deployment
  Name: api-deployment
  Namespace: production
  Labels (4):
    app: api
    env: production
    version: 2.0
    patched: true
  Status: 5/5 replicas ready

📄 Updated Manifest:
────────────────────────────────────────────────────────────────────────────────
apiVersion: apps/v1
kind: Deployment
...

💡 Tip: Monitor the resource to ensure it reaches the desired state.

重要提示：

通过以下方式进行更改 patch_resource 如果应用程序已同步并且更改与Git冲突，ArgoCD可能会覆盖该更改
对于永久性更改，请考虑更新Git存储库并使用 sync_application
此操作在以下情况下禁用 ARGOCD_READ_ONLY=true

看 docs/patch_resource.md 有关详细文档、补丁策略指南和高级示例。

`rollback_application`

通过历史ID将ArgoCD应用程序回滚到以前部署的版本。此操作将应用程序还原到其部署历史中的特定点。 注意：这是一个写操作，在只读模式下被阻止。

论据：

application_name （必填）：要回滚的应用程序的名称
id （必需）：要回滚到的历史ID。使用0回滚到以前的版本
dry_run （可选）：如果为true，则预览回滚而不实际执行（默认值：false）
prune （可选）：是否修剪目标修订中不再定义的资源（默认值：false）
app_namespace （可选）：应用程序命名空间
project （可选）：项目标识符

退货： 优化摘要包括：

应用程序名称
回滚到的历史ID
手术是否为模拟手术
回滚后的当前同步状态和修订
回滚后的当前运行状况
回滚后的目标修订
是否启用修剪

使用案例：

部署失败后快速恢复到以前的工作版本
在事件发生时回滚到已知的良好状态
在执行之前使用模拟运行模式预览回滚效果
使用修剪选项删除孤立资源
审计和跟踪回滚操作

输出示例：

Rollback Completed for application 'guestbook'

Rolled back to History ID: 5
Target Revision: abc123
Current Sync Revision: abc123def456

Status:
  Sync Status: Synced
  Health Status: Healthy

Options:
  Dry Run: false
  Prune Enabled: false

✅ Rollback completed successfully.
    Monitor the application to ensure it reaches the desired state.

模拟运行示例：

Rollback (Dry Run) for application 'guestbook'

Rolled back to History ID: 3
Target Revision: v1.0.0

Status:
  Sync Status: OutOfSync
  Health Status: Healthy

Options:
  Dry Run: true
  Prune Enabled: false

⚠️  Note: This was a dry run. No actual changes were made.
    Run without dry_run=true to perform the actual rollback.

使用示例：

基本回滚到特定历史ID：

{
  "application_name": "guestbook",
  "id": 5
}

回滚到以前的版本（ID 0）：

{
  "application_name": "guestbook",
  "id": 0
}

使用模拟运行预览回滚：

{
  "application_name": "guestbook",
  "id": 3,
  "dry_run": true
}

修剪后回滚：

{
  "application_name": "guestbook",
  "id": 5,
  "prune": true
}

最佳实践：

始终先进行试运行：使用预览回滚 dry_run: true 执行前
回滚后的监控：观察应用程序以确保其达到所需状态
检查历史记录：使用 revision_metadata 验证正确的历史ID
小心梅干：仅当您确定要删除资源时才启用修剪
文档回滚：跟踪执行回滚的原因和时间

只读模式： 此工具是一种写入操作 在只读模式下被阻止。如果您在以下情况下尝试使用它，您将收到错误 ARGOCD_READ_ONLY=true.

看 docs/rollback_application.md 查看详细文档和其他示例。

配置

服务器需要以下环境变量：

必需变量

ARGOCD_BASE_URL：ArgoCD服务器的基本URL（例如。， https://argocd.example.com)
ARGOCD_ACCESS_TOKEN：您的ArgoCD API访问令牌

可选变量

ARGOCD_INSECURE （可选）：设置为 true 跳过TLS证书验证（对自签名证书有用）
ARGOCD_READ_ONLY （可选）：设置为 true 强制只读模式（默认： false)

只读模式

服务器支持只读模式，可以通过设置 ARGOCD_READ_ONLY 环境变量 true.启用时：

✅ 所有只读工具继续工作（GET请求）
❌ 写入操作如下 rollback_application 被封锁
✅ 服务器信息显示“只读模式”指示灯
✅ 为生产环境提供额外的安全保障
✅ 对审计/合规要求有用

写入操作（在只读模式下被阻止）：

sync_application -将应用程序同步到Git中的目标状态
rollback_application -将应用程序回滚到以前的版本
patch_resource -在应用程序中修补Kubernetes资源

读取操作（始终可用）：

所有其他工具（列表、get、树、日志、清单、元数据、事件、sync_windows、get_source、get_application_history、refresh_applications等）

只读模式适用于：

生产监控和故障排除，无意外变更风险
审计和合规要求
为初级团队成员提供安全通道
明确记录访问级别
加强安全态势

# Enable read-only mode
export ARGOCD_READ_ONLY=true

# Disable read-only mode (default)
export ARGOCD_READ_ONLY=false

TLS/SSL配置

如果您的ArgoCD服务器使用自签名证书或系统不信任的证书，您可以禁用TLS证书验证：

export ARGOCD_INSECURE=true

安全警告：仅使用 ARGOCD_INSECURE=true 在开发/测试环境中或使用内部ArgoCD服务器。对于生产使用，建议：

使用来自受信任CA的正确签名的证书
将组织的CA证书添加到系统信任存储中
使用 argocd login --insecure 只有在绝对必要的时候

获取ArgoCD访问令牌

登录您的ArgoCD实例：

   argocd login

生成帐户令牌：

   argocd account generate-token

安装

先决条件

锈1.70或更高版本（用于建筑）
Python 3.8+（用于通过包装器运行）

建筑

# Clone the repository
git clone https://github.com/yourusername/argocd-mcp-server.git
cd argocd-mcp-server

# Build the Rust binary
cargo build --release

部署到其他位置

构建后，您可以将服务器部署到任何位置。服务器由两个组件组成：

Python包装器(argocd_mcp_server.py)
Rust二进制(target/release/argocd-mcp-server)

重要：Python包装器在相对于自身的特定位置查找二进制文件：

bin/argocd-mcp-server （建议部署）
argocd-mcp-server （与包装器目录相同）
target/release/argocd-mcp-server （仅限开发）

快速安装

使用提供的安装脚本：

# Install to default location (~/.local/bin/argocd-mcp-server)
./install.sh

# Or install to custom location
./install.sh /path/to/installation/directory

手动安装

# Create installation directory
mkdir -p /path/to/install/bin

# Copy files
cp argocd_mcp_server.py /path/to/install/
cp target/release/argocd-mcp-server /path/to/install/bin/

# Make executable
chmod +x /path/to/install/argocd_mcp_server.py
chmod +x /path/to/install/bin/argocd-mcp-server

看安装.md 有关详细的安装说明、故障排除和部署最佳实践。

用法

运行服务器

服务器可以通过两种方式运行：

方法1：通过Python包装器（推荐-最兼容）

此方法与所有需要标准可执行文件的MCP框架兼容：

# Set environment variables
export ARGOCD_BASE_URL=https://your-argocd-server.com
export ARGOCD_ACCESS_TOKEN=your-access-token-here

# Run via Python wrapper
python3 argocd_mcp_server.py

方法2：直接Rust二进制

对于直接执行或测试（并非所有MCP框架都支持）：

# Set environment variables
export ARGOCD_BASE_URL=https://your-argocd-server.com
export ARGOCD_ACCESS_TOKEN=your-access-token-here

# Run the binary directly
./target/release/argocd-mcp-server
# OR
cargo run --release

与MCP检查器一起使用

使用MCP检查器测试服务器：

# Via Python wrapper (recommended)
npx @modelcontextprotocol/inspector python3 argocd_mcp_server.py

# OR via direct binary
npx @modelcontextprotocol/inspector ./target/release/argocd-mcp-server

与克劳德桌面/克劳德代码集成

添加到您的Claude桌面/代码配置(.mcp.json 或 claude_desktop_config.json):

选项1：使用Python包装器（推荐-最兼容）

{
  "mcpServers": {
    "argocd": {
      "command": "python3",
      "args": ["/absolute/path/to/argocd-mcp-server/argocd_mcp_server.py"],
      "env": {
        "ARGOCD_BASE_URL": "https://your-argocd-server.com",
        "ARGOCD_ACCESS_TOKEN": "your-access-token-here",
        "ARGOCD_INSECURE": "true"
      }
    }
  }
}

选项2：直接二进制（如果您的框架支持）

{
  "mcpServers": {
    "argocd": {
      "command": "/absolute/path/to/argocd-mcp-server/target/release/argocd-mcp-server",
      "env": {
        "ARGOCD_BASE_URL": "https://your-argocd-server.com",
        "ARGOCD_ACCESS_TOKEN": "your-access-token-here",
        "ARGOCD_INSECURE": "true"
      }
    }
  }
}

选项3：使用uvx/pipx（发布到PyPI后）

{
  "mcpServers": {
    "argocd": {
      "command": "uvx",
      "args": ["argocd-mcp-server"],
      "env": {
        "ARGOCD_BASE_URL": "https://your-argocd-server.com",
        "ARGOCD_ACCESS_TOKEN": "your-access-token-here",
        "ARGOCD_INSECURE": "true"
      }
    }
  }
}

备注:

使用选项1（Python包装器） -与所有MCP框架最兼容
仅包括 "ARGOCD_INSECURE": "true" 如果您的ArgoCD服务器使用自签名证书
包装器在保持Rust性能的同时增加了最小的开销（~1-2ms）
始终使用绝对路径 -更换 /absolute/path/to/ 与你的实际路径

发展

运行测试

# Run all tests
cargo test

# Run with output
cargo test -- --nocapture

# Run specific test
cargo test test_list_all_applications

项目结构

argocd-mcp-server/
├── src/
│   ├── main.rs                  # Entry point with stdio transport
│   ├── lib.rs                   # Library exports
│   ├── argocd_client.rs         # ArgoCD API client
│   ├── models.rs                # Data models (optimized for context efficiency)
│   └── tools.rs                 # MCP tool implementations
├── tests/
│   └── integration_test.rs      # Integration tests with mock server
├── argocd_mcp_server.py         # Python wrapper (RECOMMENDED)
├── setup.py                     # Python package setup
├── pyproject.toml               # Python project configuration
├── Cargo.toml                   # Rust package configuration
├── Cargo.lock                   # Rust dependency lock
└── README.md

建筑

组件

ArgoCD客户端 (argocd_client.rs)

- 处理与ArgoCD API的HTTP通信 - 实现身份验证和错误处理 - 提供优化和完整的响应方法

数据模型 (models.rs)

- ArgoCD对象的类型安全模型 - 优化摘要格式以减少上下文使用 - 具有适当字段映射的全面反序列化

MCP工具 (tools.rs)

- 使用以下工具实现MCP工具接口 #[tool] 宏 - 处理刀具布线和参数验证 - 格式化响应以获得最佳可读性

响应优化

服务器使用 ApplicationSummaryOutput 仅提供基本字段：

与完整应用程序对象相比，响应大小减少了约70%
包括决策所需的所有关键信息
提供人类可读和JSON格式

测试

全面的测试套件包括：

客户端创建和验证的单元测试
与mock ArgoCD API服务器的集成测试（使用wiremock）
错误处理测试（身份验证、网络、服务器错误）
筛选和分页测试
空响应处理

API兼容性

此服务器与ArgoCD API v1alpha1兼容。它已经过以下测试：

ArgoCD2.x API终点
标准ArgoCD身份验证

演出

启动时间：\<100ms
响应时间：列表应用程序通常\<500ms（取决于ArgoCD服务器）
内存使用：约10MB基本内存占用
并发：使用Tokio运行时完全异步

故障排除

常见问题

“ArgoCD客户端未初始化”

- 确保 ARGOCD_BASE_URL 和 ARGOCD_ACCESS_TOKEN 已设定 - 运行前检查是否导出了环境变量

身份验证错误

- 验证您的访问令牌是否有效： argocd account get-user-info - 如果需要，生成新令牌

连接超时

- 检查ArgoCD服务器的网络连接 - 验证基本URL是否正确且可访问

TLS/SSL证书错误

- 错误：“无法将请求发送到ArgoCD API” - 常见原因：自签名或不受信任的证书 - 解决方案：设置 ARGOCD_INSECURE=true 在您的环境配置中 - 替代方案：将组织的CA证书添加到系统信任存储中

调试日志记录

启用调试日志记录：

RUST_LOG=debug cargo run

安全考虑

安全地存储访问令牌（使用环境变量或秘密管理器）
从不将令牌提交到版本控制
ArgoCD服务器连接使用HTTPS
定期轮换访问令牌
考虑使用具有最低所需权限的服务帐户

未来的增强功能

潜在补充：

其他工具（同步应用程序、回滚应用程序等）
应用程序创建和更新
详细的资源状态查询
Webhook支持实时更新
缓存层可提高性能
应用程序清单生成

贡献

欢迎投稿！请确保：

所有测试均通过(cargo test)
代码已格式化(cargo fmt)
没有刺耳的警告(cargo clippy)

致谢

内置 MCP防锈sdk
用途 reqwest 对于HTTP客户端
测试与线模

Hypen Argocd MCP

快速接入

详细介绍

ArgoCD MCP服务器

特性

ArgoCD版本兼容性

工具

list_applications

list_application_names

get_application

server_side_diff

resource_tree

list_resource_events

pod_logs

revision_metadata

get_application_sync_windows

sync_application

get_application_history

refresh_application

get_resource

patch_resource

rollback_application

配置

必需变量

可选变量

只读模式

TLS/SSL配置

获取ArgoCD访问令牌

安装

先决条件

建筑

部署到其他位置

快速安装

手动安装

用法

运行服务器

方法1：通过Python包装器（推荐-最兼容）

方法2：直接Rust二进制

与MCP检查器一起使用

与克劳德桌面/克劳德代码集成

选项1：使用Python包装器（推荐-最兼容）

选项2：直接二进制（如果您的框架支持）

选项3：使用uvx/pipx（发布到PyPI后）

发展

运行测试

项目结构

建筑

组件

响应优化

测试

API兼容性

演出

故障排除

常见问题

调试日志记录

安全考虑

未来的增强功能

贡献

致谢

目录标签

接入字段

权限和风险

来源信息

继续浏览同类 MCP

`list_applications`

`list_application_names`

`get_application`

`server_side_diff`

`resource_tree`

`list_resource_events`

`pod_logs`

`revision_metadata`

`get_application_sync_windows`

`sync_application`

`get_application_history`

`refresh_application`

`get_resource`

`patch_resource`

`rollback_application`