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

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

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

Important

開始前，請先完成快速啟動。

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

TOC - 準備工作 - Step 1: 配置 MCP 客戶端 - Step 2: 驗證連線狀態 - 故障排除

Note

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

Step 1: 配置 MCP 客戶端¶

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

準備工作¶

記錄專案的完整路徑（例如 C:/Users/YourUserName/Desktop/time_compass，或是你解壓縮、git clone 下來的路徑）
替換以下範例中的 [PROJECT_PATH] 為實際路徑，並且將其中的 \ 都換成 \\。例如
```
C:/Users/YourUserName/Desktop/time_compass
```
要換成
```
C://Users//YourUserName//Desktop//time_compass
```

選擇你的工具¶

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

分成三個部分:

JSON 格式（大多數工具）
外層 key 不同的 JSON 格式（VS Code Copilot）
TOML 格式（Codex）

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

請選擇對應的路徑，貼到終端機以後，按下enter，即可編輯檔案。

工具	設定檔路徑 (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`，給`Copilot(VScode)`跟`Codex`以外的）¶

開啟設定檔：%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)¶

工具	設定檔路徑 (Windows)	格式 / 外層 key
VS Code (Copilot)	`%APPDATA%\Code\User\mcp.json`（或工作區 `.vscode/mcp.json`）	JSON / `servers`

開啟設定檔：工作區的 .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": { ... }
  }
}

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

引用：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 文件

Step 2: 驗證連線狀態¶

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

VS Code (Copilot) 特殊步驟¶

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

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

基本驗證¶

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

或是測試以下範例

幫我看看我這兩周都做了甚麼，我好累喔，還得複習微積分才行，也幫我排未來兩周的複習行程

最後一步: 接入真實資訊¶

注: 在測試前端時， AI 產生的資訊不一定都在當天，需要切換時間來檢查產出成果

請到登入google驗證文件

如果您不想要登入google，也可停留在這一步。

故障排除¶

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

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