mcp-integration-debug

name	mcp-integration-debug
description	MCP server 連不上、tools/list/call 出錯時的診斷和除錯。當使用者遇到 MCP 相關的技術問題時使用。

MCP 整合除錯 (MCP Integration Debug) 工作流程

本技能旨在提供一個系統化的方法來診斷和解決 MCP (Model Context Protocol) 伺服器連接和工具呼叫的問題。

何時使用此技能

• MCP 伺服器無法連接（「MCP 伺服器連不上」）
• 工具列表無法載入（tools/list 失敗）
• 工具呼叫出錯（mcp.call_tool 返回錯誤）
• 工具返回意外的結果
• MCP 伺服器間歇性連接失敗
• 需要驗證 MCP 伺服器的配置

工具需求

• mcp.list_tools: 列出 MCP 伺服器提供的所有工具
• mcp.call_tool: 呼叫特定的 MCP 工具
• 系統日誌和診斷工具（可選）

除錯工作流程

步驟 1: 收集基本信息

與使用者溝通，收集關於問題的基本信息。

信息收集清單:

• MCP 伺服器的名稱和版本
• 問題首次出現的時間
• 是否曾經正常工作過
• 最近是否進行了任何配置或環境變更
• 錯誤訊息的確切內容
• 問題的重現步驟
• 涉及的具體工具名稱（如果適用）

步驟 2: 驗證 MCP 伺服器的連接狀態

檢查 MCP 伺服器是否可以被存取和連接。

連接驗證步驟:

• 確認 MCP 伺服器進程是否正在運行
• 檢查伺服器監聽的端口是否正確
• 驗證網絡連接（如果是遠程伺服器）
• 檢查防火牆和安全組設定
• 驗證認證憑證（如果需要）
• 測試基本的連接（例如，ping 或 telnet）

診斷命令範例:

# 檢查伺服器進程
ps aux | grep mcp-server

# 檢查監聽的端口
netstat -tuln | grep :PORT_NUMBER

# 測試連接
telnet localhost PORT_NUMBER

# 檢查防火牆規則
sudo iptables -L -n | grep PORT_NUMBER

步驟 3: 驗證 MCP 伺服器配置

檢查 MCP 伺服器的配置是否正確。

配置驗證清單:

• 檢查伺服器配置檔案的語法（JSON/YAML）
• 驗證所有必需的配置參數是否存在
• 檢查環境變數是否正確設定
• 驗證依賴項是否已安裝
• 檢查日誌檔案中是否有啟動錯誤
• 驗證伺服器的版本是否與預期相符

配置檢查範例:

# 驗證 JSON 配置
python3 -m json.tool /path/to/config.json

# 檢查環境變數
env | grep MCP

# 查看伺服器日誌
tail -f /var/log/mcp-server.log

# 檢查伺服器版本
mcp-server --version

步驟 4: 測試工具列表

使用 mcp.list_tools 驗證伺服器是否能夠返回工具列表。

工具列表測試步驟:

• 呼叫 mcp.list_tools 並檢查是否返回成功
• 驗證返回的工具列表是否非空
• 檢查工具定義是否完整（包括名稱、描述、輸入 schema）
• 識別任何缺失或損壞的工具定義
• 比較返回的工具列表與預期的工具列表

測試程式碼範例:

import mcp

try:
    tools = mcp.list_tools()
    print(f"成功列出 {len(tools)} 個工具")
    for tool in tools:
        print(f"  - {tool['name']}: {tool['description']}")
except Exception as e:
    print(f"列出工具失敗: {e}")
    print(f"錯誤類型: {type(e).__name__}")

步驟 5: 測試單個工具呼叫

選擇一個簡單的工具進行測試，驗證工具呼叫機制是否正常。

工具呼叫測試步驟:

• 選擇一個簡單的、無副作用的工具進行測試
• 準備最小化的輸入參數
• 呼叫工具並記錄返回值和任何錯誤
• 驗證返回值的格式是否符合預期
• 檢查是否有任何超時或性能問題

測試程式碼範例:

import mcp

# 選擇一個簡單的工具進行測試
tool_name = "example_tool"
tool_input = {"param1": "test_value"}

try:
    result = mcp.call_tool(tool_name, tool_input)
    print(f"工具呼叫成功")
    print(f"返回值: {result}")
except mcp.ToolNotFoundError as e:
    print(f"工具未找到: {tool_name}")
except mcp.InvalidInputError as e:
    print(f"輸入參數無效: {e}")
except mcp.ToolExecutionError as e:
    print(f"工具執行失敗: {e}")
except Exception as e:
    print(f"未預期的錯誤: {e}")

步驟 6: 診斷特定錯誤

根據遇到的具體錯誤進行診斷。

常見錯誤及診斷:

錯誤	可能原因	診斷步驟
連接被拒絕	伺服器未運行或端口錯誤	檢查伺服器進程和端口配置
超時	伺服器響應緩慢或網絡問題	檢查伺服器性能和網絡延遲
工具未找到	工具名稱錯誤或工具未註冊	驗證工具列表和工具名稱
無效的輸入	輸入參數不符合 schema	檢查工具的輸入 schema 定義
認證失敗	認證憑證不正確	驗證認證配置和憑證
內部伺服器錯誤	伺服器端的程式碼錯誤	檢查伺服器日誌和錯誤堆棧

步驟 7: 生成診斷報告

將所有診斷結果整理成一份清晰的報告，包括可重現的步驟和建議的修正方案。

診斷報告結構:

# MCP 整合除錯報告

## 問題描述
[使用者報告的問題]

## 環境信息
- MCP 伺服器版本: [版本]
- 伺服器地址: [地址:端口]
- 作業系統: [OS]
- 相關依賴版本: [版本]

## 診斷步驟和結果

### 1. 連接狀態
- [✓/✗] 伺服器進程運行中
- [✓/✗] 端口可訪問
- [✓/✗] 網絡連接正常
- [✓/✗] 認證成功

**詳細結果**: [具體診斷結果]

### 2. 工具列表
- [✓/✗] 工具列表可以檢索
- 返回的工具數量: [數量]
- 缺失的工具: [列表]

**詳細結果**: [具體診斷結果]

### 3. 工具呼叫測試
- [✓/✗] 測試工具成功執行
- 測試工具: [工具名稱]
- 執行時間: [時間]

**詳細結果**: [具體診斷結果]

## 根本原因分析
[基於診斷結果的根本原因分析]

## 建議的修正方案

### 方案 1: [標題]
[詳細步驟]

### 方案 2: [標題]
[詳細步驟]

## 可重現的步驟
1. [步驟 1]
2. [步驟 2]
3. ...

## 後續行動
- [ ] 實施修正方案
- [ ] 驗證問題已解決
- [ ] 監控伺服器狀態
- [ ] 更新文件（如需要）

最佳實踐

1. 系統化診斷: 按照邏輯順序進行診斷，從基本連接開始，逐步深入。

2. 記錄詳細信息: 記錄所有診斷步驟和結果，包括時間戳和錯誤訊息。

3. 隔離問題: 通過逐個測試工具和配置參數來隔離問題。

4. 檢查日誌: 始終查看伺服器和客戶端的日誌檔案，尋找有用的錯誤信息。

5. 驗證修正: 在實施修正方案後，重新執行診斷步驟以驗證問題已解決。

6. 文件化解決方案: 記錄問題和解決方案，以便將來參考。

7. 預防性監控: 設定監控和警報，及時發現和解決問題。

常見的 MCP 問題和解決方案

問題: 伺服器間歇性連接失敗

可能原因: 網絡不穩定、伺服器過載、防火牆規則 解決方案: 實施連接重試邏輯、增加伺服器資源、檢查防火牆規則

問題: 工具呼叫超時

可能原因: 工具執行時間過長、網絡延遲、伺服器性能問題 解決方案: 優化工具實現、增加超時時間、檢查伺服器性能

問題: 工具返回不一致的結果

可能原因: 工具實現有 bug、外部依賴問題、並發問題 解決方案: 檢查工具實現、驗證外部依賴、實施鎖定機制

問題: 新工具未出現在工具列表中

可能原因: 工具未正確註冊、伺服器未重新啟動、配置錯誤 解決方案: 驗證工具註冊、重新啟動伺服器、檢查配置檔案