OBI MCP服务器

](https://github.com/raibid-labs/obi-mcp/releases) ![License](./LICENSE) ![Tests](./tests) ![Coverage](./tests) ![Conventional Commits](https://conventionalcommits.org) ![TypeScript](https://www.typescriptlang.org/)

用于开放遥测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.安装依赖项

# 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

{
  "mcpServers": {
    "obi": {
      "command": "node",
      "args": ["/absolute/path/to/obi-mcp/dist/index.js"]
    }
  }
}

或者，在发布到npm后：

{
  "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端点URL - otlp.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"

退货:

{
  "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%的覆盖率.

# 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 详细指南。

开发工作流程

# 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`

示例：

# 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

发布过程

通过常规提交自动发布：

# 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的前身）

🔗 链接

💬 支持

GitHub问题: 报告错误或请求功能
Slack: #otel-ebpf-instrumentation 上 CNCF松弛
讨论:

______________________________________________________________________

状态: 🚀 Beta-准备测试

版本：0.1.0-初始MVP版本，包含6个工具、3个资源和1个提示。生产已准备好进行评估和测试。

仅使用命令

如果你有仅仅安装后，您可以使用方便的快捷方式：

# 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]

obi MCP

快速接入

详细介绍

OBI MCP服务器

目录

🌟 特性

🚀 快速开始

5分钟设置

1.安装依赖项

2.配置克劳德桌面

3.重新启动克劳德桌面

4.与Claude一起使用

🛠️ 可用工具

1. obi_get_status

2. obi_deploy_local

3. obi_get_config

4. obi_update_config

5. obi_get_logs

6. obi_stop

📦 资源

obi://config/current

obi://status/health

obi://logs/recent

💬 提示词

setup-obi-local

📋 先决条件

可选的

📚 文档

🧪 测试

测试故障

🏗️ 项目结构

🗺️ 路线图

✅ v0.1.0-MVP（当前版本）

🚧 v0.2.0-增强功能（下）

🔮 v0.3.0-高级功能（未来）

🤝 贡献

开发工作流程

提交消息约定

发布过程

📄 许可证

🙏 致谢

🔗 链接

💬 支持

仅使用命令

📖 用法示例

示例1：部署和监控OBI

示例2：配置管理

示例3：使用资源

示例4：故障排除

目录标签

接入字段

权限和风险

来源信息

继续浏览同类 MCP

1. `obi_get_status`

2. `obi_deploy_local`

3. `obi_get_config`

4. `obi_update_config`

5. `obi_get_logs`

6. `obi_stop`

`obi://config/current`

`obi://status/health`

`obi://logs/recent`

`setup-obi-local`