Mindwtr

Mindwtr MCP 服务

Mindwtr 的 MCP 服务。将 MCP 客户端（Claude Desktop 等）连接到本地 SQLite 数据库、桌面应用的 Local API，或可自托管的 Mindwtr Cloud 端点。

默认情况下，这是一个 stdio 服务：MCP 客户端将其作为子进程启动，并通过 stdin/stdout 使用 JSON-RPC 通信。它还提供可选的 HTTP 传输（参见远程访问（HTTP）），供希望通过 URL 将其公开的自托管用户使用。

---

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

桌面应用在**设置 → 集成 → 本地 MCP 服务（高级）**中内置了 MCP 服务，无需单独安装运行时或辅助程序。桌面安装程序不会将独立的 mindwtr-mcp 命令添加到你的 PATH；移动应用不托管 MCP。

使用 MCP 不需要从源代码运行整个应用。你可以使用常规桌面应用二进制文件完成任务，然后使用 Bun 从代码仓库运行这个独立的 MCP 辅助程序，或构建一次辅助程序后使用 Node 运行。将辅助程序指向桌面应用的本地 mindwtr.db，或使用下方的 Local API 后端。

在桌面设备上，可在要求中列出的默认数据库位置找到数据库。移动端二进制文件不提供本地 MCP 服务接口。

---

要求

这些要求适用于独立辅助程序，不适用于内置桌面服务。

• 运行辅助程序需要 Node.js 20+。建议使用 Node.js 22+，以便在受支持的平台上使用预构建的 SQLite 二进制文件；Node 20 需要原生构建工具链。
• 基于 Node 的 SQLite 模式使用可选的 better-sqlite3 原生插件。仅使用 API 的安装可以通过 --omit=optional 忽略该插件。如果你的平台没有可用的预构建二进制文件，npm 需要可用的 C/C++ 构建工具链和 Python，以供 node-gyp 使用。
• Bun（推荐用于此代码库的开发）
• SQLite 模式需要本地数据库（mindwtr.db）；API 模式需要正在运行的桌面 Local API 和 bearer token；Cloud 模式需要可自托管的 Mindwtr Cloud URL 和 bearer token

对于使用 npm 12 的 SQLite 模式，请批准 SQLite 依赖项的安装脚本；否则，即使安装成功，启动时仍可能因缺少原生绑定而失败。对于 npx 或全局安装，只允许 better-sqlite3：

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。批准前请检查依赖项；不要启用所有依赖项脚本。

默认数据库位置。自版本 1.3.2 起，已安装的 Windows 和 macOS 应用会将数据库保存在 data 子文件夹中；Linux 和便携版不变。服务会同时检查这两个位置，因此无论数据库位于哪个位置都能找到。

• Linux：~/.local/share/mindwtr/mindwtr.db（Flatpak：~/.var/app/tech.dongdongbh.mindwtr/data/mindwtr/mindwtr.db；Snap：~/snap/mindwtr/current/.local/share/mindwtr/mindwtr.db）
• macOS，1.3.2 及更高版本：~/Library/Application Support/mindwtr/data/mindwtr.db
• macOS，1.3.1 及更早版本：~/Library/Application Support/mindwtr/mindwtr.db
• Windows，1.3.2 及更高版本：%APPDATA%\mindwtr\data\mindwtr.db
• Windows，1.3.1 及更早版本：%APPDATA%\mindwtr\mindwtr.db

沙盒版 macOS 应用的其他路径：

• 1.3.2 及更高版本：~/Library/Containers/tech.dongdongbh.mindwtr/Data/Library/Application Support/mindwtr/data/mindwtr.db
• 1.3.1 及更早版本：~/Library/Containers/tech.dongdongbh.mindwtr/Data/Library/Application Support/mindwtr/mindwtr.db

在 MCP 客户端配置中固定的 --db 路径在迁移后仍可使用：如果配置的路径下没有该文件，服务会检查对应的 data 子文件夹（或父文件夹），并在 stderr 中报告打开的是哪个数据库。

如果 mindwtr.db 不存在，但同一桌面数据文件夹中存在 data.json，MCP 服务会在首次启动时根据该本地数据快照初始化一个新的 SQLite 数据库。 桌面数据文件夹是指上述默认位置中存放 mindwtr.db 的文件夹。

你可以通过以下方式覆盖本地模式：

• --db /path/to/mindwtr.db
• MINDWTR_DB_PATH=/path/to/mindwtr.db
• MINDWTR_DB=/path/to/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

---

启动 / 停止

从 npm 运行

安装已发布的软件包后，直接运行：

mindwtr-mcp --db "/path/to/mindwtr.db"

也可以让 MCP 客户端通过 npx 启动：

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

npm 软件包默认是只读的。仅当你明确需要启用添加 / 更新 / 完成 / 删除工具时，才添加 --write。

桌面本地 API 模式

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

在设置中启用桌面应用的 本地 API，并复制其 bearer token。保持应用和 API 处于运行状态。此后端使用应用的 REST 端点，不会打开数据库，也不会回退到 SQLite。

对于仅使用 API 的安装，可省略可选的原生 SQLite 插件：

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

配置 MCP 客户端通过环境变量传递 token，而不是将其放入命令行参数：

{
  "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，否则写入仍处于禁用状态。如果应用已关闭或 token 无效，辅助程序会返回错误。超时的写入可能已到达应用：重试前请检查任务，因为辅助程序不会自动重试写入。

MCP 能力	桌面本地 API 支持情况
列出/获取任务	支持，包括丰富的搜索运算符、日期筛选、排序和分页
创建任务	支持指定标题和字段；quickAdd 不可用
更新/完成/删除/恢复任务	通过 API 对应的端点支持；不能将终止状态变更作为普通编辑提交
列出/获取/创建/更新/删除项目	支持 API 的基本项目字段：标题、颜色、状态、Area 和顺序行为
列出区域	支持
查看分区目录和项目分配	不可用；支持通过已知 ID 分配任务
分区、受管理人员、Area 写入	不可用；这些工具在 API 模式下会被隐藏
GTD 可用性 view	不可用，因为 API 不会公开所需的分区快照
替换附件链接	不可用，因为 API 不提供有条件的附件更新

其他不受支持的字段会在写入前被拒绝。桌面 API 的重复规则限制同样适用；某些重复任务的完成操作必须在应用中进行。此后端不保证与 SQLite/Cloud 工具完全一致。

--api-url 用于选择辅助程序的数据源。--http 则用于选择 MCP 客户端如何连接到辅助程序；它可与任何后端搭配使用，并且使用单独的身份验证 token。

自托管 Cloud 模式

如果你运行自己的 Mindwtr Cloud 服务，并希望使用 MCP 工具而不将辅助程序指向本地 SQLite 数据库，请使用 Cloud 模式：

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

也可以通过环境变量传递相同的值：

MINDWTR_MCP_CLOUD_URL="https://mindwtr.example.com" \
MINDWTR_MCP_CLOUD_TOKEN="$MINDWTR_TOKEN" \
npx -y mindwtr-mcp

Cloud 模式使用自托管的 Cloud API。读取操作来自当前的 /v1/data 快照；启用 --write 后，任务/项目/分区/区域的写入会通过 Cloud 服务针对各资源的 REST 端点（POST /v1/tasks、PATCH /v1/tasks/:id 等）进行，因此会获得与其他客户端相同的验证和修订版本标记。未启用 --write 时，写入工具会返回 read_only。Cloud 模式目前不支持编辑人员和恢复已删除的任务。

这并不意味着 Mindwtr Cloud 本身变成了托管的 MCP 服务。它仍是同一个 stdio 辅助程序，只是由你运行的 Cloud URL 提供后端支持。

对于私有 HTTP 测试部署，共享 Cloud 客户端规则允许使用本地/私有 HTTP URL。只有在你有意信任某个自托管端点时，才使用 --cloud-allow-insecure-http=true。

远程访问（HTTP）

默认情况下，mindwtr-mcp 只使用 stdio。传入 --http 后，服务器还会（而不是通过 stdio）提供无状态的可流式传输 HTTP MCP 端点，这样你就可以让远程 MCP 客户端连接到一个 URL。典型场景是 Gemini Spark 的“自定义应用”，它需要 MCP 服务 URL。HTTP 模式适用于全部三个后端。

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

标志（全部都有对应的 MINDWTR_MCP_HTTP* 环境变量）：

• --http / MINDWTR_MCP_HTTP — 启用 HTTP 模式。设置 --http-host、--http-port 或 --http-token 时，也会自动启用。
• --http-token <token> / MINDWTR_MCP_HTTP_TOKEN — HTTP 模式开启时必须提供，长度至少为 16 个字符。可使用 openssl rand -hex 32 生成。未提供时，服务将拒绝启动；即使绑定到回环地址，也无法在不进行身份验证的情况下启用 HTTP 模式。
• --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；多次身份验证失败会收到带有 Retry-After 标头的 429。超过 1 MiB 的请求正文会收到 413。启用 HTTP 模式后，服务不会同时连接 stdio 传输；只要 HTTP 服务仍在监听，服务就会保持运行，不受 stdin 状态影响。

服务不内置 TLS 终止或针对已通过身份验证请求的速率限制。如果要将其暴露给本地主机以外的网络，请在前面放置反向代理（例如 Caddy、nginx）来处理 TLS，并将生成的 https:// URL（以及令牌）填入远程 MCP 客户端。

直接从代码库运行

# from repo root (read-only by default)
bun run mindwtr:mcp -- --db "/path/to/mindwtr.db"

启用写入（添加/更新/完成/删除工具所必需）：

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

停止：

• 在终端中按 Ctrl+C。

保持运行行为（以及服务有时为何会退出）

MCP 服务基于 stdio。只要 stdin 处于打开状态，它就会保持运行。 如果 Shell 或客户端关闭了 stdin，进程就会退出。

若要在 stdin 关闭时立即退出（不保持运行），请传入 --nowait：

bun run mindwtr:mcp -- --db "/path/to/mindwtr.db" --nowait

注意：MCP 客户端启动服务时会保持 stdin 打开，因此服务应保持连接。

不使用辅助脚本运行

bun run --filter mindwtr-mcp dev -- --db "/path/to/mindwtr.db"

停止：

• 在终端中按 Ctrl+C。

构建并运行二进制入口（Node）

# from repo root
bun run --filter mindwtr-mcp build
node apps/mcp-server/dist/cli.js --db "/path/to/mindwtr.db"

停止：

• 在终端中按 Ctrl+C。

---

为什么会出现 mindwtr-mcp“找不到命令”

mindwtr-mcp 是此 npm 包的二进制命令。全局安装 npm 包后、MCP 客户端通过 npx 启动它后，或构建源代码包并通过 Node 运行后，该命令才会存在。

也可以使用以下任一种方式从源代码树运行：

# ✅ works immediately
bun run mindwtr:mcp -- --db "/path/to/mindwtr.db"

# ✅ build then run
bun run --filter mindwtr-mcp build
node apps/mcp-server/dist/cli.js --db "/path/to/mindwtr.db"

可选：创建全局 mindwtr-mcp 命令

如果你希望在 PATH 中使用真正的 mindwtr-mcp 命令，可以创建一个简易包装脚本：

cat > ~/bin/mindwtr-mcp <<'EOF'
#!/usr/bin/env bash
set -euo pipefail
cd /absolute/path/to/Mindwtr
exec bun run mindwtr:mcp -- "$@"
EOF
chmod +x ~/bin/mindwtr-mcp

然后运行：

mindwtr-mcp --db "/path/to/mindwtr.db"

桌面应用开关？

桌面应用提供 设置 → 集成 → 本地 MCP 服务（高级）。默认情况下，访问处于禁用和只读状态。启用后，复制连接信息，供支持经过身份验证的 Streamable HTTP 的客户端使用。默认端点为 http://127.0.0.1:8722/mcp；高级设置允许选择 1024 到 65535 之间的端口。保存端口，然后更新客户端的连接信息。服务仍绑定到回环地址。

从 v1.3.7 开始，允许编辑任务和项目可用于创建、编辑、完成和恢复任务，以及创建或编辑项目。高级设置中有单独的 允许归档和允许删除权限。每项权限相互独立；全新安装时均默认关闭。已启用 允许更改的现有安装会保留之前的删除权限，现在可以单独禁用该权限。归档需要明确授予新权限。同时涉及常规编辑和归档／取消操作的更新需要同时具备这两项权限。专用的 mindwtr_archive_task 工具使用应用的归档操作，不会完成任务或生成重复任务。删除仍为软删除。

复制到 Codex会生成 ~/.codex/config.toml 所需的 TOML 内容。添加或替换 mcp_servers.mindwtr 条目，同时保留其他配置；Mindwtr 不会编辑该文件。复制连接信息会保留使用 mcpServers 的客户端所需的 JSON 格式。两者都包含私有 bearer 令牌。已连接的 AI 客户端可以读取已公开的 Mindwtr 数据，并可能将其发送给自己的提供商。重新生成令牌会断开旧客户端的连接。

内置服务在桌面应用内运行，并与本地 API 共用任务和项目操作。无需启用本地 API。关闭到系统托盘后，服务仍会运行；禁用 MCP 或退出应用后，服务将停止。启动失败或端口被占用时，设置中会显示重试选项。此模式不支持远程 ChatGPT 访问、隧道或托管。独立助手特定于后端的功能和 --write 标志与这些桌面权限相互独立。

源码构建会将内置服务与桌面 Rust 应用一同编译；不会捆绑单独的 MCP 可执行文件或运行时。

---

MCP 客户端配置

MCP 客户端会将服务作为子进程运行。你需要指定命令并传递参数／环境变量。

**重要：**请勿在 MCP 客户端中使用 bun run mindwtr:mcp。bun run 包装器会向标准输出写入 shell 消息（例如 $ bun run --filter...），从而破坏 JSON-RPC 协议。请始终直接使用 bun 运行源文件。

示例（通用 MCP 配置）

{
  "mcpServers": {
    "mindwtr": {
      "command": "bun",
      "args": [
        "/absolute/path/to/Mindwtr/apps/mcp-server/src/cli.ts",
        "--db",
        "~/.local/share/mindwtr/mindwtr.db"
      ]
    }
  }
}

如果要启用添加／更新／完成／删除工具，请在参数中添加 --write。

如果你的客户端不支持 Bun，请先构建，然后使用 Node：

# Build once
cd /path/to/Mindwtr && bun run --filter mindwtr-mcp build

{
  "mcpServers": {
    "mindwtr": {
      "command": "node",
      "args": [
        "/absolute/path/to/Mindwtr/apps/mcp-server/dist/cli.js",
        "--db",
        "~/.local/share/mindwtr/mindwtr.db"
      ]
    }
  }
}

如果要启用添加／更新／完成／删除工具，请在参数中添加 --write。

Claude Desktop

Claude Desktop 支持 MCP（stdio）。在其 MCP 配置中添加服务条目。

典型配置文件位置：

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

编辑完成后，完全退出并重新启动 Claude Desktop。

Claude Code（CLI）

通过 CLI 添加服务：

claude mcp add mindwtr -- \
  bun /path/to/Mindwtr/apps/mcp-server/src/cli.ts --db "/path/to/mindwtr.db" --write

或者直接编辑 ~/.claude.json：

{
  "projects": {
    "/path/to/your/project": {
      "mcpServers": {
        "mindwtr": {
          "type": "stdio",
          "command": "bun",
          "args": [
            "/absolute/path/to/Mindwtr/apps/mcp-server/src/cli.ts",
            "--db",
            "~/.local/share/mindwtr/mindwtr.db",
            "--write"
          ]
        }
      }
    }
  }
}

然后重启 Claude Code 会话，并运行 /mcp 验证是否已连接。

OpenAI Codex（config.toml）

Codex 将 MCP 配置存储在 ~/.codex/config.toml 中。添加：

[mcp_servers.mindwtr]
command = "bun"
args = ["/absolute/path/to/Mindwtr/apps/mcp-server/src/cli.ts", "--db", "/path/to/mindwtr.db", "--write"]

# Optional: pass env vars to the server
[mcp_servers.mindwtr.env]
MINDWTR_DB_PATH = "/path/to/mindwtr.db"

保存后重启 Codex。

Gemini CLI

Gemini CLI 使用包含 mcpServers 的 JSON settings.json，位置可以是：

• 用户范围：~/.gemini/settings.json
• 项目范围：仓库中的 .gemini/settings.json

添加 Mindwtr MCP 有两种方式：

1) CLI（推荐）：

gemini mcp add mindwtr \
  bun /absolute/path/to/Mindwtr/apps/mcp-server/src/cli.ts \
  --db "/path/to/mindwtr.db" --write

2) 手动编辑 settings.json：

{
  "mcpServers": {
    "mindwtr": {
      "command": "bun",
      "args": ["/absolute/path/to/Mindwtr/apps/mcp-server/src/cli.ts", "--db", "/path/to/mindwtr.db", "--write"]
    }
  }
}

保存后重启 Gemini CLI 会话。

其他 MCP 客户端

只要支持通过上述命令和参数启动 stdio 服务，任何兼容 MCP 的客户端都可以使用。

---

迁移：工具重命名（mindwtr.* → mindwtr_*）

破坏性变更（在此版本中引入）：所有工具名称都从点号格式（mindwtr.list_tasks）改为下划线格式（mindwtr_list_tasks），以符合 MCP 客户端的验证规则（例如 Claude Desktop）。

旧名称 → 新名称映射：

旧名称	新名称
mindwtr.list_tasks	mindwtr_list_tasks
mindwtr.list_projects	mindwtr_list_projects
mindwtr.get_project	mindwtr_get_project
mindwtr.get_task	mindwtr_get_task
mindwtr.list_areas	mindwtr_list_areas
mindwtr.add_task	mindwtr_add_task
mindwtr.update_task	mindwtr_update_task
mindwtr.complete_task	mindwtr_complete_task
mindwtr.delete_task	mindwtr_delete_task
mindwtr.restore_task	mindwtr_restore_task
mindwtr.add_project	mindwtr_add_project
mindwtr.update_project	mindwtr_update_project
mindwtr.delete_project	mindwtr_delete_project
mindwtr.add_area	mindwtr_add_area
mindwtr.update_area	mindwtr_update_area
mindwtr.delete_area	mindwtr_delete_area

**升级操作：**在引用这些工具名称的任何 MCP 客户端配置、系统提示词、脚本或自动化流程中，查找并将 mindwtr. 替换为 mindwtr_。无需进行其他更改。

---

工具

• mindwtr_list_tasks
  • 输入：{ status?, projectId?, includeDeleted?, limit?, offset?, search?, dueDateFrom?, dueDateTo?, isFocusedToday?, view?, sortBy?, sortOrder? }
  • view 可按 GTD 可用性缩小范围：available、deferred 或 blocked
• mindwtr_list_projects
  • 输入：{}
• mindwtr_get_project
  • 输入：{ id, includeDeleted? }
• mindwtr_list_view_sections — 视图分区的 ID、标题和顺序；可选的 view：someday、waiting 或 focus（SQLite/Cloud）
• mindwtr_list_sections
  • 输入：{ projectId?, includeDeleted? }
• mindwtr_get_section
  • 输入：{ id, includeDeleted? }
• mindwtr_list_areas
  • 输入：{}
• mindwtr_list_people
  • 输入：{ includeDeleted? }
• mindwtr_get_person
  • 输入：{ id, includeDeleted? }
• mindwtr_get_task
  • 输入：{ id, includeDeleted? }
• mindwtr_add_task （需要 --write）
  • 输入：{ title? | quickAdd?, status?, projectId?, sectionId?, viewSectionIds?, areaId?, dueDate?, startTime?, cancelledAt?, reviewAt?, recurrence?, contexts?, tags?, description?, priority?, energyLevel?, assignedTo?, timeEstimate?, taskMode?, relativeStartOffset?, showFutureRecurrence?, pushCount?, checklist?, textDirection?, location?, isFocusedToday?, timeSpentMinutes?, suppressMindwtrReminders?, reminderPolicy?, repeatReminderMinutes?, dueReminderLeadMinutes?, attachments? }
• mindwtr_update_task （需要 --write）
  • 输入：{ id, title?, status?, projectId?, sectionId?, viewSectionIds?, areaId?, dueDate?, startTime?, cancelledAt?, reviewAt?, recurrence?, contexts?, tags?, description?, priority?, energyLevel?, assignedTo?, timeEstimate?, taskMode?, relativeStartOffset?, showFutureRecurrence?, pushCount?, checklist?, textDirection?, location?, isFocusedToday?, timeSpentMinutes?, suppressMindwtrReminders?, reminderPolicy?, repeatReminderMinutes?, dueReminderLeadMinutes?, order?, boardOrder?, focusOrder?, attachments? }
  • reminderPolicy 对开始和截止提醒接受 inherit、send 或 skip。使用 inherit 可沿用库的默认设置；不接受 null。现有任务会保留旧版提醒选项，直到明确更改为止。
  • recurrence 接受重复规则对象或 RFC 5545 RRULE 字符串。传入 null 可清除该值。
  • attachments 仅包含链接附件（{ id?, title?, uri }，例如 obsidian://、file:// 或 https://）。传入的列表是完整链接集合：未包含的链接会被移除，文件附件不会受到影响，传入 null 会清除所有链接。
  • cancelledAt 是带时区的 ISO 时间戳。设置此值会将任务关闭并标记为已取消（archived），不会将其计为已完成，也不会生成下一次重复任务。将任务移至活动状态或将其标记为已完成会清除取消标记。使用取消功能前，请先更新所有同步客户端；旧版写入方可能会丢弃此标记。
• mindwtr_complete_task （需要 --write）
  • 输入：{ id }
• mindwtr_delete_task （需要 --write）
  • 输入：{ id }
• mindwtr_restore_task （需要 --write）
  • 输入：{ id }
• mindwtr_add_project （需要 --write）
  • 输入：{ title, color?, status?, areaId?, isSequential?, isFocused?, viewSectionIds?, dueDate?, startDate?, cancelledAt?, reviewAt?, supportNotes?, attachments? }
• mindwtr_update_project （需要 --write）
  • 输入：{ id, title?, color?, status?, areaId?, isSequential?, isFocused?, viewSectionIds?, dueDate?, startDate?, cancelledAt?, reviewAt?, supportNotes?, attachments? }
  • attachments 遵循与 mindwtr_update_task 相同的规则：仅包含链接附件，列表是完整链接集合，传入 null 会清除所有链接。
• mindwtr_delete_project （需要 --write）
  • 输入：{ id }
• mindwtr_add_section （需要 --write）
  • 输入：{ projectId, title, description?, order?, isCollapsed? }
• mindwtr_update_section （需要 --write）
  • 输入：{ id, title?, description?, order?, isCollapsed? }
• mindwtr_delete_section （需要 --write）
  • 输入：{ id }
• mindwtr_add_area （需要 --write）
  • 输入：{ name, color?, icon? }
• mindwtr_update_area （需要 --write）
  • 输入：{ id, name?, color?, icon? }
• mindwtr_delete_area （需要 --write）
  • 输入：{ id }
• mindwtr_add_person （需要 --write）
  • 输入：{ name, note?, referenceLink? }
• mindwtr_update_person （需要 --write）
  • 输入：{ id, name?, note?, referenceLink? }
• mindwtr_rename_person （需要 --write）
  • 输入：{ id, name, updateTasks? }
• mindwtr_delete_person （需要 --write）
  • 输入：{ id } 所有工具都会以 JSON 文本载荷的形式返回相应的任务、项目、分区、区域、人员或集合载荷。

---

测试

快速冒烟测试（CLI）

1. 启动服务（只读）：

bun run mindwtr:mcp -- --db "~/.local/share/mindwtr/mindwtr.db"

2. 通过 MCP 客户端连接并运行：

• mindwtr_list_tasks（limit 5）

如果要测试写入操作，请使用 --write 重启：

bun run mindwtr:mcp -- --db "~/.local/share/mindwtr/mindwtr.db" --write

然后测试：

• mindwtr_add_task（quickAdd: "Test task @home /due:tomorrow"）
• mindwtr_complete_task（使用返回的任务 id）
• mindwtr_update_task（例如设置 status 或 dueDate）
• mindwtr_delete_task（使用返回的任务 id）
• mindwtr_get_task（使用返回的任务 id）
• mindwtr_restore_task（删除后恢复该任务）
• mindwtr_list_projects
• mindwtr_get_project（使用返回的项目 id）
• mindwtr_list_areas
• mindwtr_list_people
• mindwtr_add_project
• mindwtr_update_project
• mindwtr_delete_project
• mindwtr_add_area
• mindwtr_update_area
• mindwtr_delete_area
• mindwtr_add_person
• mindwtr_update_person
• mindwtr_rename_person
• mindwtr_get_person（使用返回的人员 id）
• mindwtr_delete_person
• 使用 dueDateFrom、dueDateTo、sortBy、sortOrder 调用 mindwtr_list_tasks

如果列表返回了任务，且添加和完成操作正常，则服务运行正常。

Stdio JSON-RPC 端到端测试（传输验证）

使用任意 MCP 客户端或简短脚本发送：

• initialize
• notifications/initialized
• tools/list
• tools/call（例如 mindwtr_list_projects 或 mindwtr_list_tasks）

如果这些操作成功，则 stdio 传输已端到端正常运行。

Claude Code 健全性检查

1. 添加服务：

claude mcp add mindwtr -- \
  bun /path/to/Mindwtr/apps/mcp-server/src/cli.ts --db "/path/to/mindwtr.db" --write

2. 重启 Claude Code，运行 /mcp，并确认 mindwtr 已连接。
3. 请模型调用：
   • mindwtr_list_tasks（limit 5）
   • mindwtr_add_task（quickAdd: "Test MCP @home /due:tomorrow"）
   • mindwtr_complete_task（使用返回的 id）

---

安全性与并发

以下 SQLite 说明适用于直接数据库模式。本地 API 模式使用桌面应用的原生处理程序，云模式使用可自托管服务。

• 服务使用 SQLite WAL 模式。桌面应用打开时，只读工具仍可运行。
• SQLite 写入锁定时，写入工具会快速失败，然后重试整个 Mindwtr 写入操作。每次重试都会重新加载当前数据，再应用所请求的更改，因此延迟的 MCP 写入不会基于过时的锁定前快照继续操作。
• 写入操作默认已禁用。使用 --write 启用编辑。
• 写入操作通过共享的 @mindwtr/core 存储层执行，以强制实施业务规则（Bun 和 Node 均适用）。
• SQL 仅用于对性能有要求的读取密集型路径（列表／搜索）。
• 请勿让单独的容器／服务部署指向同一份本地存储，或在桌面应用也正在写入时同步数据。这会在本地 SQLite 协调机制之外产生独立写入方，因此不受支持。

---

备注

• 此 MCP 服务面向桌面应用使用的 SQLite 数据库，并通过 @mindwtr/core 路由变更操作。
• 请留意应用不同版本之间的架构变更（必要时更新查询）。

查看视图分区

在 SQLite 和 Cloud 模式下，调用 mindwtr_list_view_sections（可选传入 {"view":"someday"}）以解析分区 ID 和标题。结果为 {"viewSections":[{"view":"someday","id":"books","title":"Books","order":0}]}。 这些是视图标题，与 mindwtr_list_sections 返回的项目分区不同。请在 Mindwtr 应用中创建或重命名视图标题。

任务和项目的创建/更新工具接受 viewSectionIds，例如 {"someday":"books","waiting":"people"}。分配标题不会更改实体的状态。更新会替换整个映射：请包含要保留的其他视图分配。省略此字段可保留现有分配；传入 {}，或在更新时传入 null，可清除所有分配。若要清除某个视图，请仅发送包含其他分配的映射。值必须是非空的分区 ID 字符串；为兼容较新的应用，仍支持未知视图名称。

目录支持只读模式。分配写入需要 --write。Cloud 模式使用现有的数据端点，并兼容 Mindwtr Cloud 1.3.7。 Desktop Local API 模式支持按已知 ID 分配任务，但不提供视图分区目录或项目分配；不支持的输入会被拒绝。