MCP Tools 完整實作參考¶

簡介¶

MCP Tools（Model Context Protocol Tools）是 Time Compass 系統中核心的能力模組。透過 MCP 架構，AI 助手可以存取使用者的 Google 日曆、Google Tasks、Moodle 課程系統與時間規劃工具，提供整合性的時間管理服務。

本系統將 15 個工具分為三大類別： - 日曆工具（5個）：管理 Google 日曆事件 - 任務工具（4個）：管理 Google Tasks 任務列表
- 其他工具（6個）：時間上下文聚合、Moodle 爬取、Planner Studio 啟動等

快速工具分類速覽¶

1. 排程與上下文（核心整合）¶

工具	功能
`get_time_context`	最核心工具。一次性抓取 Calendar + Tasks + Moodle 資訊，以 TOON 格式回傳
`launch_planner_studio`	接收 AI 生成的規劃方案（DraftVariants）並啟動本地視覺化介面

2. Google Calendar（日曆管理）¶

工具	功能
`list_calendars`	列出使用者帳號中所有可寫入的日曆資訊
`get_all_calendar_events`	跨日曆抓取指定範圍內的所有事件
`get_event_from_calendar`	鎖定單一日曆抓取事件
`create_calendar_event`	在指定日曆中建立新事件
`get_free_busy`	查詢特定時段的忙碌狀態（用於衝突檢查）

3. Google Tasks（任務管理）¶

工具	功能
`list_tasklists`	獲取所有任務清單 (Task Lists) 的 ID 與標題
`get_all_tasks`	掃描所有清單中的任務，支援時間範圍過濾
`get_task_from_tasklist`	獲取特定任務清單內的詳細細項
`create_task`	在指定的清單中新增一項任務

4. 教育整合（Moodle）¶

工具	功能
`get_moodle_events`	爬取並解析 Moodle 上的課程公告、作業截止日與考試事件

5. 系統與授權¶

工具	功能
`launch_google_token_auth`	啟動本機 OAuth 流程，幫助使用者完成 Google 授權
`get_planner_studio_status`	檢查當前 Planner Studio 伺服器的運行狀態
`shutdown_planner_studio`	安全關閉本地執行中的 Planner Studio 實例

6. Prompt 模板工具（系統提示）¶

這 3 個工具回傳專用的 SYSTEM INSTRUCTION 供 AI 使用

工具	功能
`summary_writer_prompt`	回傳「回顧/總結」專用 SYSTEM INSTRUCTION
`emotion_support_prompt`	回傳「情緒支持」專用 SYSTEM INSTRUCTION
`time_management_master_prompt`	回傳「規劃排程主流程」專用 SYSTEM INSTRUCTION

如何測試工具：使用官方 MCP Inspector 驗證

npx @modelcontextprotocol/inspector uv run time-compass-mcp

進入 Inspector 網頁後，可手動點擊各工具並填入參數，觀察 TOON 格式回傳值。

15 個工具列表與功能表¶

序號	工具名稱	類型	功能摘要	參數群	返回值
1	`get_all_calendar_events`	Calendar	獲取所有日曆的事件（TOON 格式）	start_time, end_time	TOON 格式日曆事件
2	`get_event_from_calendar`	Calendar	指定日曆的事件查詢	calendar_id, start_time, end_time	TOON 格式單一日曆事件
3	`list_calendars`	Calendar	列出使用者所有可寫日曆	無	JSON（日曆 ID、標題、角色）
4	`create_calendar_event`	Calendar	建立日曆事件	summary, start, end, calendar_id, description?	JSON（event ID、狀態）
5	`get_free_busy`	Calendar	查詢日曆空閒/繁忙狀態	time_min, time_max, items[]	JSON（Free/Busy 查詢結果）
6	`get_all_tasks`	Task	獲取所有任務（TOON 格式）	start_time?, end_time?, time_mode	TOON 格式任務列表
7	`list_tasklists`	Task	列出使用者所有任務列表	無	JSON（任務列表 ID、標題）
8	`get_task_from_tasklist`	Task	指定任務列表的任務查詢	tasklist_id, start_time?, end_time?	TOON 格式任務清單
9	`create_task`	Task	建立任務	title, list_id, notes?, due?	JSON（task ID、狀態）
10	`get_moodle_events`	Other	爬取 Moodle 課程事件	start_date, end_date, account?, password?	文本格式課程事件
11	`get_time_context`	Other	聚合完整生活上下文	start_time, end_time, moodle_account?, moodle_password?	TOON 格式完整上下文
12	`launch_google_token_auth`	Other	啟動 Google OAuth 授權頁	open_browser?, port?, token_file?, wait_timeout?	授權流程狀態 JSON
13	`launch_planner_studio`	Other	啟動排程規劃網頁介面	start_time, end_time, ai_draft, draft_variants, ...	網頁 URL、session ID
14	`get_planner_studio_status`	Other	查詢 Planner Studio 執行狀態	無	執行狀態 JSON
15	`shutdown_planner_studio`	Other	關閉 Planner Studio 伺服器	wait_timeout_seconds?	關閉狀態 JSON

效能考量與最佳實踐¶

API 呼叫決策矩陣¶

使用情境	推薦工具	原因
初次載入完整背景	`get_time_context`	單一呼叫 vs 3 次呼叫，延遲減少 ~40%
指定日曆查詢	`get_event_from_calendar`	精準篩選，避免全量日程轉換
空閒時段檢測	`get_free_busy`	Google API 原生支援，高效率
新增排程到日曆	`create_calendar_event` + `launch_planner_studio`	先預覽後建立，降低誤操作
Moodle 課程回顧	`get_moodle_events`+`get_time_context`	統整課程與個人日程

快取策略¶

# ResourceContext 典型快取時間表
get_time_context()        # 快取 5-10 分鐘（涵蓋 Google + Moodle）
get_all_calendar_events() # 快取 3-5 分鐘
get_all_tasks()           # 快取 3-5 分鐘
get_moodle_events()       # 快取 15-30 分鐘（Web 爬取成本高）

Dev Mode 與測試¶

所有工具支援 is_dev_mode() 切換，自動使用 Mock Fixtures
時間平移邏輯：自動計算 anchor_date (2025-11-15) 與執行日期的差值
Fixture 位置：tests/snapshots/fixtures/google/{calendar,tasks,moodle}/

工具分類與架構模式¶

按責任分類¶

1. 資料讀取工具（只讀） - list_calendars, list_tasklists - get_all_calendar_events, get_event_from_calendar - get_all_tasks, get_task_from_tasklist - get_moodle_events, get_free_busy

2. 資料寫入工具（建立） - create_calendar_event, create_task

3. 聚合工具（多源合併） - get_time_context：Calendar + Tasks + Moodle

4. 執行環境工具（狀態管理） - launch_google_token_auth, launch_planner_studio - get_planner_studio_status, shutdown_planner_studio

按資料流向分類¶

使用者請求
  ↓
┌─────────────────────────────────────┐
│  MCP Tools 層 (15 個工具)             │
├─────────────────────────────────────┤
│  ├─ Calendar API (5 tools)           │
│  ├─ Tasks API (4 tools)               │
│  ├─ Moodle Scraper (1 tool)           │
│  ├─ Aggregation (1 tool: get_time_context)│
│  └─ Runtime (4 tools)                │
└─────────────────────────────────────┘
  ↓
┌─────────────────────────────────────┐
│  Integration 層                       │
│  ├─ google_calendar.async_core      │
│  ├─ google_tasks.async_core         │
│  ├─ moodle.async_core               │
│  └─ get_all_information_from_api    │
└─────────────────────────────────────┘
  ↓
┌─────────────────────────────────────┐
│  Google/Moodle API / Web Scraper    │
└─────────────────────────────────────┘

錯誤處理與復見策略¶

統一錯誤檢查¶

# 所有工具的錯誤檢查模式
try:
    result = await some_api_call()
    if is_err(result):
        return f"AUTH_REQUIRED: {result.error}"
    if not is_ok(result):
        return "AUTH_REQUIRED: API failure"
    # 處理成功情況
except Exception as err:
    if is_google_auth_error(err):
        return get_auth_required_text()
    raise  # 重新拋出非認證例外

常見例外情況¶

例外類型	工具	復見策略
認證過期	所有 Google API 工具	重新呼叫 `launch_google_token_auth()`
Moodle 連線失敗	`get_moodle_events`, `get_time_context`	環境變數檢查、重試邏輯
Planner Studio 埠號佔用	`launch_planner_studio`	自動遞增埠號或清理舊程式
Token 檔案遺失	`launch_google_token_auth`	觸發首次授權流程

詳細工具實作說明¶

完整的每個工具的詳細文檔（含 Docstring、函式簽名、核心實作邏輯、使用案例），請參考本文的完整版本或直接查看原始程式碼位置：src/time_compass/mcp/tools/

整合與調用流程¶

典型流程：AI 排程規劃¶

1. 使用者輸入抽象目標
   ↓
2. get_time_context() 
   └─ 聚合背景（Calendar + Tasks + Moodle）
   ↓
3. AI 規劃邏輯
   └─ 根據背景產生 3-5 個排程變體
   ↓
4. launch_planner_studio()
   ├─ 傳入 ai_draft（引導文案）
   ├─ 傳入 draft_variants（3-5 個方案）
   └─ 返回網頁 URL + session ID
   ↓
5. 使用者在 Planner Studio 中
   ├─ 查看背景日程與任務
   ├─ 比選排程變體
   └─ 點選「應用」
   ↓
6. Planner Studio 後端
   ├─ 呼叫 create_calendar_event() 建立選中變體的事件
   └─ 呼叫 create_task()（如需）
   ↓
7. 排程應用完成

典型流程：查詢特定日曆¶

1. list_calendars()
   └─ 返回日曆列表供選擇
   ↓
2. get_event_from_calendar(calendar_id, start, end)
   └─ 查詢特定日曆事件
   ↓
3. 應用於 UI 篩選或報告

實作變更追蹤與版本¶

V1.0（初始版本）¶

基本 Calendar & Tasks 工具集
JSON 格式輸出
單一日曆/任務列表查詢

V1.5（TOON 格式與批次優化）¶

引入 TOON 編碼（減少 Token 消耗 ~40%）
引入 Batch API：get_all_calendar_events, get_all_tasks
get_time_context 統一聚合介面

V2.0（Planner Studio & OAuth）¶

新增執行環境工具：launch_planner_studio
OAuth Token 管理：launch_google_token_auth
Dev Mode 時間平移邏輯（確保測試環保一致性）

V2.1（當前）¶

Moodle 整合：get_moodle_events
完整上下文聚合：增強 get_time_context 支援 Moodle
錯誤處理增強：統一 is_google_auth_error() 檢查

總結¶

Time Compass 的 15 個 MCP 工具形成了一個完整的時間管理資料橋樑，從原始資料源（Google Calendar/Tasks、Moodle）到高層規劃介面（Planner Studio）。每個工具的設計原則是：

✅ 高效率：Batch API、TOON 編碼、快取策略
✅ 易整合：統一錯誤檢查、相容 Mock & 生產環境
✅ 可擴展：Dev Mode 測試、時間平移邏輯、中間層聚合
✅ 使用者友善：預視→選擇→應用的完整流程控制

更新日期：2026年3月2日 | Time Compass MCP Tools Reference