OBI MCP服务器
> 用于开放遥测eBPF仪器(OBI)的模型上下文协议(MCP)服务器
使AI助手能够使用OpenTetry的零代码eBPF仪器部署、配置和分析应用程序的可观察性。
目录
- 特性
- 快速开始
- 可用工具
- 资源
- 提示词
- 先决条件
- 文档
- 测试
- 项目结构
- 贡献
- 许可证
🌟 特性
- 6个MCP工具:通过人工智能助手完成OBI生命周期管理
- 3 MCP资源:实时访问配置、状态和日志
- 1 MCP提示:引导本地部署设置
- 通过AI实现零代码检测:使用自然语言命令部署OBI
- 流程生命周期管理:启动、停止和监控OBI过程
- 配置管理:通过AI辅助更新OBI配置
- 日志分析:查询和分析OBI遥测输出
- 多平台:适用于任何兼容MCP的AI客户端(Claude Desktop、Continue等)
- 99.81%的测试覆盖率:包含270个测试的综合测试套件
- 完全支持TypeScript:具有完整类型定义的类型安全实现
🚀 快速开始
5分钟设置
1.安装依赖项```bash
Clone the repository
git clone https://github.com/raibid-labs/obi-mcp.git
cd obi-mcp
Install dependencies
npm install
Build the project
npm run build
#### 2.配置克劳德桌面
添加到您的Claude Desktop配置文件中:
- **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
- **视窗**: `%APPDATA%\Claude\claude_desktop_config.json`
- **Linux**: `~/.config/Claude/claude_desktop_config.json````json
{
"mcpServers": {
"obi": {
"command": "node",
"args": ["/absolute/path/to/obi-mcp/dist/index.js"]
}
}
}
或者,在发布到npm后:```json
{
"mcpServers": {
"obi": {
"command": "npx",
"args": ["obi-mcp-server"]
}
}
}
#### 3.重新启动克劳德桌面
更新配置后,重新启动Claude Desktop以加载MCP服务器。
#### 4.与Claude一起使用```
You: "Deploy OBI with default configuration"
Claude: [Uses obi_deploy_local tool to start OBI]
You: "What's the current status of OBI?"
Claude: [Uses obi_get_status tool to check health]
You: "Show me the recent logs"
Claude: [Uses obi_get_logs tool to fetch logs]
🛠️ 可用工具
OBI MCP服务器提供6个工具来管理OpenTetry eBPF仪器:
1. obi_get_status
获取OBI流程的当前状态。
论据:
verbose(布尔值,可选):包括详细的进程信息(CPU、内存、正常运行时间)- 违约:
false
Claude中的示例用法:```
"What's the status of OBI?"
"Check if OBI is running and show me detailed metrics"
"Is OBI healthy?"
**退货:**```
=== OBI Status ===
Status: running
PID: 12345
Uptime: 3600s
--- Details ---
CPU Usage: 2.5%
Memory Usage: 150.32 MB
Config Path: /path/to/obi-config.yml
2. obi_deploy_local
以独立模式在本地部署OBI。
论据:
config(对象,可选):OBI配置对象configPath(字符串,可选):OBI配置文件的路径binaryPath(字符串,可选):OBI二进制文件的路径(如果没有提供,则使用Path)
备注:要么 config 或 configPath 应该提供。
Claude中的示例用法:```
"Deploy OBI with default configuration"
"Start OBI using the config at /etc/obi/config.yaml"
"Deploy OBI with network monitoring enabled"
**退货:**```
=== OBI Local Deployment ===
Status: SUCCESS
Message: OBI deployed successfully
PID: 12345
Config Path: /tmp/obi-config.yaml
3. obi_get_config
检索当前OBI配置。
论据: 无
Claude中的示例用法:```
"Show me the current OBI configuration"
"What's the active configuration?"
"Get OBI config"
**退货:**```
=== OBI Configuration ===
{
"network": {
"enable": true,
"allowed_attributes": ["http.method", "http.status_code"]
},
"export": {
"otlp": {
"endpoint": "localhost:4317",
"protocol": "grpc"
}
}
}
4. obi_update_config
通过验证更新OBI配置。
论据:
config(object,必填):新配置对象(或部分配置,如果merge=true)network(对象,可选):网络检测设置enable(boolean):启用网络监控allowed_attributes(string[]):允许的HTTP属性cidrs(数组):CIDR配置attributes(对象,可选):属性设置kubernetes.enable(boolean):启用Kubernetes属性export(对象,可选):导出配置otlp.endpoint(字符串):OTLP端点URLotlp.protocol(string):协议(grpc或http/protobuf)merge(布尔值,可选):与现有配置合并(默认值:true)restart(布尔值,可选):更新后重新启动OBI(默认值:false)
Claude中的示例用法:```
"Update the OTLP endpoint to localhost:4318"
"Enable Kubernetes attributes in the config"
"Change the configuration and restart OBI"
**退货:**```
=== OBI Config Update ===
Status: Success
Message: Configuration updated successfully
Note: Restart OBI for changes to take effect.
--- Updated Configuration ---
{...}
5. obi_get_logs
从OBI进程中检索最近的日志。
论据:
lines(number,可选):要检索的最近日志行数- 违约:
100 - 范围:1-10000
level(字符串,可选):按级别筛选日志- 选项:
info,warn,error,debug,all
Claude中的示例用法:```
"Show me the last 50 lines of OBI logs"
"Get error logs from OBI"
"Show recent debug logs"
**退货:**```
=== OBI Logs === [Level: ERROR] [Last 5 lines]
[2025-11-14 10:23:45] [ERROR] Failed to connect to OTLP endpoint
[2025-11-14 10:23:46] [ERROR] Retrying connection...
[2025-11-14 10:24:00] [ERROR] Connection timeout
--- End of Logs ---
6. obi_stop
停止正在运行的OBI进程。
论据:
force(boolean,可选):使用SIGKILL强制立即终止- 违约:
false(使用优雅的SIGTERM)
Claude中的示例用法:```
"Stop OBI"
"Shut down the OBI process"
"Force stop OBI immediately"
**退货:**```
=== OBI Stop ===
Status: Success
Message: OBI process stopped successfully
The OBI process has been stopped successfully.
📦 资源
MCP资源提供对OBI状态和配置的只读访问。这些可以被人工智能助手用来获取实时信息。
obi://config/current
名字:当前OBI配置
mime类型: application/json
描述:JSON格式的当前OBI配置
Claude中的用法:```
"Read the current OBI configuration resource"
**退货**:当前配置为JSON
______________________________________________________________________
### `obi://status/health`
**名字**:OBI过程健康
**mime类型**: `application/json`
**描述**:OBI流程的当前健康状况和指标
**Claude中的用法:**```
"Check the OBI health resource"
"Show me the health status"
退货:```json
{
"status": "running",
"running": true,
"pid": 12345,
"uptimeSeconds": 3600,
"cpuUsagePercent": 2.5,
"memoryUsageMB": 150.32,
"configPath": "/tmp/obi-config.yaml",
"timestamp": "2025-11-14T10:30:00.000Z"
}
______________________________________________________________________
### `obi://logs/recent`
**名字**:最近的OBI日志
**mime类型**: `text/plain`
**描述**:OBI日志的最后100行
**Claude中的用法:**```
"Read the recent logs resource"
退货:纯文本日志条目(最后100行)
💬 提示词
MCP提示为常见任务提供指导工作流程。
setup-obi-local
名字:设置OBI本地部署
描述:本地部署OBI(开放遥测eBPF仪器)的指导设置
论据:
environment(字符串,可选):目标环境类型- 选项:
development,production - 违约:
development
Claude中的用法:```
"Use the setup-obi-local prompt"
"Guide me through setting up OBI for production"
**提供**:
- 先决条件检查(内核版本、sudo访问、依赖关系)
- 配置文件模板
- 部署选项(二进制、Docker、源代码)
- 验证步骤
- 故障排除指南
- 生产检查表(当环境=生产时)
______________________________________________________________________
## 📋 先决条件
- **Node.js** >= 18.0.0
- **Linux** 内核5.8+(用于OBI eBPF支持)
- **OBI二进制** 已安装(安装指南)
- **Root/sudo访问权限** (OBI要求eBPF运行)
### 可选的
- **码头工人** (适用于集装箱化部署)
- **bpftool** (用于调试eBPF程序)
- **开放遥测采集器** (用于接收遥测数据)
## 📚 文档
- API 参考 -完整的工具、资源和提示规范
- 建筑 -系统设计和组件
- 快速入门指南 -入门指南
- 语义化版本 -提交消息和版本控制
- 发布过程 -如何创建发布
- 路线图 -未来功能和时间线
- 更新日志 -版本历史和发行说明
## 🧪 测试
该项目具有全面的测试覆盖率 **270次测试** 和 **99.81%的覆盖率**.```bash
# Run all tests
npm test
# Run with coverage report
npm test -- --coverage
# Run unit tests only
npm run test:unit
# Run integration tests (requires OBI binary)
npm run test:integration
# Run E2E tests
npm run test:e2e
# Watch mode
npm run test -- --watch
测试故障
- 单元测试:工具处理程序、资源处理程序、实用程序
- 集成测试:MCP协议集成,OBI管理器
- E2E测试:完整的生命周期工作流
🏗️ 项目结构```
obi-mcp-server/
├── src/
│ ├── index.ts # Entry point
│ ├── server/
│ │ └── index.ts # MCP server implementation
│ ├── tools/ # MCP tools (6 tools)
│ │ ├── index.ts # Tool exports
│ │ ├── status.ts # obi_get_status
│ │ ├── deploy-local.ts # obi_deploy_local
│ │ ├── get-config.ts # obi_get_config
│ │ ├── update-config.ts # obi_update_config
│ │ ├── get-logs.ts # obi_get_logs
│ │ └── stop.ts # obi_stop
│ ├── resources/ # MCP resources (3 resources)
│ │ └── index.ts # Resource handlers
│ ├── prompts/ # MCP prompts (1 prompt)
│ │ ├── index.ts # Prompt exports
│ │ └── setup-local.ts # setup-obi-local prompt
│ ├── types/
│ │ ├── obi.ts # OBI type definitions
│ │ └── mcp.ts # MCP type definitions
│ └── utils/
│ ├── logger.ts # Logging utility
│ ├── process.ts # Process management
│ └── obi-manager.ts # OBI lifecycle manager
├── tests/
│ ├── unit/ # Unit tests
│ ├── integration/ # Integration tests
│ └── e2e/ # End-to-end tests
├── docs/
│ ├── API.md # API reference
│ ├── ARCHITECTURE.md # Architecture documentation
│ ├── QUICKSTART.md # Quick start guide
│ ├── SEMANTIC_VERSIONING.md # Commit message guide
│ ├── RELEASING.md # Release process
│ ├── RELEASE_QUICKSTART.md # Quick release reference
│ └── ROADMAP.md # Feature roadmap
├── examples/
│ └── configs/ # Example configurations
├── package.json
├── tsconfig.json
├── CHANGELOG.md
└── README.md
## 🗺️ 路线图
### ✅ v0.1.0-MVP(当前版本)
- \[x\] TypeScript项目结构
- \[x\] 带stdio传输的MCP服务器
- \[x\] 6个用于OBI管理的MCP工具
- \[x\] 3个MCP资源用于配置/状态/日志
- \[x\] 1个MCP提示,用于指导设置
- \[x\] 全面的测试套件(270个测试,99.81%的覆盖率)
- \[x\] 完整的文档
- \[x\] 完全支持TypeScript
### 🚧 v0.2.0-增强功能(下)
- \[\]Docker部署支持
- \[\]基本的Kubernetes集成
- \[\]指标汇总和分析
- \[\]OTLP端点集成
- \[\]配置验证工具
- \[\]性能基准测试
### 🔮 v0.3.0-高级功能(未来)
- \[\]多实例OBI管理
- \[\]高级过滤和查询
- \[\]自定义仪器目标
- \[\]与可观测性平台集成
- \[\]实时指标流
- \[\]仪表板生成
看 ROADMAP.md 了解详细的时间线和功能规格。
## 🤝 贡献
欢迎投稿!请看 贡献.md 详细指南。
### 开发工作流程```bash
# Install dependencies
npm install
# Watch TypeScript compilation
npm run watch
# Run in development mode
npm run dev
# Run linter
npm run lint
# Format code
npm run format
# Type check
npm run typecheck
# Run all quality checks
npm run lint && npm run typecheck && npm run test:all && npm run build
提交消息约定
我们跟随 约定式提交 用于自动版本控制和变更日志生成。
格式:```
():
[optional body]
[optional footer]
**常见类型:**
|类型|效果|示例|
|------|--------|---------|
| `feat` |MINOR版本| `feat(tools): add Docker deployment` |
| `fix` |补丁版本| `fix(status): handle edge case` |
| `docs` |补丁版本| `docs(api): update examples` |
| `perf` |补丁版本| `perf(logs): optimize reading` |
| `refactor` |补丁版本| `refactor: simplify manager` |
| `test` |补丁版本| `test: add E2E tests` |
| `chore` |补丁版本| `chore(deps): update packages` |
| `feat!` |主要版本| `feat!: change API format` |
**示例:**```bash
# New feature
git commit -m "feat(tools): add Kubernetes deployment support"
# Bug fix
git commit -m "fix(status): prevent crash when OBI is not running"
# Breaking change
git commit -m "feat(config)!: restructure configuration schema
BREAKING CHANGE: Config format has changed. See migration guide."
# Documentation
git commit -m "docs(readme): add troubleshooting section"
请参阅详细指南: docs/语义_版本.md
发布过程
通过常规提交自动发布:```bash
Create release (choose based on your changes)
npm run release # PATCH: 0.1.0 → 0.1.1 (bug fixes)
npm run release:minor # MINOR: 0.1.0 → 0.2.0 (new features)
npm run release:major # MAJOR: 0.1.0 → 1.0.0 (breaking changes)
Or use just
just release
just release-minor
just release-major
**请参阅:** docs/RELEASE_QUICKSTART.md 供快速参考
## 📄 许可证
MIT许可证-请参阅 许可证 了解详情。
## 🙏 致谢
- 开放遥测社区 OBI
- Anthropic 用于模型上下文协议
- Grafana实验室 Beyla(OBI的前身)
## 🔗 链接
- OBI文件
- MCP规范
- MCP TypeScript SDK
- GitHub问题
## 💬 支持
- **GitHub问题**: 报告错误或请求功能
- **Slack**: `#otel-ebpf-instrumentation` 上 CNCF松弛
- **讨论**: GitHub讨论
______________________________________________________________________
**状态**: 🚀 Beta-准备测试
**版本**:0.1.0-初始MVP版本,包含6个工具、3个资源和1个提示。生产已准备好进行评估和测试。
### 仅使用命令
如果你有 仅仅 安装后,您可以使用方便的快捷方式:```bash
# Full setup from scratch
just setup
# Start development server
just dev
# Run all tests
just test
# Run tests with coverage
just test-coverage
# Build project
just build
# Run quality checks (typecheck + lint + test)
just check
# Show all available commands
just --list
# Interactive demo
just demo
# Get Claude Desktop setup instructions
just setup-claude
📖 用法示例
示例1:部署和监控OBI```
You: "Deploy OBI with default configuration"
Claude: ✓ Deployed OBI successfully (PID: 12345)
You: "What's the status? Show me detailed metrics"
Claude: [Shows CPU: 2.5%, Memory: 150MB, Uptime: 30s]
You: "Show me the last 50 log lines"
Claude: [Displays recent OBI logs]
### 示例2:配置管理```
You: "Show me the current OBI configuration"
Claude: [Displays config JSON]
You: "Update the configuration to enable Kubernetes attributes and restart OBI"
Claude: ✓ Configuration updated and OBI restarted
You: "Verify the new configuration is active"
Claude: [Shows updated config with Kubernetes enabled]
示例3:使用资源```
You: "What resources does the OBI server provide?"
Claude: Three resources available:
• obi://config/current - Current configuration
• obi://status/health - Health metrics
• obi://logs/recent - Recent logs
You: "Show me obi://status/health"
Claude: [Displays real-time health data]
### 示例4:故障排除```
You: "Help me set up OBI locally"
Claude: [Launches setup-obi-local prompt with step-by-step guide]
You: "OBI isn't starting - what should I check?"
Claude: Let me help debug:
1. Checking if OBI is already running... ✓ Not running
2. Checking prerequisites...
3. Attempting to deploy with verbose logging...
You: "Show me error logs from the last hour"
Claude: [Filters and displays error-level logs]
