MCP 環境建置與整合指南（Mock 模式）¶

本文檔涵蓋 Time Compass MCP Server 的完整安裝與配置流程，提供一套無成本、無 OAuth 的 MCP 快速設置方式，並使用內建 Mock 數據進行完整功能體驗。整體預計可在 5-10 分鐘內完成。

若需要真實數據（Google Calendar / Tasks），完成本步驟後可升級至 30+ 分鐘完整設置體驗（見 README）。

[!IMPORTANT] 開始前，請先完成 quickstart。

本指南分為兩個主要步驟，從 MCP 客戶端配置到完整驗證。每一步都有明確的目標與執行原因。

TOC - 1. 配置 MCP 客戶端 - 2. 驗證連線狀態 - 故障排除

如果你已經熟悉 MCP 安裝與配置流程¶

如果您已經熟悉 MCP 的概念，並且只想快速完成安裝與配置，可以直接參考以下精簡版步驟：如果您不熟悉，請直接從下方「1. 配置 MCP 客戶端」開始，依序完成完整流程。

確保你完成了 quickstart
註冊 MCP

將下列設定加入你的 MCP 客戶端設定檔（把 [PROJECT_PATH] 換成專案絕對路徑）：

{
  "mcpServers": {
    "time-compass": {
      "command": "uv",
      "args": [
        "--directory",
        "[PROJECT_PATH]",
        "run",
        "time-compass-mcp"
      ]
    }
  }
}

兩大步驟概覽¶

這裡先提供流程概覽，幫您快速掌握整體有哪些步驟，以及每一步會帶來的結果。

最終目的: 成功啟動 MCP Server，並讓 IDE（如 Claude Desktop、VS Code）能夠呼叫 MCP 工具。

配置 MCP 客戶端
目的與效果：將 MCP Server 加入 IDE 設定，讓客戶端可自動發現並連線。
完成後您會得到：✅ IDE 設定檔已更新、MCP 伺服器配置已加入
驗證連線狀態
目的與效果：驗證 IDE 連線、工具呼叫與介面啟動，確認整體流程可正常運作。
完成後您會得到：✅ IDE 可成功呼叫 MCP 工具、Planner Studio 網頁介面可正常開啟

[!NOTE] 關於「執行」：本指南中的「執行 [指令]」表示： 1. 複製下方框框內的完整指令 2. 貼到終端機中 3. 按下 Enter 鍵執行

1. 配置 MCP 客戶端¶

本步驟會將 MCP Server 配置加入 IDE 或 AI 工具的設定檔。

準備工作¶

記錄專案的完整路徑（例如 C:/Users/User/Desktop/time_compass，或是你解壓縮、git clone 下來的路徑）
替換以下範例中的 [PROJECT_PATH] 為實際路徑

選擇你的工具¶

此處列出幾個常見工具：Claude Desktop、Windsurf、Cursor、Antigravity、OpenClaw、OpenCode、Claude Cowork、VS Code（Copilot）、Codex、Gemini CLI。請根據你使用的工具選擇對應配置方法。

分成三個部分: - JSON 格式（大多數工具） - 外層 key 不同的 JSON 格式（VS Code Copilot） - TOML 格式（Codex）

工具與設定檔對照（Windows）¶

工具	設定檔路徑 (Windows)	格式 / 外層 key
Claude Desktop	`%APPDATA%\Claude\claude_desktop_config.json`	JSON / `mcpServers`
Windsurf	`%USERPROFILE%\.codeium\windsurf\mcp_config.json`	JSON / `mcpServers`
Cursor	`%USERPROFILE%\.cursor\mcp.json`（或專案 `.cursor/mcp.json`）	JSON / `mcpServers`
Antigravity	`%USERPROFILE%\.gemini\antigravity\mcp_config.json`	JSON / `mcpServers`
OpenClaw	`%USERPROFILE%\.openclaw\openclaw.json`	JSON / 依 OpenClaw 文件
OpenCode	`~/.config/opencode/opencode.json`（文件定義路徑）	JSON / `mcp`
Claude Cowork	尚未查到官方公開固定本機設定檔路徑	請依產品內設定頁
VS Code (Copilot)	`%APPDATA%\Code\User\mcp.json`（或工作區 `.vscode/mcp.json`）	JSON / `servers`
Codex	`~/.codex/config.toml`	TOML / `[mcp_servers.<name>]`
Gemini CLI	`%USERPROFILE%\.gemini\settings.json`	JSON / `mcpServers`

對照表參考來源： Claude Desktop、Windsurf、Cursor、Antigravity、OpenClaw、OpenCode、VS Code、Codex、Gemini CLI

JSON 格式（`mcpServers`）¶

開啟設定檔：%APPDATA%\Claude\claude_desktop_config.json (Claude Desktop 為例)
檢查並合併 JSON 配置：
若設定檔中已有 "mcpServers" 物件，請在該物件內新增下方的 "time-compass" 項目
若設定檔中還沒有 "mcpServers" 物件，請將整個下方配置複製到檔案中（確保 JSON 格式正確）

您會看到：設定檔中的 mcpServers 物件內新增了 time-compass 項目

{
  "mcpServers": {
    "time-compass": {
      "command": "uv",
      "args": [
        "--directory",
        "[PROJECT_PATH]",
        "run",
        "time-compass-mcp"
      ]
    }
  }
}

範例：若設定檔已有其他 MCP（如 Anthropic 官方工具），合併後應該看起來像：
{
  "mcpServers": {
    "time-compass": { ... },
    "another_tools": { ... }
  }
}

儲存檔案

引用：mcpServers 格式可參考 Claude Desktop、Windsurf、Cursor、Gemini CLI

VS Code (Copilot)¶

開啟設定檔：工作區的 .vscode/mcp.json 或使用者層級 mcp.json
檢查並合併 JSON 配置：
若設定檔中已有 "servers" 物件，請在該物件內新增下方的 "time-compass" 項目
若設定檔中還沒有 "servers" 物件，請將整個下方配置複製到檔案中（確保 JSON 格式正確）

您會看到：設定檔中的 servers 物件內新增了 time-compass 項目

{
  "servers": {
    "time-compass": {
      "command": "uv",
      "args": [
        "--directory",
        "[PROJECT_PATH]",
        "run",
        "time-compass-mcp"
      ]
    }
  }
}

提示：若已有其他 MCP server，合併後應該看起來像：
{
  "servers": {
    "time-compass": { ... },
    "other-server": { ... }
  }
}

儲存檔案 您會看到：編輯器標題列不再顯示「*」或「改變」標記，表示設定檔已儲存成功

引用：VS Code MCP mcp.json 與 servers 格式見 VS Code 官方文件

Codex¶

開啟 ~/.codex/config.toml
檢查並合併 TOML 配置：
若設定檔中已有 [mcp_servers] 段落，請在該段落內新增下方的 [mcp_servers.time-compass] 項目
若設定檔中還沒有 [mcp_servers] 段落，請將下方配置複製到檔案中

您會看到：設定檔中新增了 [mcp_servers.time-compass] 段落及其配置

[mcp_servers.time-compass]
command = "uv"
args = [
  "--directory",
  "[PROJECT_PATH]",
  "run",
  "time-compass-mcp"
]
enabled = true

提示：若已有其他 MCP server，合併後應該看起來像：
[mcp_servers.time-compass]
...

[mcp_servers.other-server]
...

儲存檔案 您會看到：編輯器標題列不再顯示「*」或「改變」標記，表示設定檔已儲存成功

> 引用：Codex 的 `~/.codex/config.toml` 與 `[mcp_servers.*]` 格式見 Codex config 文件 ¶

2. 驗證連線狀態¶

本步驟會確認 MCP Server 與 IDE 連線正常。

基本驗證¶

重啟 IDE 或 Claude Desktop（完全關閉再開啟） 您會看到：應用程式完全重新啟動，之前的對話窗口關閉
測試 MCP 工具連線，於對話框輸入：
```
List my calendars using time-compass tools
```
您會看到：
IDE 的工具面板應顯示 MCP 工具已載入（如 mcp_time-compass_list_calendars 等）
對話框會呼叫該工具並回傳日曆清單或測試資料
測試微前端介面，呼叫 launch_planner_studio 工具 您會看到：
應有瀏覽器視窗自動開啟（通常在 http://localhost:8766）
Planner Studio 排程管理介面載入完成

驗證結果¶

請確認你打開的 Studio 網址是由 MCP 工具啟動，而不是測試用前端。

您會看到：以 vscode 的 copilot 為例，第一次啟用工具時，應該要顯示工具圖案，代表真的有調用。

第二個方法是以下的 url 判斷法。

URL 判斷規則（重要）¶

若最取得的網址最後一段（最後一個 / 後面的字串）是以 dev- 或 real- 開頭，代表這次不是透過 MCP 工具呼叫。
這種情況通常是開到了 scripts/run_planner_studio.py 啟動的測試用前端。
正常 MCP 驗證請回到對話中重新呼叫 launch_planner_studio，並再次檢查網址。

VS Code (Copilot) 特殊步驟¶

因 VS Code 系統限制，您需要手動啟動 MCP 伺服器：

按下 Ctrl + Shift + P
輸入 mcp: List Servers
點選 "time-compass" 項目
點擊 啟動伺服器

進階調試：使用 Inspector 工具¶

若 MCP 連線失敗，您可以單獨測試 MCP Tools 邏輯：見 quickstart

完成後檢查清單¶

✅ 恭喜！您已完成 Mock 模式設置（5 分鐘快速開始）

請確認：

[ ] IDE 已配置 MCP（mcpServers / servers 設定檔已更新）
[ ] IDE 已重啟並連線到 MCP Server
[ ] launch_planner_studio 工具可成功呼叫，Web UI 開啟

您現在可以： 1. ✨ 使用 IDE 的 AI 助手結合 MCP 工具進行時間規劃 2. 🔍 使用 MCP Inspector 測試所有工具 3. 📊 在 Planner Studio 中進行完整的排程體驗

下一步選項： - 🎯 繼續使用 Mock 模式 - 📅 升級至完整體驗 — 集成真實 Google / Moodle 數據，見 README 第二階段

故障排除¶

遇到問題時，按下表快速查找解決方案：

問題	解決方案
MCP Server 無法啟動	檢查 IDE 設定檔中的 `[PROJECT_PATH]` 是否為正確的絕對路徑