Telebugs MCP服务器
MCP(模型上下文协议)服务器,允许AI代理从Telebugs检索错误报告,Telebugs是一种自托管的哨兵替代方案。
建筑```
┌─────────────────┐ ┌─────────────────────────────────────┐
│ Local Machine │ │ Remote VPS │
│ │ HTTPS │ │
│ Claude Desktop │ ◄───────────────────────► │ Bun MCP Server ───► Telebugs │
│ │ (SSE transport) │ :3100 SQLite DB │
└─────────────────┘ └─────────────────────────────────────┘
## 特性
- **直接数据库访问** -读取和写入Telebugs SQLite数据库
- **MCP OAuth身份验证** -Telebugs用户支持的基于浏览器的OAuth流
- **API密钥验证** -仍然接受现有Telebugs用户API密钥作为承载令牌
- **访问控制** -用户只能看到他们所属的项目
- **SSE运输** -允许远程克劳德桌面连接
- **代币高效** -压缩JSON,默认仅打开错误
- **单个二进制** -交叉编译到Linux,无运行时依赖关系
## 可用工具
|工具|说明|
|------|-------------|
| `list_projects` |列出所有可访问的项目|
| `list_error_groups` |列出具有过滤功能的重复数据消除错误组|
| `get_error_group` |获取特定错误组的详细信息|
| `list_reports` |列出单个错误事件|
| `get_report` |获取包含回溯、面包屑和上下文的完整报告|
| `get_statistics` |获取聚合错误统计信息|
| `search_errors` |在错误中进行全文搜索|
| `list_releases` |列出带有工件计数的项目的所有版本|
| `list_release_artifacts` |列出发布时上传的工件|
| `get_sourcemap_status` |检查调试ID是否有可用的源映射|
| `resolve_error_group` |解决错误组(标记为已修复)|
| `unresolve_error_group` |重新打开已解决的错误组|
| `mute_error_group` |将具有可选过期时间的错误组静音|
| `unmute_error_group` |取消静音错误组|
| `add_note` |向错误组添加注释|
| `delete_note` |从错误组中删除注释(仅限作者)|
| `create_project` |创建新项目(仅限管理员)|
| `update_project` |更新项目名称或时区(仅限管理员)|
| `delete_project` |软删除项目(仅限管理员)|
| `get_project_token` |获取项目的令牌/DSN以进行SDK配置|
| `regenerate_project_token` |重新生成项目的令牌(仅限管理员)|
| `add_project_member` |将用户添加到项目中(仅限管理员)|
| `remove_project_member` |从项目中删除用户(仅限管理员)|
| `list_project_members` |列出具有角色的项目成员|
| `list_platforms` |列出可用于项目创建的平台名称|
### list_error_groups
|参数|类型|默认值|说明|
|-----------|------|---------|-------------|
| `project_id` |number |-|按项目ID筛选|
| `status` |字符串| `"open"` | `"open"`, `"resolved"`, `"muted"`,或 `"all"` |
| `error_type` |string |-|按确切错误类型筛选|
| `error_message` |string |-|按错误消息筛选(子字符串匹配)|
| `from` |string |-|开始日期(ISO 8601)|
| `to` |string |-|结束日期(ISO 8601)|
| `limit` |number |20|最大结果(1-100)|
| `offset` |number |0 |跳过N个结果进行分页|
退货 `total_count` 用于分页。
### list_reports
|参数|类型|默认值|说明|
|-----------|------|---------|-------------|
| `group_id` |number |-|按错误组ID筛选|
| `project_id` |number |-|按项目ID筛选|
| `from` |string |-|开始日期(ISO 8601)|
| `to` |string |-|结束日期(ISO 8601)|
| `limit` |number |20|最大结果(1-100)|
| `offset` |number |0 |跳过N个结果进行分页|
退货 `total_count` 用于分页。
### 搜索错误
|参数|类型|默认值|说明|
|-----------|------|---------|-------------|
| `query` |string |必填|全文搜索查询|
| `project_id` |number |-|按项目ID筛选|
| `limit` |number |20|最大结果(1-100)|
### resolve_error_group/unresolve_error组/unmute_error组
这些工具只需要 `group_id` (数字)。
### mute_error_group
|参数|类型|默认值|说明|
|-----------|------|---------|-------------|
| `group_id` |number |必填|错误组ID|
| `muted_until` |string |-|可选的ISO 8601日期,直到该组被静音|
### add_note
|参数|类型|默认值|说明|
|-----------|------|---------|-------------|
| `group_id` |number |必填|错误组ID|
| `content` |string |必填|备注内容|
### delete_note
|参数|类型|默认值|说明|
|-----------|------|---------|-------------|
| `group_id` |number |必填|错误组ID|
| `note_id` |number |必填|要删除的笔记ID|
### create_project(仅限管理员)
|参数|类型|默认值|说明|
|-----------|------|---------|-------------|
| `name` |string |必填|项目名称(唯一)|
| `platform` |string |必填|平台名称--使用 `list_platforms` 查看选项|
| `timezone` |字符串| `"UTC"` |项目时区(例如。 `"America/New_York"`) |
### update_project(仅限管理员)
|参数|类型|默认值|说明|
|-----------|------|---------|-------------|
| `project_id` |number |必填|要更新的项目ID|
| `name` |string |-|新项目名称|
| `timezone` |string |-|新时区|
### delete_project/regenerate_project_token(仅限管理员)
这些工具只需要 `project_id` (数字)。
### add_project_member/remove_project_member(仅限管理员)
|参数|类型|默认值|说明|
|-----------|------|---------|-------------|
| `project_id` |number |必填|项目ID|
| `user_id` |number |必填|要添加/删除的用户ID|
### 获取项目令牌/列表项目成员
这些工具只需要 `project_id` (数字)。
### list_platforms
没有参数。返回所有可用的平台名称。
## 安装```bash
cd telebugs-mcp
bun install
构建```bash
Build for current platform
bun run build
Build for Linux (for VPS deployment)
bun run build:linux
## 配置
|变量|描述|默认值|
|----------|-------------|---------|
| `TELEBUGS_DB_PATH` |Telebugs SQLite数据库的路径| `/var/lib/docker/volumes/telebugs-data/_data/db/production.sqlite3` |
| `PORT` |要侦听的HTTP端口| `3100` |
| `MCP_BASE_URL` |OAuth元数据和重定向的公共基础URL |根据请求推断|
| `OAUTH_ACCESS_TOKEN_TTL_SECONDS` |MCP OAuth访问令牌的生命周期| `43200` |
| `TELEBUGS_SECRET_KEY_BASE` |Telebugs Rails `secret_key_base`,需要接受Telebugs登录链接|未设置|
## 本地运行```bash
TELEBUGS_DB_PATH=/path/to/telebugs/storage/db/development.sqlite3 bun run dev
部署
单一二进制```bash
Copy to server
scp telebugs-mcp-linux root@your-server:~/telebugs-mcp-linux
On server
chmod +x ~/telebugs-mcp-linux
./telebugs-mcp-linux
### systemd服务
复制 `telebugs-mcp.service` 到 `/etc/systemd/system/`:```bash
cp telebugs-mcp.service /etc/systemd/system/
systemctl daemon-reload
systemctl enable telebugs-mcp
systemctl start telebugs-mcp
检查状态:```bash
systemctl status telebugs-mcp
### Nginx反向代理(可选)```nginx
location /mcp {
proxy_pass http://127.0.0.1:3100;
proxy_http_version 1.1;
proxy_set_header Host $host;
proxy_set_header X-Real-IP $remote_addr;
proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
proxy_set_header X-Forwarded-Proto $scheme;
# SSE support
proxy_set_header Connection '';
proxy_buffering off;
proxy_cache off;
chunked_transfer_encoding off;
}
Claude桌面配置
对于支持OAuth的MCP客户端,仅配置服务器URL。客户端将发现OAuth元数据,打开浏览器登录页面,并使用颁发的承载令牌重试:```json
{
"mcpServers": {
"telebugs": {
"url": "https://your-server/mcp"
}
}
}
当MCP服务器在反向代理后面运行时,设置 `MCP_BASE_URL` 到公共HTTPS源:```bash
MCP_BASE_URL=https://your-server bun run start
OAuth登录页面由React渲染,CSS由Bun的Tailwind插件从Tailwind生成。它与Telebugs登录页面匹配,显示请求客户端和重定向来源,并在发出授权码之前需要明确批准。它接受您的Telebugs电子邮件/密码,并使用相同的bcrypt进行验证 users.password_digest 由Telebugs使用。它还可以接受来自Telebugs的登录链接 /session/transfers/... 当 TELEBUGS_SECRET_KEY_BASE 设置为使MCP服务器可以派生Rails active_record/signed_id 验证器密钥,并验证签名的id有效载荷。
如果Telebugs配置了 RAILS_MASTER_KEY 而不是 SECRET_KEY_BASE,使用以下命令从Telebugs应用程序读取值 bin/rails runner 'puts Rails.application.secret_key_base' 并将其传递给此服务器 TELEBUGS_SECRET_KEY_BASE.
对于尚不支持MCP OAuth的客户端,静态承载令牌仍然有效。添加 ~/Library/Application Support/Claude/claude_desktop_config.json (macOS):```json
{
"mcpServers": {
"telebugs": {
"url": "http://your-server:3100/mcp",
"headers": {
"Authorization": "Bearer your_telebugs_api_key"
}
}
}
}
### 获取API密钥
1. 登录您的Telebugs实例
1. 转到用户→ 账户设置→ 安全
1. 复制API密钥
## 安全
- 仅限管理员的项目管理操作(创建、更新、删除、令牌再生、成员资格)
- 写入操作仅限于错误状态更改、注释和项目管理
- 所有突变都适用于用户的项目成员资格
- 仅针对活动用户验证API密钥
- OAuth访问令牌是短暂的,由MCP服务器保存在内存中
- 按用户的项目成员资格筛选的所有查询
- 参数化查询(无SQL注入)
## 健康检查```bash
curl http://localhost:3100/health
# {"status":"ok"}
许可证
麻省理工学院
