NetBeez MCP服务器
一个模型上下文协议(MCP)服务器,将LLM客户端(Cursor、Claude Desktop等)连接到 NetBeez 的 网络监控平台。支持人工智能辅助的网络故障排除、监控分析和事件调查。
特性
- 32工具 用于查询和管理代理、代理组、目标、测试、计划测试模板、警报、事件、WiFi配置文件、统计数据、路径分析,以及运行ad-hoc Iperf/sepeed/VoIP/自定义命令测试(包括多代理运行状态)
- 5资源 向LLM提供NetBeez数据模型知识、交叉代理关联方法、故障排除工作流程、完整的API参考资料和特别测试指南
- 5个提示模板 对于常见工作流:排除目标故障、分析代理运行状况、调查事件、网络概述、运行即席测试
- 双重运输:stdio(用于Cursor/Claude Desktop)和HTTP(用于远程客户端)
快速入门(推荐)
运行一行安装程序——它处理一切:Node.js、依赖关系、构建、凭据和MCP客户端配置:```bash
curl -fsSL https://raw.githubusercontent.com/netbeez/nb-mcp-server/main/install.sh | bash
安装程序将提示您:
1. 你的 **NetBeez实例URL** (例如。 `https://demo1.netbeezcloud.net`)
1. 你的 **API密钥** (来自仪表板→ 设置→ API密钥)
1. **SSL 验证** 首选项(对于自签名证书禁用)
1. 哪个 **MCP客户端** 配置(光标、克劳德桌面、Windsurf、Codex、Kiro)
该脚本是幂等的——随时重新运行它以更新到最新版本或更改配置。
### 开发安装(无需git推送)
从该仓库的克隆中,使用以下命令运行安装程序 `--dev` 将Cursor、Claude Desktop、Codex、Windsurf和Kiro指向您的本地版本:```bash
./install.sh --dev
# or from anywhere:
bash ~/path/to/nb-mcp-server/install.sh --dev
做 不 使用 cat install.sh | bash --这样脚本就不会接收任何参数 --dev 被忽略。
这跳过了克隆;它使用当前目录,运行 npm install 和 npm run build,然后配置相同的MCP客户端以使用 ./dist/index.js。更改后,运行 npm run build 并重新启动客户端——无需推送到git进行测试。
安装程序的作用
| 步骤 | 详细信息 |
|---|---|
| Node.js | 检查Node.js 18+;如果缺少,则通过Homebrew、apt或nvm安装 |
| 下载 | 从GitHub下载最新源代码(不需要git)并提取到 ~/.netbeez-mcp |
| 构建 | 运行 npm install 和 npm run build |
| 配置 | 提示凭据和写入 ~/.netbeez-mcp/.env |
| MCP客户端 | 将服务器条目合并到Cursor/Claude Desktop/Windsurf/Codex/Kiro配置中 |
先决条件
如果您更喜欢手动安装,则需要:
- Node.js 18+
- 具有API访问权限的NetBeez BeezKeeper实例
- API键(仪表板→ 设置→ API密钥)
单行安装程序只需要Node.js 18+和curl(无git)。
手动安装
1.下载并构建```bash
curl -fsSL https://github.com/netbeez/nb-mcp-server/archive/refs/heads/main.tar.gz -o nb-mcp-server.tar.gz
tar -xzf nb-mcp-server.tar.gz && cd nb-mcp-server-main
npm install
npm run build
### 2.配置
复制示例环境文件并填写您的值:```bash
cp .env.example .env
编辑 .env:```
NETBEEZ_BASE_URL=https://your-instance.netbeezcloud.net
NETBEEZ_API_KEY=your-api-key-here
### 3.跑步```bash
npm start
MCP客户端配置
光标
添加到光标MCP设置(~/.cursor/mcp.json):```json
{
"mcpServers": {
"netbeez": {
"command": "node",
"args": ["~/.netbeez-mcp/dist/index.js"],
"env": {
"NETBEEZ_BASE_URL": "https://your-instance.netbeezcloud.net",
"NETBEEZ_API_KEY": "your-api-key-here"
}
}
}
}
### 克劳德桌面
添加到您的Claude桌面配置(`~/Library/Application Support/Claude/claude_desktop_config.json`):```json
{
"mcpServers": {
"netbeez": {
"command": "node",
"args": ["~/.netbeez-mcp/dist/index.js"],
"env": {
"NETBEEZ_BASE_URL": "https://your-instance.netbeezcloud.net",
"NETBEEZ_API_KEY": "your-api-key-here"
}
}
}
}
帆板运动
添加到您的Windsurf MCP配置(~/.codeium/windsurf/mcp_config.json):```json
{
"mcpServers": {
"netbeez": {
"command": "node",
"args": ["~/.netbeez-mcp/dist/index.js"],
"env": {
"NETBEEZ_BASE_URL": "https://your-instance.netbeezcloud.net",
"NETBEEZ_API_KEY": "your-api-key-here"
}
}
}
}
### 法典
添加到您的Codex配置(`~/.codex/config.json`):```json
{
"mcpServers": {
"netbeez": {
"command": "node",
"args": ["~/.netbeez-mcp/dist/index.js"],
"env": {
"NETBEEZ_BASE_URL": "https://your-instance.netbeezcloud.net",
"NETBEEZ_API_KEY": "your-api-key-here"
}
}
}
}
基罗
添加到您的Kiro用户MCP配置(~/.kiro/settings/mcp.json):```json
{
"mcpServers": {
"netbeez": {
"command": "node",
"args": ["~/.netbeez-mcp/dist/index.js"],
"env": {
"NETBEEZ_BASE_URL": "https://your-instance.netbeezcloud.net",
"NETBEEZ_API_KEY": "your-api-key-here"
}
}
}
}
Kiro还支持工作区级别的MCP配置 `.kiro/settings/mcp.json`.
> **提示:** 安装程序(`curl | bash` 上面)会自动写入这些配置文件。
## 更新
重新运行安装程序以获取最新版本并重新生成:```bash
curl -fsSL https://raw.githubusercontent.com/netbeez/nb-mcp-server/main/install.sh | bash
您现有的凭据将显示为默认值——按Enter键保留它们。
如果您安装了 --dev,跑 npm run build 在仓库中,重新启动MCP客户端以获取更改。
卸载```bash
rm -rf ~/.netbeez-mcp
然后移除 `"netbeez"` 从MCP客户端配置文件中输入。
## 环境变量
|变量|必填|默认|描述|
|----------|----------|---------|-------------|
| `NETBEEZ_BASE_URL` |是|--|BeezKeeper实例URL|
| `NETBEEZ_API_KEY` |是|-|用于身份验证的API密钥|
| `NETBEEZ_SSL_VERIFY` |没有| `true` |设置为 `false` 用于自签名证书|
| `MCP_TRANSPORT` |没有| `stdio` |运输方式: `stdio`, `http`,或 `both` |
| `MCP_HTTP_PORT` |没有| `3000` |HTTP传输端口|
## 工具(32)
### 代理工具(6)
|工具|说明|
|------|-------------|
| `list_agents` |列出所有代理,并按名称、类别、类、活动状态进行筛选|
| `get_agent` |按ID获取特定代理的详细信息|
| `search_agents` |按名称搜索代理(精确或正则表达式)|
| `get_agent_logs` |获取连接/断开事件日志(包括无线WiFi/DHCP)|
| `get_agent_performance_metrics` |获取CPU、内存、磁盘随时间的使用情况|
| `get_agent_access_point_connections` |获取WiFi接入点连接历史记录(SSID/BSSID、信号、DHCP)以进行无线故障排除|
### 代理组工具(4)
|工具|说明|
|------|-------------|
| `list_agent_groups` |列出具有过滤和分页功能的代理组|
| `get_agent_group` |获取具有关系的单个代理组|
| `create_agent_group` |创建一个包含成员代理和可选目标分配的代理组|
| `update_agent_group` |更新现有代理组(名称、成员、目标、auto_assign)|
### 目标工具(6)
|工具|说明|
|------|-------------|
| `list_targets` |列出带有过滤器的监控目标(代理组、开放事件、WiFi/有线等)|
| `get_target` |使用测试模板获取目标详细信息|
| `create_target` |创建自定义监控目标(原始JSON:API负载)|
| `create_target_saas` |从内置SaaS应用程序创建目标|
| `create_target_from_template` |从简化的模板(网站、DNS、VPN、网关)创建目标|
| `update_target` |按ID更新现有目标(原始JSON:API负载)|
### 测试和结果工具(3)
|工具|说明|
|------|-------------|
| `list_tests` |列出所有监控测试(ping/dns/http/traceroute/path_analysis)|
| `get_test_results` |按类型、时间范围和代理过滤器获取测试结果|
| `get_path_analysis_results` |获取逐跳路径分析数据|
### 预定测试工具(5)
|工具|说明|
|------|-------------|
| `list_scheduled_test_templates` |列出带过滤器的计划Iperf、网络速度和VoIP模板|
| `get_scheduled_test_template` |按ID获取计划测试模板|
| `create_scheduled_test_template` |创建计划的Iperf/Speed/VoIP模板|
| `update_scheduled_test_template` |更新现有的计划测试模板|
| `get_scheduled_test_results` |按时间范围和代理获取计划模板的结果(带宽、VoIP质量、Iperf)|
### 警报和事故工具(2)
|工具|说明|
|------|-------------|
| `list_alerts` |列出具有广泛过滤功能的警报(严重性、状态、时间、代理、目标)|
| `list_incidents` |列出事件及其时间线、确认状态和事件日志|
### 统计工具(3)
|工具|说明|
|------|-------------|
| `get_test_statistics` |随时间变化的聚合测试性能统计数据|
| `get_agent_statistics` |代理正常运行时间/可用性统计|
| `get_access_point_metrics` |WiFi信号质量指标(信号、质量、速率)|
### 临时和其他(3)
|工具|说明|
|------|-------------|
| `run_adhoc_test` |运行按需Iperf测试(代理到代理或代理通过IP/FQDN到服务器)、网络速度测试、VoIP测试(代理对代理)或自定义命令测试(一个或多个代理上的脚本);返回多代理运行ID|
| `get_multiagent_test_run_status` |按ID获取多代理测试运行的状态和结果(使用后 `run_adhoc_test` 轮询或检索结果)|
| `list_wifi_profiles` |列出WiFi配置文件及其事件状态|
## 资源(5)
|资源|URI|描述|
|----------|-----|-------------|
|NetBeez数据模型| `netbeez://data-model` |实体关系、数据形状、时间序列数据目录|
|相关指南| `netbeez://correlation-guide` |跨代理关联方法、警报解释|
|故障排除指南| `netbeez://troubleshooting-guide` |分步故障排除工作流程|
|API参考| `netbeez://api-reference` |JSON的全面端点参考:API和遗留统计API|
|临时测试指南| `netbeez://ad-hoc-tests` |Ad hoc Iperf/Speed/VoIP/自定义命令有效负载、轮询和结果解析|
## 提示(5)
|提示|参数|描述|
|--------|-----------|-------------|
| `troubleshoot-target` | `target_name` 或 `target_id` |指导工作流程以诊断目标问题|
| `analyze-agent-health` | `agent_name` 或 `agent_id` |全面的代理人健康检查|
| `investigate-incident` | `incident_id` |深入了解特定事件|
| `network-overview` |(无)|总体网络健康状况摘要|
| `run-adhoc-test` | `test_type`, `agent_hint`, `destination_hint` |Iperf、速度、VoIP和自定义命令测试的引导式即席执行流程|
## 发展```bash
# Build
npm run build
# Watch mode
npm run dev
# Test with MCP Inspector
npm run inspect
建筑```
src/
├── index.ts # Entry point, transport setup
├── server.ts # MCP server definition, registration
├── config.ts # Environment variable loading
├── api/
│ ├── base-client.ts # Shared HTTP client (fetch, retries, errors)
│ ├── jsonapi-client.ts # JSON:API client (Bearer auth, filters, pagination)
│ ├── legacy-client.ts # Legacy API client (API-VERSION v1)
│ └── types.ts # TypeScript types for all entities
├── tools/
│ ├── agents.ts # Agent tools (6)
│ ├── agent-groups.ts # Agent group tools (4)
│ ├── targets.ts # Target tools (6)
│ ├── tests.ts # Test tools (2)
│ ├── incidents.ts # Incident tools (1)
│ ├── alerts.ts # Alert tools (1)
│ ├── wifi.ts # WiFi tools (1)
│ ├── scheduled-tests.ts # Scheduled test template & results tools (5)
│ ├── statistics.ts # Statistics tools (3)
│ ├── path-analysis.ts # Path analysis tools (1)
│ ├── actions.ts # Ad-hoc test tools (2): run_adhoc_test, get_multiagent_test_run_status
│ └── ad-hoc.ts # Re-exports actions for ad-hoc tests
├── resources/
│ ├── data-model.ts # Entity relationships and data shapes
│ ├── correlation-guide.ts # Cross-agent correlation patterns
│ ├── troubleshooting-guide.ts
│ ├── api-reference.ts # API endpoint reference
│ └── ad-hoc-tests.ts # Ad-hoc tests payloads and result parsing guide
└── prompts/
├── troubleshoot-target.ts
├── analyze-agent-health.ts
├── investigate-incident.ts
├── network-overview.ts
└── run-adhoc-test.ts
```
API覆盖范围
服务器与两个NetBeez API层通信:
- JSON:API (主要):使用的所有实体和关系端点
Authorization: Bearer身份验证。支持过滤、分页、包含和排序。 - 传统API:三个统计端点(
nb_test_statistics,nb_agent_statistics,access_point_metrics)使用Authorization:+API-VERSION: v1标题。
许可证
麻省理工学院
