incident-assistant — MCP "Hello World"

一个测试用 MCP（Model Context Protocol）服务器，按照 MCP 书籍/课程中的"事件响应"练习构建——区别在于这里接入的是 Claude Code 作为客户端，而不是 Gemini CLI。

该服务器模拟一个生产系统的警报仪表盘，并暴露：

• 一个资源（resource://incidents/active），包含活动警报列表（模拟数据）。

• 一个工具（resolve_incident），通过"重启"服务来解决警报，模拟成功率为 80%（这样你也能看到失败路径）。

源代码：src/index.ts

技术栈

• @modelcontextprotocol/sdk — 官方的 TypeScript/Node MCP SDK。

• stdio 传输方式（客户端将服务器作为子进程启动，它们通过 stdin/stdout 通信）。

• TypeScript 编译到 dist/（参见 tsconfig.json）。

1. 安装并构建

npm install
npx tsc

这将把 src/index.ts 编译为 dist/index.js（启动服务器的入口点）。

注意：服务器内部特意使用 console.error 进行日志记录——stdout 保留给 MCP JSON-RPC 协议使用，因此任何 console.log 都会破坏与客户端的通信。

2. 向 Claude Code 注册服务器

与书中不同（书中使用 Gemini CLI 的 settings.json），在 Claude Code 中，本地 MCP 服务器通过 claude mcp add 命令注册：

cd /absolute/path/to/incident-assistant
claude mcp add --scope project incident-assistant -- node /absolute/path/to/incident-assistant/dist/index.js

要点：

• -- 用于将 claude mcp add 自身的标志与启动服务器的实际命令分隔开。

• 使用指向 dist/index.js 的绝对路径（相对路径会相对于启动 claude 的目录解析，而不是相对于 .mcp.json 所在的位置）。

• --scope project 将配置存储在仓库根目录的 .mcp.json 中（可在 git 中进行版本控制）。备选方案：--scope local（仅对我私有，不共享）或 --scope user（可用于我的所有项目，存储在 ~/.claude.json 中）。

这会生成一个本地 .mcp.json，其中写入了你机器的绝对路径。由于该路径特定于你的环境，.mcp.json 本身已被 gitignore——仓库改为提供 .mcp.json.example，展示带有占位符路径的预期结构：

{
  "mcpServers": {
    "incident-assistant": {
      "type": "stdio",
      "command": "node",
      "args": ["/absolute/path/to/incident-assistant/dist/index.js"]
    }
  }
}

3. 批准服务器

由于 .mcp.json 是项目文件（它可能来自共享仓库），Claude Code 会在首次使用时要求明确批准：

claude

启动时，它会为 incident-assistant 显示一个信任提示——每个项目接受一次即可（除非之后服务器的命令/参数发生变化）。

4. 验证

claude mcp list
claude mcp get incident-assistant

批准后的预期输出：

incident-assistant: node /absolute/path/to/incident-assistant/dist/index.js - ✔ Connected

在 claude 会话中，/mcp 会列出服务器可用的工具/资源。

5. 演示——实际结果

给代理的提示："是否有任何严重警报？如果有，请尝试修复它们并告诉我结果"

代理：

1. 列出了可用的 MCP 资源（listMcpResources），并找到了 resource://incidents/active。

2. 读取了该资源（readMcpResource），获得了模拟警报：

   ID	服务	状态	消息
   ALRT-001	auth-api	🔴 CRITICAL	检测到内存泄漏
   ALRT-002	payment-gateway	🟡 WARNING（非严重）	延迟 > 500ms

3. 确定只有 ALRT-001 是严重警报，并调用 resolve_incident 工具，参数为 serviceName: "auth-api"。

4. 结果：

   ✅ 已修复：auth-api 已优雅重启以清除内存泄漏（ALRT-001，CRITICAL）。重启成功。

   ⚠️ 未处理：payment-gateway 仍显示 WARNING（延迟 > 500ms），但这不是严重问题，因此保持原样。

   代理的说明：重启清除的是症状，不一定是根本原因——值得持续关注 auth-api 的内存，以确认泄漏不会再次发生。

5. 当被明确要求*"也重启 payment-gateway"*时，代理会再次调用 resolve_incident，参数为 serviceName: "payment-gateway"（这里没有记录确切结果，因为它取决于 80% 的模拟成功率——可能返回 ✅ 或 ❌ FAILURE）。

这验证了完整闭环：MCP 客户端（Claude Code）→ 资源/工具发现 → 读取资源 → 决策 → 工具调用 → 结果。

致谢

本练习基于/学习自 maliksahil/mcp-incident-assistant。原始教程使用 Gemini CLI 作为 MCP 客户端；本仓库将同一个服务器改编为与 Claude Code 配合使用。

注意事项 / 陷阱

• 服务器在 WSL 下运行；由于在此环境中 Claude Code 也是从 WSL 终端启动的，.mcp.json 中的路径是原生 Linux 路径（例如 /home/<user>/...），而不是 Windows UNC 路径（\\wsl.localhost\...）。

• 如果编辑了 src/index.ts，需要重新构建（npx tsc）后更改才会生效——服务器从 dist/index.js 启动，而不是直接使用 .ts 文件。

• resolve_incident 故意模拟了 80% 的成功率（Math.random() > 0.2），因此你可以观察代理如何处理成功和失败（isError: true）两种情况。