# Local Computer Bridge

一个可自行部署的轻量级本机 MCP 服务，让 ChatGPT 经由本机安全隧道读取文件、编辑文本及执行命令。项目以 **MIT License** 开源。

> **安全提示：** 本服务提供完整的 Shell 命令执行能力。它不是沙箱，也没有路径/命令白名单；只连接到自己信任的 ChatGPT 工作空间或 MCP 客户端，切勿暴露为未授权的公共服务。首次使用前请阅读下方安全说明。

## 从 GitHub 安装（Quick Start）

```bash
git clone https://github.com/szkeli/local-computer-bridge.git
cd local-computer-bridge
npm install
npm test
npm run check
npm start
```

`npm start` 会启动本地 stdio MCP Server，并等待 MCP 客户端连接，**不会自动连接 ChatGPT**。要将其接到 ChatGPT，请按 [`docs/CHATGPT_SETUP.md`](docs/CHATGPT_SETUP.md) 使用 OpenAI Secure MCP Tunnel 配置自己的账号、Tunnel ID 和认证信息。

**公开仓库仅包含源代码、文档、测试和示例。** 不包含作者本机的 `config/`、`runtime/`、`logs/`、`minutes/`、`backups/` 以及专用 `.command` 启动脚本。请在自己的电脑上独立安装 Node.js 20+、获取官方 tunnel-client 并完成授权；不要复制别人的 Token 或 Tunnel 配置。

**English:** Clone the repository, install dependencies, and run the tests. The MCP server communicates over stdio; connecting it to ChatGPT requires your own secure tunnel and credentials. This server can run arbitrary shell commands, so use it only in a trusted environment.

---

一个尽量薄的本地 MCP Server，让 ChatGPT 可以直接读写你的电脑，而不把它重新实现成一个完整 Coding Agent。

它只暴露 4 个工具：

- `read`：读取本地文本文件
- `write`：创建或完整覆盖本地文本文件
- `edit`：对已有文本文件做一次精确、唯一的字符串替换
- `bash`：在本机执行 Bash 命令

核心目标只有两个：

1. ChatGPT 做完调研后，直接把报告写到你指定的本地路径，不再手工复制粘贴。
2. ChatGPT 可以直接查看本地项目目录和源码，给出分析与优化建议，不再上传项目文件。

## 架构

```text
┌───────────────────────────────┐
│            ChatGPT            │
│                               │
│ Web / Research / Reasoning     │
│ Conversation Context          │
└───────────────┬───────────────┘
                │ MCP
                ▼
┌───────────────────────────────┐
│     Local Computer Bridge     │
│                               │
│ read   write   edit   bash    │
└───────────────┬───────────────┘
                │
                ▼
          macOS / Linux
```

这个项目本身不做 Agent planning、不维护项目 session、不建立代码索引、不做向量数据库，也不管理长期进程。ChatGPT 负责“想什么、做什么”，Bridge 只负责本地 I/O。

## 环境要求

- macOS 或 Linux
- Node.js 20+
- npm
- ChatGPT Developer Mode
- 如果 MCP Server 只运行在本机：OpenAI Secure MCP Tunnel

本项目使用当前 MCP TypeScript/JavaScript SDK 的拆分包：`@modelcontextprotocol/server@2.0.0`。官方 SDK 文档要求 Node.js 20+，stdio server 使用 `@modelcontextprotocol/server` 与 `@modelcontextprotocol/server/stdio`。

## 快速开始

### 1. 安装依赖

```bash
cd local-computer-bridge
npm install
```

### 2. 本地检查

```bash
npm test
npm run check
```

### 3. 用 MCP Inspector 测试

```bash
npm run inspect
```

或者直接：

```bash
npx @modelcontextprotocol/inspector node src/index.js
```

Inspector 中应该能看到 4 个工具：

```text
read
write
edit
bash
```

### 4. 接入 ChatGPT

推荐通过 OpenAI Secure MCP Tunnel，把本地 stdio MCP Server 接到 ChatGPT，而不开放公网端口。

完整步骤见：

- [`docs/CHATGPT_SETUP.md`](docs/CHATGPT_SETUP.md)

## 典型使用方式

### 调研后直接保存报告

你可以直接对 ChatGPT 说：

```text
帮我深入调研目前主流的 Agent Benchmark。
完成后把完整报告保存到：
~/Documents/research/agent-benchmark.md
```

ChatGPT 完成研究后可以调用：

```text
write({
  path: "~/Documents/research/agent-benchmark.md",
  content: "...完整报告..."
})
```

### 分析本地项目

```text
帮我检查 ~/Projects/my-app 这个项目的架构，重点看：
1. 模块边界
2. 重复逻辑
3. API 设计
4. 可能的性能问题

先阅读代码，不要修改。
```

ChatGPT 可以组合使用：

```text
bash("find ~/Projects/my-app -maxdepth 2 -type f | head -200")
read("~/Projects/my-app/package.json")
read("~/Projects/my-app/src/...")
bash("cd ~/Projects/my-app && rg 'TODO|FIXME' src")
```

然后直接在对话中给出建议。

## Tool 设计

### `read`

```json
{
  "path": "~/Projects/foo/src/index.ts",
  "offset": 1,
  "limit": 1000
}
```

- `offset`：1-based 起始行，默认 1
- `limit`：最大返回行数，默认 1000，最大 5000
- 支持绝对路径、`~/...`、相对路径
- V1 只读取 UTF-8 文本
- 大文件通过多次 `read` 翻页
- 文件正文同时放入 `structuredContent.content`，兼容 ChatGPT Plugin/Tunnel 的结果传递

### `write`

```json
{
  "path": "~/Documents/report.md",
  "content": "# Report\n..."
}
```

- 文件不存在：创建
- 文件已存在：完整覆盖
- 父目录不存在：自动创建
- V1 不提供 append mode

### `edit`

```json
{
  "path": "~/Projects/foo/config.ts",
  "old_text": "const timeout = 3000;",
  "new_text": "const timeout = 5000;"
}
```

规则非常简单：

- `old_text` 找不到：失败
- `old_text` 恰好出现 1 次：替换
- `old_text` 出现多次：失败，要求模型提供更多上下文使其唯一

V1 不做 fuzzy matching、不做 patch engine、不做批量 edit。

### `bash`

```json
{
  "command": "cd ~/Projects/foo && git status"
}
```

- 使用 `/bin/bash -lc` 执行
- 默认工作目录是用户 HOME
- 默认 timeout：60 秒
- stdout 与 stderr 分开返回，并同时放入 `structuredContent.stdout/stderr`
- 每个 stream 最多保留 100 KiB，超出后保留尾部
- V1 不提供 PTY、stdin、长期进程 session 或 job 管理

更多细节见 [`docs/TOOLS.md`](docs/TOOLS.md)。

## 配置

不需要 `.env` 库，直接使用环境变量：

| 环境变量 | 默认值 | 说明 |
|---|---:|---|
| `LOCAL_BRIDGE_BASE_DIR` | `$HOME` | 相对路径与 Bash 的默认工作目录 |
| `LOCAL_BRIDGE_SHELL` | `/bin/bash` | Bash executable |
| `LOCAL_BRIDGE_READ_DEFAULT_LINES` | `1000` | `read` 默认返回行数 |
| `LOCAL_BRIDGE_READ_MAX_LINES` | `5000` | `read` 单次最大行数 |
| `LOCAL_BRIDGE_BASH_TIMEOUT_MS` | `60000` | Bash timeout |
| `LOCAL_BRIDGE_BASH_MAX_OUTPUT_BYTES` | `102400` | stdout/stderr 各自最大保留字节数 |

例如：

```bash
export LOCAL_BRIDGE_BASE_DIR="$HOME/Projects"
export LOCAL_BRIDGE_BASH_TIMEOUT_MS=120000
npm start
```

注意：如果通过 `tunnel-client --mcp-command` 启动，应该让这些环境变量存在于 `tunnel-client` 的进程环境中。

## 路径规则

文件工具统一使用以下规则：

```text
/absolute/path
    ↓
直接使用

~/foo
    ↓
$HOME/foo

foo/bar
    ↓
$LOCAL_BRIDGE_BASE_DIR/foo/bar
```

默认：

```text
LOCAL_BRIDGE_BASE_DIR=$HOME
```

因此：

```text
read("Documents/a.md")
```

等价于：

```text
read("~/Documents/a.md")
```

## 为什么没有 `ls` / `grep` / `find` / `git` 工具？

因为 `bash` 已经覆盖这些能力：

```bash
ls
find
rg
grep
git
npm
pnpm
python
node
curl
ssh
...
```

`read / write / edit` 是高频文件操作的简洁 primitive；其余本地能力全部交给 shell。

## 为什么没有 `cwd` 参数？

为了保持 schema 极简。

文件工具直接使用明确路径；Bash 可以天然写：

```bash
cd ~/Projects/foo && npm test
```

因此没有必要再给每个 tool 增加 cwd/session 状态。

## 为什么 MCP Server 是无状态的？

Bridge 不保存：

- current project
- current directory
- conversation id
- open files
- active process
- project index

ChatGPT 对话上下文已经知道当前在处理哪个项目。每次 tool call 都是独立操作，更简单，也不会产生不同对话之间的隐藏状态冲突。

## 目录结构

```text
local-computer-bridge/
├── README.md
├── package.json
├── LICENSE
├── src/
│   ├── index.js
│   ├── lib/
│   │   ├── config.js
│   │   ├── path.js
│   │   ├── shell.js
│   │   └── text.js
│   └── tools/
│       ├── read.js
│       ├── write.js
│       ├── edit.js
│       └── bash.js
├── test/
│   └── ...
├── docs/
│   ├── ARCHITECTURE.md
│   ├── CHATGPT_SETUP.md
│   ├── TOOLS.md
│   └── TROUBLESHOOTING.md
└── examples/
    └── prompts.md
```

## 当前明确不做的东西

为了避免重新造一个 Coding Agent，V1 刻意不包含：

- repo indexing / repo map
- embeddings / RAG
- AST 索引
- planner
- agent loop
- shell session / PTY
- background job manager
- git 专用工具
- 自动 checkpoint
- fuzzy edit
- append/write streaming
- UI
- Plugin Skill
- OAuth / 多用户权限系统

如果以后真实使用中出现明确摩擦，再逐项增加。

## 关于安全

按照当前讨论，V1 的目标是验证体验，而不是设计完整安全边界。因此 `bash` 是一个真正的通用 shell tool，`write` 和 `edit` 也可以修改本地文件。

代码仍然提供了准确的 MCP tool annotations，但没有做路径 allowlist、命令 allowlist、沙箱、用户鉴权等硬化。

不要把这个版本当成面向陌生用户的公共服务。

## 官方资料

- OpenAI Plugins / MCP Server: https://developers.openai.com/plugins/build/mcp-server
- ChatGPT 连接与测试 Plugin: https://developers.openai.com/plugins/deploy/connect-chatgpt
- OpenAI Secure MCP Tunnel: https://developers.openai.com/api/docs/guides/secure-mcp-tunnels
- MCP TypeScript SDK: https://github.com/modelcontextprotocol/typescript-sdk
- MCP TypeScript SDK 文档: https://ts.sdk.modelcontextprotocol.io/v2/