MCP

MCP 标准工具接入

适合支持 MCP 的客户端。复制提示词给自己的 AI，让它下载 server.py、备份并修改客户端配置、验证工具和接入健康。

mkdir -p ~/omemai-mcp
cd ~/omemai-mcp
curl -fsSLO https://omemai.com/downloads/omemai-mcp/server.py
OMEMAI_API_BASE=https://omemai.com OMEMAI_API_KEY=<YOUR_KEY> python3 server.py --transport stdio

MCP 客户端提示词

你要在当前这台机器上配置 OMemAI MCP Server，让支持 MCP 的客户端通过标准 tools 使用 OMemAI 长期记忆。

目标：
- 在本机创建轻量 MCP Server 工作目录；
- 下载 OMemAI MCP Server 单文件；
- 配置当前 MCP 客户端，让它通过 stdio 启动 OMemAI MCP Server；
- 完成后验证 OMemAI MCP tools 可用；
- 完成一次最小闭环：list_projects → session_start → load_context → session_message → checkpoint → search_memory → agent_health；
- 最后在 https://omemai.com/agent-health 验证 source=mcp 且状态 healthy。

安装位置：
- 使用 ~/omemai-mcp 作为本机 MCP 工作目录；
- 如目录不存在，直接创建；
- MCP Server 从 https://omemai.com/downloads/omemai-mcp/server.py 下载。

执行注意：
- 不要打印完整 API Key；
- 不要把 API Key 写进仓库、公开文档、日志或聊天回复；
- 如果必须写入 MCP 客户端本地配置文件，先备份配置文件，并尽量将权限设为 600；
- 不要修改 nginx；
- 不要开放公网端口；
- HTTP 调试模式只能绑定 127.0.0.1；
- 如果 MCP 客户端、API Key 或 OMemAI 不可用，必须明确告诉我，不要假装已经接入成功；
- 不要跨项目写入，默认只在当前项目内搜索和保存。

执行步骤：

1. 检查本机环境：
   command -v python3
   command -v curl
   如果缺少 python3 或 curl，停止并告诉我需要先安装。

2. 创建 MCP 工作目录：
   mkdir -p ~/omemai-mcp
   cd ~/omemai-mcp

3. 下载 OMemAI MCP Server：
   curl -fsSLO https://omemai.com/downloads/omemai-mcp/server.py
   test -s server.py
   chmod 600 server.py

4. 获取 OMemAI Agent API Key：
   让我打开 https://omemai.com/api-keys 创建包含 agent:read 和 agent:write 的 API Key。
   让我粘贴 Key 时不要回显，不要把 Key 输出到聊天回复里。
   普通 MCP 接入不需要 memory:approve。

5. 识别当前 MCP 客户端：
   - 如果你能判断用户正在使用 Claude Desktop、Cursor、OpenCode、OpenClaw、VS Code 或其他 MCP 客户端，就定位它的 MCP 配置文件；
   - 如果无法判断客户端或配置位置，先问我正在用哪个客户端，不要乱改文件。

6. 修改 MCP 客户端配置前必须备份：
   cp <config-file> <config-file>.bak-$(date +%Y%m%d-%H%M%S)

7. 在 MCP 客户端配置中加入 OMemAI server。
   通用 stdio 配置形态如下，按当前客户端实际格式调整：

   {
     "mcpServers": {
       "omemai": {
         "command": "python3",
         "args": ["/home/<USER>/omemai-mcp/server.py", "--transport", "stdio"],
         "env": {
           "OMEMAI_API_BASE": "https://omemai.com",
           "OMEMAI_API_KEY": "<YOUR_OMEMAI_AGENT_API_KEY>"
         }
       }
     }
   }

   注意：把 /home/<USER>/omemai-mcp/server.py 替换成当前机器的真实绝对路径。
   如果客户端支持 secret/env 引用，优先使用更安全的 secret/env 方式。

8. 保存配置后，重启或 reload MCP 客户端。

9. 验证 MCP tools 是否出现：
   - omemai_list_projects
   - omemai_load_context
   - omemai_search_memory
   - omemai_session_start
   - omemai_session_message
   - omemai_checkpoint
   - omemai_recent_sessions
   - omemai_agent_health

10. 完成一次最小健康验证：
   - 调用 omemai_list_projects；
   - 选择或确认 project_id，不确定就问用户；
   - 调用 omemai_session_start；
   - 调用 omemai_load_context；
   - 保存一条带唯一 TEST_TOKEN 的 user message 和一条 assistant message；
   - 调用 omemai_checkpoint；
   - 调用 omemai_search_memory，确认能搜回 TEST_TOKEN；
   - 调用 omemai_agent_health。

11. 打开 https://omemai.com/agent-health，确认对应 API Key：
   - status 是 healthy；
   - source 包含 MCP；
   - warnings 为空或已解释。

后续每个项目任务都应该通过 MCP tools 使用 OMemAI：
- 开始任务：omemai_session_start + omemai_load_context；
- 需要历史：omemai_search_memory；
- 每轮保存：omemai_session_message，user 和 assistant 都要保存；
- 阶段完成/上下文快满/重要状态变化：omemai_checkpoint；
- 新对话恢复：omemai_recent_sessions + omemai_load_context。

事实使用规则：
- 优先使用 current facts；
- superseded facts 只作为历史，不要当成当前结论；
- 搜索默认限定当前项目；
- API/MCP 调用失败时明确说明记忆链路不可用，不要伪装已经接入成功。

严格失败条件：
- MCP tools 未出现；
- omemai_agent_health 不可调用；
- 最小闭环失败；
- search 无法搜回 TEST_TOKEN；
- 需要修改 nginx、开放公网端口或写入不明配置才能完成。

如果任一步失败，输出失败步骤、错误摘要和修复建议。不要伪装成已经接入成功。