MemoryCode MCP Server

将 MemoryCode 记忆配置通过 MCP 暴露给 Claude Desktop、Cursor 等客户端。Claude 桌面版的 MCP 交互方式为：自然语言（如「请使用职场配置」）与点击输入框旁的 「+」 展开后选择记忆配置；@ 在 Claude 桌面版中对 MCP 无任何作用（参见 YIS-20 研究）。其他 AI 客户端的引用方式以各产品为准，本 Server 均支持通过自然语言（Tool）及 Resources 供客户端加载。

环境要求

• Node.js 18+
• 已从 MemoryCode Web 端导出的 memorycode-mcp.json（设置 → MCP Server → 导出到 MCP）

安装

cd memorycode-mcp-server
npm install
npm run build

构建完成后，可执行文件为 dist/index.js。

快速开始

1. 导出配置
   在 MemoryCode 应用中：设置 → MCP Server → 导出到 MCP，将 memorycode-mcp.json 保存到本机（例如 ~/memorycode/ 或 ~/Desktop/MCP/）。

2. 启动 Server（二选一）

   • 使用默认路径 ~/memorycode/memorycode-mcp.json：

     node dist/index.js

   • 或指定文件：

     node dist/index.js --file /path/to/memorycode-mcp.json

3. 在 Claude Desktop 或 Cursor 中配置 MCP（见下方「Cursor / Claude Desktop 配置」）。

4. 使用方式

   • Claude Desktop：用自然语言（如「请使用职场配置」「有哪些配置可用」），或点击输入框旁的 「+」 展开后选择记忆配置加载。其他客户端（如 Cursor）若支持 @ 或类似引用方式，可按其界面操作；否则同样通过自然语言或该客户端的资源/附件入口选择配置。

命令行与配置文件

| 选项 | 说明 | |------|------| | -f, --file <path> | 监听的 memorycode-mcp.json 路径 | | -c, --config <path> | 使用 JSON 配置文件（见下） | | -h, --help | 显示帮助 |

默认监听路径：

• macOS / Linux：~/memorycode/memorycode-mcp.json
• Windows：%USERPROFILE%\memorycode\memorycode-mcp.json

配置文件示例（--config /path/to/config.json）：

{
  "watchFile": "/path/to/memorycode-mcp.json",
  "logLevel": "info"
}

logLevel 可选：info、warn、error。

Cursor / Claude Desktop 配置

Claude Desktop

1. 打开 MCP 配置目录：

   open ~/Library/Application\ Support/Claude/

2. 编辑 claude_desktop_config.json，在 mcpServers 中增加一项（将 command 和 args 中的路径改为你本机实际路径）：

   "memorycode": {
     "command": "/usr/local/bin/node",
     "args": [
       "/Users/你的用户名/ai-identity-wallet/memorycode-mcp-server/dist/index.js",
       "--file",
       "/Users/你的用户名/Desktop/MCP/memorycode-mcp.json"
     ]
   }

3. 查询本机 node 路径：终端执行 which node，将得到的路径填到 command。

4. 完全退出 Claude Desktop 后重新打开。在 Claude 桌面版中：通过自然语言（如「请使用职场配置」「有哪些配置可用」）或点击输入框旁的 「+」 展开附件/资源菜单并选择 MemoryCode 记忆配置加载。注意：@ 在 Claude 桌面版中对 MCP 无任何功能，请勿依赖 @ 调用记忆配置。

Cursor

重要： 在 Cursor 中请不要使用 npx @memorycode/mcp-server。该方式容易触发 "No server info found" / "Server not yet created"。请改用本仓库本地构建的 server：command 填本机 node 路径，args 填 [本机 dist/index.js 绝对路径, "--file", memorycode-mcp.json 绝对路径]，并在 memorycode 配置里必须写 "type": "stdio"。可直接复制 cursor-mcp-example.json 中 memorycode 一段，把路径改成你的本机路径后粘贴到 ~/.cursor/mcp.json 的 mcpServers 中。

以下配置格式已在 Cursor 中验证通过，按此填写即可正常接入。Cursor 通过 mcp.json 配置 MCP Server，需手动编辑 JSON 并填写本机路径。根据 Cursor MCP 文档，STDIO 类型服务器必须包含 "type": "stdio"，且 memorycode 必须写在 mcpServers 对象内部（与其它 MCP 并列），不能写在 mcpServers 外面。

配置位置（二选一）：

• 全局配置（所有项目可用）：~/.cursor/mcp.json（macOS/Linux）或 %USERPROFILE%\.cursor\mcp.json（Windows）
• 项目配置（仅当前项目）：项目根目录下的 .cursor/mcp.json

步骤：

1. 确认已构建
   在 memorycode-mcp-server 目录执行过 npm run build，且存在 dist/index.js。

2. 确认 Node 路径
   终端执行 which node（Windows 可用 where node），记下路径，例如 /usr/local/bin/node。

3. 编辑 mcp.json（已验证格式）

   • 若文件不存在：在 ~/.cursor/ 下新建 mcp.json。
   • 在 mcpServers 对象中增加 memorycode 一项；若已有其他 server（如 linear），保留它们，只在 mcpServers 里新增 memorycode。完整示例（仅 memorycode 时整文件如下）：

   {
     "mcpServers": {
       "memorycode": {
         "type": "stdio",
         "command": "/usr/local/bin/node",
         "args": [
           "/你的本机路径/memorycode-mcp-server/dist/index.js",
           "--file",
           "/你的本机路径/memorycode-mcp.json"
         ]
       }
     }
   }

   若已有其他 MCP，则只在 mcpServers 中多加一段，例如：

   {
     "mcpServers": {
       "linear": { "command": "npx", "args": ["-y", "mcp-remote", "https://mcp.linear.app/mcp"] },
       "memorycode": {
         "type": "stdio",
         "command": "/usr/local/bin/node",
         "args": [
           "/你的本机路径/memorycode-mcp-server/dist/index.js",
           "--file",
           "/你的本机路径/memorycode-mcp.json"
         ]
       }
     }
   }

   必填说明：

   • "type": "stdio"：Cursor 要求 STDIO 服务器必须写明，缺此项会无法正确识别。
   • command：上一步得到的 node 可执行文件路径（如 /usr/local/bin/node）。
   • args：严格为 3 项——① dist/index.js 的绝对路径；② "--file"；③ memorycode-mcp.json 的绝对路径。

4. （可选）使用变量便于多机共用
   Cursor 支持在 mcp.json 中使用 ${userHome} 等变量，例如：

   "args": [
     "${userHome}/ai-identity-wallet/memorycode-mcp-server/dist/index.js",
     "--file",
     "${userHome}/Desktop/MCP/memorycode-mcp.json"
   ]

   路径按你本机实际目录调整。

5. 重启 Cursor
   保存 mcp.json 后完全退出 Cursor 再打开，使配置生效。

6. 验证与使用

   • 打开 Settings → Features → Model Context Protocol，确认 memorycode 已列出且为开启状态，并能看到 load_config、list_configs 及你的配置名（如职场、创作者、学生等）。
   • 在对话中用自然语言（如「请使用职场配置」「有哪些配置可用」）使用，或直接点选界面中展示的配置按钮。

排查： 若连接失败，打开 Output → MCP Logs（Cmd+Shift+U 后切换下拉）查看报错；常见原因：路径错误、未先执行 npm run build、漏写 "type": "stdio"、或将 memorycode 写到了 mcpServers 外面。

若出现 "Error - Show Output" / "No server info found"： 多为 Cursor 与 MCP 的启动竞态。请：① 确认已用最新构建（在 memorycode-mcp-server 目录执行 npm run build）；② 完全退出 Cursor 后重新打开；③ 确认 mcp.json 中 memorycode 在 mcpServers 内且含 "type": "stdio"。若仍报错，可尝试暂时关闭其他 MCP 仅保留 memorycode 再试。

说明： 应用内「完整教程」中有更详细的图文步骤，建议一并查看。

Windsurf（Codeium）

MemoryCode 应用内 MCP Connect 支持为 Windsurf 一键写入配置，配置文件路径为：

• macOS / Linux：~/.codeium/windsurf/mcp_config.json
• Windows：%USERPROFILE%\.codeium\windsurf\mcp_config.json

写入内容使用 command: "npx"、args: ["-y", "@memorycode/mcp-server"]，并通过环境变量 MEMORYCODE_FILE 指定本机 memorycode-mcp.json 路径（默认 ~/memorycode/memorycode-mcp.json）。Server 会优先读取该环境变量。

若出现「MCP server initialization timed out」：

1. 确认配置文件存在：先在 MemoryCode 中「导出 MCP 配置」或通过 MCP Connect 导出，确保 ~/memorycode/memorycode-mcp.json（或你设置的路径）存在。
2. 首次运行较慢：npx -y @memorycode/mcp-server 第一次会拉取 npm 包，可能超过 60 秒。可在终端先执行一次以预拉取（将 MEMORYCODE_FILE 换成你的实际路径）：

   MEMORYCODE_FILE=~/memorycode/memorycode-mcp.json npx -y @memorycode/mcp-server

   看到 “MemoryCode MCP Server running” 后按 Ctrl+C 结束，再在 Windsurf 中重新加载 MCP。
3. 若仍超时：改用本地 node 启动（推荐）
   在项目内构建后，用 node 直接运行可执行文件，避免 npx 拉包与网络延迟，启动更快、不易超时。编辑 ~/.codeium/windsurf/mcp_config.json，将 memorycode 一项改为（路径按本机实际修改）：

   "memorycode": {
     "name": "memorycode",
     "command": "/usr/local/bin/node",
     "args": [
       "/你的路径/ai-identity-wallet/memorycode-mcp-server/dist/index.js",
       "--file",
       "/你的路径/memorycode/memorycode-mcp.json"
     ]
   }

   其中 command 填本机 node 路径（终端执行 which node 可得），args[0] 填 memorycode-mcp-server/dist/index.js 的绝对路径，args[2] 填 memorycode-mcp.json 的绝对路径。保存后重启 Windsurf。
4. 检查路径：在 Windsurf 的 memorycode 配置页中确认「Configuration File」显示的路径与 MemoryCode 中导出的文件路径一致。

若 @memorycode 提示「MCP server not found / 服务器名称为空」： 通常表示该 MCP 未成功启动或未在 Cascade 中正确注册。请先解决「initialization timed out」（按上三步），确保 memorycode 在「Installed MCPs」中为已启用且无报错；配置中已包含 "name": "memorycode" 时部分客户端会正确显示 ServerName。若为手动编辑的 mcp_config.json，请确保 mcpServers.memorycode 存在且含 command、args、env（及可选 name: "memorycode"）。

云盘同步（可选）

若希望多台设备共用同一份配置，或将配置备份到云盘：

1. 将 memorycode-mcp.json 放在云盘同步目录中（如 iCloud Drive、Dropbox、OneDrive 等）。
2. 在本机启动 MCP Server 时，用 --file 指向该同步路径，例如：

   node dist/index.js --file "$HOME/Library/Mobile Documents/com~apple~CloudDocs/MemoryCode/memorycode-mcp.json"

3. 在 Claude Desktop / Cursor 的 MCP 配置里，args 中填写同一路径。

注意： 云盘冲突或同步延迟可能导致文件短暂不可用，若出现「加载 0 个资源」，请检查文件是否已同步完成、路径是否正确。

Windsurf 问题与修复方向（参考）

若后续需重新研究文档或调整实现，可参考以下结论：

1. 应用内「测试连接」对 Windsurf 无反应

• 原因：前端 handleTestConnection 曾仅允许 claude / cursor，toolId === 'windsurf' 时直接 return，未发请求。
• 修复：已去掉该限制，Windsurf 与 Claude/Cursor 共用同一测试连接逻辑；并增加 15 秒请求超时与 20 秒兜底清除，避免按钮长期处于「测试中…」。

2. Windsurf 内 MCP「initialization timed out after 60 seconds」

• 原因：Cascade 用 stdio 启动我们配置的 command（默认 npx -y @memorycode/mcp-server）。首次运行 npx 会拉取 npm 包，网络或磁盘慢时易超过 Cascade 的 60 秒等待。
• 文档：Windsurf 官方 Cascade MCP 仅描述 mcp_config.json 的 command/args/env 格式，未写超时时间；实际观测为约 60 秒。
• 修复方向：优先推荐用户改用本地 node + 绝对路径（见上方「若仍超时：改用本地 node 启动」），避免 npx；或先在终端预运行一次 npx 完成拉包后再在 Windsurf 中启用。后续若官方提供更长超时或「后台预加载」能力，可再对接。

故障排查

1. MCP 开关无法打开 / 看不到 MemoryCode 配置

• 检查：Claude Desktop 会请求 tools/list，Server 必须响应（本实现已支持）。
• 建议：确认使用最新构建（npm run build），并完全退出后重新打开 Claude Desktop。

2. 提示「Loaded 0 resources」

• 原因：未找到文件，或文件不是 MemoryCode 导出的有效 JSON（需包含 meta.origin_app === 'MemoryCode' 且 mcp.resources 存在）。
• 处理：确认 --file 路径正确；在 MemoryCode 中重新「导出到 MCP」并覆盖该文件。

3. 自然语言不触发配置加载

• 原因：需通过 Tool（load_config）实现，本 Server 已提供。
• 处理：确认 MCP 连接正常（开关为开启状态）；可说「请使用职场配置」「有哪些配置可用」等，由 Claude 调用对应 Tool。

4. 第一次打开 Claude 白屏，第二次才正常

• 可能原因：与 MCP 首次连接或其它扩展有关。
• 建议：暂时移除 MemoryCode MCP 配置后重启，若不再白屏，则多为 MCP 启动顺序问题；可保留当前配置，后续启动通常正常。

5. 修改 JSON 后列表未更新

• 说明：Server 会监听文件变化并防抖约 500ms 后重载。
• 处理：保存文件后稍等片刻；若仍不更新，可重启 MCP Server 或重启 Claude / Cursor。

6. Windsurf 提示「MCP server initialization timed out after 60 seconds」

• 原因：首次通过 npx -y @memorycode/mcp-server 启动时会从 npm 拉包，耗时可能超过 60 秒；或 MEMORYCODE_FILE 指向的文件不存在导致启动异常。
• 处理：见上方 Windsurf（Codeium） 小节：先确保 memorycode-mcp.json 已导出并存在；可选在终端预运行一次 npx -y @memorycode/mcp-server 完成拉包后再在 Windsurf 中重试。

使用场景

• Claude Desktop：用自然语言（如「请使用职场配置」「有哪些配置可用」）由模型调用 Tool 加载；或点击输入框旁 「+」，在展开的菜单中选择 MemoryCode 记忆配置加载。@ 在桌面版中对 MCP 无作用。
• 其他客户端（如 Cursor）：以该客户端实际支持的引用方式为准（可能包含 @ 或菜单入口）；自然语言在两端均可用。
• 多配置组合：不同对话选用不同配置，或在同一对话中先选一个再自然语言切换另一个，按需切换身份/风格。
• 热更新：在 MemoryCode 中调整配置后重新导出并覆盖 memorycode-mcp.json，Server 会自动重载，无需重启 Claude/Cursor。

开发

npm run build   # 编译到 dist/
npm run dev     # 监听源码变更并重新编译
npm start       # 运行 dist/index.js
npm test        # 集成测试（导出→加载、热更新、错误恢复）

集成测试见 tests/integration.test.mjs；Cursor / Claude Desktop 的手动验证步骤见 tests/MANUAL.md。

相关链接

• 应用内 完整教程：安装、Cursor/Claude 配置、云盘同步、FAQ 等。
• Resource URI 格式：memorycode://profile/{id}。

License

MIT