PromptSync MCP · AI 使用说明

给 Cursor / Claude / 其他 Agent 看的调用手册。人类也可对照排查。连接成功后，MCP initialize.instructions 会注入同一份说明；也可随时调工具 usage_guide。

写入默认关闭。检索工具开箱即用；要存档对话/附件，用户须在控制台 → MCP →「高级：工具开关」打开 put_asset、create_conversation、append_message、import_conversation 等。Agent 若看到「工具已关闭」，应提示用户开启，不要假装已写入。

0. 连上后先做

调 health 或 server_info：确认用户名与 enabledTools
不确定流程 → 调 usage_guide
需要写入但工具不在列表里 → 让用户去控制台打开开关

提示词

控制台的「提示词」保存可复用提示词。已连接的 AI 调用 list_prompts 和 get_prompt 读取同一份；upsert_prompt 与 delete_prompt 默认关闭。

共用 MCP 配置

控制台的「配置库」保存一份 MCP 服务器。已连接的 AI 调用 list_mcp_configs 读取同一份；upsert_mcp_config 与 delete_mcp_config 默认关闭。

高亮

与控制台「高亮」页同一份数据。查询：list_highlights / get_highlight。写入（默认关）：upsert_highlight / delete_highlight（需 confirm=true）。颜色：yellow / green / blue / pink / orange / todo。

待办

与控制台「待办」页同一份数据（不是 find_todos 从消息抽 TODO 文本）。查询：list_todos / get_todo / list_todo_categories。写入（默认关）：upsert_todo / set_todo_done / delete_todo / upsert_todo_category / delete_todo_category / reorder_todos / reorder_todo_categories / todo_from_highlight。

1. 检索（默认可用）

场景	工具
列会话	`list_conversations`（query / platform / pinned / limit）
读全文	`get_conversation`；太长用 `get_messages` 或 `get_excerpt`
搜正文	`search_messages`(query)
原链接反查	`find_by_url`(url)
导出	`export_markdown` / `export_json`
附件	`get_asset`(id)；要文件体设 `includeContent=true`
高亮标记	`list_highlights` / `get_highlight`
待办任务	`list_todos` / `get_todo` / `list_todo_categories`

2. 写入存档

消息里只存附件索引（assetId），不要把 base64 塞进 content。

2a. 推荐：整段导入 / 更新

import_conversation({
  conversation: {
    id: "cursor_<uuid>",   // 稳定 ID，便于重复导入覆盖
    title: "对话标题",
    platform: "cursor"
  },
  messages: [
    { role: "user", content: "…", attachmentIds: ["asset_xxx"] },
    { role: "assistant", content: "…" }
  ],
  replaceMessages: true   // 更新时必开：先清空旧消息再写入
})

附件三种写法任选：

先 put_asset → attachmentIds
messages[].attachments: [{ name, mime, contentBase64 }] 内联
顶层 assets: [{ id?, name, mime, contentBase64 }]，消息用 id/下标引用

2b. 增量写

put_asset({ name, mime, contentBase64 }) → assetId
create_conversation({ id?, title, platform })
append_message({ conversationId, role, content, attachmentIds })

2c. 附件硬规则（否则网页气泡不显示图）

❌ 不要在 content 里写 [asset:…] 当图片——那只是纯文本
✅ 必须用 attachmentIds / attachments 字段
单文件建议 ≤8MB；base64 可带 data:image/png;base64, 前缀
相同内容按哈希去重

2d. 改名与元数据

rename_conversation / pin_conversation / set_tags / set_note / archive_conversation

2e. 删除

delete_conversation({ id: "…", confirm: true })  // confirm 必须为 true，不可恢复

3. Cursor 批量导入（本机脚本）

大批量全文 + 附件，优先用仓库脚本，比逐条 MCP 稳：

python3 scripts/promptsync-import-chats.py \
  --transcript ~/.cursor/projects/.../agent-transcripts/<uuid>/<uuid>.jsonl \
  --title "自定义标题"

# 批量 + 改名
python3 scripts/promptsync-import-chats.py \
  --transcripts-dir ~/.cursor/projects/.../agent-transcripts \
  --rename-map renames.json

# 全量本地对话
bash scripts/promptsync-import-all-cursor.sh

稳定 ID = cursor_<uuid>；重复跑即更新。鉴权读 ~/.cursor/mcp.json 或环境变量 PROMPTSYNC_MCP_TOKEN。

3b. 对话结束自动上传（每台机器装一次）

用 Cursor stop hook：Agent 每轮结束后把当前 transcript 推到云端。详细步骤见仓库 docs/cursor-auto-push.md。

cd /path/to/PromptSync
bash scripts/install-cursor-auto-push.sh
# 然后 Reload Cursor；看 ~/.cursor/promptsync-push.log

需已配置 MCP Bearer，并在控制台打开 import_conversation / put_asset 等写入工具。Cloud Agent（无本机 jsonl）不会自动推。

4. 常见失败

现象	处理
工具不在 list /「已关闭」	控制台打开对应开关
401	检查 Bearer 密钥
create 报「已存在」	改用 import + replaceMessages，或换 id
附件不存在	先 put_asset，核对 attachmentIds
网页有字没图	检查 messages.attachments，不是 content 占位符

5. Cursor 配置示例

{
  "mcpServers": {
    "promptsync": {
      "url": "https://promptsync.top/mcp/你的用户名",
      "headers": {
        "Authorization": "Bearer ps_你的密钥"
      }
    }
  }
}

密钥在控制台 MCP 页生成；也支持 OAuth 自定义连接器登录。

6. 安全

只读写当前用户自己的数据
不要把 MCP 密钥写进对话正文或公开仓库
大批量 base64 用本机脚本或分批 put_asset