Skill

mcp-debug

From mcp-tools

MCP Server 功能除錯（框架分析、權限問題、錯誤診斷）

Invocation

How this skill is triggered — by the user, by Claude, or both

Slash command

/mcp-tools:mcp-debug

User invocable

Model invocable

Inline context

Default effort

Tool Access

This skill is limited to the following tools:

Bash(sdef:*)Bash(osascript:*)Bash(claude mcp:*)Bash(pkill:*)Bash(swift:*)Bash(tccutil:*)Bash(open:*)Bash(lipo:*)Bash(file:*)Bash(shasum:*)Bash(cp:*)Bash(chmod:*)Bash(rm:*)Bash(ls:*)Bash(grep:*)Bash(codesign:*)ReadWriteGrepGlob

Context Preview

The summary Claude sees in its skill listing — used to decide when to auto-load this skill

當 MCP Server 功能有問題時，使用此流程診斷。

SKILL.md

343 lines · ~1.8k tokens

Stats

LanguageTeX

Parent stars0

MaintenanceExcellent

Last CommitMar 29, 2026

Actions

View Source View Plugin View on GitHub View README

Stats

Actions

MCP Debug - 功能除錯

當 MCP Server 功能有問題時，使用此流程診斷。

連線問題請用 /mcp-tools:mcp-diagnose 完整測試請用 /mcp-tools:mcp-test

參數

$1 = MCP Server 名稱（如 che-things-mcp、che-ical-mcp）
$2 = 可選的錯誤訊息（用於快速判斷問題類型）

Phase 0: 快速診斷

Step 0: 建立除錯日誌目錄

在專案根目錄建立 logs/mcptools/debug/ 結構：

cd ~/Library/CloudStorage/Dropbox/che_workspace/projects/mcp/$1
mkdir -p logs/mcptools/debug

目錄結構：

<project>/
└── logs/
    └── mcptools/
        └── debug/          ← 除錯報告存放處
            └── debug-report-<timestamp>.md

Step 1: 檢查連線狀態

claude mcp list 2>&1 | grep -A1 "$1"

結果判讀：

✓ Connected → 連線正常，進入 Phase 1
✗ Failed 或找不到 → 先用 /mcp-tools:mcp-diagnose

Step 2: 快速測試（3 個讀取類 tools）

直接呼叫 MCP tools 測試基本功能：

找到該 MCP Server 的讀取類 tools（list_*、get_*）
呼叫 3 個不需要參數的 tools
根據結果判斷：
- 全部成功 → 基本功能正常
- 部分失敗 → 進入框架特定除錯
- 全部失敗 → 可能是權限問題

Step 3: 錯誤訊息分析

如果有錯誤訊息（$2），快速判斷問題類型：

錯誤關鍵字	問題類型	進入流程
`access denied` / `permission`	權限問題	→ B3 權限除錯
`not found` / `does not exist`	資源不存在	→ 檢查參數
`Can't set property`	AppleScript 唯讀	→ A2 Dictionary 分析
`connection` / `timeout`	連線問題	→ Phase 3 重啟
`parse` / `invalid`	參數格式錯誤	→ 檢查參數格式

Phase 1: 識別框架類型

Step 1: 找到原始碼

ls -la ~/Library/CloudStorage/Dropbox/che_workspace/projects/mcp/$1/

Step 2: 判斷框架

# 檢查 Swift imports
grep -r "^import" $1/Sources/ 2>/dev/null | head -20

特徵	框架類型	除錯流程
`import EventKit`	EventKit	→ 框架 B
`tell application` / `NSAppleScript`	AppleScript	→ 框架 A
`import Contacts`	Contacts	→ 框架 C
HTTP/REST calls	Web API	→ 框架 C

框架 A: AppleScript 除錯

適用於：che-things-mcp、che-apple-mail-mcp

A1: 匯出 Dictionary

sdef /Applications/<AppName>.app > /tmp/<AppName>-dictionary.xml

A2: 分析 Dictionary

# 找唯讀屬性
grep 'access="r"' /tmp/<AppName>-dictionary.xml

# 找可用命令
grep 'command name=' /tmp/<AppName>-dictionary.xml

A3: 測試 AppleScript 層

osascript -e 'tell application "<AppName>" to <test-code>'

A4: 常見錯誤

錯誤	原因	解決
`Can't set property`	屬性唯讀	用替代命令
`Can't get list "Inbox"`	localized 名稱	用 internal ID

框架 B: EventKit 除錯

適用於：che-ical-mcp

B1: 讀取程式碼

cat $1/Sources/*/EventKitManager.swift

B2: 關鍵模式

模式	功能
`EKEventStore`	存取行事曆
`requestAccess`	權限請求
`predicateForEvents`	查詢事件

B3: 權限除錯（最常見問題！）

Step 1: 開啟系統設定

open "x-apple.systempreferences:com.apple.preference.security?Privacy_Calendars"
open "x-apple.systempreferences:com.apple.preference.security?Privacy_Reminders"

Step 2: 找到正確的授權對象

重要：要授權的是 IDE，不是 binary！

你使用的工具	要授權的項目
Cursor	Cursor
VS Code	Code
Terminal	Terminal / iTerm
Claude Desktop	Claude

Step 3: 如果列表中沒有項目

# 重置權限
tccutil reset Calendars
tccutil reset Reminders

# 觸發權限請求
osascript -e 'tell application "Calendar" to get name of every calendar'
osascript -e 'tell application "Reminders" to get name of every list'

B4: 權限機制說明

┌─────────────────────────────────────────────────────────┐
│  AppleScript (osascript)  vs  EventKit Framework        │
├─────────────────────────────────────────────────────────┤
│  osascript 成功          │  MCP (EventKit) 失敗         │
│  ↓                       │  ↓                           │
│  Apple Events 權限       │  Privacy - Calendars/        │
│  (Automation)            │  Reminders 權限              │
├─────────────────────────────────────────────────────────┤
│  這是兩個不同的權限機制！                                │
│  AppleScript 能用不代表 EventKit 也能用                 │
└─────────────────────────────────────────────────────────┘

框架 C: 其他 Framework

C1: 讀取程式碼

grep -r "class.*Manager\|class.*Service" $1/Sources/
cat $1/Package.swift

Phase 2: 診斷報告

Step 1: 產生報告

將報告存到 logs/mcptools/debug/debug-report-<timestamp>.md：

# 報告檔案路徑
REPORT_FILE="logs/mcptools/debug/debug-report-$(date +%Y%m%d-%H%M%S).md"

Step 2: 報告格式

# MCP Debug Report: <server-name>
Generated: <timestamp>

## 問題摘要
- 錯誤訊息: <error>
- 問題類型: 權限 / 參數 / 連線 / 其他

## 框架識別
- 類型: AppleScript / EventKit / Other
- 除錯流程: 框架 A / B / C

## 診斷結果
- 快速測試: ✅ / ❌
- 問題根因: <root-cause>

## 修復建議
1. <step-1>
2. <step-2>

Step 3: 儲存報告

使用 Write 工具將報告寫入 $REPORT_FILE。

完成後輸出：

✅ 除錯報告已儲存: logs/mcptools/debug/debug-report-<timestamp>.md

Phase 3: 修復後驗證

Step 1: 重新建置

cd $1
swift build -c release

Step 2: 同步 Binary 到 mcpb/server 和 ~/bin

取得 Binary 名稱：

BINARY_NAME=$(grep -A5 'executableTarget' Package.swift | grep 'name:' | head -1 | sed 's/.*"\([^"]*\)".*/\1/')

情況 A: 兩種架構的 build 都存在 → 用 lipo 合併

if [ -f ".build/arm64-apple-macosx/release/$BINARY_NAME" ] && [ -f ".build/x86_64-apple-macosx/release/$BINARY_NAME" ]; then
    echo "Building universal binary..."
    lipo -create \
        .build/arm64-apple-macosx/release/$BINARY_NAME \
        .build/x86_64-apple-macosx/release/$BINARY_NAME \
        -output mcpb/server/$BINARY_NAME
    codesign --force --sign - mcpb/server/$BINARY_NAME
else
    echo "Single-arch build detected, copying directly..."
    # 找到可用的 release binary
    BUILD_BIN=$(ls .build/arm64-apple-macosx/release/$BINARY_NAME .build/x86_64-apple-macosx/release/$BINARY_NAME .build/release/$BINARY_NAME 2>/dev/null | head -1)
    if [ -n "$BUILD_BIN" ]; then
        cp "$BUILD_BIN" mcpb/server/$BINARY_NAME
    fi
fi

複製到 ~/bin

cp mcpb/server/$BINARY_NAME ~/bin/$BINARY_NAME
chmod +x ~/bin/$BINARY_NAME
codesign --force --sign - ~/bin/$BINARY_NAME

驗證同步

echo "=== Post-rebuild Sync Verification ==="
shasum -a 256 mcpb/server/$BINARY_NAME ~/bin/$BINARY_NAME
file mcpb/server/$BINARY_NAME
file ~/bin/$BINARY_NAME

Step 3: 重啟 Server

pkill -f <BinaryName>
claude mcp list 2>&1 | grep -A1 "$1"

快速參考

MCP Server 對應表

MCP Server	框架	Binary
che-things-mcp	AppleScript	CheThingsMCP
che-apple-mail-mcp	AppleScript	CheAppleMailMCP
che-ical-mcp	EventKit	CheICalMCP

Things 3 List IDs

清單	ID
Inbox	`TMInboxListSource`
Today	`TMTodayListSource`
Upcoming	`TMCalendarListSource`
Anytime	`TMNextListSource`
Someday	`TMSomedayListSource`
Logbook	`TMLogbookListSource`

mcp-debug

Invocation

Tool Access

Context Preview

SKILL.md

mcp-debug

Invocation

Tool Access

Context Preview

SKILL.md

MCP Debug - 功能除錯

參數

Phase 0: 快速診斷

Step 0: 建立除錯日誌目錄

Step 1: 檢查連線狀態

Step 2: 快速測試（3 個讀取類 tools）

Step 3: 錯誤訊息分析

Phase 1: 識別框架類型

Step 1: 找到原始碼

Step 2: 判斷框架

框架 A: AppleScript 除錯

A1: 匯出 Dictionary

A2: 分析 Dictionary

A3: 測試 AppleScript 層

A4: 常見錯誤

框架 B: EventKit 除錯

B1: 讀取程式碼

B2: 關鍵模式

B3: 權限除錯（最常見問題！）

Step 1: 開啟系統設定

Step 2: 找到正確的授權對象

Step 3: 如果列表中沒有項目

B4: 權限機制說明

框架 C: 其他 Framework

C1: 讀取程式碼

Phase 2: 診斷報告

Step 1: 產生報告

Step 2: 報告格式

Step 3: 儲存報告

Phase 3: 修復後驗證

Step 1: 重新建置

Step 2: 同步 Binary 到 mcpb/server 和 ~/bin

情況 A: 兩種架構的 build 都存在 → 用 lipo 合併

複製到 ~/bin

驗證同步

Step 3: 重啟 Server

快速參考

MCP Server 對應表

Things 3 List IDs

Similar Skills

MCP Debug - 功能除錯

參數

Phase 0: 快速診斷

Step 0: 建立除錯日誌目錄

Step 1: 檢查連線狀態

Step 2: 快速測試（3 個讀取類 tools）

Step 3: 錯誤訊息分析

Phase 1: 識別框架類型

Step 1: 找到原始碼

Step 2: 判斷框架

框架 A: AppleScript 除錯

A1: 匯出 Dictionary

A2: 分析 Dictionary

A3: 測試 AppleScript 層

A4: 常見錯誤

框架 B: EventKit 除錯

B1: 讀取程式碼

B2: 關鍵模式

B3: 權限除錯（最常見問題！）

Step 1: 開啟系統設定

Step 2: 找到正確的授權對象

Step 3: 如果列表中沒有項目

B4: 權限機制說明

框架 C: 其他 Framework

C1: 讀取程式碼

Phase 2: 診斷報告

Step 1: 產生報告

Step 2: 報告格式

Step 3: 儲存報告

Phase 3: 修復後驗證