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工具指标名称快速查找指南
- **** -开发指南和项目架构
�🔧 安装
1.克隆存储库
git clone https://github.com/yourusername/datastax-opscenter-mcp.git
cd datastax-opscenter-mcp2.安装依赖项
npm install3.建设项目
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：
code ~/.vscode/mcp-settings.json窗户：
code %APPDATA%\Code\User\mcp-settings.json如果文件不存在，请创建它。
2.添加服务器配置
将以下内容添加到您的 mcp-settings.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：
~/Library/Application Support/Claude/claude_desktop_config.json窗户：
%APPDATA%\Claude\claude_desktop_config.jsonLinux：
~/.config/Claude/claude_desktop_config.json2.编辑配置文件
打开配置文件并添加MCP服务器：
{
"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
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.构建和运行
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、主机名、机架
- 用例：无需大负载即可快速查看集群拓扑
- 示例:
{
"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 （可选）-默认值：“平均”
- 退货:
- 聚合时间序列（每个时间戳的总数、平均数、最小值、最大值） - 全面统计 - 每个节点的详细信息和错误状态
- 用例：获取整个数据中心的总读/写量
- 示例:
{
"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：获取集群信息
// Get all clusters
await callTool("get_cluster_configs", {});
// Get specific cluster details
await callTool("get_cluster_info", {
cluster_id: "Test_Cluster"
});示例2：监控写入性能
// 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：检查节点运行状况
// 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：分析表性能
// 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：发现可用指标
// 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：
🛠️ 发展
项目结构
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开发命令
# 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进行更改
- 在中编辑TypeScript源代码
src/index.ts - 跑
npm run build或npm run watch - 重新启动VS Code或Claude Desktop以获取更改
添加新工具
要添加新的MCP工具：
- 将工具定义添加到
tools数组insrc/index.ts - 在中添加处理程序案例
CallToolRequestSchema处理器 - 用用法示例更新README
- 重建：
npm run build
______________________________________________________________________
📚 API 参考
可用的MCP工具
🔍 故障排除
常见问题
❌ “无法连接到OpsCenter”
问题： Error: connect ECONNREFUSED
解决：
- 验证OpsCenter是否正在运行：
curl http://localhost:8888/cluster-configs- 检查
OPSCENTER_URL在您的配置中 - 验证防火墙是否允许连接到OpsCenter端口（默认值：8888）
- 测试网络连接：
telnet your-opscenter-host 8888❌ “身份验证失败”
问题： 401 Unauthorized
解决：
- 验证OpsCenter是否需要身份验证（检查OpsCenter设置）
- 设置正确
OPSCENTER_USERNAME和OPSCENTER_PASSWORD - 如果OpsCenter不需要身份验证环境变量，请删除它们
- 登录OpsCenter web UI检查凭据
❌ “MCP服务器未显示”
VS代码：
- 检查路径
mcp-settings.json绝对正确 - 验证文件是否存在：
ls /path/to/datastax-opscenter-mcp/build/index.js - 检查中的语法错误
mcp-settings.json - 完全重新启动VS代码
- 检查VS代码输出面板是否有MCP错误
克劳德桌面：
- 验证配置文件位置是否与您的操作系统匹配
- 在配置中使用绝对路径
- 完全退出Claude Desktop（不仅仅是关闭窗口）
- 检查克劳德桌面日志：
- macOS： ~/Library/Logs/Claude/ - 窗户： %APPDATA%\Claude\logs\
❌ “未找到度量”
问题： API Error (400): Invalid metric
解决：
- 使用
list_available_metrics查看有效指标的工具：
@datastax-opscenter list_available_metrics- 检查度量拼写和连字符（例如。，
read-ops不read_ops) - 验证指标类别是否与您的请求匹配：
- 集群指标：使用 get_cluster_metrics - 节点指标：使用 get_node_metrics - 表指标：使用 get_table_metrics
❌ “构建错误”
问题： TypeScript编译失败
解决：
- 确保Node.js版本兼容：
node --version # Should be 18.x, 20.x, or 22.x- 清除并重新安装依赖关系：
rm -rf node_modules package-lock.json
npm install
npm run build- 检查TypeScript版本：
npm list typescript🐛 调试模式
通过检查stderr输出启用详细日志记录：
VS代码：
- 检查输出面板→ 从下拉菜单中选择“MCP”
克劳德桌面：
- 检查操作系统的日志目录（见上文）
手动测试：
OPSCENTER_URL=http://localhost:8888 node build/index.js______________________________________________________________________
🤝 贡献
欢迎投稿！以下是您可以提供帮助的方式：
报告问题
- 先搜索现有问题
- 包括：
- OpsCenter版本 - Node.js版本 - 错误消息和堆栈跟踪 - 重现步骤
提交拉取请求
- 分叉存储库
- 创建要素分支：
git checkout -b feature/your-feature-name- 进行更改
- 彻底测试：
npm run build
# Test with VS Code or Claude Desktop- 以明确的信息承诺：
git commit -m "Add feature: description"- 推送并创建拉取请求
开发指南
- 遵循现有的TypeScript代码风格
- 为新功能添加JSDoc注释
- 用新功能更新README.md
- 使用经过身份验证和未经身份验证的OpsCenter进行测试
- 确保向后兼容性
______________________________________________________________________
📄 许可证
MIT许可证-有关详细信息，请参阅许可证文件
______________________________________________________________________
🙏 致谢
- 模型上下文协议 通过Anthropic
- DataStax操作中心 API文档
- Apache Cassandra 社区
______________________________________________________________________
📞 支持
- 问题：
- 讨论：
- 操作输入API文档： DataStax文档
______________________________________________________________________
🗺️ 路线图
- \[\]支持DataStax OpsCenter 7.x
- \[\]Grafana风格仪表板生成
- \[\]警报配置工具
- \[\]备份/还原操作
- \[\]维修管理
- \[\]性能建议
- \[\]WebSocket支持实时指标
______________________________________________________________________
由以下材料制成❤️ Cassandra社区