DataStax OpsCenter MCP服务器
模型上下文协议(MCP)服务器,提供对DataStax操作中心API的访问,用于监视和管理Apache Cassandra和DataStax Enterprise集群。
🚀 特性
此MCP服务器提供以下工具:
- 群集管理:获取集群配置和详细信息
- 指标收集:检索集群、节点和表级别的性能指标
- 节点监控:查询单个节点信息和指标
- 架构信息:访问密钥空间和表架构
- 事件跟踪:监视群集事件和警报
- 综合指标:支持100多个指标,包括:
- 集群指标(读/写操作、延迟、内存使用)
- 线程池指标(待处理/活动任务)
- 表度量(磁盘使用率、SSTable计数、延迟)
- 操作系统指标(CPU、内存、磁盘、网络)
📋 先决条件
- Node.js:版本18.x、20.x或22.x
- DataStax操作中心:版本6.8.x或兼容
- 访问:与OpsCenter实例的网络连接
文档
- Cassandra故障排除指南 -生产故障排除的全面指南,包括9阶段工作流程、关键阈值和应急程序
- 指标覆盖率分析 -所有340多个OpsCenter指标的完整覆盖报告
- 指标快速参考 -MCP工具指标名称快速查找指南
- GitHub副本说明 -开发指南和项目架构
🔧 安装
1.克隆存储库```bash
git clone https://github.com/yourusername/datastax-opscenter-mcp.git
cd datastax-opscenter-mcp
### 2.安装依赖项```bash
npm install
3.建设项目```bash
npm run build
这将TypeScript编译为JavaScript `build/` 目录。
## ⚙️ 配置
### 环境变量
|变量|必填|默认|描述|
|----------|----------|---------|-------------|
| `OPSCENTER_URL` |是的| `http://localhost:8888` |OpsCenter基本URL|
| `OPSCENTER_USERNAME` |无|-|身份验证用户名(如果启用)|
| `OPSCENTER_PASSWORD` |否|-|身份验证密码(如果启用)|
______________________________________________________________________
## 🔌 使用GitHub Copilot设置VS代码
### 1.找到您的VS代码MCP设置文件
**macOS/Linux:**```bash
code ~/.vscode/mcp-settings.json
窗户:```powershell
code %APPDATA%\Code\User\mcp-settings.json
如果文件不存在,请创建它。
### 2.添加服务器配置
将以下内容添加到您的 `mcp-settings.json`:```json
{
"mcpServers": {
"datastax-opscenter": {
"command": "node",
"args": [
"/absolute/path/to/datastax-opscenter-mcp/build/index.js"
],
"env": {
"OPSCENTER_URL": "http://your-opscenter-host:8888",
"OPSCENTER_USERNAME": "your_username",
"OPSCENTER_PASSWORD": "your_password"
}
}
}
}
⚠️ 重要提示:
- 替换
/absolute/path/to/datastax-opscenter-mcp使用克隆存储库的实际路径 - 更新
OPSCENTER_URL,OPSCENTER_USERNAME,以及OPSCENTER_PASSWORD与你的价值观 - 在Windows上,在路径中使用正斜杠或转义反斜杠:
C:/Users/YourName/datastax-opscenter-mcp/build/index.js
3.重新启动VS代码
关闭并重新打开VS Code以使更改生效。
4.验证安装
- 在VS代码中打开GitHub Copilot聊天
- 类型
@datastax-opscenter您应该看到服务器可用 - 尝试执行测试命令:```
@datastax-opscenter get_cluster_configs
______________________________________________________________________
## 🖥️ Claude桌面设置
### 1.找到Claude桌面配置
**macOS:**```bash
~/Library/Application Support/Claude/claude_desktop_config.json
窗户:```powershell
%APPDATA%\Claude\claude_desktop_config.json
**Linux:**```bash
~/.config/Claude/claude_desktop_config.json
2.编辑配置文件
打开配置文件并添加MCP服务器:```json
{
"mcpServers": {
"datastax-opscenter": {
"command": "node",
"args": [
"/absolute/path/to/datastax-opscenter-mcp/build/index.js"
],
"env": {
"OPSCENTER_URL": "http://localhost:8888",
"OPSCENTER_USERNAME": "admin",
"OPSCENTER_PASSWORD": "password"
}
}
}
}
**⚠️ 配置说明:**
- 使用 **绝对路径** 为了 `args` 参数
- 移除 `OPSCENTER_USERNAME` 和 `OPSCENTER_PASSWORD` 如果您的OpsCenter不需要身份验证
- 更新 `OPSCENTER_URL` 以匹配您的OpsCenter实例
### 3.重新启动克劳德桌面
完全退出并重新启动Claude Desktop应用程序。
### 4.验证安装
在Claude Desktop中,您应该看到MCP服务器已连接。尝试:```
Can you get the cluster configurations from OpsCenter?
🐳 Docker设置(可选)
如果您更喜欢在容器中运行MCP服务器:
1.创建Dockerfile```dockerfile
FROM node:20-alpine
WORKDIR /app
COPY package*.json ./
RUN npm ci --only=production
COPY . .
RUN npm run build
ENV OPSCENTER_URL=http://localhost:8888
CMD ["node", "build/index.js"]
### 2.构建和运行```bash
docker build -t datastax-opscenter-mcp .
docker run -it \
-e OPSCENTER_URL=http://your-opscenter:8888 \
-e OPSCENTER_USERNAME=admin \
-e OPSCENTER_PASSWORD=password \
datastax-opscenter-mcp
📖 快速入门示例
配置后,您可以使用MCP服务器监视Cassandra集群:
可用工具
集群操作
get_cluster_configs
获取OpsCenter管理的所有群集的配置信息。
get_cluster_info
获取特定集群的详细信息。
- 参数:
cluster_id
get_nodes
获取集群中所有节点及其属性的列表。
- 参数:
cluster_id - 备注:返回完整的节点详细信息(对于大型集群可能很大)
get_nodes_summary ✨ 新
获取按数据中心组织的节点的简明摘要。
- 参数:
cluster_id(必填)datacenter(可选)-按特定数据中心筛选- 退货:按数据中心列出的节点数、IP、主机名、机架
- 用例:无需大负载即可快速查看集群拓扑
- 示例:```json
{
"total_nodes": 68,
"datacenter_counts": {
"us-east1-v1": 15,
"us-central1-v1": 15,
"HD_ATC": 18,
"HD_SSC": 20
}
}
#### `get_node_info`
获取特定节点的详细信息。
- **参数**: `cluster_id`, `node_ip`
### 指标收集
#### `get_cluster_metrics`
检索集群范围内的指标。
- **参数**:
- `cluster_id` (必填)
- `datacenter` (默认值:“全部”)
- `metric` (必填)-例如,“写操作”、“读操作”和“数据加载”
- `start` -Unix时间戳(秒)
- `end` -Unix时间戳(秒)
- `step` -时间间隔(分钟)(1、5、120或1440)
- `function` -聚合:“最小”、“最大”或“平均”
**示例指标**:
- `write-ops`:每秒写入请求数
- `read-ops`:每秒读取请求数
- `data-load`:已使用活动磁盘空间
- `heap-used`:Java堆内存使用情况
- `pending-compaction-tasks`:待定的契约
#### `get_node_metrics`
检索特定节点的指标。
- **参数**:与集群指标相同,另外 `node_ip`
#### `get_bulk_node_metrics` ✨ **新**
使用自动聚合检索数据中心中所有节点的指标。
- **参数**:
- `cluster_id` (必填)
- `datacenter` (必填)-例如“us-east1-v1”
- `metric` (必填)-例如,“读取操作”、“写入操作”
- `start` (可选)-默认为1小时前
- `end` (可选)-默认为当前时间
- `step` (可选)-默认值:5分钟
- `function` (可选)-默认值:“平均”
- **退货**:
- 聚合时间序列(每个时间戳的总数、平均数、最小值、最大值)
- 全面统计
- 每个节点的详细信息和错误状态
- **用例**:获取整个数据中心的总读/写量
- **示例**:```json
{
"cluster_id": "Production_Cluster",
"datacenter": "us-east1-v1",
"metric": "read-ops",
"nodes": {"total": 15, "with_data": 15},
"overall_statistics": {
"total_sum": 785160,
"average": 14.54,
"max": 17.89
}
}
get_table_metrics
检索特定表的指标。
- 参数:
cluster_id,datacenter,keyspace,table,metric- 时间范围和聚合参数
示例表格指标:
cf-write-ops:每秒表写入操作数cf-read-ops:每秒表读取操作数cf-live-disk-used:表使用的磁盘空间cf-live-sstables:SST表的数量
get_new_metrics
使用统一的API检索多个度量。
- 参数:
cluster_id,metrics(逗号分隔)nodes或node_group(所有用“*”表示)step以秒为单位(60、300、7200或86400)node_aggregation(0或1)
list_available_metrics
列出所有可用的度量类型及其说明。
- 参数:
category(可选)-“集群”、“线程池”、“表”、“操作系统”
架构操作
get_keyspaces
获取集群中所有密钥空间的列表。
- 参数:
cluster_id
get_keyspace_schema
获取特定键空间的架构信息。
- 参数:
cluster_id,keyspace
事件监控
get_events
获取集群的事件和警报。
- 参数:
cluster_id,limit(默认值:100)
📖 快速入门示例
配置后,您可以使用MCP服务器监视Cassandra集群:
示例1:列出所有集群
在VS Code Copilot聊天中:```
@datastax-opscenter get_cluster_configs
**在克劳德桌面中:**```
Show me all Cassandra clusters managed by OpsCenter
示例2:获取集群拓扑概述✨ 新```
Get a summary of all nodes in "Production_Cluster" organized by datacenter
**使用get_nodes_summary工具:**
- 显示每个数据中心的节点计数
- 列出节点IP、主机名、机架
- 轻量级响应(无大有效载荷)
### 示例3:分析数据中心读取量✨ **新**```
What is the total read request volume for all nodes in us-east1-v1
datacenter of "Production_Cluster" for the last hour?
使用get_bulk_node_metrics工具:
- 自动查询us-east1-v1中的所有15个节点
- 聚合所有节点的指标
- 返回总计、平均值、最小值、最大值统计信息
- 包括每个时间戳的细分
示例4:检查群集运行状况```
Get detailed information about the cluster "Production_Cluster"
### 示例5:监控读取性能```
Show me read operations per second for "Production_Cluster"
in the last 3 hours with 5-minute intervals
示例6:分析表性能```
What is the disk usage and read latency for the table
"users" in keyspace "app_data" on cluster "Production_Cluster"?
### 示例7:节点健康检查```
Get heap memory usage and CPU metrics for node 10.0.1.50
in cluster "Production_Cluster" for the last hour
示例1:获取集群信息```typescript
// Get all clusters
await callTool("get_cluster_configs", {});
// Get specific cluster details
await callTool("get_cluster_info", {
cluster_id: "Test_Cluster"
});
### 示例2:监控写入性能```typescript
// Get write operations per second for last hour
const now = Math.floor(Date.now() / 1000);
const oneHourAgo = now - 3600;
await callTool("get_cluster_metrics", {
cluster_id: "Test_Cluster",
datacenter: "all",
metric: "write-ops",
start: oneHourAgo,
end: now,
step: 5, // 5-minute intervals
function: "average"
});
示例3:检查节点运行状况```typescript
// Get node CPU usage
await callTool("get_node_metrics", {
cluster_id: "Test_Cluster",
node_ip: "10.11.12.150",
metric: "os-cpu-user",
start: oneHourAgo,
end: now
});
### 示例4:分析表性能```typescript
// Get table read latency
await callTool("get_table_metrics", {
cluster_id: "Test_Cluster",
datacenter: "all",
keyspace: "Keyspace1",
table: "Users",
metric: "cf-read-latency-op",
function: "max"
});
示例5:发现可用指标```typescript
// List all cluster metrics
await callTool("list_available_metrics", {
category: "cluster"
});
// List all available metrics
await callTool("list_available_metrics", {});
## 度量类别
### 集群指标
跨集群汇总的性能指标:
- 操作: `write-ops`, `read-ops`, `write-failures`, `read-failures`
- 延迟时间: `write-histogram`, `read-histogram`
- 内存: `heap-used`, `heap-max`, `nonheap-used`
- 隐藏物: `key-cache-hit-rate`, `row-cache-hit-rate`
- 压实: `pending-compaction-tasks`, `total-bytes-compacted`
### 线程池指标
线程池活动和队列深度:
- 悬而未决的: `pending-read-stage`, `pending-mutation-stage`, `pending-flushes`
- 活动: `active-read-stage`, `active-mutation-stage`
- 完整的: `completed-read-stage`, `completed-mutation-stage`
### 表度量
每张表的性能和存储:
- 操作: `cf-write-ops`, `cf-read-ops`
- 延迟时间: `cf-write-latency-op`, `cf-read-latency-op`
- 储存: `cf-live-disk-used`, `cf-total-disk-used`, `cf-live-sstables`
- SSTable统计数据: `cf-sstables-per-read`, `cf-partition-size`
### 操作系统指标
主机级资源利用率:
- CPU: `os-cpu-user`, `os-cpu-system`, `os-cpu-idle`, `os-load`
- 内存: `os-memory-used`, `os-memory-free`
- 磁盘: `os-disk-used`, `os-disk-free`, `os-disk-read-throughput`
- 网络: `os-net-received`, `os-net-sent`
## 时间范围参数
所有指标查询都支持时间范围过滤:
- `start`:Unix时间戳(秒)(范围的开始)
- `end`:Unix时间戳(秒)(范围结束)
- `step`:数据点间隔
- 对于传统API:分钟(1、5、120、1440)
- 对于新计量API:秒(60、300、7200、86400)
## 聚合函数
可以使用以下方式汇总指标:
- `min`:时间段内的最小值
- `max`:时间段内的最大值
- `average`:时间段内的平均值
## API 参考
基于DataStax操作中心6.8 API:
- 度量API文档
- 操作中心API参考
## 🛠️ 发展
### 项目结构```
datastax-opscenter-mcp/
├── src/
│ └── index.ts # Main MCP server implementation
├── build/ # Compiled JavaScript output
│ ├── index.js
│ └── index.d.ts
├── .github/
│ └── copilot-instructions.md # AI coding assistant guide
├── package.json
├── tsconfig.json
├── .gitignore
└── README.md
开发命令```bash
Install dependencies
npm install
Build the project
npm run build
Watch mode for development (auto-rebuild on changes)
npm run watch
Run the compiled server
npm start
Run directly with environment variables
OPSCENTER_URL=http://localhost:8888 npm start
### 进行更改
1. 在中编辑TypeScript源代码 `src/index.ts`
1. 跑 `npm run build` 或 `npm run watch`
1. 重新启动VS Code或Claude Desktop以获取更改
### 添加新工具
要添加新的MCP工具:
1. 将工具定义添加到 `tools` 数组in `src/index.ts`
1. 在中添加处理程序案例 `CallToolRequestSchema` 处理器
1. 用用法示例更新README
1. 重建: `npm run build`
______________________________________________________________________
## 📚 API 参考
### 可用的MCP工具
## 🔍 故障排除
### 常见问题
#### ❌ “无法连接到OpsCenter”
**问题:** `Error: connect ECONNREFUSED`
**解决:**
1. 验证OpsCenter是否正在运行:```bash
curl http://localhost:8888/cluster-configs
- 检查
OPSCENTER_URL在您的配置中 - 验证防火墙是否允许连接到OpsCenter端口(默认值:8888)
- 测试网络连接:```bash
telnet your-opscenter-host 8888
#### ❌ “身份验证失败”
**问题:** `401 Unauthorized`
**解决:**
1. 验证OpsCenter是否需要身份验证(检查OpsCenter设置)
1. 设置正确 `OPSCENTER_USERNAME` 和 `OPSCENTER_PASSWORD`
1. 如果OpsCenter不需要身份验证环境变量,请删除它们
1. 登录OpsCenter web UI检查凭据
#### ❌ “MCP服务器未显示”
**VS代码:**
1. 检查路径 `mcp-settings.json` 绝对正确
1. 验证文件是否存在: `ls /path/to/datastax-opscenter-mcp/build/index.js`
1. 检查中的语法错误 `mcp-settings.json`
1. 完全重新启动VS代码
1. 检查VS代码输出面板是否有MCP错误
**克劳德桌面:**
1. 验证配置文件位置是否与您的操作系统匹配
1. 在配置中使用绝对路径
1. 完全退出Claude Desktop(不仅仅是关闭窗口)
1. 检查克劳德桌面日志:
- **macOS:** `~/Library/Logs/Claude/`
- **窗户:** `%APPDATA%\Claude\logs\`
#### ❌ “未找到度量”
**问题:** `API Error (400): Invalid metric`
**解决:**
1. 使用 `list_available_metrics` 查看有效指标的工具:```
@datastax-opscenter list_available_metrics
- 检查度量拼写和连字符(例如。,
read-ops不read_ops) - 验证指标类别是否与您的请求匹配:
- 集群指标:使用get_cluster_metrics
- 节点指标:使用get_node_metrics
- 表指标:使用get_table_metrics
❌ “构建错误”
问题: TypeScript编译失败
解决:
- 确保Node.js版本兼容:```bash
node --version # Should be 18.x, 20.x, or 22.x
1. 清除并重新安装依赖关系:```bash
rm -rf node_modules package-lock.json
npm install
npm run build
- 检查TypeScript版本:```bash
npm list typescript
#### 🐛 调试模式
通过检查stderr输出启用详细日志记录:
**VS代码:**
- 检查输出面板→ 从下拉菜单中选择“MCP”
**克劳德桌面:**
- 检查操作系统的日志目录(见上文)
**手动测试:**```bash
OPSCENTER_URL=http://localhost:8888 node build/index.js
🤝 贡献
欢迎投稿!以下是您可以提供帮助的方式:
报告问题
- 先搜索现有问题
- 包括:
- OpsCenter版本
- Node.js版本
- 错误消息和堆栈跟踪
- 重现步骤
提交拉取请求
- 分叉存储库
- 创建要素分支:```bash
git checkout -b feature/your-feature-name
1. 进行更改
1. 彻底测试:```bash
npm run build
# Test with VS Code or Claude Desktop
- 以明确的信息承诺:
bash git commit -m "Add feature: description" - 推送并创建拉取请求
开发指南
- 遵循现有的TypeScript代码风格
- 为新功能添加JSDoc注释
- 用新功能更新README.md
- 使用经过身份验证和未经身份验证的OpsCenter进行测试
- 确保向后兼容性
📄 许可证
MIT许可证-有关详细信息,请参阅许可证文件
🙏 致谢
- 模型上下文协议 通过Anthropic
- DataStax操作中心 API文档
- Apache Cassandra 社区
📞 支持
- 问题: GitHub问题
- 讨论: GitHub讨论
- 操作输入API文档: DataStax文档
🗺️ 路线图
- []支持DataStax OpsCenter 7.x
- []Grafana风格仪表板生成
- []警报配置工具
- []备份/还原操作
- []维修管理
- []性能建议
- []WebSocket支持实时指标
由以下材料制成❤️ Cassandra社区