内容
# Vibecoders MCP
**一款将 Claude Code 转为整个开发栈的 MCP。** 它可以替代其他所有 MCP 服务器，将任务委托给 Codex 和 Gemini，并使用您 CLI 订阅（而非按量计费 API），在可搜索的知识图谱中记住您的项目，并在会话之间保留您的设置 —— **设计上无秘密，完全可选。**
> 构建以 **Claude Code 作为驱动程序**，优化 vibecoding。Claude 始终保持控制；Vibecoders赋予它超能力：到达任何其他 MCP 服务器，将工作委托给您已付费的计划上的 Codex/Gemini，记住决策，在会话之间保持一致，立即定位到仓库，设计超越其自身通用默认值的接口，并研究网络上的任何参考资料。无需任何先决条件 - 无需密钥，无需服务器，无需 CLI。仅添加您需要的内容。** 每个密钥始终属于您；Vibecoders 交付并计费均为零。**
## 快速开始（约 1 分钟，零配置）
**1. 克隆、安装、构建：**
```bash
git clone https://github.com/<you>/vibecoders-mcp
cd vibecoders-mcp
npm install && npm run build
```
**2. 将 `vibecoders` CLI 添加到您的 PATH（在整个 README 中使用）：**
```bash
npm link
```
> 如果您不想链接，请跳过此步骤，并运行以下每个 `vibecoders <command>` 命令作为 `node bin/vibecoders.mjs <command>`。
**3. 在 Claude Code 中注册它（指向绝对路径）：**
```bash
claude mcp add vibecoders -s user -- node "$(pwd)/dist/index.js"
```
`-s user` 注册一次，适用于 **所有** 项目（如果要仅限于当前目录，请删除它）。就这样 - 它在 **没有密钥和设置的情况下** 运行。要求 Claude 运行 `doctor`，它将向您显示可用和可选的内容。MCP `doctor` 和 `vibecoders doctor` CLI 共享一个渲染器，因此它们报告相同的部分；传递 `{json:true}`（MCP）或 `--json`（CLI）以获取结构化、可脚本化的输出。
> 配置更改和重建将在下一次 Claude Code 重启后生效。
## 工具表面概览
两个 **独立** 的启用系统控制这些工具（相同的拆分 `doctor` 在其图例中显示）：**功能** 在您配置提供程序（CLI 或您自己的密钥）时启用；**工具组** 通过 `features.*` 切换启用。其他一切都始终开启。
| 组 | 工具 | 启用方式 |
| --- | --- | --- |
| **网关**（替代其他 MCP） | `search_tools` · `load_tool` · `call_tool` | 始终开启 |
| **委托**（其他代理，您的计划） | `list_providers` · `delegate` (+ `background:true`) | 始终开启（使用 CLI 认证） |
| **后台任务**（异步委托） | `tasks_list` · `tasks_steer` · `tasks_interrupt` | 工具组 `features.tasks`（开启） |
| **记忆图（RAG）** | `memory_store` · `memory_recall` · `memory_walk` · `memory_forget` | 工具组 `features.memory`（开启）；语义回忆是可选的（您的密钥） |
| **定位** | `project_context` | 工具组 `features.projectContext`（开启） |
| **研究 - 网络** | `web_search` | **功能** - 配置提供程序（Gemini CLI 或 Gemini/Brave/Tavily 密钥） |
| **研究 - 参考** | `reference_inspect` · `reference_excerpt` · `reference_read_source` | 工具组 `features.reference`（开启） |
| **生成** | `generate_image` | **功能** - 配置提供程序（Codex CLI 或 OpenAI/Gemini 密钥） |
| **设计 RAG**（超越通用默认值） | `design_core` · `design_layer` | 工具组 `features.rag`（开启） |
| **交接**（每条通道） | `write_handoff` · `recall_handoff` | 始终开启 |
| **设备**（可选 · macOS） | `device_search` · `chat_history_search` | 工具组 `features.device`（关闭） |
| **笔记保险库**（可选） | `vault_search` · `vault_read` | 工具组 `features.vault`（关闭） |
| **状态** | `doctor` | 始终开启 |
## 您获得的内容
### 1. 替代其他所有 MCP 服务器
与其让下游工具淹没上下文，Claude 看到了几个元工具，并在需要时拉取其他工具：`search_tools` → `load_tool` → `call_tool`。在 `servers.json` 中安装 Playwright、GitHub、Vercel、Supabase 等；在需要时 **延迟加载**，因此数百种工具几乎不会增加任何上下文成本。
**安装服务器。** 复制模板并列出您要的服务器。`servers.json` 是 **git-ignored**；将其放在存储库根目录或 `~/.vibecoders/` 中：
```bash
cp servers.example.json servers.json # 然后编辑它
```
服务器按以下顺序解析： **`$VIBECODERS_SERVERS`** → **`~/.vibecoders/servers.json`** → **`./servers.json`**（存储库根目录）。参见 [`servers.example.json`](./servers.example.json) 获取注释示例；最小条目只是一个命令：
```json
{
"servers": {
"playwright": { "command": "npx", "args": ["-y", "@playwright/mcp@0.0.76"] }
}
}
```
引用服务器需要的任何机密 **环境变量名称** 在 `"env": [...]` 数组中 - 永远不要粘贴值。`lazy: true`（默认值）使服务器在第一次使用之前保持冷状态；将 `lazy: false` 设置为一两个您每次会话都访问的服务器。
**示例 - 查找工具，加载它，调用它（Claude 为您执行此操作）：**
```
search_tools { "query": "screenshot" }
→ playwright.browser_take_screenshot — 截取当前页面的截图
load_tool { "name": "playwright.browser_take_screenshot" } # 返回其输入模式
call_tool { "name": "playwright.browser_take_screenshot", "arguments": { "filename": "home.png" } }
```
### 2. 委托给 Codex 和 Gemini - 在您的订阅上，而非 API
Claude 可以通过其 **CLI** 将工作委托给另一个编码代理，因此计费会通过您已经付费的计划：
- **CLI，而非 API，刻意为之。** `delegate` 运行 `codex exec`、`gemini -p` 或 `claude -p`。用法计入您的 **Codex/ChatGPT、Gemini 或 Claude 计划**。
- **默认只读。** 委托代理仅在 `mode: "write"` 时编辑文件。
- **无需泄露密钥。** CLI 持有自己的身份验证。
- **在后台运行。** 传递 `background: true`，`delegate` 立即返回任务 ID 而不是阻塞 - 使用 `tasks_list` / `tasks_steer` / `tasks_interrupt` 管理它，因此长时间的 Codex/Gemini 运行永远不会阻塞 Claude。
**示例 - 将编写任务委托给 Codex（默认为只读；选择编辑）：**
```
delegate { "provider": "codex",
"prompt": "Add a --json flag to the doctor command and update its test",
"mode": "write" }
```
### 3. 具有 RAG 回忆的记忆图
每个用户的知识图谱，跨越每个会话：
```
memory_store 记住决策/事实/经验教训；将其链接到其他记忆（图边）
memory_recall 通过含义查找记忆（RAG）- 默认全局 + 当前项目
memory_walk 遍历节点的链接（决策的上下文）
memory_forget 标记记忆
```
- **无需密钥即可工作。** 回忆是开箱即用的 BM25 词汇 - 无需提供程序，无需设置，完全离线。
- **您想要时使用语义。** 启用嵌入式记忆（`memory.embeddings: true`），回忆融合余弦相似度 - 使用 **您自己的** OpenAI/Gemini 密钥。任何失败都回落到词汇，确保它永远不会中断。
- **范围限定。** 记忆是 `project`（此存储库 + 分支）或 `global`，因此项目不会相互影响。存储在纯附加日志文件中 - 无需数据库引擎，可移植。
**示例 - 存储决策并将其链接到约束背后：**
```
memory_store { "kind": "decision",
"text": "Use BM25 for recall; embeddings stay opt-in",
"edges": [{ "rel": "because", "text": "must work offline with zero keys" }] }
```
稍后，`memory_recall { "query": "why BM25" }` 找到它，`memory_walk` 从该节点遍历到链接的约束。
### 4. 立即定位 - `project_context`
一次调用返回此存储库的分支、最近的提交、保存的交接和项目的最新记忆。直接从 `.git` 读取 git 状态（无需子进程），因此即使在缓慢/云备份的目录中也很快。
### 5. 研究任何参考资料 - `reference_inspect` / `reference_excerpt` / `reference_read_source`
指向一个 URL 以了解其构建方式：标题、描述、**检测到的框架/库**、标题和链接 - 或提取一个有针对性的文本摘录。`reference_read_source` 是完整的源代码逃生口，需要书面 **reason**。所有这些都是 **SSRF 保护的**（拒绝 localhost/private/metadata 地址，重新检查每个重定向跳的解析 IP），大小上限和超时限制。为学习参考资料而非克隆它。
### 6. 跨会话携带工作（通道）
`write_handoff` / `recall_handoff` 保存和恢复您离开的地方，**每个工作通道隔离**（cwd + git 分支），因此在不同存储库或分支的两个会话永远不会覆盖彼此的笔记。
### 7. 可选：设备搜索、聊天历史和笔记保险库
默认关闭 - 这些读取个人数据，因此您需要显式启用它们：
- **`device_search`** - 跨 Mac 的 Spotlight（`mdfind`）文件搜索（仅限 macOS）。
- **`chat_history_search`** - 通过含义搜索您自己的过去 Claude Code 会话（`~/.claude/projects` 转录）。
- **`vault_search` / `vault_read`** - **笔记保险库**：使用与记忆图相同的 BM25 排名器索引本地笔记目录；`vault_read` 受到路径保护，限定为该目录。（与 **秘密保险库** 不同，后者存储 OS 密钥链中的 API 密钥。）
```bash
vibecoders config set features.device true # device_search + chat_history_search (macOS)
vibecoders config set features.vault true
vibecoders config set vault.dir ~/notes # 您的笔记目录
```
### 8. 像最好的设计师一样设计：超越 Claude 的通用默认值
`design_core` 和 `design_layer`：一个品牌无关的设计智能层，它将 Claude 的 UI、网站和组件输出提升到超越其默认的通用、模板化、明显 AI 生成的外观。**默认开启**（`features.rag`）。
**工作原理。** 按需交付，因此直到设计任务需要它时成本几乎为零：
- **`design_core`** 加载精简的核心：肯定标准加上两个预构建门户，模型必须在编写任何代码之前通过这两个门户。第一个门户强制每个决策 **源自品牌**（不是形容词，不是类别模板）。第二个门户，即 **活力门户**，强制执行运动和布局以实现概念，而不是装饰它。
- **`design_layer`** 在需要时拉取更深层次的层：`donts`（目录中的 AI 特征清单，供自我检查使用，在交付前）、`craft`（无缝、醒目运动和专业外观的视觉效果的机制级工艺）、`capabilities`（情境调色板：2.5D 照片、着色器、粒子、视频、3D）、`typography`、`cards`（工作技术示例）、`image_gen` 和 `standard`（精英标准，使其易于理解）。
- **图像免费合成。** `image_gen` 层直接指向模型 `generate_image`，因此生成的、符合概念的图像是同一流程的一部分。
始终开启的成本是服务器指令中的一行。核心仅在设计任务开始时加载，层仅在需要时拉取，因此没有任何东西会增加体积。
**工作原理。** 智能从大约 150 个精英、获奖网站的精选语料库中提炼成一个品牌无关的规则手册：什么是好的，什么是永远不会交付的特征，以及使运动无缝的工艺。它通过 **盲测试** 加强：一个全新的代理，沙盒到 RAG，仅凭一个模糊的品牌线，就必须 **推导出** 整个设计，而无需访问任何答案，然后根据相同的提示将其与基线 Claude 控制进行判断。
**效果。** 两件事情发生变化，而且两者都不微妙。
1. **AI 特征消失了。** 那些在每个元素上反射性淡入的特征，手绘的 SVG 地图，标题上堆叠的点，斜体单词，居中列模板，标点符号癖好。那些使输出看起来像 AI 生成的模式被命名和剪除。
2. **创造力从副本转移到设计中。** 基线 Claude 用文字表达品牌理念，即押韵的标题。RAG 使品牌理念成为 **架构**：结构、运动、类型和图像都执行概念。
**前后对比。**鉴于 `make a website for a cafe called the daily press`：
- **基线克劳德** 构建了一个有能力的但通用的咖啡馆模板：淡入的章节，手绘的 SVG 地图，产品卡片，以及新闻/纸张理念卡在一个字里。
- **相同的四字提示，通过设计 RAG，** 派生出一个全新的 **报纸**。网站 **就是** 报纸：每个部分都是印刷页面，有半色调新闻图像，编辑栏目，运行的提要，和运动执行概念。相同的模型，相同的提示。唯一不同的东西是前面的设计智能。
**示例 - 加载核心，拉取层，渲染图像：**
```
design_core # 标准 + 两个门户；先做这个
design_layer { "layer": "donts" } # 自我检查 AI 特征以避免交付
design_layer { "layer": "craft" } # 无缝运动 + 专业外观的工艺，按需拉取
generate_image { "prompt": "...", "out_path": "/abs/out/hero.png" }
```
## 自定义所有内容
所有非机密行为都存在于 `~/.vibecoders/config.json`（git-ignored）中。复制 [`config.example.json`](./config.example.json) 或使用 CLI：
```bash
vibecoders config path # 文件位置
vibecoders config get # 打印整个配置
vibecoders config set memory.embeddings true # 开启语义回忆（您的密钥）
vibecoders config set memory.defaultScope global
vibecoders config set reference.allowPrivateHosts false
```
**功能开关** (`features.*`) 打开/关闭整个工具组。`memory`、`reference`、`projectContext` 和 `tasks` **开启**；`device` 和 `vault` **关闭**（它们读取个人数据 - 可选开启）。**解析顺序：** 内置默认值 → `config.json` → 环境变量。
## 参考设置（作者如何运行它）
Vibecoders 旨在由 **[Claude Code](https://claude.com/claude-code)** 驱动，并针对其设计的参考环境是 **[Warp](https://www.warp.dev)** 终端。为了获得具体的起点，以下是作者自己的配置 - 每个条目都是 **工具/提供者选择**，**而非机密**（当需要时，密钥存储在 Keychain 或 `.env` 中，而非存储库中）：
| 能力 | 作者使用什么 | 连接方式 |
| --- | --- | --- |
| `delegate` | `codex` · `gemini` · `claude` 命令行工具，基于 **订阅**（而非按量计费 API） | 安装命令行工具，一次通过命令行工具登录 - Vibecoders 无需存储任何内容 |
| `image_gen` | **Codex 命令行工具**（ChatGPT / Codex 计划） | `vibecoders config set capabilities.image_gen.provider codex-cli` |
| `web_search` | **Gemini 命令行工具**（GoogleSearch，OAuth 计划） | `vibecoders config set capabilities.web_search.provider gemini-cli` |
| 内存 · 参考 · 项目上下文 · 任务 | 默认开启 | - |
| 设备搜索 · 笔记保险库 | 可选（关闭） | `vibecoders config set features.device true` · `… features.vault true` |
上述基于订阅的命令行工具路径 **无需机密** - 每个命令行工具都对其自身进行身份验证，派生的命令行工具默认仅接收非机密的环境允许列表（`delegation.envMode=minimal`），因此您的 shell 中的无关密钥永远不会到达它们。如果您更喜欢 API 提供程序，请将其密钥存储在 Keychain 或 `.env` 中，并固定它，例如 `vibecoders config set capabilities.image_gen.provider openai-api`。
## 携带您自己的密钥（永远不是作者的）
Vibecoders 捆绑 **无** 密钥，**无** 费用。您提供自己的，仅用于需要密钥的功能：
- **密钥存储，优先使用密钥链（推荐，macOS 仅限）：** `vibecoders vault set OPENAI_API_KEY`
将密钥存储在 OS 密钥链（**密钥存储**）中 - 永远不会写入磁盘，从每行日志中删除。
（此密钥存储；上述的可选 **笔记存储库** 是独立的文本搜索功能。）
`vault set` 仅写入 macOS 密钥链 - 在 Linux/Windows 上使用 `.env` 代替。
- **或 `.env`（跨平台）：** 复制 [`.env.example`](./.env.example) 并填写（git-ignored）。
- **委托 CLI** (`codex`/`gemini`/`claude`) 使用 **它们自己的** 登录 - Vibecoders 无需存储任何内容。
识别的密钥（全部可选）：`OPENAI_API_KEY`、`GEMINI_API_KEY`、`BRAVE_API_KEY`、
`TAVILY_API_KEY`、`ANTHROPIC_API_KEY`、`GITHUB_TOKEN`、`VERCEL_TOKEN`、
`SUPABASE_ACCESS_TOKEN`.
## 安装为插件（MCP 服务器）
此存储库也是一个 Claude Code **插件**。`.claude-plugin/plugin.json` 是清单，`.claude-plugin/marketplace.json` 将其列为一个插件市场，
`.mcp.json` 注册了 MCP 服务器 - 全部在安装时自动发现。
将市场添加到 Claude Code 中，然后从内部安装插件：
```bash
claude plugin marketplace add RaedBerjaoui/vibecoders-mcp # 或本地路径/ Git URL
```
```
/plugin # 打开插件浏览器，选择“vibecoders”→安装
```
`/plugin`（或 `claude plugin install vibecoders@vibecoders`）为您注册 MCP 服务器 - 无需单独的 `claude mcp add`。
## 安全 - 严格，不烦人
- **存储库中永远没有机密。** `.env`、`servers.json`、`config.json` 和内存存储都是 git-ignored 的；只提供空白模板。
- **优先使用密钥链**，从每行日志中删除（实时值 + 已知令牌形状）。
- **关闭时失败。** 需要您尚未设置的密钥的工具会停止并显示清晰的消息。
- **无 shell 注入**：每个子进程都是 `spawn(cmd, argsArray)` - 永远不是 shell 字符串，因此委托的 CLI 和下游服务器不能被参数注入。
- **SSRF 保护的获取。** 引用工具拒绝私有/环路/元数据目标并重新检查每个重定向跳的解析 IP。
- **下游调用有超时限制**；委托为只读，除非您选择。
查看 [SECURITY.md](./SECURITY.md) 获取完整的威胁模型。
## 比较
Vibecoders 涵盖了完整代理 OS 的 **开发者生产力** 表面 - 内存/RAG、多代理委托、网络研究、参考研究、项目上下文、交接 - 作为一个开放的、无秘密的、可自我托管的 MCP，您可以使用 **您自己的** 帐户运行。超出此范围的任何内容 - 浏览器自动化、消息传递、日历 - 您通过 **安装** 您信任的 MCP 服务器的网关添加，Vibecoders 捆绑了 none。
## 命令
| 命令 | 它做什么 |
| --- | --- |
| `vibecoders init` | 构建 `dist/index.js` 并打印状态 |
| `vibecoders register` | 将此服务器添加到 Claude Code（用户范围） |
| `vibecoders onboard` | 有指导的设置 + 状态 |
| `vibecoders setup [capability]` | 有指导的、只读的每个功能设置 |
| `vibecoders doctor [--json]` | 显示提供者、服务器、密钥、工具组、内存和您的通道（与 MCP 的 `doctor` 相同）；`--json` 发出脚本/CI 的结构化输出 |
| `vibecoders config get/set/path` | 自定义非机密行为（功能、内存、参考）；`set` 警告未知/拼写错误的密钥 |
| `vibecoders vault set <NAME>` | 在 OS 密钥链（**密钥存储**）中存储机密 - **仅限 macOS**；在 Linux/Windows 上使用 `.env` |
| `vibecoders vault list` | 显示已设置的机密（而非值） |
| `vibecoders handoff recall/write` | 打印或保存此项目的 `HANDOFF.md` |
## 文档
- [私有功能覆盖](./docs/private-overlay.md) - 从每个机器的目录加载所有者本地工具，该目录永远不会随存储库发布。
- [SECURITY.md](./SECURITY.md) - 威胁模型和如何报告漏洞。
- [CONTRIBUTING.md](./CONTRIBUTING.md) - 开发循环、布局和发布手册。
- [CHANGELOG.md](./CHANGELOG.md) - 版本更新内容。
## 许可证和归属
MIT - 参见 [LICENSE](./LICENSE)。第三方依赖项在 [NOTICE.md](./NOTICE.md) 中注明。
MCP 配置
以下是此 MCP Server 的配置信息，可直接复制到 Cursor 或其他 MCP 客户端中使用。
mcp.json
连接信息
猜你喜欢
暂无推荐服务器