内容
# cli-bridge
**一个本地模型上下文协议（MCP）服务器，为Claude Desktop或任何MCP兼容的客户端提供沙盒文件系统访问和受控的Shell命令执行，范围限定在一个单独的工作区根目录内。**
<p align="left">
<img src="https://img.shields.io/badge/MCP-Server-6E56CF?style=for-the-badge&logo=anthropic&logoColor=white" alt="MCP 服务器"/>
<img src="https://img.shields.io/badge/Node.js-18.17%2B-339933?style=for-the-badge&logo=node.js&logoColor=white" alt="Node.js 18.17+"/>
<img src="https://img.shields.io/badge/TypeScript-5.3-3178C6?style=for-the-badge&logo=typescript&logoColor=white" alt="TypeScript"/>
<img src="https://img.shields.io/badge/Claude%20Desktop-Compatible-D97757?style=for-the-badge&logo=claude&logoColor=white" alt="Claude Desktop 兼容"/>
</p>
<p align="left">
<img src="https://img.shields.io/badge/Windows-Tested-0078D6?style=flat-square&logo=windows&logoColor=white" alt="Windows 已测试"/>
<img src="https://img.shields.io/badge/macOS-Untested-lightgrey?style=flat-square&logo=apple&logoColor=white" alt="macOS 未测试"/>
<img src="https://img.shields.io/badge/Linux-Untested-lightgrey?style=flat-square&logo=linux&logoColor=white" alt="Linux 未测试"/>
<img src="https://img.shields.io/badge/Dev%20Mode-OFF%20by%20default-critical?style=flat-square" alt="开发模式默认关闭"/>
<img src="https://img.shields.io/badge/License-MIT-black?style=flat-square" alt="MIT 许可证"/>
</p>
---
## 什么是 cli-bridge？
`cli-bridge` 是一个轻量级的MCP服务器，连接到Claude Desktop（或任何MCP客户端），并为其提供：
- 📂 **文件系统工具** — 读取、写入、编辑、搜索和grep文件，所有操作都限定在一个工作区根目录内
- 💻 **Shell执行** — 在您的机器上运行真正的命令，通过显式的 **开发模式** 开关进行控制
- 📝 **项目记忆** — 一个追加日志（`PROJECT_LOG.md`），以便代理可以跨会话恢复上下文
- 🔒 **审计日志** — 每个工具调用都记录到一个本地日志文件中，不会发送到其他地方
所有操作都在 **本地，在您的机器上运行** — 没有外部API调用，没有云依赖，没有遥测。
---
## ⚠️ 开发模式 — 在启用Shell执行前请阅读
> [!CAUTION]
> `execute_command` 可以运行 **系统上可用的任何可执行文件**，具有 **与托管MCP客户端的应用相同的权限**。这是真正的Shell执行，不是沙盒。
| | |
|---|---|
| **默认状态** | 开发模式在服务器启动时默认为 **关闭**。`execute_command` 在任何内容启动前被阻止。 |
| **启用它** | 需要显式调用 `toggle_dev_mode({ enable_dev_mode: true })` — 不会无声启用。 |
| **您的责任** | 启用后，运行的任何命令 — 包括破坏性命令（删除文件、修改系统状态、安装软件、网络调用） — 都将实际执行。**没有命令允许列表，没有确认，只有MCP客户端自己的批准设置，没有撤销。** |
| **责任** | 该项目的作者/开发者 **不负责** 数据丢失、系统损坏、安全事件或启用开发模式或使用 `execute_command` 的任何其他后果。启用它是由您自行决定，风险自担。 |
除非您不确定，否则其他所有操作（读取、在工作区中搜索、编辑文件）都可以在关闭开发模式的情况下完全运行。
---
## 功能
<details>
<summary><b>🔍 只读工具</b>（点击展开）</summary>
| 工具 | 描述 |
|---|---|
| `read_file(path, start_line?, end_line?)` | 读取UTF-8文件内容，可选的行范围支持 |
| `list_directory(path, recursive?)` | 列出目录内容（名称、大小、目录标志） |
| `search_files(pattern, path?)` | 递归全局搜索（例如 `*.ts`, `**/*.js`） |
| `grep_content(pattern, path?, case_sensitive?, max_results?)` | 通过捆绑的 `@vscode/ripgrep` 进行快速固定字符串搜索，限制在 `max_results`（默认为50） |
| `get_dev_mode_status()` | 报告Shell执行是否启用或阻止 |
| `get_recent_journal_entries(count?, project?)` | 从 `PROJECT_LOG.md` 读取最后N条记录 |
所有工具都严格限定在工作区根目录内。
</details>
<details>
<summary><b>✍️ 写入和执行工具</b>（点击展开）</summary>
| 工具 | 描述 |
|---|---|
| `write_file(path, content)` | 覆盖/创建文件，自动创建父目录 |
| `edit_file(path, old_str, new_str)` | 目标查找和替换；如果匹配零次或多次，则出错 |
| `execute_command(command, args, cwd?, timeout?)` | Shell执行，**由开发模式控制** — 请参见上面的警告 |
| `toggle_dev_mode(enable_dev_mode)` | 启用/锁定当前会话的Shell执行 |
| `log_journal_entry(summary, files_changed?, commit_hash?, project?)` | 追加结构化记录到 `PROJECT_LOG.md` |
</details>
---
## 安全架构
```
┌─────────────────────────────────────────────┐
│ MCP 客户端 (Claude) │
└────────────────────┬──────────────────────────┘
│ 工具调用
┌────────────────────▼──────────────────────────┐
│ cli-bridge │
│ ┌───────────────────────────────────────────┐ │
│ │ 1. 路径限制 (resolveSafePath) │ │
│ │ 2. 符号链接解析 (fs.realpathSync) │ │
│ │ 3. 开发模式门控 (execute_command only) │ │
│ │ 4. Shell 元字符扫描 (仅限 Windows) │ │
│ │ 5. 审计日志写入 (.cli-bridge-audit.log) │ │
│ └───────────────────────────────────────────┘ │
└────────────────────┬──────────────────────────┘
│ 限定在
<workspaceRoot>/
```
- **路径限制** — 每个路径（包括命令 `cwd`）都严格相对于工作区根目录；拒绝遍历尝试。
- **符号链接保护** — 指向工作区边界外部的符号链接被解析并阻止。
- **开发模式门控** — `execute_command` 在显式启用之前被硬阻止。
- **无命令允许列表** — 一旦开发模式启用，主机上的任何可执行文件都可以运行。请参见上面的警告。
- **Shell 元字符扫描** — Windows 构建工具包装器（`npm`, `npx`, `yarn`, `pnpm`, `tsc`, `jest`, `eslint`, `prettier`）以 `shell: true` 运行；参数被扫描以查找 `& | ; $ > < ^`，如果找到则阻止。其他所有操作都以 `shell: false` 运行。
- **审计日志** — 每个工具调用都记录为 `<workspaceRoot>/.cli-bridge-audit.log` 中的 JSON（时间戳，参数截断为200个字符，状态：`success` / `error` / `blocked`）。
---
## 兼容性
| 平台 | 状态 |
|---|---|
| 🪟 Windows 11 (x64) | ✅ 已测试和验证 |
| 🍎 macOS (arm64 / x64) | ⚠️ 架构支持（纯ESM + 自动解析的 `ripgrep` 二进制文件），但尚未实时测试 |
| 🐧 Linux (x64) | ⚠️ 架构支持，但尚未实时测试 |
Windows 特有的处理（`.cmd`/`.bat` 包装器允许列表和 Shell 元字符扫描）仅在 `process.platform === 'win32'` 时应用。在 macOS/Linux 上，所有命令直接以 `shell: false` 启动。如果您在 macOS 或 Linux 上运行此程序，欢迎反馈/问题。
---
## 高效工作流
1. 使用 `grep_content` 在读取完整文件之前定位关键词/函数。
2. 使用 `read_file` 带有 `start_line`/`end_line` 一旦您有坐标。
3. 使用 `edit_file` 进行有针对性的更改，而不是重写整个文件。
4. 使用 `git diff` / `git log` / `git show` 通过 `execute_command` （需要开发模式）验证磁盘上的更改。
---
## 项目日志
一个追加日志，位于 `<workspaceRoot>/PROJECT_LOG.md`，用于在新会话开始时由代理读取以恢复先前的上下文。代理在完成工作后调用 `log_journal_entry`，包括文件列表和提交哈希。
---
## 安装
**先决条件：** Node.js v18.17.0+（推荐 v20 或 v24 LTS）
```bash
npm install
npm run build
```
---
## 在 Claude Desktop 中配置
### 查找配置文件（Windows）
根据 Claude Desktop 的安装方式（标准安装程序与 MSIX/Microsoft Store 包），其配置文件的位置有所不同。您可以运行此 PowerShell 命令自动定位您的 `claude_desktop_config.json`：
```powershell
Get-ChildItem -Path "$env:APPDATA\Claude\claude_desktop_config.json", "$env:LOCALAPPDATA\Packages\Claude_*\LocalCache\Roaming\Claude\claude_desktop_config.json" -ErrorAction SilentlyContinue | Select-Object FullName
```
> [!NOTE]
> 如果两个路径均未返回结果，则配置文件可能尚未创建（这会在您第一次打开Claude Desktop时发生）或安装在非标准位置。
#### 手动文件路径参考
- **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`（或 `%LOCALAPPDATA%\Packages\Claude_...\LocalCache\Roaming\Claude\claude_desktop_config.json`，适用于商店/MSIX安装）
- **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
### 注册 cli-bridge
在您的 `claude_desktop_config.json` 中添加 `cli-bridge` 到 `mcpServers` 对象：
```json
{
"mcpServers": {
"cli-bridge": {
"command": "node",
"args": [
"<您的默认安装路径>/build/index.js",
"<您的默认工作区路径>"
],
"env": {
"WORKSPACE_ROOT": "<您的默认工作区路径>"
}
}
}
}
```
- 将 `<您的默认安装路径>` 替换为克隆 `cli-bridge` 的文件夹（例如 `C:/Projects/cli-bridge` 在 Windows 上或 `/Users/username/Projects/cli-bridge` 在 macOS/Linux 上）。
- 将 `<您的默认工作区路径>` 替换为 `cli-bridge` 要管理的目标项目工作区文件夹。
---
## 测试和调试
```bash
npx @modelcontextprotocol/inspector node build/index.js <您的默认工作区路径>
```
---
<p align="center">
<sub>构建为本地优先的MCP工具。无云依赖，无遥测，无数据离开您的机器。</sub>
</p>
