mcp-tester-hot-swap-development

name	mcp-tester-hot-swap-development
description	Iterative MCP server replacement without client restart or session loss. 熱換伺服器，不斷客端，不失狀態。 Use when: developing MCP servers iteratively, replacing server binary mid-session, avoiding reconnection overhead.
disable-model-invocation	true

Hot-Swap MCP Development Workflow

引導開發者行熱換工作流，以 mcp-debug 為器。

Overview

熱換開發，替換 MCP 伺服器實作，無須：

• 重啟 Claude Code 或他 MCP 客端
• 丟棄除錯歷史
• 更改工具名或前綴

The Problem

舊式 MCP 開發流程：

1. 改程式碼
2. 重建伺服器
3. 重啟伺服器
4. 重連客端
5. 復原狀態
6. 測試更動
7. 往復...

每輪迭代耗時於重連與狀態復原。

The Solution

mcp-debug 開熱換之道：

1. 改程式碼
2. 重建伺服器
3. 呼叫 server_disconnect 繼以 server_reconnect
4. 即刻測試

客端持連，狀態保全。

Workflow Steps

1. Initial Setup

先加入開發伺服器：

Use server_add tool:
- name: "myserver"
- command: "go run ./cmd/server" (or your dev command)

2. Development Cycle

每改程式碼後：

1. 建新版本

   go build -o ./bin/server-v2 ./cmd/server
   # or: npm run build
   # or: cargo build --release
   

2. 斷當前伺服器

   Use server_disconnect tool:
   - name: "myserver"
   

   工具仍登記，呼叫暫佇。

3. 以新執行檔重連

   Use server_reconnect tool:
   - name: "myserver"
   - command: "./bin/server-v2"
   

4. 驗工具可用

   Use server_list tool to confirm connection
   Test a tool to verify functionality
   

3. Debugging Changes

以除錯工具驗行為：

• debug_logs — 檢視請求/回應流量
• debug_status — 查連線健康
• schema_validate — 驗模式更動

Server Management Tools

server_add

動態加入新伺服器：

server_add with:
- name: "myserver"
- command: "python server.py"

server_disconnect

暫停伺服器（工具仍登記）：

server_disconnect with:
- name: "myserver"

server_reconnect

以新執行檔重連：

server_reconnect with:
- name: "myserver"
- command: "./new-binary"

server_list

列所有伺服器及狀態：

server_list

server_remove

完全移除伺服器：

server_remove with:
- name: "myserver"

Workflow Patterns

Pattern 1: Watch and Rebuild

# Terminal 1: Watch and rebuild
watchexec -e go -- go build -o bin/myserver ./cmd/server

# In Claude Code: After each rebuild
# Call server_disconnect then server_reconnect

Pattern 2: A/B Testing

1. 測版本 A
2. 以 server_reconnect 熱換至版本 B
3. 測版本 B
4. 以 debug_logs 比對行為

Pattern 3: Debug Mode Toggle

# Normal mode
server_reconnect with command="./server"

# Debug mode with extra logging
server_reconnect with command="./server --debug --verbose"

Best Practices

1. 用版本化執行檔 — 命名含版本，便於回滾
2. 換後查日誌 — 驗無流量錯誤
3. 先測關鍵工具 — 確認核心功能
4. 保留前版執行檔 — 問題時快速回滾

Troubleshooting

伺服器不重連：

• 查命令路徑正確否
• 驗執行檔有執行權限
• 查有無埠衝突（若用網路）

換後工具消失：

• 伺服器或已更改工具定義
• 以 server_list 查現有工具
• 查伺服器日誌中初始化錯誤

意外行為：

• 以 debug_logs 比對換前換後請求
• 驗模式未作不相容更改