observer-launch-mcp

向 Claude 询问有关你的 Observe 数据的问题——最近的错误、常见故障、按 Pod 统计的日志量——无需手动编写 OPAL。这是一个 MCP 服务器，让 Claude 直接、实时访问你的 Observe 租户。

设置（2 步）

1. 运行设置向导。 它会询问你的 Observe 凭据和数据集别名，然后自动向 Claude Code 注册自身：

npx @aryanbansal-launch/observer-launch-mcp init

系统会要求你提供：

• Observe customer ID —— 一个数字，可在你的 Observe URL 中找到。

• Observe API key —— 在 Manage account → My API tokens 创建一个。（不是 ingest/datastream token——它们看起来相似，但在这里不起作用。）

• Cluster —— 例如 eu-1。如果你使用默认的美国租户，请留空。

• Dataset aliases（可选）—— 你经常询问的数据集的友好名称，例如 launch-management → 41249178。在 Observe UI 中找到 ID：打开数据集，它就在 URL 中。你可以跳过此步骤，改用原始数据集 ID，或稍后添加别名。

2. 重启 Claude Code（或启动新会话），以便它加载新服务器。确认它是否正常工作：

Is the Observe connection working?

就这样——下面的其他工具现在可以在聊天中使用。

claude mcp add observe -s user \
  -e OBSERVE_CUSTOMER_ID=<your id> \
  -e OBSERVE_API_KEY=<your token> \
  -e OBSERVE_CLUSTER=eu-1 \
  -e OBSERVE_DATASETS='{"launch-management":"41249178"}' \
  -- node <path to installed server.js>

如果你只想要绝对路径，请先运行一次 npx @aryanbansal-launch/observer-launch-mcp init —— 它会在运行前打印出它将执行的确切命令。使用直接的 node <path> 命令，而不是 npx <package> 作为最终条目 —— Claude Code 会在裸环境（无 PATH）中启动已注册的服务器，而 npx 自身的 shebang 需要 PATH 来找到 node，因此 npx 作为命令会静默显示“Failed to connect.”。向导已经为你避免了这种情况。

Related MCP server: Fathom AI MCP Server

你可以问什么

设置完成后，只需自然地与 Claude 交谈：

• “Observe 连接是否正常？”

• “我配置了哪些服务/数据集别名？”

• “显示过去一小时内 launch-management 的最近错误”

• “本周 launch-nginx 中最常见的错误是什么？”

• “现在哪些 Pod 在 launch-management-bg 中记录日志最多？”

• “过去 6 小时内 launch-nginx 产生了多少 stderr 输出？”

• “统计过去一小时内 launch-telemetry 中每个 Pod 的日志行数”

• “从 launch-logs-bg-exporter 拉取最后 20 行原始日志”

对于任何未涵盖的特定问题形式，只需描述你的需求——Claude 将使用通用查询工具为你编写 OPAL 管道。

工具参考

get_error_summary 和 get_log_stats 在服务器端聚合，因此无论时间窗口如何，它们都保持快速。get_service_errors 和 run_opal_query 会在你查询 6 小时以上且未聚合的窗口时添加警告，因为宽窗口上的原始行转储可能触及 Observe 的 100k 行上限。

日志格式

一个租户中的数据集很少共享日志模式，因此 get_service_errors 和 get_error_summary 会按数据集检测格式（每个进程一次）并构建匹配的查询：

每个结果都会说明检测到的格式。要跳过探测，请在数据集配置中声明它：

{ "launch-nginx": { "id": "41250854", "shape": "http" } }

普通的 "alias": "id" 条目仍然有效，并且会自动检测。

覆盖率会被报告，而不是隐藏。 在 level 数据集上，某些行没有可解析的 level 字段（堆栈跟踪、裸字符串、非 JSON 输出），严重性过滤器无法看到它们。当该比例超过 1% 时，工具会说明：

Note: 529 of 2136 rows (24.8%) have no parseable "level" field and were not
scanned. Pass includeUnparsed=true to keyword-match those too.

includeUnparsed=true 会对这些行进行关键字扫描。它是可选的，因为关键字匹配也会标记仅包含“error”一词的 info 行。

配置参考

数据集 ID 是租户特定的，并且有意不随此包捆绑。如果没有配置任何内容，别名查找会失败，你仍然可以直接向任何工具传递原始数字数据集 ID。

故障排除

• 健康检查失败 → 你的 API 密钥可能是 ingest/datastream token，而不是来自 Manage account → My API tokens 的 token。请重新生成。

• claude mcp list 在手动注册的条目上显示“Failed to connect” → 检查命令是否为 node <path>，而不是 npx <package>（参见上面的提示）。

• 工具返回“Unknown service/dataset” → 运行 list_known_services 查看已配置的内容，或改为传递原始数字数据集 ID。

• get_service_errors/get_error_summary 没有返回有用信息 → 检查结果上的“Detected log format”注释。如果猜测错误，请使用 {"alias": {"id": "...", "shape": "http"}} 显式固定格式（参见 日志格式）。如果显示 text，则你的日志没有严重性字段，匹配基于关键字。

• 你在 Observe UI 中可以看到的错误在结果中缺失 → 查找覆盖率注释。默认情况下，没有可解析 level 的行会被跳过；传递 includeUnparsed=true。

贡献

npm install
npm run build   # tsc, then chmod +x on the bin entry
npm publish      # only if you intend to ship a new version

复制 src/run-server.ts 中的 get_error_summary/get_log_stats 模式，用于其他重复的 OPAL 查询（例如按服务成本、延迟百分位数）——为工具提供描述性名称/描述，以便 Claude 在适当时选择它而不是 run_opal_query。