MCP 伺服器

Mindwtr 提供選用的 MCP（Model Context Protocol）伺服器。你可以將 AI agent（例如 Claude Desktop、Claude Code、OpenAI Codex 或 Gemini CLI）連接至本機 Mindwtr 資料庫、桌面版 Local API 或自行託管的 Mindwtr Cloud 端點。

獨立輔助工具預設使用 stdio。

實作參考文件：apps/mcp-server/README.md。如果該 README 與目前的伺服器程式碼或產生的 MCP 工具 schema 不一致，請以程式碼及 schema 為準。

應用程式 Binary 與 MCP 輔助工具

獨立 MCP 輔助工具繼續以 mindwtr-mcp 發佈，並已列入公開的 MCP Registry。

使用 MCP 不需要從原始碼執行整個應用程式。你可以使用一般桌面版處理任務，再讓 MCP 用戶端透過 npx 啟動 mindwtr-mcp，或使用 npm 全域安裝。請將輔助工具指向桌面版的本機 mindwtr.db，或使用下文的 Local API 後端。

桌面版的預設資料庫路徑列於下方的預設資料庫位置。行動版 binary 不提供本機 MCP 伺服器介面。

桌面版內建 MCP

桌面應用程式在**設定 → 集成 → 本機 MCP 伺服器（進階）**提供 MCP 伺服器。它在應用程式內部執行，與 Local API 共用內部操作。不需要 Node、npm、Bun 或獨立輔助工具，Local API 開關可以保持停用。MCP 預設停用且僅允許讀取。

啟用伺服器並保持 Mindwtr 執行。關閉視窗至系統匣後仍可使用；停用 MCP 或結束應用程式會停止伺服器。用戶端必須支援經過驗證的 Streamable HTTP。預設端點為：

text

http://127.0.0.1:8722/mcp

自 v1.3.7 起可用：以下控制項新增了複製 Codex 設定、設定連接埠和獨立寫入權限。較早的版本使用固定連接埠和單一的允許修改開關。

連接 Codex

選擇複製用於 Codex 的設定，將複製的 TOML 加入 ~/.codex/config.toml。如果該檔案已包含 mcp_servers.mindwtr，請取代現有項目，避免重複加入。保留其他設定。Mindwtr 只複製文字，不會修改 Codex 的檔案。

複製的設定格式如下，其中包含目前的端點和權杖：

toml

[mcp_servers.mindwtr]
url = "http://127.0.0.1:8722/mcp"

[mcp_servers.mindwtr.http_headers]
Authorization = "Bearer <token from Mindwtr>"

修改設定後，請重新啟動或重新連線 Codex 用戶端。複製連線詳情為使用 mcpServers 的用戶端提供 JSON；僅支援 stdio 的用戶端仍需要獨立輔助工具。

權限與連接埠

允許編輯任務和專案允許建立、編輯、完成和還原任務，以及建立或編輯專案。在進階中，可依需要分別啟用允許封存和允許刪除。各項權限彼此獨立，新安裝時均預設停用。既有安裝如果啟用了允許修改，會保留原有的刪除權限；你可以停用刪除權限，同時保留編輯權限。封存需要另外明確授權。

內建的 mindwtr_archive_task 工具透過應用程式現有操作封存任務。它不會完成任務或產生下一次重複任務。如果一次更新同時包含一般編輯和封存或取消操作的變更，就需要這兩項權限。刪除採用軟刪除。這些設定適用於內建伺服器，不適用於獨立輔助工具或另外的 Local API。

進階也允許選擇 1024 到 65535 之間的連接埠。儲存後，請為用戶端複製更新後的連線詳情。如果其他行程占用了連接埠，請選擇可用連接埠或解決衝突，然後選擇重試。伺服器始終繫結至 127.0.0.1。

連線的 AI 用戶端可以讀取這些工具公開的資料，並可能將資料傳送給其服務供應商。請妥善保管複製的權杖。重新產生權杖會中斷現有用戶端，之後需要為其設定新權杖。

此端點僅供同一部電腦上的用戶端使用，不提供遠端 ChatGPT 存取、通道或託管服務。行動應用程式不執行此伺服器。

需求

以下需求適用於獨立輔助工具。

Node.js 22+，可免編譯安裝：SQLite 相依套件提供 Node 22 以上版本的預先組建 binary。Node 20 仍可執行伺服器，但安裝時需要 C++ build tools
僅使用 API 的安裝可透過 --omit=optional 省略選用的 SQLite 擴充模組。
npm 或其他 Node package runner，用來執行已發佈的 mindwtr-mcp package
SQLite 模式需要本機 Mindwtr 資料庫（mindwtr.db）；API 模式需要執行中的桌面版 Local API 及其 bearer token；Cloud 模式則需要自行託管的 Mindwtr Cloud URL 及 bearer token
只有從原始碼樹執行輔助工具時才需要 Bun

在 SQLite 模式下使用 npm 12 時，需要核准 SQLite 相依套件的安裝指令碼；否則，即使安裝成功，啟動時仍可能因缺少原生綁定而失敗。使用 npx 或全域安裝時，僅允許 better-sqlite3：

bash

npx --allow-scripts=better-sqlite3 -y mindwtr-mcp --db "/path/to/mindwtr.db"
npm install -g --allow-scripts=better-sqlite3 mindwtr-mcp

在使用 npx 的 MCP 設定中，將 "--allow-scripts=better-sqlite3" 加入 args 的 "mindwtr-mcp" 之前。對於已安裝於專案中的套件，請在該專案內先執行 npm install-scripts approve better-sqlite3，再執行 npm rebuild better-sqlite3。核准前請檢查該相依套件，不要啟用所有相依套件的指令碼。

預設資料庫位置

Linux：~/.local/share/mindwtr/mindwtr.db
Linux（Snap）：~/snap/mindwtr/current/.local/share/mindwtr/mindwtr.db
macOS：~/Library/Application Support/mindwtr/data/mindwtr.db
Windows：%APPDATA%\mindwtr\data\mindwtr.db

沙盒化組建的其他 macOS 路徑：

~/Library/Containers/tech.dongdongbh.mindwtr/Data/Library/Application Support/mindwtr/data/mindwtr.db

上面的 macOS 和 Windows 路徑適用於 v1.3.2 及更新版本。v1.3.2 之前，資料庫直接放在 mindwtr 資料夾裡，例如 %APPDATA%\mindwtr\mindwtr.db。Linux 沒有變化。

你可以使用下列方式覆寫本機資料庫位置：

--db /path/to/mindwtr.db
環境變數：MINDWTR_DB_PATH 或 MINDWTR_DB

自行託管的 Cloud 模式請使用：

--cloud-url https://mindwtr.example.com 或 MINDWTR_MCP_CLOUD_URL
--cloud-token <token> 或 MINDWTR_MCP_CLOUD_TOKEN
可信賴的私人 HTTP 部署可選用 --cloud-allow-insecure-http=true

設定與組態

使用獨立輔助工具時，MCP 用戶端會將伺服器當成子程序執行。請指定命令並傳入引數。

建議 MCP 用戶端使用下列免安裝命令：

json

{
  "command": "npx",
  "args": [
    "-y",
    "mindwtr-mcp",
    "--db",
    "/path/to/mindwtr.db"
  ]
}

此 package 預設為唯讀。只有明確希望 AI 用戶端新增、更新、完成或刪除 Mindwtr 資料時，才加入 --write。

桌面版 Local API 模式

需要 mindwtr-mcp 1.1.11 或更新版本。

在設定中啟用桌面版應用程式的 Local API，並複製其 bearer token。保持應用程式與 API 執行。此後端使用應用程式的 REST 端點，絕不會開啟資料庫或退回使用 SQLite。

僅使用 API 安裝時，請省略選用的原生 SQLite 擴充模組：

bash

npm install -g --omit=optional mindwtr-mcp

將 MCP 用戶端設定為透過環境變數傳遞權杖，而非將權杖放在命令列引數中：

json

{
  "command": "mindwtr-mcp",
  "args": ["--api-url", "http://127.0.0.1:3456"],
  "env": {
    "MINDWTR_MCP_API_TOKEN": "<token from desktop settings>"
  }
}

使用設定中顯示的連接埠。MINDWTR_MCP_API_URL 可取代 --api-url。URL 必須使用字面位址 127.0.0.1 或 [::1]，不得包含憑證、路徑、查詢參數或片段；重新導向會被拒絕。不要混用 API 與 Cloud/--db 選項。在 API 模式下，既有的資料庫路徑環境變數會被忽略。

除非明確使用 --write 啟用，否則寫入始終停用。如果應用程式已關閉或權杖無效，輔助工具會傳回錯誤。逾時的寫入可能已到達應用程式：重試前請檢查任務，因為輔助工具不會自動重試寫入。

MCP 功能	桌面版 Local API 支援情況
列出／取得任務	支援，包括豐富的搜尋運算子、日期篩選、排序與分頁
建立任務	明確指定標題與欄位；不支援 `quickAdd`
更新／完成／刪除／還原任務	透過 API 的相應端點支援；終態變更不能當作一般編輯提交
列出／取得／建立／更新／刪除專案	支援 API 的基本專案欄位：標題、顏色、狀態、領域與循序執行行為
列出領域	支援
分區、受管理的人員、領域寫入	不支援；這些工具在 API 模式下隱藏
GTD 可執行性 `view`	不支援，因為 API 不提供所需的分區快照
取代附件連結	不支援，因為 API 不提供附帶條件的附件更新

其他不支援的欄位會在寫入之前被拒絕。桌面版 API 的重複任務限制同樣適用；某些重複任務必須在應用程式中完成。此後端不保證與 SQLite／Cloud 工具完全一致。

--api-url 選擇輔助工具的資料來源。--http 則選擇 MCP 用戶端如何連接至輔助工具；它可用於任何後端，並使用獨立的驗證權杖。

自行託管 Cloud 模式

若你執行自己的 Mindwtr Cloud 伺服器，且希望使用 MCP 工具而不公開本機 SQLite 檔案，請使用 Cloud 模式：

bash

npx -y mindwtr-mcp \
  --cloud-url "https://mindwtr.example.com" \
  --cloud-token "$MINDWTR_TOKEN"

也可在 MCP 用戶端組態中使用環境變數：

json

{
  "command": "npx",
  "args": ["-y", "mindwtr-mcp"],
  "env": {
    "MINDWTR_MCP_CLOUD_URL": "https://mindwtr.example.com",
    "MINDWTR_MCP_CLOUD_TOKEN": "your-token"
  }
}

Cloud 模式會從自行託管的 Cloud 伺服器讀取目前的 /v1/data 快照，並提供任務、專案、分區、領域及人員的讀取工具。使用 --write 時，任務、專案、分區及領域的寫入會經過 Cloud 伺服器各項資源的 REST 端點（POST /v1/tasks、PATCH /v1/tasks/:id 等），因此每項編輯都會獲得與應用程式編輯相同的驗證及修訂追蹤。若沒有 --write，寫入工具會回傳 read_only。Cloud 模式目前無法編輯人員或還原已刪除的任務；這些操作請使用本機資料庫後端。

透過 Cloud 模式的 MCP 更新連結附件需要 Mindwtr Cloud 1.2.8 或更新版本。輔助程式會使用條件寫入，保留其他用戶端修改過的檔案附件，並在發生並行修改時最多嘗試三次。如果伺服器沒有提供記錄的 ETag，請先升級伺服器再更新連結；輔助程式會拒絕更新，不執行寫入。僅修改其他欄位以及建立任務或專案的行為保持不變。

這並不是目前受阻的託管式多租戶 connector。Cloud 伺服器及 MCP 輔助工具仍由你自行執行；Mindwtr 不會營運儲存所有人任務資料的服務。

若要改用全域安裝：

bash

npm install -g mindwtr-mcp
mindwtr-mcp --db "/path/to/mindwtr.db"

主要引數

--db "/path/to/mindwtr.db"：本機模式的 SQLite 資料庫路徑。
--write：在本機或 Cloud 模式中啟用寫入操作（新增、更新、完成、刪除）。若沒有此 flag，伺服器為唯讀。
--cloud-url "https://mindwtr.example.com"：使用自行託管的 Mindwtr Cloud 端點，而非本機資料庫。
--cloud-token "<token>"：自行託管 Cloud 端點的 bearer token。
--cloud-allow-insecure-http=true：刻意不使用 HTTPS 時，允許可信賴的私人 HTTP Cloud URL。

1. Claude Desktop

在 Claude Desktop 組態檔中加入伺服器項目。

macOS：~/Library/Application Support/Claude/claude_desktop_config.json
Windows：%APPDATA%\Claude\claude_desktop_config.json

json

{
  "mcpServers": {
    "mindwtr": {
      "command": "npx",
      "args": [
        "-y",
        "mindwtr-mcp",
        "--db",
        "~/.local/share/mindwtr/mindwtr.db",
        "--write"
      ]
    }
  }
}

注意：請將 DB 路徑換成實際的本機 Mindwtr 資料庫路徑。

2. Claude Code（CLI）

你可以透過 CLI 加入伺服器：

bash

claude mcp add mindwtr -- \
  npx -y mindwtr-mcp --db "/path/to/mindwtr.db" --write

3. OpenAI Codex（CLI／IDE Extension）

Codex 從 ~/.codex/config.toml 讀取 MCP 伺服器組態。你也可以在受信任的專案中使用專案範圍的 .codex/config.toml。Codex CLI 與 IDE extension 共用此組態。

命令列：

bash

codex mcp add mindwtr -- \
  npx -y mindwtr-mcp \
  --db "/path/to/mindwtr.db"

只有希望 Codex 修改本機 Mindwtr 資料時，才加入 --write：

bash

codex mcp add mindwtr -- \
  npx -y mindwtr-mcp \
  --db "/path/to/mindwtr.db" --write

在 Codex TUI 中執行 /mcp，確認伺服器已啟用。

手動組態：

toml

[mcp_servers.mindwtr]
command = "npx"
args = [
  "-y",
  "mindwtr-mcp",
  "--db",
  "/path/to/mindwtr.db"
]

具備寫入權限：

toml

[mcp_servers.mindwtr]
command = "npx"
args = [
  "-y",
  "mindwtr-mcp",
  "--db",
  "/path/to/mindwtr.db",
  "--write"
]

4. Gemini CLI

Gemini CLI 使用 settings.json（使用者：~/.gemini/settings.json；專案：.gemini/settings.json）。

命令列：

bash

gemini mcp add mindwtr \
  npx -y mindwtr-mcp \
  --db "/path/to/mindwtr.db" --write

手動組態：

json

{
  "mcpServers": {
    "mindwtr": {
      "command": "npx",
      "args": [
        "-y",
        "mindwtr-mcp",
        "--db",
        "/path/to/mindwtr.db",
        "--write"
      ]
    }
  }
}

5. Gemini 應用程式（自訂應用程式）

Gemini 網頁版與行動版應用程式可以透過 URL 連接遠端 MCP 伺服器（即 gemini.google.com 上的「自訂應用程式」）。這需要 mindwtr-mcp 以 HTTP 模式執行：把伺服器託管在 Google 伺服器可以連到的位置（反向代理之後的公開 HTTPS URL；Gemini 是從 Google 端發起連線，因此 localhost 行不通），然後將該 URL 連同你的 Bearer 權杖一起新增為自訂應用程式。

6. Google Antigravity

Antigravity（Google 的代理式 IDE）從 JSON 設定檔讀取本機 MCP 伺服器，沒有用於新增伺服器的 CLI 指令。可在代理側邊欄中透過 MCP Servers -> Manage MCP Servers -> View raw config 開啟該檔案，也可以直接編輯：

目前版本：~/.gemini/config/mcp_config.json（工作區層級：.agents/mcp_config.json）
舊版本：~/.gemini/antigravity/mcp_config.json（Windows：%USERPROFILE%\.gemini\antigravity\mcp_config.json）

json

{
  "mcpServers": {
    "mindwtr": {
      "command": "npx",
      "args": [
        "-y",
        "mindwtr-mcp",
        "--db",
        "C:\\Users\\YOUR_USERNAME\\AppData\\Roaming\\mindwtr\\data\\mindwtr.db",
        "--write"
      ]
    }
  }
}

把路徑換成你所在平台的本機資料庫路徑（Windows 路徑在 JSON 中需要雙反斜線）。省略 --write 即為唯讀存取。重新啟動 Antigravity，確認 mindwtr 出現在其 MCP 伺服器設定中。Antigravity 的本機 MCP 設定與 Gemini CLI 的 settings.json 以及 Gemini 應用程式的自訂應用程式彼此獨立。

遠端存取（HTTP）

需要比 1.1.1 更新的 mindwtr-mcp 版本（或從原始碼執行）。

伺服器預設使用 stdio。傳入 --http 後改為提供可串流的 HTTP MCP 端點，遠端 MCP 用戶端即可透過 URL 連線。HTTP 模式對三種後端（本機 SQLite、桌面版 Local API 或自行託管的 Cloud）皆適用。

bash

mindwtr-mcp --http --http-token "$(openssl rand -hex 32)" --db "/path/to/mindwtr.db"

各旗標（皆有對應的 MINDWTR_MCP_HTTP* 環境變數）：

旗標	環境變數	意義
`--http`	`MINDWTR_MCP_HTTP`	啟用 HTTP 模式。設定下列任一旗標時也會隱含啟用。
`--http-token <token>`	`MINDWTR_MCP_HTTP_TOKEN`	只要啟用 HTTP 模式即必填，至少 16 個字元。可用 `openssl rand -hex 32` 產生。沒有權杖伺服器會拒絕啟動。
`--http-host <host>`	`MINDWTR_MCP_HTTP_HOST`	繫結位址，預設 `127.0.0.1`。
`--http-port <port>`	`MINDWTR_MCP_HTTP_PORT`	繫結連接埠，預設 `8722`。

桌面應用程式的內建 MCP 伺服器也使用連接埠 8722。如果它已啟用，請用 --http-port 指定另一個連接埠，例如 --http-port 8723。

MCP 端點為 POST /mcp，每個請求都必須帶 Authorization: Bearer <token>。GET /healthz 不需驗證即回傳 200 ok，供反向代理做健康檢查。沒有有效權杖的請求會得到 401；連續驗證失敗會得到 429，並附帶 Retry-After 回應標頭。超過 1 MiB 的請求主體會得到 413。HTTP 模式下伺服器只要在監聽就持續執行（不會連接 stdio），--write／唯讀行為維持不變。

伺服器未內建 TLS，也不限制已通過驗證的請求速率。若要讓伺服器對 localhost 以外開放，請在前面架一個反向代理（Caddy、nginx）處理 HTTPS，並把取得的 https:// URL 連同權杖交給遠端 MCP 用戶端。

手動執行

通常不需要手動執行（MCP 用戶端會代為執行），但手動執行有助於測試。

從 npm 執行

bash

# Read-only
npx -y mindwtr-mcp --db "/path/to/mindwtr.db"

# With write access
npx -y mindwtr-mcp --db "/path/to/mindwtr.db" --write

從原始碼執行（Bun）

bash

# Read-only
bun run mindwtr:mcp -- --db "/path/to/mindwtr.db"

# With write access
bun run mindwtr:mcp -- --db "/path/to/mindwtr.db" --write

組建及執行（Node）

bash

# Build
bun run --filter mindwtr-mcp build

# Run
node apps/mcp-server/dist/cli.js --db "/path/to/mindwtr.db"

遷移：工具重新命名（`mindwtr.` → `mindwtr_`）

工具名稱目前採用底線標記法，例如 mindwtr_list_tasks；不再記錄舊的點號標記法名稱。

可用工具

連線後，AI agent 可使用下列工具。伺服器預設為唯讀；必須傳入 --write，才能啟用任何寫入工具。寫入權限只支援 --write（沒有其他別名）。

工具	操作	需要 `--write`
`mindwtr_list_tasks`	列出任務	否
`mindwtr_list_projects`	列出專案	否
`mindwtr_get_project`	取得單一專案	否
`mindwtr_list_sections`	列出分區	否
`mindwtr_get_section`	取得單一分區	否
`mindwtr_list_areas`	列出領域	否
`mindwtr_list_people`	列出人員	否
`mindwtr_get_person`	取得單一人員	否
`mindwtr_get_task`	依 ID 取得單一任務	否
`mindwtr_add_task`	建立任務	是
`mindwtr_update_task`	更新任務	是
`mindwtr_complete_task`	標記為已完成	是
`mindwtr_delete_task`	軟刪除任務	是
`mindwtr_restore_task`	還原任務	是
`mindwtr_add_project`	建立專案	是
`mindwtr_update_project`	更新專案	是
`mindwtr_delete_project`	軟刪除專案	是
`mindwtr_add_section`	建立分區	是
`mindwtr_update_section`	更新分區	是
`mindwtr_delete_section`	軟刪除分區	是
`mindwtr_add_area`	建立領域	是
`mindwtr_update_area`	更新領域	是
`mindwtr_delete_area`	軟刪除領域	是
`mindwtr_add_person`	建立人員	是
`mindwtr_update_person`	更新人員	是
`mindwtr_rename_person`	重新命名人員	是
`mindwtr_delete_person`	軟刪除人員	是

讀取工具

mindwtr_list_tasks：使用篩選條件（狀態、專案、日期範圍、搜尋、用於今日專注的 isFocusedToday、用於 GTD 可執行性的 view）列出任務。
mindwtr_list_projects：列出所有專案。
mindwtr_get_project：依 ID 取得特定專案的詳細資料。
mindwtr_list_sections：列出專案分區，也可依專案篩選。
mindwtr_get_section：依 ID 取得特定分區的詳細資料。
mindwtr_list_areas：列出所有領域。
mindwtr_list_people：列出受管理的人員記錄。
mindwtr_get_person：依 ID 取得特定人員的詳細資料。
mindwtr_get_task：依 ID 取得特定任務的詳細資料。

寫入工具（需要 `--write`）

寫入工具可用於本機資料庫及自行託管的 Cloud 後端，但 Cloud 模式有兩項例外：人員寫入工具及 mindwtr_restore_task 會傳回明確錯誤，因為 Cloud API 目前尚無相應端點。

mindwtr-mcp 允許在更新任務或專案時保留既有的網路共用連結，或修改其標題。URI 必須保持完全一致；可以重用附件 ID，也可以省略 ID，透過 URI 比對。該連結必須仍存在於同一個任務或專案中且未被刪除。MCP 仍會拒絕新增網路共用連結、變更網路共用 URI，以及還原已刪除的網路共用連結。

mindwtr_add_task：建立新任務。支援自然語言 quickAdd（例如「Buy milk @errands /due:tomorrow」）。同時支援透過 attachments 新增連結附件。
mindwtr_update_task：更新現有任務，包括 dueDate、startTime、reviewAt 及 isFocusedToday 等排程欄位（支援使用 null 清除欄位）。attachments 用於設定連結附件：你傳入的清單就是連結的完整集合，未列出的連結會被移除，檔案附件不受影響，傳入 null 會清除所有連結。
mindwtr_complete_task：將任務標記為已完成。
mindwtr_delete_task：軟刪除任務。
mindwtr_restore_task：還原已軟刪除的任務。
mindwtr_add_project：建立新專案，可選用 startDate、dueDate 及 reviewAt。也可以透過 attachments 新增連結附件。
mindwtr_update_project：更新專案，可選用 startDate、dueDate 及 reviewAt。attachments 中的連結附件遵循與更新任務時相同的完整清單規則。
mindwtr_delete_project：軟刪除專案。
mindwtr_add_section：在專案內建立分區。
mindwtr_update_section：更新專案分區。
mindwtr_delete_section：軟刪除專案分區。該分區中的任務會保留，並由 core 移至無分區狀態。
mindwtr_add_area：建立新領域。
mindwtr_update_area：更新領域。
mindwtr_delete_area：軟刪除領域。
mindwtr_add_person：建立受管理的人員，供受指派者及等待中任務使用。
mindwtr_update_person：更新受管理人員的中繼資料。
mindwtr_rename_person：重新命名受管理人員，也可更新完全相符的任務指派。
mindwtr_delete_person：軟刪除受管理人員，但不清除任務指派。

Schema 注意事項：

任務寫入工具涵蓋 dueDate、startTime，更新時也涵蓋 reviewAt。
專案寫入工具同時涵蓋 dueDate 及 reviewAt。
人員寫入工具涵蓋 name、note、referenceLink，重新命名時也可更新指派。
確切的標準輸入請參閱 apps/mcp-server/README.md。

權限矩陣

決定要以唯讀模式或 --write 執行伺服器時，請參考此矩陣。

工具	資料存取	修改類型	唯讀模式	`--write` 模式
`mindwtr_list_tasks`	任務列（已篩選）	無	允許	允許
`mindwtr_list_projects`	專案列	無	允許	允許
`mindwtr_get_project`	依 ID 取得單一專案	無	允許	允許
`mindwtr_list_sections`	分區列	無	允許	允許
`mindwtr_get_section`	依 ID 取得單一分區	無	允許	允許
`mindwtr_list_areas`	領域列	無	允許	允許
`mindwtr_list_people`	人員列	無	允許	允許
`mindwtr_get_person`	依 ID 取得單一人員	無	允許	允許
`mindwtr_get_task`	依 ID 取得單一任務	無	允許	允許
`mindwtr_add_task`	任務資料表	插入	拒絕	允許
`mindwtr_update_task`	任務資料表	更新	拒絕	允許
`mindwtr_complete_task`	任務資料表	更新狀態	拒絕	允許
`mindwtr_delete_task`	任務資料表	軟刪除	拒絕	允許
`mindwtr_restore_task`	任務資料表	還原軟刪除	拒絕	允許
`mindwtr_add_project`	專案資料表	插入	拒絕	允許
`mindwtr_update_project`	專案資料表	更新	拒絕	允許
`mindwtr_delete_project`	專案資料表	軟刪除	拒絕	允許
`mindwtr_add_section`	分區資料表	插入	拒絕	允許
`mindwtr_update_section`	分區資料表	更新	拒絕	允許
`mindwtr_delete_section`	分區資料表	軟刪除	拒絕	允許
`mindwtr_add_area`	領域資料表	插入	拒絕	允許
`mindwtr_update_area`	領域資料表	更新	拒絕	允許
`mindwtr_delete_area`	領域資料表	軟刪除	拒絕	允許
`mindwtr_add_person`	人員資料表	插入	拒絕	允許
`mindwtr_update_person`	人員資料表	更新	拒絕	允許
`mindwtr_rename_person`	人員資料表／任務	重新命名／更新參照	拒絕	允許
`mindwtr_delete_person`	人員資料表	軟刪除	拒絕	允許

實務建議：

探索及製作報告時，預設使用唯讀模式。
只有你信任 AI 用戶端可編輯該後端時，才啟用 --write：本機資料庫或你自己的 Cloud 伺服器。
Agent 工作流程在執行刪除／完成操作前，最好要求明確確認。

進階使用範例

1）引導式每週回顧

呼叫 mindwtr_list_tasks，使用 status: "waiting" 及 status: "someday"。
依專案摘要停滯項目。
對所選項目呼叫 mindwtr_update_task，設定 reviewAt。

2）收集箱分類工作階段

呼叫 mindwtr_list_tasks，使用 status: "inbox" 及 sortBy: "createdAt"。
對每項任務使用 mindwtr_update_task 分類（next、waiting、reference 等）。
第二輪再補上缺少的中繼資料（專案、情境、標籤）。

3）安全批次關閉模式

對於可能造成破壞的自動化：

執行讀取階段：只列出候選 ID。
顯示確認摘要（數量及標題）。
只有取得使用者明確核准後，才執行寫入（complete_task／delete_task）。
保留 ID，以便透過 restore_task 回復。

4）以自然語言快速收集

使用 mindwtr_add_task + quickAdd：

json

{
  "quickAdd": "Follow up with Alex +Hiring @work #ops /due:tomorrow 10am"
}

若在快速收集流程中，使用解析命令比手動設定每個欄位更有效率，就適合採用此方式。

工具參考

所有工具都在 content.text 欄位中傳回 JSON。請解析 JSON 以取得實際 payload。

操作限制

將 Mindwtr 接入 agent 工作流程時，請留意下列限制：

mindwtr_list_tasks 預設為 limit: 200，且 limit 上限為 500。
MCP 任務建立／更新驗證會將任務標題限制在 500 個字元。
MCP 任務建立會將快速新增輸入限制在 2000 個字元，與 cloud task API 的快速新增限制相同。
SQLite layer 使用 5 秒的 busy_timeout，因此資料庫鎖定時應會失敗，而不是無限期停滯。

若需要超過 500 項任務，請以 limit + offset 分頁，不要期待一次取得無上限的回應。

`mindwtr_list_tasks`

輸入欄位

status：inbox | next | waiting | someday | reference | done | archived | all
projectId：string
includeDeleted：boolean
limit：number
offset：number
search：string
dueDateFrom：ISO date 或 datetime string（依日曆日期比較）
dueDateTo：ISO date 或 datetime string（依日曆日期比較）
isFocusedToday：boolean
view：available | deferred | blocked —— GTD 可執行性。available = 現在就能做（下一步行動，或複查日期已到的任務；所屬專案處於作用中，已過開始日期，且未被循序專案中較早的步驟擋住）。deferred = 開始日期仍在未來。blocked = 循序專案中較早的步驟占著位置。
sortBy：updatedAt | createdAt | dueDate | title | priority
sortOrder：asc | desc

範例

json

{
  "status": "next",
  "limit": 20,
  "offset": 0,
  "sortBy": "updatedAt",
  "sortOrder": "desc"
}

回應

json

{
  "tasks": [
    {
      "id": "task-uuid",
      "title": "Follow up with design",
      "status": "next",
      "updatedAt": "2026-01-25T03:45:57.246Z"
    }
  ]
}

`mindwtr_list_projects`

輸入欄位

回應

json

{
  "projects": [
    {
      "id": "project-uuid",
      "title": "Mindwtr",
      "status": "active"
    }
  ]
}

`mindwtr_get_project`

輸入欄位

id：string（project UUID）
includeDeleted：boolean（選用）

範例

json

{ "id": "project-uuid" }

`mindwtr_list_sections`

輸入欄位

projectId：string（選用）
includeDeleted：boolean（選用）

回應

json

{
  "sections": [
    {
      "id": "section-uuid",
      "projectId": "project-uuid",
      "title": "Planning"
    }
  ]
}

`mindwtr_get_section`

輸入欄位

id：string（section UUID）
includeDeleted：boolean（選用）

範例

json

{ "id": "section-uuid" }

`mindwtr_list_areas`

輸入欄位

回應

json

{
  "areas": [
    {
      "id": "area-uuid",
      "name": "Work"
    }
  ]
}

`mindwtr_list_people`

輸入欄位

includeDeleted：boolean（選用）

回應

json

{
  "people": [
    {
      "id": "person-uuid",
      "name": "Alex"
    }
  ]
}

`mindwtr_get_person`

輸入欄位

id：string（person UUID）
includeDeleted：boolean（選用）

範例

json

{ "id": "person-uuid" }

`mindwtr_get_task`

輸入欄位

id：string（task UUID）
includeDeleted：boolean（選用）

範例

json

{ "id": "task-uuid" }

`mindwtr_add_task`（寫入）

輸入欄位

title：string（省略 quickAdd 時必填）
quickAdd：string（省略 title 時必填）
status：inbox | next | waiting | someday | reference | done | archived
projectId：string
sectionId：string
dueDate：ISO string
startTime：ISO string
recurrence：重複規則物件或 RFC 5545 RRULE 字串
contexts：string[]
tags：string[]
description：string
priority：low | medium | high | urgent
energyLevel：low | medium | high
assignedTo：string
timeEstimate：5min | 10min | 15min | 30min | 1hr | 2hr | 3hr | 4hr | 4hr+
其他可寫欄位：areaId、reviewAt、taskMode、relativeStartOffset、showFutureRecurrence、pushCount、checklist、textDirection、location、isFocusedToday、timeSpentMinutes、suppressMindwtrReminders、repeatReminderMinutes、attachments

範例

json

{
  "quickAdd": "Send invoice +Acme /due:tomorrow 9am #finance"
}

`mindwtr_update_task`（寫入）

輸入欄位

id：string（task UUID）
title、status、projectId、sectionId、areaId、dueDate、startTime、contexts、tags、description、priority、energyLevel、assignedTo、timeEstimate、reviewAt、taskMode、relativeStartOffset、showFutureRecurrence、pushCount、checklist、textDirection、location、isFocusedToday、timeSpentMinutes、suppressMindwtrReminders、repeatReminderMinutes、order、boardOrder、focusOrder、attachments
recurrence：重複規則物件、RFC 5545 RRULE 字串，或使用 null 清除

注意事項

使用 null 清除可為 null 的欄位。這適用於 projectId、dueDate、startTime、contexts 及 tags 等任務欄位；areaId、startDate、dueDate、reviewAt 及 supportNotes 等專案欄位；分區的 description；領域的 color 及 icon；以及人員的 note 及 referenceLink。

範例

json

{
  "id": "task-uuid",
  "status": "waiting",
  "reviewAt": "2026-01-27T09:00:00.000Z"
}

`mindwtr_complete_task`（寫入）

輸入欄位

id：string（task UUID）

`mindwtr_delete_task`（寫入）

輸入欄位

id：string（task UUID）

`mindwtr_restore_task`（寫入）

輸入欄位

id：string（task UUID）

`mindwtr_add_project`（寫入）

輸入欄位

title：string
color：string（選用）
status：active | someday | waiting | archived（選用）
areaId：string 或 null
isSequential：boolean（選用）
isFocused：boolean（選用）
startDate：ISO string 或 null
dueDate：ISO string 或 null
reviewAt：ISO string 或 null
supportNotes：string 或 null

`mindwtr_update_project`（寫入）

輸入欄位

id：string（project UUID）
title、color、status、areaId、isSequential、isFocused、startDate、dueDate、reviewAt、supportNotes、attachments

`mindwtr_delete_project`（寫入）

輸入欄位

id：string（project UUID）

`mindwtr_add_section`（寫入）

輸入欄位

projectId：string
title：string
description：string 或 null（選用）
order：number（選用）
isCollapsed：boolean（選用）

`mindwtr_update_section`（寫入）

輸入欄位

id：string（section UUID）
title、description、order、isCollapsed

`mindwtr_delete_section`（寫入）

輸入欄位

id：string（section UUID）

`mindwtr_add_area`（寫入）

輸入欄位

name：string
color：string（選用）
icon：string（選用）

`mindwtr_update_area`（寫入）

輸入欄位

id：string（area UUID）
name、color、icon

`mindwtr_delete_area`（寫入）

輸入欄位

id：string（area UUID）

`mindwtr_add_person`（寫入）

輸入欄位

name：string
note：string 或 null（選用）
referenceLink：string 或 null（選用）

`mindwtr_update_person`（寫入）

輸入欄位

id：string（person UUID）
name、note、referenceLink

`mindwtr_rename_person`（寫入）

輸入欄位

id：string（person UUID）
name：string
updateTasks：boolean（選用）

`mindwtr_delete_person`（寫入）

輸入欄位

id：string（person UUID）

輸出格式注意事項

工具輸出是 JSON string，而非結構化 MCP 值。用戶端應解析 content[0].text。
任務／專案 ID 是來自本機 SQLite 資料庫的 UUID。
日期採用 ISO 8601 string（UTC）。

安全性與注意事項

並行處理（本機 SQLite 模式）：伺服器使用 SQLite WAL 模式。遇到暫時鎖定衝突時，伺服器會依目前資料重新執行寫入。只有這些重試全數失敗後，用戶端才需要重試。
共用邏輯：寫入操作使用共用的 @mindwtr/core 函式庫，確保套用商業規則。
保持執行：在 stdio 模式下，只要 stdin 維持開啟，伺服器就會繼續執行；在 HTTP 模式下，只要監聽器執行，伺服器就會繼續執行。

`cancelledAt`

Task 和 Project 的 cancelledAt 是帶時區的可選 ISO 時間戳記。設定它會取消並封存該紀錄。取消的任務沒有 completedAt，也不會產生下一次重複任務；取消專案會保留已完成步驟，取消剩餘待辦。同步使用此欄位前，請升級所有會寫入資料的用戶端。詳見 GTD 工作流程。

單獨傳送 cancelledAt: null 只會清除取消標記，不會重新啟用。重新啟用請明確設定非封存的 status。

疑難排解

"Command not found"：在 MCP 用戶端組態中使用 npx -y mindwtr-mcp，或使用 npm install -g mindwtr-mcp 全域安裝 package。
用戶端連線問題：確認 MCP 用戶端組態中的命令不是 bun run，因為它可能輸出額外文字。建議使用 npx -y mindwtr-mcp；若使用原始碼簽出版本，請直接以 bun 執行原始碼檔案，或以 node 執行組建後的檔案。

MCP 伺服器 ​

應用程式 Binary 與 MCP 輔助工具 ​

桌面版內建 MCP ​

連接 Codex ​

權限與連接埠 ​

需求 ​

預設資料庫位置 ​

設定與組態 ​

桌面版 Local API 模式 ​

自行託管 Cloud 模式 ​

主要引數 ​

1. Claude Desktop ​

2. Claude Code（CLI） ​

3. OpenAI Codex（CLI／IDE Extension） ​

4. Gemini CLI ​

5. Gemini 應用程式（自訂應用程式） ​

6. Google Antigravity ​

遠端存取（HTTP） ​

手動執行 ​

從 npm 執行 ​

從原始碼執行（Bun） ​

組建及執行（Node） ​

遷移：工具重新命名（mindwtr.* → mindwtr_*） ​

可用工具 ​

讀取工具 ​

寫入工具（需要 --write） ​

權限矩陣 ​

進階使用範例 ​

1）引導式每週回顧 ​

2）收集箱分類工作階段 ​

3）安全批次關閉模式 ​

4）以自然語言快速收集 ​

工具參考 ​

操作限制 ​

mindwtr_list_tasks ​

mindwtr_list_projects ​

mindwtr_get_project ​

mindwtr_list_sections ​

mindwtr_get_section ​

mindwtr_list_areas ​

mindwtr_list_people ​

mindwtr_get_person ​

mindwtr_get_task ​

mindwtr_add_task（寫入） ​

mindwtr_update_task（寫入） ​

mindwtr_complete_task（寫入） ​

mindwtr_delete_task（寫入） ​

mindwtr_restore_task（寫入） ​

mindwtr_add_project（寫入） ​

mindwtr_update_project（寫入） ​

mindwtr_delete_project（寫入） ​

mindwtr_add_section（寫入） ​

mindwtr_update_section（寫入） ​

mindwtr_delete_section（寫入） ​

mindwtr_add_area（寫入） ​

mindwtr_update_area（寫入） ​

mindwtr_delete_area（寫入） ​

mindwtr_add_person（寫入） ​

mindwtr_update_person（寫入） ​

mindwtr_rename_person（寫入） ​

mindwtr_delete_person（寫入） ​

輸出格式注意事項 ​

安全性與注意事項 ​

cancelledAt ​

疑難排解 ​

MCP 伺服器

應用程式 Binary 與 MCP 輔助工具

桌面版內建 MCP

連接 Codex

權限與連接埠

需求

預設資料庫位置

設定與組態

桌面版 Local API 模式

自行託管 Cloud 模式

主要引數

1. Claude Desktop

2. Claude Code（CLI）

3. OpenAI Codex（CLI／IDE Extension）

4. Gemini CLI

5. Gemini 應用程式（自訂應用程式）

6. Google Antigravity

遠端存取（HTTP）

手動執行

從 npm 執行

從原始碼執行（Bun）

組建及執行（Node）

遷移：工具重新命名（`mindwtr.` → `mindwtr_`）

可用工具

讀取工具

寫入工具（需要 `--write`）

權限矩陣

進階使用範例

1）引導式每週回顧

2）收集箱分類工作階段

3）安全批次關閉模式

4）以自然語言快速收集

工具參考

操作限制

`mindwtr_list_tasks`

`mindwtr_list_projects`

`mindwtr_get_project`

`mindwtr_list_sections`

`mindwtr_get_section`

`mindwtr_list_areas`

`mindwtr_list_people`

`mindwtr_get_person`

`mindwtr_get_task`

`mindwtr_add_task`（寫入）

`mindwtr_update_task`（寫入）

`mindwtr_complete_task`（寫入）

`mindwtr_delete_task`（寫入）

`mindwtr_restore_task`（寫入）

`mindwtr_add_project`（寫入）

`mindwtr_update_project`（寫入）

`mindwtr_delete_project`（寫入）

`mindwtr_add_section`（寫入）

`mindwtr_update_section`（寫入）

`mindwtr_delete_section`（寫入）

`mindwtr_add_area`（寫入）

`mindwtr_update_area`（寫入）

`mindwtr_delete_area`（寫入）

`mindwtr_add_person`（寫入）

`mindwtr_update_person`（寫入）

`mindwtr_rename_person`（寫入）

`mindwtr_delete_person`（寫入）

輸出格式注意事項

安全性與注意事項

`cancelledAt`

疑難排解