错误报告检索服务器

Telebugs MCP服务器

MCP（模型上下文协议）服务器，允许AI代理从Telebugs检索错误报告，Telebugs是一种自托管的哨兵替代方案。

建筑

┌─────────────────┐                           ┌─────────────────────────────────────┐
│  Local Machine  │                           │              Remote VPS             │
│                 │         HTTPS             │                                     │
│  Claude Desktop │ ◄───────────────────────► │  Bun MCP Server   ───►  Telebugs    │
│                 │      (SSE transport)      │     :3100              SQLite DB    │
└─────────────────┘                           └─────────────────────────────────────┘

特征

• REST API后端（增量） -何时 TELEBUGS_API_BASE_URL 设置，项目和成员工具调用Telebugs REST API（添加在Telebugs 1.16.0中），而不是直接写入SQLite。没有REST等效工具的工具继续使用数据库，当没有配置REST时，每个支持REST的工具都会退回到直接访问数据库。
• 直接数据库访问 -读取和写入Telebugs SQLite数据库
• MCP OAuth身份验证 -Telebugs用户支持的基于浏览器的OAuth流
• API密钥验证 -仍然接受现有Telebugs用户API密钥作为承载令牌
• 访问控制 -用户只能看到他们所属的项目
• SSE运输 -允许远程克劳德桌面连接
• 结构化输出 -每个工具都声明 outputSchema 并返回 structuredContent；故障信号为 isError 这样客户端就可以从数据中分辨出错误
• 代币高效 -压缩JSON，默认仅打开错误
• 单个二进制 -交叉编译到Linux，无运行时依赖关系

可用工具

list_error_groups

退货 total_count 用于分页。

list_reports

退货 total_count 用于分页。

搜索错误

resolve_error_group/unresolve_error组/unmute_error组

这些工具只需要 group_id （数字）。

mute_error_group

add_note

delete_note

create_project（仅限管理员）

update_project（仅限管理员）

delete_project/regenerate_project_token（仅限管理员）

这些工具只需要 project_id （数字）。

add_project_member/remove_project_member（仅限管理员）

获取项目令牌/列表项目成员

这些工具只需要 project_id （数字）。

list_platforms

没有参数。返回所有可用的平台名称。

安装

cd telebugs-mcp
bun install

构建

# Build for current platform
bun run build

# Build for Linux (for VPS deployment)
bun run build:linux

配置

Telebugs REST API（增量迁移）

Telebugs 1.16.0引入了REST API(/api/telebugs/v1).该服务器正在逐渐将直接数据库访问转移到API上。集 TELEBUGS_API_BASE_URL 选择加入：

TELEBUGS_API_BASE_URL=https://telebugs.example.com/api/telebugs/v1 bun run start

用户自己的Telebugs API密钥(users.api_key, tlbgs_...)作为REST承载令牌转发-对于API-key会话，它是客户端已经发送的令牌；对于OAuth会话，它是从用户记录中读取的。如果用户没有API密钥，则该用户的REST-based工具将回退到直接访问DB。

REST支持时间 TELEBUGS_API_BASE_URL 已设置 （否则直接联系DB）：

• list_projects, create_project, update_project, delete_project
• get_project_token, add_project_member, remove_project_member

仍然直接DB （目前还没有等效的REST，否则REST会改变行为）：

• list_project_members --REST端点需要管理员；我们允许任何项目成员列出，因此这将保留在DB上，以避免非管理员回归。
• regenerate_project_token --没有REST端点。
• 所有错误组、报告、搜索、注释、统计信息、发布和源映射工具都将随着REST API通过ID、注释和统计信息端点获得组/报告寻址而迁移。

本地运行

TELEBUGS_DB_PATH=/path/to/telebugs/storage/db/development.sqlite3 bun run dev

部署

单一二进制

# 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/:

cp telebugs-mcp.service /etc/systemd/system/
systemctl daemon-reload
systemctl enable telebugs-mcp
systemctl start telebugs-mcp

检查状态：

systemctl status telebugs-mcp

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元数据，打开浏览器登录页面，并使用颁发的承载令牌重试：

{
  "mcpServers": {
    "telebugs": {
      "url": "https://your-server/mcp"
    }
  }
}

当MCP服务器在反向代理后面运行时，设置 MCP_BASE_URL 到公共HTTPS源：

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）：

{
  "mcpServers": {
    "telebugs": {
      "url": "http://your-server:3100/mcp",
      "headers": {
        "Authorization": "Bearer your_telebugs_api_key"
      }
    }
  }
}

获取API密钥

1. 登录您的Telebugs实例
2. 转到用户→ 账户设置→ 安全
3. 复制API密钥

安全

• 仅限管理员的项目管理操作（创建、更新、删除、令牌再生、成员资格）
• 写入操作仅限于错误状态更改、注释和项目管理
• 所有突变都适用于用户的项目成员资格
• 仅针对活动用户验证API密钥
• OAuth访问令牌是短暂的；OAuth客户端和令牌哈希值被持久化，以进行重新身份验证和刷新
• 按用户的项目成员资格筛选的所有查询
• 参数化查询（无SQL注入）

健康检查

curl http://localhost:3100/health
# {"status":"ok"}

许可证

麻省理工学院