内容
mcp-multi-agents
本地M模型上下文协议）服务器兼容MCP的中提供**共享上下文连续性**。在切换VS Code + Claude Code、Antigravity、Cursor或Codex CLI之间时，您的内存、项目约定和活动任务都会跟随## 问题
每个AI IDE会话都从冷启动开始 Code + Claude Code切换ravity时，当您令牌时，新不知道：
- 您正在
- 您做出了什么决定
- 您触摸文件
- 您的是什么（CLAUDE.md 哪些任务正在进行中
该项目解决了所有这些问题。
## 工作原理
```
┌─────────────────────────────────────────────────────────────┐
│ 共享存储层 │
│ │
│ ~/.claude-mem/claude-mem.db ← 内存观察 │
│ ~/.mcp-agents/handoffs.json 会话检查点 │
│ ~/.mcp-agents/tasks.json ← 持久任务列表 │
│ ~/project/CLAUDE ← 项目约定 │
└──────────── ↑ ↑ claude-mem MCPcp-multi-agents
(现有插件) (本项目) 共享)
↑ ↑
┌───────┐ ┌──────┴────────┐
VS Code │ │ Antigravity │
│ Cursor │ │ Codex CLI │
└──────────┘ └─┘
```
上述两个MCP服务器都由每个连接。它们使用**相同的后台工作线程**（.0.0.37777`）并相同的文件**，因此上下文被共享而无需任何## 先决条件
Node.js 18+ `node --version`
claude-mem** — 必须在 Code中全局安装
验证：`~/.-mem/claude.db` 存在且/.claude-mem.pid` 在Claude Code运行时存在
- **npm** — 用于安装依赖项
## 安装
```bash
cd /home/konsing/mcp-multi-agents
npm install
npm run build
```
就这样了。服务器二进制文件现在位于 `dist/index.js`。
## MCP 工具参考
### `session_start`
最重要的工具。在任何IDE的**任何会话开始时**调用它。调用返回完整的上下文快照。
**输入：**
{ "project_pathabsolute/path/to/project```
**返回：**
一个会话的检查点一个会话正在处理- 项目的最近5个 claude-mem 观察- 所有活动任务
- 完整的CLAUDE.md从项目根目录到/.claude/CLA` 的所有文件**任何IDE的示例**
> "使用项目home/konsing` 调用 `session_start告诉我您找到。"
### `handoff_save`
在**关闭会话IDE之前**当前状态。您提供的，下一个会话的速度就越快。
**输入：**
```json
{
"project_path": "/home/konsing/my-project",
"current_task": "在 src/auth.ts 中实现 OAuth 回调处理程序",
"recent_files": ["src/auth.ts", "src/routes/callback.ts", "tests.ts"],
isions": [
"CE 流代替隐式流以提高安全性",
"令牌存储在 httpOnly，而不是 localStorage 中 ],
"next_steps "编写令牌的测试",
"更新 CLAUDE.md 中的身份验证架构决策"
],
ide_source": "vsaude"
}
```
保存到：
1. `~/.mcp-agents/handoffs.json` （始终，立即）
2. claude-mem 作为“决策”观察（尽力而为，需要工作线程运行）
### `handoff_load`
在不调用 `session_start` 的情况下，加载项目的最新检查点。当想获得交接而不需要完整的上下文转储时很有用。
**输入：**
```json
{ "project_path": "/home/konsing/my-project" }
```
### `read_project_context`
读取项目的所有CLAUDE.md文件。遍历目录树收集找到的每个CLAUDE.md，然后追加 `~/.claude/CLAUDE.md` （全局默认值）。
**输入：**
```json
{ "project_path": "/home/konsing/my-project" }
```
**这很重要：** Claude Code 自动读取 CLAUDE.md 文件。Antigravity、Cursor（无需配置）和 Codex CLI 不会自动读取。 该工具弥合了这一差距 - 在任何非 Claude Code IDE 的会话开始时调用它，以注入项目约定。
### `list_tasks`
列出持久任务。任务在会话结束、IDE切换和重启后仍然存在。
**输入：**
```json
{
"project_path": "/home/konsing/my-project",
"status": "active"
}
```
`status` 选项：`"active"` （默认），`"completed"`，`"all"`
### `create_task`
在所有IDE中创建一个可见的任务。
**输入：**
```json
{
"project_path": "/home/konsing/my-project",
"title": "为 API 添加速率限制",
"description": "使用滑动窗口算法，每分钟限制 100 个请求/用户"
}
```
### `update_task`
更新任务的标题、描述或状态。
**输入：**
```json
{
"id": "uuid-from-list-tasks",
"status": "completed"
}
```
## IDE 设置
### VS Code + Claude Code
Claude Code 自动发现 `.mcp.json` 文件。该文件已经存在于此项目根目录中：
```json
{
"mcpServers": {
"mcp-multi-agents": {
"type": "stdio",
"command": "node",
"args": ["/home/konsing/mcp-multi-agents/dist/index.js"]
}
}
}
```
对于**不是此仓库的项目**，将相同的 `.mcp.json` 添加到该项目根目录中，或将其添加到 `~/.claude/settings.json` 中的全局Claude Code设置中，位于 `mcpServers` 下。
添加后：在Claude Code中运行 `/reload-plugins` 或重新启动会话。
**注意：** claude-mem 已经通过插件系统在全局范围内启用 - 您不需要手动添加它。
### Antigravity
打开Antigravity的MCP服务器设置，并添加 `antigravity-mcp.json` 中的两个条目：
```json
{
"mcpServers": {
"mcp-multi-agents": {
"command": "node",
"args": ["/home/konsing/mcp-multi-agents/dist/index.js"]
},
"claude-mem": {
"command": "node",
"args": [
"/home/konsing/.claude/plugins/cache/thedotmack/claude-mem/10.4.3/scripts/mcp-server.cjs"
],
"env": {
"CLAUDE_PLUGIN_ROOT": "/home/konsing/.claude/plugins/cache/thedotmack/claude-mem/10.4.3"
}
}
}
}
```
**对抗重力（Gemini）的重要提示：** 在每个会话开始时，告诉AI：
> “调用 `session_start`，将 `project_path` 设置为当前项目目录。”
Antigravity 不会自动读取 CLAUDE.md 或自动触发生命周期钩子，因此 `session_start` 是它启动的方式。
### Cursor（使用 Claude Opus 4.6 / thinking models）
Cursor 使用与 Claude Code 相同的 `.mcp.json` 格式。您有两个选项：
**选项 A - 项目级** （推荐）：在项目根目录中创建 `.cursor/mcp.json`：
```json
{
"mcpServers": {
"mcp-multi-agents": {
"command": "node",
"args": ["/home/konsing/mcp-multi-agents/dist/index.js"]
},
"claude-mem": {
"command": "node",
"args": [
"/home/konsing/.claude/plugins/cache/thedotmack/claude-mem/10.4.3/scripts/mcp-server.cjs"
],
"env": {
"CLAUDE_PLUGIN_ROOT": "/home/konsing/.claude/plugins/cache/thedotmack/claude-mem/10.4.3"
}
}
}
}
```
**选项 B - 全局**：使用相同的内容创建 `~/.cursor/mcp.json` 以应用于所有项目。
**在Cursor中使用Claude Opus 4.6进行思考：** 在Cursor的模型选择器中，选择 `claude-opus-4-6` （或Cursor使用的任何标识符）。扩展思考在Cursor的设置中按模型启用。MCP工具的工作方式相同，无论使用哪个Claude模型或思考预算 - 模型协调工具调用，服务器只处理它们。
### OpenAI Codex CLI
Codex CLI 在 `~/.codex/config.toml` （全局）或 `.codex/config.toml` （项目范围，仅限受信任的项目）使用 **TOML** 格式。
**添加到 `~/.codex/config.toml`：**
```toml
[[mcp_servers]]
name = "mcp-multi-agents"
command = "node"
args = ["/home/konsing/mcp-multi-agents/dist/index.js"]
[[mcp_servers]]
name = "claude-mem"
command = "node"
args = ["/home/konsing/.claude/plugins/cache/thedotmack/claude-mem/10.4.3/scripts/mcp-server.cjs"]
[mcp_servers.env]
CLAUDE_PLUGIN_ROOT = "/home/konsing/.claude/plugins/cache/thedotmack/claude-mem/10.4.3"
```
或使用Codex CLI交互式添加：
```bash
codex mcp add
```
**关于Codex的claude-mem：** claude-mem的后台工作线程（`~/.claude-mem/worker.pid`）仅由Claude Code的`SessionStart`钩子自动启动。在不运行Claude Code的情况下使用Codex CLI时，工作线程可能不会激活。`mcp-multi-agents`服务器优雅地处理此问题 - `session_start`仍将返回交接、任务和CLAUDE.md内容；只有最近的观察部分将被跳过。要手动启动工作线程：
```bash
node ~/.claude/plugins/cache/thedotmack/claude-mem/10.4.3/scripts/bun-runner.js \
~/.claude/plugins/cache/thedotmack/claude-mem/10.4.3/scripts/worker-service.cjs start
```
## 典型会话工作流
### 从 VS Code 切换到 Antigravity
**在 VS Code 中（关闭前）：**
```
你： “保存一个交接 - 我要 Antigravity。”
克劳德： [调用_save 以及当前任务、决定和下一步**在 Antig（打开后）：你： “为/konsing/my-project 调用 session_start。”
Gem [调用 session_start完整的上下文快照]
→ 显示：上次交接、最近的内存、活动任务、.md
```
你到当前状态 - 无解释。
### IDE 中启动新```
你： “开始之前，为这个 session_start。”
AI返回完整上下文]
“现在让我们继续我们离开的地方。”
```
### 跨会话管理任务
在 VS Code 中创建任务
你： “：实现 OAuth 轮换”
德： [调用]
# 2在 Cursor 中查看你： “该项目的活动任务是什么？”
克劳德： [调用 list_tasks] → 显示在 VS Code 中创建的任务
# 在 Antigravity 中完成它
你： “将 OAuth 任务标记为完成”
Gemini： [调用 update_task，状态为“completed”]
```
## 存储与数据
| | 存储位置 | 格式 |
|------|-------|--------|
| 交接检查点 | `~/.mcp-agents/handoffs.json` | JSON，最后保存 50 条 |
| 任务 | `~/.mcp-agents/tasks.json` | JSON |
| 内存观察 | `~/.claude-mem/claude-mem.db` | SQLite（由 claude-mem 管理） |
| 向量嵌入 | `~/.claude-mem/chroma/` | ChromaDB（由 claude-mem 管理） |
| 项目约定 | `<project>/CLAUDE.md` | Markdown |
| 全局约定 | `~/./CLAUDE.md` | Markdown |
所有存储都是本地的 - 没有数据离开您的机器。
## 故障排除
**“未找到交接”** - 要么在上一个会话结束前未保存交接，要么 `project_path` 不完全匹配（使用绝对路径）。
**“claude-mem 工作线程未运行”** - 工作线程由 Claude Code 的 SessionStart 钩子启动。如果您使用非 Claude Code IDE 作为主要 IDE，请手动启动工作线程（参见上面的 CLI 部分）。
**“MCP 服务器在 IDE 中未显示”** - 检查 `dist/index.js` 是否存在（在项目根目录中运行 `npm run build`）。测试：
```bash
echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"test","version":"1"}}}' \
| node /home/konsing/mcp-multi-agents/dist/index.js
# 应该打印一个 JSON 响应，服务器信息名称为 "mcp-multi-agents"
```
**“Cursor 显示服务器但工具失败”** - Cursor 可能需要在 `.cursor/mcp.json` 中显式设置 `type: "stdio"` 字段。向服务器配置对象添加 `"type": "stdio"`。
**重新构建更改后：**
```bash
cd /home/konsing/mcp-multi-agents
npm run build
```
MCP 服务器每次会话都会重新生成，因此在重新构建后不需要重启 - 下一个 IDE 会话将使用新的二进制文件。
## 开发
```
src/
├── index.ts # 服务器入口点，工具注册
├── types.ts # 共享 TypeScript 接口
├── tools/
│ ├── session.ts # session_start
│ ├── handoff.ts # handoff_save, handoff_load
│ ├── context.ts # read_project_context
│ └── tasks.ts # list_tasks, create_task, update_task
└── services/
├── claudemem.ts # HTTP 客户端 → claude-mem 工作线程 (:37777)
├── claudemd.ts # CLAUDE.md 文件系统遍历器
├── handoffstore.ts # 交接 JSON 持久性
└── taskstore.ts # 任务 JSON 持久性
```
添加新工具：在 `src/tools/` 中实现它，在 `src/index.ts` 中调用 `registerYourTools(server)`，重新构建。
## 兼容的 IDE
| IDE | MCP 配置文件 | 传输方式 | 备注 |
|-----|----------------|-----------|-------|
| VS Code + Claude Code | `.mcp.json` | stdio | claude-mem 通过插件自动激活 |
| Antigravity | IDE 设置 UI | stdio | 手动添加两个服务器 |
| Cursor | `.cursor/mcp.json` 或 `~/.cursor/mcp.json` | stdio, SSE, HTTP | 支持 Claude Opus 4.6 及思考 |
| Codex CLI | `~/.codex/config.toml` 或 `.codex/config.toml` | 仅 stdio | claude-mem 工作线程需要手动启动 |
| 任意 MCP 客户端 | — | stdio | 服务器是标准 MCP - 与任何客户端兼容 |
