MCP 服务器

Mindwtr 提供可选的 MCP（Model Context Protocol，模型上下文协议）服务器。它允许你将 AI 智能体（例如 Claude Desktop、Claude Code、OpenAI Codex 或 Gemini CLI）连接到本地 Mindwtr 数据库、桌面端 Local API 或自托管的 Mindwtr Cloud 端点。

独立辅助程序默认使用 stdio。

实现参考：apps/mcp-server/README.md。如果该 README 与当前服务器代码或生成的 MCP 工具 schema 不一致，以代码和 schema 为准。

应用二进制文件与 MCP 辅助程序

独立 MCP 辅助程序继续以 mindwtr-mcp 发布，并已列入公共 MCP Registry。

你无需从源代码运行整个应用即可使用 MCP。正常使用桌面端应用二进制文件管理任务，然后让 MCP 客户端通过 npx 启动 mindwtr-mcp，或使用 npm 全局安装它。让辅助程序指向桌面端应用的本地 mindwtr.db，或使用下文的 Local API 后端。

桌面端的默认数据库路径列在下方的默认数据库位置中。移动端二进制文件不公开本地 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 及更高版本提供预构建二进制文件。Node 20 仍可运行服务器，但安装时需要 C++ 构建工具
仅使用 API 的安装可以通过 --omit=optional 省略可选的 SQLite 扩展。
npm 或其他 Node 包运行器，用于已发布的 mindwtr-mcp 包
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"
  ]
}

该包默认为只读。只有在你明确希望 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 服务器，并希望在不公开本地 SQLite 文件的情况下使用 MCP 工具时，请使用 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，请先升级服务器再更新链接；辅助程序会拒绝更新，不执行写入。仅修改其他字段以及创建任务或项目的行为保持不变。

这不是被搁置的托管多租户连接器。Cloud 服务器和 MCP 辅助程序仍由你自行运行；Mindwtr 并未运营存储所有人任务数据的服务。

如需全局安装，请改用：

bash

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

关键参数

--db "/path/to/mindwtr.db"：本地模式下 SQLite 数据库的路径。
--write：在本地或 Cloud 模式下启用写入操作（添加、更新、完成、删除）。若没有此标志，服务器为只读。
--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"
      ]
    }
  }
}

注意：请将数据库路径替换为你实际的本地 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 扩展）

Codex 从 ~/.codex/config.toml 读取 MCP 服务器配置。你也可以在受信任的项目中使用项目范围的 .codex/config.toml。Codex CLI 和 IDE 扩展共享此配置。

命令行：

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 智能体可以使用以下工具。服务器默认为只读；传入 --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 模式下返回明确错误，因为 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：软删除项目分区。核心逻辑会保留该分区内的任务，并将它们移至无分区状态。
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 服务器。
对于智能体工作流，执行删除/完成操作前最好要求明确确认。

高级用法示例

1）引导式每周回顾

使用 status: "waiting" 和 status: "someday" 调用 mindwtr_list_tasks。
按项目汇总停滞事项。
对选定事项调用 mindwtr_update_task 设置 reviewAt。

2）收集箱整理会话

使用 status: "inbox" 和 sortBy: "createdAt" 调用 mindwtr_list_tasks。
对每项任务使用 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 接入智能体工作流时，以下限制很有用：

mindwtr_list_tasks 默认为 limit: 200，且 limit 上限为 500。
MCP 任务创建/更新验证将任务标题限制为 500 个字符。
MCP 任务创建将快速添加输入限制为 2000 个字符，与 Cloud 任务 API 的快速添加限制一致。
SQLite 层使用 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 日期或日期时间字符串（按日历日期比较）
dueDateTo：ISO 日期或日期时间字符串（按日历日期比较）
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（项目 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（分区 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（人员 UUID）
includeDeleted：boolean（可选）

示例

json

{ "id": "person-uuid" }

`mindwtr_get_task`

输入字段

id：string（任务 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（任务 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 清除可为空的字段。这适用于 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（任务 UUID）

`mindwtr_delete_task`（写入）

输入字段

id：string（任务 UUID）

`mindwtr_restore_task`（写入）

输入字段

id：string（任务 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（项目 UUID）
title、color、status、areaId、isSequential、isFocused、startDate、dueDate、reviewAt、supportNotes、attachments

`mindwtr_delete_project`（写入）

输入字段

id：string（项目 UUID）

`mindwtr_add_section`（写入）

输入字段

projectId：string
title：string
description：string 或 null（可选）
order：number（可选）
isCollapsed：boolean（可选）

`mindwtr_update_section`（写入）

输入字段

id：string（分区 UUID）
title、description、order、isCollapsed

`mindwtr_delete_section`（写入）

输入字段

id：string（分区 UUID）

`mindwtr_add_area`（写入）

输入字段

name：string
color：string（可选）
icon：string（可选）

`mindwtr_update_area`（写入）

输入字段

id：string（领域 UUID）
name、color、icon

`mindwtr_delete_area`（写入）

输入字段

id：string（领域 UUID）

`mindwtr_add_person`（写入）

输入字段

name：string
note：string 或 null（可选）
referenceLink：string 或 null（可选）

`mindwtr_update_person`（写入）

输入字段

id：string（人员 UUID）
name、note、referenceLink

`mindwtr_rename_person`（写入）

输入字段

id：string（人员 UUID）
name：string
updateTasks：boolean（可选）

`mindwtr_delete_person`（写入）

输入字段

id：string（人员 UUID）

输出格式说明

工具输出是 JSON 字符串，而不是结构化 MCP 值。客户端应解析 content[0].text。
任务/项目 ID 是本地 SQLite 数据库中的 UUID。
日期是 ISO 8601 字符串（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 全局安装该包。
客户端连接问题：请确保没有在 MCP 客户端配置中使用 bun run 作为命令，因为它可能输出额外文本。优先使用 npx -y mindwtr-mcp；对于源码检出，请直接用 bun 运行源文件，或用 node 运行构建后的文件。

MCP 服务器 ​

应用二进制文件与 MCP 辅助程序 ​

桌面端内置 MCP ​

连接 Codex ​

权限与端口 ​

要求 ​

默认数据库位置 ​

设置与配置 ​

桌面端 Local API 模式 ​

自托管 Cloud 模式 ​

关键参数 ​

1. Claude Desktop ​

2. Claude Code（CLI） ​

3. OpenAI Codex（CLI / IDE 扩展） ​

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 服务器

应用二进制文件与 MCP 辅助程序

桌面端内置 MCP

连接 Codex

权限与端口

要求

默认数据库位置

设置与配置

桌面端 Local API 模式

自托管 Cloud 模式

关键参数

1. Claude Desktop

2. Claude Code（CLI）

3. OpenAI Codex（CLI / IDE 扩展）

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`

故障排除