讓代理來處理你的待辦清單

MCP 還是 CLI？

如果你的代理已經與 TaskForge 建立 MCP 連線，請優先使用 MCP 工具。它們具有型別，會回傳結構化錯誤，方便代理據此自我修正，而且不需要在你的 PATH 中安裝任何東西。如果是沒有 MCP 連線的 shell 環境，例如指令碼、cron、CI，或是在儲存庫簽出目錄中工作的程式代理，請改用 CLI。兩者驅動的是同一個引擎，語意完全一致，選擇你執行環境中已經接好的那一個即可。手動編輯儲存庫檔案是最後的手段。

安裝

{
  "mcpServers": {
    "taskforge": {
      "command": "npx",
      "args": ["-y", "taskforge-md", "mcp", "--stdio"],
      "env": {
        "TASKFORGE_VAULT": "/path/to/your/vault"
      }
    }
  }
}

在 Windows 上，請在 npx 前加上 cmd /c。像 Claude Desktop 這樣的桌面 MCP 使用者端啟動伺服器時不經過 shell，而 npx 是 .cmd 指令碼，Windows 只能透過 shell 執行它：

{
  "mcpServers": {
    "taskforge": {
      "command": "cmd",
      "args": ["/c", "npx", "-y", "taskforge-md", "mcp", "--stdio"],
      "env": {
        "TASKFORGE_VAULT": "C:\\path\\to\\your\\vault"
      }
    }
  }
}

自行從原始碼建置了 taskforge，而不是使用 npx？請將設定直接指向該執行檔：

"command": "taskforge",
"args": ["mcp", "--stdio"]

僅支援桌面版，因為 MCP 客戶端都在桌面環境中執行。taskforge 以單一原生執行檔形式提供，支援 macOS 與 Windows，MCP 伺服器是它的子指令之一。 Linux 版即將推出。

完整工具集

總共有 30 個工具，涵蓋任務的完整生命週期：新增、讀取、更新、完成、封存與刪除，每項都有對應的批次版本；此外還有移動、重新指定上層任務，以及在行內格式與任務檔案之間轉換；寫入前的 lint 檢查；用於檢查儲存庫健康狀態的 doctor 呼叫；以及 schema 與空間資源，讓代理在動手前先了解你的格式。下面這六個是最常用的。每次呼叫都會重新從磁碟讀取儲存庫，因此代理操作的永遠是最新的檔案。

每個工具現在都帶有註解，讓客戶端一眼就能看出哪些呼叫只是讀取、哪些會寫入、哪一個會刪除。其餘工具還包括 bulk_add_tasks、bulk_update_tasks、bulk_complete_tasks、bulk_delete_tasks、get_tasks、archive_task、move_task、bulk_move_tasks、convert_task、bulk_convert_tasks、outdent_task、bulk_reparent_tasks、lint_task、doctor、list_spaces 與 create_note, read_note, update_note, patch_note_block, patch_note_frontmatter, delete_note, move_note, normalize_references, get_dialect。

三項資源

除了工具之外，伺服器還提供唯讀情境資訊，讓代理在動手之前先了解你儲存庫的規則：

如果找不到你的儲存庫

伺服器一律會啟動，即使還不知道儲存庫在哪裡，因此 Claude Desktop 永遠不會顯示令人一頭霧水的'server failed to start'。當某個工具呼叫無法解析出儲存庫時，會回傳一則代理能夠轉達的簡單錯誤訊息：請將 TASKFORGE_VAULT 環境變數設為你的儲存庫路徑，或重新安裝套件包，並在系統詢問時輸入儲存庫目錄。

僅限本機

TaskForge MCP 伺服器在本機執行，讀寫你儲存庫中的 Markdown 檔案。透過 npx 安裝時會從 npm 下載套件。你的 AI 客戶端可能會把工具的輸入與結果傳送給其供應商，其隱私設定仍然適用。你原本使用的儲存庫同步方式會在裝置之間搬移這些編輯。

偏好使用終端機？

如果你想用指令碼處理任務，或執行一次性指令，而不是透過代理操作，taskforge CLI 能以同樣的規則處理同一個儲存庫。

常見問題