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 文件。