Wave-Engineering/mcp-server-wtf

# WTF (Why That Failed) 一个用于在 Claude Code 内部进行故障排查的飞行记录器。WTF 将 每一次工具调用和手动观察捕获到一个持久的 SQLite 数据库中，该数据库能够在上下文压缩后依然保留数据，随后通过后台分类器对原始记录进行丰富，并生成一条精炼的时间线。 ## 前置条件 - [Claude Code](https://claude.ai/code) CLI (`claude`) - `jq` (JSON 处理器) - `curl` 或 `wget` - 用于 Bedrock 的 AWS 凭证（可选 — 启用后台分类器） ## 安装 ``` curl -fsSL https://raw.githubusercontent.com/Wave-Engineering/mcp-server-wtf/main/scripts/install-remote.sh | bash ``` 这会为您的平台下载一个预编译的二进制文件，安装 PostToolUse hook，并注册 MCP server。无需克隆或运行时环境。 技能 (`/wtf`, `/wtf now`, `/wtf happened`, `/wtf imout`) 由 [claudecode-workflow](https://github.com/Wave-Engineering/claudecode-workflow) 提供。 验证安装： ``` curl -fsSL https://raw.githubusercontent.com/Wave-Engineering/mcp-server-wtf/main/scripts/install-remote.sh | bash -s -- --check ``` 安装特定版本： ``` curl -fsSL https://raw.githubusercontent.com/Wave-Engineering/mcp-server-wtf/main/scripts/install-remote.sh | bash -s -- --version v1.0.0 ``` ### 开发安装 如果您正在开发 WTF server 本身，请克隆仓库并使用本地安装程序（需要 [Bun](https://bun.sh)）： ``` git clone https://github.com/Wave-Engineering/mcp-server-wtf.git cd mcp-server-wtf ./scripts/install.sh ``` ## 快速开始 ``` # 开始 troubleshooting /wtf # 调查问题……Claude 会自动记录 tool calls # 获取提炼后的 timeline wtf_happened # 添加你自己的观察 /wtf now "DNS resolver returning stale records" ``` ## 架构概述 WTF 是一个三层系统： ``` /wtf, /wtf now Skills (user-facing entry points) | v wtf_now, wtf_happened MCP Server (journal storage, retrieval, wtf_freshell background classification) ^ | PostToolUse hook Auto-capture (every tool call -> JSONL queue) ``` **第一层 -- 技能：** `/wtf` 启动故障排查会话并激活 飞行记录器模式。`/wtf now` 会添加手动日志条目。 **第二层 -- MCP Server：** 一个基于 Bun + TypeScript 的服务器，通过 stdio 传输暴露四个工具。它管理一个 SQLite 数据库，提取 hook 队列数据，并运行一个 后台分类器（通过 AWS Bedrock 调用 Claude Haiku），将条目分类为 操作、线索、推测或噪音。 **第三层 -- PostToolUse Hook：** 一个 shell 脚本，在每次 Claude Code 工具调用时触发，提取相关字段，截断过大的值，并将一行 JSON 追加到 `.wtf/hook-queue.jsonl` 中以便提取。 ## 用法 ### 启动会话 ``` /wtf ``` 归档任何之前的事件并创建一个新事件。提示输入可选的 标题，然后将 Claude 置于飞行记录器模式，在该模式下，重要的观察结果 会自动记录到日志中。 ### 记录观察结果 ``` /wtf now the health endpoint is returning 503s /wtf now "theory: connection pool exhaustion under load" /wtf now checked nginx logs — 502s started at 14:32 ``` 向日志中添加一条手动条目。分类工作由后台分类器处理。 ### 获取时间线 调用 `wtf_happened` MCP 工具（Claude 可以直接调用它，或者您可以主动 要求它）： ``` wtf_happened # summary (max 50 lines) wtf_happened { detail: "full" } # all entries ``` 返回一条精炼的 Markdown 时间线： ``` ## WTF 总结 -- DNS Resolution Failure **Duration:** 45 min | **Entries:** 127 raw, 34 distilled | **Status:** active 1. [12:03] BREADCRUMB -- Health endpoint returning 503s intermittently 2. [12:05] THEORY -- Connection pool exhaustion, idle timeout set to 0 3. [12:08] ACTION -- Set DB_POOL_IDLE_TIMEOUT=30s in .env ``` ### 暂停记录 ``` /wtf imout ``` 暂停飞行记录器且不会丢失数据。在切换到 非故障排查工作时非常有用。Hook 仍然会触发，但条目会被过滤掉。 ### 生成运行手册 `wtf_happened` 还会将一个运行手册框架写入 `.wtf/runbook.md`，该文件可以被 完善为可复用的操作手册。 ### 清除 / 重新开始 ``` wtf_freshell ``` 归档当前事件并开始一个新事件。之前的条目将 保留在数据库中。 ## 配置 ### 数据目录 所有运行时数据都位于项目根目录（已被 gitignore 忽略）下的 `.wtf/` 中： ``` .wtf/ wtf.db SQLite database (WAL mode) hook-queue.jsonl Hook queue (consumed by MCP server) runbook.md Generated runbook skeleton ``` ### 可调参数 | 参数 | 默认值 | 位置 | |-----------|---------|----------| | 队列轮询间隔 | 2,000 ms | `queue.ts` | | 分类器轮询间隔 | 5,000 ms | `classifier/worker.ts` | | 分类器速率限制 | 2,000 ms | `classifier/worker.ts` | | Hook 截断限制 | 4,096 bytes | `scripts/hooks/wtf-post-tool-use.sh` | | 摘要行数上限 | 50 lines | `tools/happened.ts` | ### MCP Server 注册 远程安装程序会注册已编译的二进制文件： ``` claude mcp add --scope user --transport stdio wtf-server -- ~/.local/bin/wtf-server ``` 开发安装程序直接注册 Bun 源代码： ``` claude mcp add --scope user --transport stdio wtf-server -- bun /path/to/mcp-server-wtf/index.ts ``` ### Hook 配置 PostToolUse hook 在 `~/.claude/settings.json` 中配置： ``` { "hooks": { "PostToolUse": [ { "type": "command", "command": "/absolute/path/to/scripts/hooks/wtf-post-tool-use.sh" } ] } } ``` ## 卸载 如果通过远程安装程序安装： ``` curl -fsSL https://raw.githubusercontent.com/Wave-Engineering/mcp-server-wtf/main/scripts/install-remote.sh | bash -s -- --uninstall ``` 如果从本地克隆安装： ``` ./scripts/install.sh --uninstall ``` 这两者都会移除 MCP server 注册和 hook 配置。针对各个项目的 `.wtf/` 数据目录会被保留（它们包含事件 历史记录）。要移除它们： ``` rm -rf .wtf/ ``` ## 许可证 MIT -- 见 [LICENSE](LICENSE)。

标签：AI编程辅助, API集成, Claude Code, Cutter, MCP, SOC Prime, SQLite, 可观测性, 开发工具, 故障排查, 自动化攻击