MCP Rewatch

🚀 MCP Rewatch

MCP Rewatch 是一个模型上下文协议（MCP）服务器，它能让像 Claude Code 这样的 AI 编码助手管理长期运行的开发进程。如果没有这个工具，Claude Code 无法运行像 npm run dev 这样的命令，因为它会阻塞并等待进程完成，最终在没有看到任何输出的情况下超时。

🚀 快速开始

单项目快速设置

1. 将 MCP Rewatch 添加到 Claude Code：

# 使用 npx（无需安装）
claude mcp add rewatch npx -- mcp-rewatch

# 或者如果全局安装
claude mcp add rewatch mcp-rewatch

# 或者用于本地开发
claude mcp add rewatch node -- /path/to/mcp-rewatch/dist/index.js

2. 在项目根目录创建 rewatch.config.json。
3. 从项目目录启动 Claude Code，MCP Rewatch 会在当前工作目录中查找配置文件。

用户范围设置（全局访问）

要使 MCP Rewatch 在所有 Claude Code 会话中可用：

claude mcp add -s user rewatch npx -- mcp-rewatch

重要提示：服务器会在 Claude Code 运行的当前工作目录中查找 rewatch.config.json。每个项目都需要有自己的配置文件。

管理多个项目

工作原理：MCP Rewatch 会在 Claude Code 运行的当前工作目录中查找 rewatch.config.json。 最佳实践：

1. 保持配置文件特定于项目：每个项目都应该有自己的 rewatch.config.json。
2. 使用相对路径：在配置中，使用相对的 cwd 路径，如 "./backend" 或 "./frontend"。
3. 从项目根目录启动 Claude Code：始终从项目目录启动 Claude Code。

多服务配置示例：

{
  "processes": {
    "frontend": {
      "command": "npm",
      "args": ["run", "dev"],
      "cwd": "./frontend"
    },
    "backend": {
      "command": "npm",
      "args": ["run", "dev"],
      "cwd": "./backend"
    },
    "database": {
      "command": "docker",
      "args": ["compose", "up", "postgres"],
      "cwd": "./"
    }
  }
}

✨ 主要特性

• 后台运行进程：Claude Code 不会被阻塞。
• 捕获所有输出：标准输出/标准错误输出会保存在内存缓冲区中。
• 提供异步访问：Claude Code 可以随时查看日志。
• 支持重启：Claude Code 可以在进行更改后重启服务器。
• 管理多个进程：可以同时运行前端、后端和数据库服务器。

📦 安装指南

通过 npm 全局安装：

npm install -g mcp-rewatch

或者直接使用 npx（无需安装）：

npx mcp-rewatch

📚 详细文档

问题描述

在使用 Claude Code 进行开发时，会遇到一个基本限制：

# Claude Code 尝试运行开发服务器时的情况：
$ npm run dev

> my-app@1.0.0 dev
> next dev

▲ Next.js 14.0.0
- Local: http://localhost:3000

[Claude Code 现在会卡在这，等待进程退出]
[大约 2 分钟后，它会在没有看到任何输出的情况下超时]
[Claude Code 永远看不到编译错误、成功消息或任何日志]

Claude Code 无法做到以下几点：

• ❌ 查看长期运行进程的任何输出
• ❌ 知道开发服务器是否成功启动
• ❌ 检查编译错误
• ❌ 在进行更改后重启服务器
• ❌ 同时运行多个开发进程

这使得使用 Claude Code 进行有效开发几乎变得不可能，因为你需要手动运行所有开发服务器，并在更改后手动重启它们。

解决方案

MCP Rewatch 充当 Claude Code 和你的开发进程之间的桥梁：

• 在后台运行进程：Claude Code 不会被阻塞。
• 捕获所有输出：标准输出/标准错误输出会保存在内存缓冲区中。
• 提供异步访问：Claude Code 可以随时查看日志。
• 支持重启：Claude Code 可以在进行更改后重启服务器。
• 管理多个进程：可以同时运行前端、后端和数据库服务器。

工作原理

MCP Rewatch 充当 Claude Code 和你的开发进程之间的中介：

1. 作为独立服务运行：Claude Code 可以通过 MCP 与之通信。
2. 独立管理进程：将开发服务器作为子进程启动。
3. 非阻塞操作：Claude Code 可以启动/重启进程并立即继续。
4. 异步日志检索：Claude Code 可以稍后查看日志而不会被阻塞。
5. 正确处理生命周期：优雅关闭，不会产生孤儿进程。

这种架构允许 Claude Code 有效地管理长期运行的进程，尽管它本身无法直接运行这些进程。

配置

在项目根目录（即你将运行 Claude Code 的地方）创建一个 rewatch.config.json 文件。

startupDelay 应根据你的具体进程进行调整：

• 快速工具（脚本、小型服务器）：1000 - 2000 毫秒
• Next.js/React 开发服务器：3000 - 5000 毫秒
• 大型构建进程：5000 - 10000 毫秒
• 依赖服务：8000 - 15000 毫秒

{
  "processes": {
    "convex": {
      "command": "pnpm",
      "args": ["dlx", "convex", "dev"],
      "cwd": "./",
      "startupDelay": 5000
    },
    "nextjs": {
      "command": "pnpm",
      "args": ["dev"],
      "cwd": "./",
      "env": {
        "PORT": "3000"
      },
      "startupDelay": 4000 
    },
    "backend": {
      "command": "npm",
      "args": ["run", "dev"],
      "cwd": "./backend",
      "env": {
        "NODE_ENV": "development",
        "PORT": "8080"
      },
      "startupDelay": 2000
    }
  }
}

配置选项

• command：要运行的可执行文件（例如，npm、pnpm、node）
• args：命令参数数组
• cwd：进程的工作目录（相对于 MCP 服务器运行的位置，即项目根目录）
• env：额外的环境变量（可选）
• startupDelay：启动后等待检查状态的时间（以毫秒为单位，默认值：3000）
• readyPattern：（尚未实现 - 请参阅路线图）

可用工具

配置完成后，Claude Code 可以使用以下工具：

restart_process

按名称停止并重启开发进程。等待配置的 startupDelay（或默认 3 秒），然后返回初始日志。

await restart_process({ name: "nextjs" })
// 输出:
// 进程 'nextjs' 成功启动
//
// 初始日志:
// [2024-01-07T10:00:01.123Z] [stdout] > my-app@1.0.0 dev
// [2024-01-07T10:00:01.456Z] [stdout] > next dev
// [2024-01-07T10:00:02.789Z] [stdout] ▲ Next.js 14.0.0
// [2024-01-07T10:00:03.012Z] [stdout] - Local: http://localhost:3000

get_process_logs

从进程中检索日志，可选择限制行数。

await get_process_logs({ name: "nextjs", lines: 50 })
// 返回 Next.js 进程的最后 50 行日志

await get_process_logs({ name: "convex" })
// 返回 Convex 进程的所有可用日志

list_processes

列出所有配置的进程及其当前状态。

await list_processes()
// 输出:
// nextjs: 运行中 (PID: 12345)
// convex: 已停止

stop_all

优雅地停止所有正在运行的进程。

await stop_all()
// 输出: "所有进程已停止"

典型工作流程

以下是 Claude Code 在开发过程中使用 MCP Rewatch 的方式：

1. 初始设置（你只需执行一次）：
   • 在项目中创建 rewatch.config.json。
   • 启动 Claude Code，服务器可以按需启动。
2. 开发过程中，Claude Code 会：
   • 对文件进行代码更改。
   • 调用 restart_process({ name: "nextjs" }) 重启服务器。
   • 自动接收 3 秒启动延迟后的初始日志。
   • 检查日志中的成功指标或错误。
   • 根据结果继续进行更多更改。
   • 如果需要，稍后调用 get_process_logs({ name: "nextjs" })。
3. 主要优点：
   • Claude Code 不会被长期运行的进程阻塞。
   • 你无需在每次更改后手动重启服务器。
   • Claude Code 可以通过检查日志来验证更改是否生效。
   • 可以并行管理多个服务器。

restart_process 调用时的工作原理

1. 停止任何具有该名称的现有进程。
2. 启动新进程。
3. 等待配置的 startupDelay（默认值：3 秒）。
4. 返回启动状态和初始日志。

这使 Claude Code 能够立即获得以下方面的反馈：

• 进程是否成功启动。
• 是否立即出现错误（端口冲突、缺少依赖项）。
• 服务器是否开始编译/构建。

对于持续监控，Claude Code 可以使用 get_process_logs 稍后检查进度。

重要性

没有 MCP Rewatch，使用 Claude Code 进行开发的流程会令人沮丧：

• ❌ Claude Code 尝试 npm run dev → 阻塞并超时。
• ❌ 你进行更改 → 服务器崩溃 → 需要手动重启。
• ❌ 无法检查更改是否成功编译。

有了 MCP Rewatch：

• ✅ Claude Code 使用 restart_process → 立即返回。
• ✅ 服务器在更改后自动重启。
• ✅ Claude Code 可以检查日志以验证成功。

故障排除

• 进程无法启动：检查项目根目录中是否存在 rewatch.config.json。
• 权限错误：确保配置中的命令具有适当的执行权限。
• 找不到工具：验证 MCP Rewatch 是否出现在 Claude Code 的 MCP 菜单中。
• 日志未显示：进程可能正在缓冲输出；某些服务器需要特定标志来禁用缓冲。

开发

要为 MCP Rewatch 做出贡献：

git clone https://github.com/brennancheung/mcp-rewatch.git
cd mcp-rewatch
pnpm install
pnpm build

对于开发，你可以将 Claude Code 直接指向构建输出：

# 构建项目
pnpm build

# 添加到 Claude Code
claude mcp add rewatch-dev node -- /path/to/mcp-rewatch/dist/index.js

然后在你进行测试的任何目录中创建一个 rewatch.config.json 文件。