npm package: @memorycode/mcp-server
Description: MCP Server for MemoryCode - Use your memory configs in Claude Desktop/Cursor
Latest version: 1.0.0

# 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）

---

## 安装

```bash
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`：
     ```bash
     node dist/index.js
     ```
   - 或指定文件：
     ```bash
     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`）：

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

`logLevel` 可选：`info`、`warn`、`error`。

---

## Cursor / Claude Desktop 配置

### Claude Desktop

1. 打开 MCP 配置目录：
   ```bash
   open ~/Library/Application\ Support/Claude/
   ```
2. 编辑 `claude_desktop_config.json`，在 `mcpServers` 中增加一项（将 `command` 和 `args` 中的路径改为你本机实际路径）：

   ```json
   "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](./cursor-mcp-example.json) 中 `memorycode` 一段，把路径改成你的本机路径后粘贴到 `~/.cursor/mcp.json` 的 `mcpServers` 中。

以下配置格式已在 Cursor 中验证通过，按此填写即可正常接入。Cursor 通过 **`mcp.json`** 配置 MCP Server，需手动编辑 JSON 并填写本机路径。根据 [Cursor MCP 文档](https://cursor.com/docs/context/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 时整文件如下）：

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

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

   ```json
   {
     "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}` 等变量，例如：
   ```json
   "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` 换成你的实际路径）：
   ```bash
   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` 一项改为（路径按本机实际修改）：
   ```json
   "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`** 指向该同步路径，例如：
   ```bash
   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](https://docs.windsurf.com/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。

---

## 开发

```bash
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