文档

Memo / Todo MCP 接入指南

在线阅读：/zh/doc（与本文同步，直达锚点：/doc#memo-mcp）。自建部署与排障见 docs/MCP/ops-external-mcp.md（运维向，不随站内页发布）。

Memo 与 Todo 共用 /mcp、/mcp/readonly 传输；凭证 scope 决定可见工具域（Memo-only / Todo-only / 双域 PAT 均可）。

---

一、快速开始

1. 打开 设置 → 访问凭证，创建密钥并立即复制保存（关闭后无法再看）。
2. 创建时勾选权限：

- 只让 AI 查看便签 → 勾选 Memo · 读取

- 还要 新建/修改/删除便签 → 再加 Memo · 写入

- 只让 AI 查看 Todo → 勾选 Todo · 读取

- 还要 新建/修改/删除 Todo → 须同时勾选 Todo · 读取 与 Todo · 写入（仅 todo:write 无法初始化 MCP）

1. 在 Cursor / Claude / LobeChat 中粘贴配置，把占位符 <你的凭证> 换成刚保存的那串密钥。
2. 按权限选连接地址（见下一节），保存后由客户端自动完成 initialize 与会话；无需手写 HTTP。

默认 90 天过期（也可选 30 天或永不过期）；若怀疑泄露，请在设置里立即撤销。

---

二、权限与连接地址（请先分清）

补充：

• 也可用请求头 X-MCP-Readonly: true 代替只读地址。
• 密钥只有读取 scope（memo:read 或 todo:read）、无对应写入 scope 时，即使连 /mcp，服务端也会按只读处理。
• OAuth 一键登录支持 Memo 与 Todo scope（memo:read / memo:write / todo:read / todo:write）；PAT 仍适合手动配置和长期自托管客户端。

---

三、客户端配置示例

Cursor — 仅查看便签

{
  "mcpServers": {
    "mesq-memo-readonly": {
      "url": "https://<your-host>/mcp/readonly",
      "headers": { "Authorization": "Bearer <你的凭证>" }
    }
  }
}

Cursor — 可修改便签

{
  "mcpServers": {
    "mesq-memo": {
      "url": "https://<your-host>/mcp",
      "headers": { "Authorization": "Bearer <你的凭证>" }
    }
  }
}

Claude Desktop（仅查看）

claude mcp add --transport http mesq-memo-readonly https://<your-host>/mcp/readonly \
  --header "Authorization: Bearer <你的凭证>"

LobeChat

路径：设置 → 技能 → 自定义 → Streamable HTTP。下方为可写示例；若密钥只有「Memo · 读取」，请把 url 中的 /mcp 改为 /mcp/readonly。

{
  "mcpServers": {
    "mesq-memo": {
      "url": "https://<your-host>/mcp",
      "type": "http",
      "headers": { "Authorization": "Bearer <你的凭证>" }
    }
  }
}

兼容情况

会话由响应头 Mcp-Session-Id 维护；约 30 分钟无活动会失效（后台每 5 分钟扫描清理），需重新连接。多机部署须按该 ID 做负载均衡 sticky（详见运维手册）。

---

四、Memo 工具一览（16 个）

list_memos 常用参数

search_memos 常用参数

带附件新建便签

1. upload_memo_resource → 得到 path
2. create_memo → resources: [{ path, displayName, fileSize, mimeType, type }]

附件怎么读

MCP 资源 URI 形如 memo://resource/{encodedPath}，与 mcp_uri 对应。

---

五、Todo MCP（49 个工具）

Todo 与 Memo 共用同一 MCP 端点；tools/list 仅展示当前 PAT scope 允许的工具（Todo-only PAT 不会看到 Memo 工具，反之亦然）。

目的地规则（写操作必读）

常用读工具

默认响应为紧凑模式：长 notes 默认省略（列表/上下文工具）；详情工具或 includeNotes: true 可包含。列表工具支持 limit/offset/maxItems，截断时返回 truncated、hasMore 等分页字段。

附件

1. upload_todo_attachment → 得到 path 与 mcp_uri
2. 绑定到任务/收件箱项的 attachments 字段
3. 大文件用 todo://attachment/{encodedPath} → MCP resources/read

Toolset 过滤（X-MCP-Toolsets）

Memo 兼容别名不变：tags / resources 仍仅指 Memo 标签与附件；Todo 请用 todo-* 前缀 toolset。

Todo MCP 未暴露

• Todo 偏好、有效时区、提醒 token、调度器（RunDueReminderTick 等）
• ListUserAttachments / DiscardOrphanAttachments 等 Cookie-only 清理能力

Todo 工具输出

49 个 Todo 工具都声明统一 outputSchema envelope：成功时 structuredContent 含 data，并可带 traceId / correlationId；失败时返回 error 且 isError: true。content[].text 仍保留同一份 JSON，兼容只读文本的客户端。

---

六、内容与配额限制

---

七、常见问题

调用过于频繁时会限速；具体阈值见下文「开发者参考」。

---

八、暂不支持

• resources/subscribe、MCP Prompts

---

开发者参考

协议要点

• 传输：Streamable HTTP；服务名 mesq-memo，版本 1.3.0（Memo 16 + Todo 49 工具）。
• 鉴权：Authorization: Bearer <token>；OAuth 与 PAT 均支持 memo:read / memo:write / todo:read / todo:write；至少需 memo:read 或 todo:read 之一才能 initialize；写操作分别需 memo:write / todo:write。
• 手动调试时：POST /mcp 或 /mcp/readonly 发 initialize，后续请求（含 GET / DELETE）都要带 Mcp-Session-Id。

限流（可按 PAT / IP）

环境变量：MCP_RATE_LIMIT_ENABLED、MCP_RATE_LIMIT_PROFILE=normal|relaxed|off。

429 响应：Retry-After（秒）；body 含 error.code=RATE_LIMITED、error.retryAfterSeconds。客户端优先读 header。

连接层限流仅作用于 initialize 与 tools/list；read_memo_resource、read_todo_attachment 及 todo://attachment/... 的 resources/read 单独计入附件读桶。

工具子集过滤（请求头）

• X-MCP-Tools：白名单（逗号分隔）
• X-MCP-Exclude-Tools：黑名单
• X-MCP-Toolsets：Memo — memos / tags / resources（别名 memo-tags / memo-resources）；Todo — todos / todo-spaces / todo-columns / todo-inbox / todo-attachments / todo-trash
• 以上过滤在 initialize 建立会话与工具注册时生效；不能越权暴露 scope 外的工具；后续调用沿用该会话内的工具子集。

版本说明

当前为上线观察档（500/150/100/50），首月复盘后可调整阈值。