MCP Ambari

Ambari MCP服务器


在Go中实现的Apache Ambari的高性能模型上下文协议（MCP）服务器。该项目使AI代理和助手能够通过标准化的MCP工具和资源与Ambari集群无缝交互。

概述

Ambari MCP服务器充当AI代理和Apache Ambari集群之间的桥梁，通过模型上下文协议为自动化集群管理、服务操作、监控和故障排除提供全面的访问。 该服务器旨在供AI代理使用 而不是直接的人类用户。

以代理为中心的体系结构：

AI Agents → Ambari MCP Server → Apache Ambari REST API → Hadoop Cluster

主要优势：

• 🚀 高性能：内置Go，带有连接池和重试逻辑
• 🔒 企业安全：具有基于角色的权限的LDAP身份验证\[WIP\]
• 📊 全面覆盖：52多种工具，涵盖Ambari的所有主要业务，包括用户/组管理
• 🔧 生产就绪：强大的错误处理、TLS/mTLS支持和优雅的关机

建筑

服务器实现了几种可维护性和可扩展性的设计模式：

┌─────────────────┐    ┌──────────────────┐    ┌─────────────────┐
│   AI Agents     │    │  Transport Layer │    │  Auth Provider  │
│                 │    │                  │    │                 │  
│ • Claude         │◄──►│ • Stdio (MCP)    │◄──►│ • LDAP Headers  │
│ • Cline         │    │ • HTTP/HTTPS     │    │ • Permission    │
│ • Custom Agents │    │ • mTLS           │    │   Groups        │
└─────────────────┘    └──────────────────┘    └─────────────────┘
                                │
                                ▼
            ┌─────────────────────────────────────────────┐
            │         Operation Registry                  │
            │                                             │
            │  ┌─────────────────┐ ┌─────────────────────┐│
            │  │   Read-Only     │ │    Actionable       ││
            │  │   Operations    │ │    Operations       ││
            │  │   (24 tools)    │ │    (28 tools)       ││
            │  │                 │ │                     ││
            │  │ • Get clusters  │ │ • Start services    ││
            │  │ • List services │ │ • Restart components││
            │  │ • View alerts   │ │ • Create clusters   ││
            │  │ • Check status  │ │ • Manage alerts     ││
            │  └─────────────────┘ └─────────────────────┘│
            └─────────────────────────────────────────────┘
                                │
                                ▼
            ┌─────────────────────────────────────────────┐
            │         Template Method Executor            │
            │                                             │
            │  Authorization → Validation → Execution     │
            └─────────────────────────────────────────────┘
                                │
                                ▼
            ┌─────────────────────────────────────────────┐
            │          Ambari REST Client                 │
            │                                             │
            │  • Connection pooling  • Retry logic        │
            │  • Request timeout     • Error handling     │  
            └─────────────────────────────────────────────┘
                                │
                                ▼
                    ┌───────────────────────┐
                    │    Ambari Cluster     │
                    │                       │
                    │          │
                    │                       │
                    │  • Services          │
                    │  • Hosts             │
                    │  • Configurations    │
                    │  • Alerts            │
                    └───────────────────────┘

已实现的设计模式

• 策略模式：可插拔的身份验证提供程序和传输模式
• 模板方法：标准化操作执行生命周期
• 工厂模式：动态运营和运输创建
• 注册模式：集中运营管理
• 存储库模式：具有连接抽象的Ambari客户端

坚实的原则

• 单一责任：每个包裹都有一个明确的目的
• 打开/关闭：可通过接口扩展，无需修改
• 里氏替换：所有操作均执行操作界面
• 接口隔离：简洁、专注的界面
• 依赖倒置：通过构造函数注入依赖关系

特性

🛠️ 51种MCP工具可用

• 51工具：管理和监测安巴里集群的行动
• 12资源：基于URI的群集数据访问
• 8提示：常见任务的指导工作流程

______________________________________________________________________

🛠️ 工具（共51个）

只读工具（24）-始终可用

这些工具是安全的，仅限GET操作，权限要求较低：

集群操作（2）

服务运营（8）

主机操作（2）

警报操作（7）

用户和组操作（5）

可操作工具（27）-要求ENABLE_ATIONABLE_Tools=true

这些工具执行状态更改操作，需要明确启用：

集群管理（1）

服务生命周期（7）

警报定义管理（1）

警报组管理（5）

警报通知管理（5）

用户和组管理（8）

______________________________________________________________________

📊 资源（共12个）

资源通过URI模式提供对集群数据的只读访问：

资源访问示例

# Get cluster details
URI: ambari://cluster/sagarautomation

# Get service components
URI: ambari://cluster/sagarautomation/service/HDFS/components

# Get alert summary
URI: ambari://cluster/sagarautomation/alerts/summary

______________________________________________________________________

📝 提示（共8条）

提示是可重复使用的模板，可指导AI代理完成多步工作流程：

1.集群健康检查

描述：对Ambari集群进行全面的健康检查，包括服务、主机和警报

必需参数:

• clusterName -要检查的Ambari集群的名称

工作流程：检查群集概述、服务状态、警报、主机运行状况和过时配置，然后提供总体运行状况评估和建议。

______________________________________________________________________

2.维修_故障排查

描述：排除特定Ambari服务的问题

必需参数:

• clusterName -安巴里集群的名称
• serviceName -要排除故障的服务名称（例如HDFS、YARN）

工作流程：分析服务状态、警报、组件和配置，以识别问题并提供故障排除建议。

______________________________________________________________________

3.警报调查

描述：调查和分析安巴里集群中的警报

必需参数:

• clusterName -安巴里集群的名称

可选参数:

• severity -要调查的警报严重程度（严重、警告、正常）

工作流程：审查警报摘要、详细信息、受影响的服务/主机，并提供根本原因分析和补救措施。

______________________________________________________________________

4.性能分析

描述：分析集群服务的性能和资源使用情况

必需参数:

• clusterName -安巴里集群的名称

可选参数:

• serviceName -具体服务分析

工作流程：评估服务状态、主机资源使用情况、瓶颈，并提供性能优化建议。

______________________________________________________________________

5.配置_查看

描述：审查集群配置并确定潜在问题

必需参数:

• clusterName -安巴里集群的名称

工作流程：识别过时的配置、需要重新启动的组件，并通过影响评估推荐重新启动策略。

______________________________________________________________________

6.用户权限审核

描述：审核Ambari用户、组和权限

必需参数：无

工作流程：审查所有用户、组、权限，并提供带有访问控制建议的安全审计报告。

______________________________________________________________________

7.升级就绪检查

描述：检查群集是否已准备好进行升级或维护

必需参数:

• clusterName -安巴里集群的名称

工作流程：验证所有服务是否正在运行，没有严重警报，没有过时的配置，所有主机是否健康，然后提供就绪评估和升级阻止程序。

______________________________________________________________________

8.服务依赖性分析

描述：分析服务依赖关系和启动/停止顺序

必需参数:

• clusterName -安巴里集群的名称
• serviceName -用于分析依赖关系的服务

工作流程：确定服务依赖关系、建议的启动/停止顺序、影响分析和安全重启过程。

______________________________________________________________________

📝 8个MCP提示可用

用于常见Ambari工作流的可重用提示模板：

• cluster_health_check -综合集群健康分析
• service_troubleshooting -诊断并修复服务问题
• alert_investigation -调查和分析集群警报
• performance_analysis -分析服务和集群性能
• configuration_review -审查和验证集群配置
• user_permissions_audit -审核用户、组和权限
• upgrade_readiness_check -验证集群是否已准备好进行维护
• service_dependency_analysis -了解服务依赖关系

📊 12可用MCP资源

通过URI模式直接访问集群数据：

• ambari://clusters -列出所有集群
• ambari://cluster/{clusterName} -集群详细信息
• ambari://cluster/{clusterName}/services -集群服务
• ambari://cluster/{clusterName}/hosts -群集主机
• ambari://cluster/{clusterName}/alerts -集群警报
• ambari://cluster/{clusterName}/alerts/summary -警报摘要
• ambari://cluster/{clusterName}/services/stale-configs -陈旧的配置
• ambari://cluster/{clusterName}/service/{serviceName} -服务详情
• ambari://cluster/{clusterName}/service/{serviceName}/components -服务组件
• ambari://host/{hostName} -主机详细信息
• ambari://cluster/{clusterName}/requests/recent -最近的行动
• ambari://cluster/{clusterName}/configurations -配置类型

安装

先决条件

• 转到1.23+ （使用Go 1.24工具链）
• 访问Apache Ambari集群

从源代码构建

# Clone the repository
git clone https://mcp-ambari.git
cd mcp-ambari

# Install dependencies
go mod download

# Build the server
go build ./cmd/server

# The binary 'server' is now ready to use

二进制安装

# Build and install to $GOPATH/bin
go install ./cmd/server

# Or build locally
make build

配置

环境变量

# Copy the example configuration
cp .env.example .env

# Required: Ambari connection
export AMBARI_BASE_URL=http://your-ambari-server:8080/api/v1
export AMBARI_USERNAME=admin  
export AMBARI_PASSWORD=your-password

# Optional: Timeouts and logging
export AMBARI_TIMEOUT=30s
export LOG_LEVEL=info

# Optional: Authentication (for HTTP transport)
export AUTH_ENABLED=false
export LDAP_HEADER_PREFIX=x-user-
export DEFAULT_PERMISSIONS=cluster:view,service:view

# Optional: Transport mode
export MCP_TRANSPORT=stdio  # Options: stdio, http, ssl, mtls

配置参考

用法

使用MCP客户端

克劳德桌面

增添 ~/Library/Application Support/Claude/claude_desktop_config.json:

{
  "mcpServers": {
    "ambari-server": {
      "command": "/path/to/mcp-ambari/server",
      "args": ["-transport", "stdio"],
      "env": {
        "AMBARI_BASE_URL": "http://your-ambari-server:8080/api/v1",
        "AMBARI_USERNAME": "admin",
        "AMBARI_PASSWORD": "your-password"
      }
    }
  }
}

Cline（VS代码扩展）

添加到Cline的MCP设置(~/.cline/mcp_servers.json):

{
  "mcpServers": {
    "ambari-server": {
      "command": "/path/to/mcp-ambari/server", 
      "args": ["-transport", "stdio"],
      "env": {
        "AMBARI_BASE_URL": "http://your-ambari-server:8080/api/v1",
        "AMBARI_USERNAME": "admin",
        "AMBARI_PASSWORD": "your-password"
      }
    }
  }
}

手动测试

# Run the server directly
./server -transport stdio

# With custom configuration
AMBARI_BASE_URL=http://your-ambari:8080/api/v1 \
AMBARI_USERNAME=admin \
AMBARI_PASSWORD=your-password \
LOG_LEVEL=debug \
./server -transport stdio

命令行选项

./server [OPTIONS]

Options:
  -transport string
        Transport mode: stdio, http, ssl, mtls (default "stdio")
  -host string
        Server host for HTTP modes (default "0.0.0.0")  
  -port string
        Server port for HTTP modes (default "9001")
  -ssl-certfile string
        SSL certificate file (default "certs/server-cert.pem")
  -ssl-keyfile string
        SSL private key file (default "certs/server-key.pem")
  -ssl-ca-certs string
        CA certs for mTLS client verification (default "certs/ca.pem")

项目结构

mcp-ambari/
├── cmd/
│   └── server/                 # Main application entry point
│       └── main.go            
├── internal/                   # Private application code
│   ├── auth/                  # Authentication & authorization
│   │   └── auth.go            # LDAP provider, permissions, middleware
│   ├── client/                # Ambari REST client
│   │   └── ambari.go          # HTTP client with pooling & retries
│   ├── operations/            # Business logic layer
│   │   ├── base.go            # Base interfaces & executor
│   │   ├── registry.go        # Operation registry & factory
│   │   ├── actionable/        # State-changing operations
│   │   │   ├── alerts.go      # Alert management operations
│   │   │   └── services.go    # Service lifecycle operations
│   │   └── readonly/          # Safe, read-only operations
│   │       ├── alerts.go      # Alert querying operations
│   │       └── clusters.go    # Cluster & service queries
│   │   │   └── users.go       # User and group queries
│   ├── resources/             # MCP resources (data endpoints)
│   │   └── resources.go       # 12 cluster data resources
│   └── transport/             # Transport layer abstraction
│       └── transport.go       # Stdio/HTTP/TLS transport modes
├── .env.example              # Configuration template
├── MCP_SETUP.md             # Detailed setup guide
├── go.mod                   # Go module definition
└── README.md               # This file

建筑亮点

• 关注点分离：只读与可操作操作操作
• 模板方法模式：标准化执行生命周期
• 策略模式：可插拔的身份验证提供程序和传输
• 注册模式：动态运营管理
• 依赖注入：干净、可测试的架构

示例：群集信息

基于您连接的集群 sagarautomation:

{
  "cluster_name": "sagarautomation",
  "cluster_id": 2,
  "version": "VDP-3.4", 
  "total_hosts": 3,
  "security_type": "KERBEROS",
  "provisioning_state": "INSTALLED",
  "health_report": {
    "Host/host_status/HEALTHY": 2,
    "Host/host_status/UNHEALTHY": 1,
    "Host/stale_config": 1
  }
}

已安装的服务：HDFS、纱线、蜂巢、HBASE、SPARK3、护林员、护林公里、AMBARI_METRICS、MAPREDUCE2、动物园管理员、KERBEROS、TEZ

身份验证和安全

权限系统

服务器实现了一个全面的权限系统：

// Available Permissions
ClusterView, ClusterAdmin, ServiceView, ServiceOperate, 
ServiceRestart, ServiceAdmin, HostView, HostManage,
AlertView, AlertManage, AlertAdmin, ConfigView, ConfigModify

// Permission Groups  
"ADMIN":    All permissions
"OPERATOR": View, operate, and restart permissions
"VIEWER":   Read-only permissions only

LDAP集成

export AUTH_ENABLED=true
export LDAP_HEADER_PREFIX=x-user-

预期标题：

• x-user-name 或 x-user-username：用户名
• x-user-groups：逗号分隔的组列表

组映射

"ambari-admins":    Full admin access
"hadoop-operators": Operational permissions
"data-engineers":   View and operate services  
"bigdata-viewers":  Read-only access

运输方式

标准（默认）

对于Claude Desktop和Cline等MCP客户：

./server -transport stdio

超文本传输协议

对于web应用程序和流式Http客户端：

./server -transport http -host 127.0.0.1 -port 8094

HTTPS/TLS

对于使用TLS加密的安全部署：

# Set TLS certificate environment variables
export TLS_CERT_FILE=/path/to/server.crt
export TLS_KEY_FILE=/path/to/server.key

./server -transport ssl -host 127.0.0.1 -port 8443

HTTPS/mTLS

对于具有双向TLS身份验证的企业部署：

# Set TLS certificate and CA environment variables
export TLS_CERT_FILE=/path/to/server.crt
export TLS_KEY_FILE=/path/to/server.key
export TLS_CA_FILE=/path/to/ca.crt

./server -transport mtls -host 127.0.0.1 -port 8443

可操作的工具控制

出于安全考虑，默认情况下禁用可操作工具。 除非明确启用，否则只有只读操作可用：

# Default: Only readonly tools (24 tools - safe operations only)
./server -transport http -port 8094

# Explicitly enable all tools (51 tools - includes user management, service control, etc.)
export ENABLE_ACTIONABLE_TOOLS=true
./server -transport http -port 8094

错误处理和可靠性

• 重试逻辑：使用指数回退自动重试
• 连接池：高效的HTTP连接重用
• 优雅关闭：终止时清理资源
• 综合录井：带相关ID的结构化JSON日志记录
• 输入验证：执行前的参数验证
• 权限检查：所有操作的授权验证

发展

先决条件

• 使用Go 1.24工具链执行Go 1.23+
• 访问Apache Ambari集群
• 可选：Docker用于容器化部署

本地开发

# Install dependencies
go mod download

# Run with development settings
export AMBARI_BASE_URL=http://localhost:8080/api/v1
export AMBARI_USERNAME=admin
export AMBARI_PASSWORD=admin
export LOG_LEVEL=debug

# Build and run
go run ./cmd/server -transport stdio

测试

# Run tests
go test ./...

# Run tests with coverage
go test -coverprofile=coverage.out ./...
go tool cover -html=coverage.out

添加新操作

1. 创建操作结构 实施 Operation 接口
2. 添加到注册表 在 main.go
3. 实施所需方法: Name(), Description(), Definition(), Validate(), Execute()
4. 添加适当的权限 以及错误处理

例子：

type GetNewData struct {
    ops.ReadOnlyBase
}

func (o *GetNewData) Execute(ctx context.Context, args map[string]interface{}) (interface{}, error) {
    return o.Client.Get(ctx, "/new-endpoint", params)
}

部署

二进制部署

# Build for production
CGO_ENABLED=0 GOOS=linux go build -ldflags="-w -s" ./cmd/server

# Deploy binary
scp server user@server:/usr/local/bin/mcp-ambari

Docker部署（未来）

FROM golang:1.24-alpine AS builder
WORKDIR /app
COPY . .
RUN go build ./cmd/server

FROM alpine:latest
RUN apk --no-cache add ca-certificates
WORKDIR /root/
COPY --from=builder /app/server .
CMD ["./server"]

监测和可观察性

结构化日志记录

所有操作日志均采用结构化JSON格式：

{
  "level": "info",
  "msg": "Operation completed",
  "tool": "ambari_services_getservices",
  "type": "readonly", 
  "execution_ms": 245,
  "timestamp": "2026-02-08T13:39:44Z"
}

性能指标

• 操作执行次数 追踪
• 错误率 按操作类型
• 身份验证成功/失败 费率
• Ambari API响应时间

故障排除

常见问题

调试模式

export LOG_LEVEL=debug
./server -transport stdio

健康检查

测试Ambari连接：

curl -u admin:password http://your-ambari:8080/api/v1/clusters

演出

• 并发操作：多个操作可以同时运行
• 连接池：高效的HTTP连接重用
• 内存效率高：对大型响应进行流式JSON解析
• 快速启动：亚秒级初始化时间
• 低延迟：无需额外层即可直接访问REST API

贡献

1. 分叉 存储库
2. 创建 特征分支(git checkout -b feature/amazing-feature)
3. 提交 您的更改(git commit -m 'Add amazing feature')
4. 推 到分行(git push origin feature/amazing-feature)
5. 打开 拉取请求

编码标准

• 遵循围棋惯例 gofmt 格式化
• 添加新功能的测试
• 更新API变更文档
• 使用有意义的提交消息
• 确保维护SOLID原则

许可证

此项目根据Apache 2.0许可证获得许可-请参阅 许可证 文件以获取详细信息。

相关项目

• 模型上下文协议 -MCP官方规范
• MCP Go SDK -MCP官方Go SDK
• 阿帕奇·安巴里 -Apache Ambari项目

支持

有关支持和问题：

1. 检查 MCP_SETUP.md 指南
2. 查看上面的故障排除部分
3. 在存储库中打开问题

______________________________________________________________________

内置于❤️ 支持Apache Ambari社区