JinDaGe - code-remote MCP Details

article

README

🚀 Code Remote

Code Remote 允许你通过任何支持 MCP 的 AI 客户端，在你的设备上执行命令。它将 MCP（模型上下文协议）与你的本地设备相连接，使 AI 助手能够运行 shell 命令、读写文件以及浏览你的文件系统，你可以通过手机或任何网页浏览器来完成这些操作。

🚀 快速开始

你可以选择以下部署方式：

选项 A：使用 ngrok 进行本地部署（最简单）

使用 ngrok 进行 HTTPS 隧道，在本地运行所有服务，无需进行云端部署。

# 终端 1：启动服务器
export AUTH_TOKEN=$(openssl rand -hex 32)
echo "AUTH_TOKEN=$AUTH_TOKEN" > .env
docker-compose up -d

# 终端 2：启动 ngrok 隧道
ngrok http 8080
# 记录 https://xxx.ngrok-free.app 这个 URL

# 终端 3：启动代理（本地连接）
cd agent
uv venv && uv pip install -r requirements.txt
source .venv/bin/activate
export AUTH_TOKEN=$(cat ../.env | cut -d= -f2)
export RELAY_URL=ws://localhost:8080/ws/agent
python agent.py

添加到你的 MCP 客户端：

URL：https://xxx.ngrok-free.app/sse（你的 ngrok URL）

注意：免费的 ngrok 层级会提供一个随机的 URL，重启后会改变。付费计划提供稳定的子域名。

选项 B：Docker + 反向代理（自托管）

在你自己的基础设施上，使用合适的域名运行服务器。

# 1. 生成认证令牌
export AUTH_TOKEN=$(openssl rand -hex 32)
echo "AUTH_TOKEN=$AUTH_TOKEN" > .env

# 2. 启动服务器
docker-compose up -d

# 3. 设置 HTTPS（见下面的 HTTPS 设置部分）

选项 C：Fly.io（托管）

部署到 Fly.io 以实现自动 HTTPS 和全球可用性。

cd server

# 编辑 fly.toml 并设置你的应用名称
# 更改：app = "YOUR-APP-NAME"
# 为：app = "yourname-code-remote"

fly launch --name YOUR-APP-NAME --region dfw --no-deploy
fly volumes create code_remote_data --size 1 --region dfw
fly secrets set AUTH_TOKEN=$(openssl rand -hex 32)
fly deploy

你的 URL 将会是：

MCP 端点：https://YOUR-APP-NAME.fly.dev/sse
WebSocket：wss://YOUR-APP-NAME.fly.dev/ws/agent

安装代理（选项 B 和 C）

原生代理（直接在你的设备上运行）：

cd agent
./setup.sh
# 输入你的中继 URL（例如，wss://your-server.example.com/ws/agent）
# 输入你的认证令牌
./run.sh

沙盒代理（在 Docker 容器中运行）：

# 使用容器化代理运行完整堆栈
docker-compose --profile full up -d

沙盒代理以非 root 用户身份在隔离的 Linux 环境中运行，包含常见的开发工具（git、curl、vim、ripgrep 等）。文件访问限制在容器内的 /home/agent/workspace。

连接你的 AI 客户端

添加到你的 MCP 客户端设置：

URL：https://your-server.example.com/sse

对于 Claude.ai：设置 > 连接器 > MCP

✨ 主要特性

可通过任何 MCP 兼容的 AI 客户端，在本地设备上执行命令。
支持多种部署方式，包括本地部署、自托管部署和托管部署。
提供沙盒代理模式，增强安全性。
支持 Tailscale 集成，进一步提高安全性。

📦 安装指南

前提条件

uv - 快速 Python 包管理器（代理所需）

curl -LsSf https://astral.sh/uv/install.sh | sh

Python 3.10+ - 用于运行代理
Docker - 用于自托管服务器部署（选项 A 和 B）
Fly.io CLI - 用于托管部署（仅选项 C）

💻 使用示例

基础用法

你可以在 MCP 客户端中调用以下工具： | 工具 | 描述 | |------|-------------| | run_shell_command | 执行任何 shell 命令 | | read_file | 读取文件内容 | | write_file | 将内容写入文件 | | list_directory | 列出目录内容 | | check_agent_status | 验证代理是否已连接 |

📚 详细文档

设置指南 - 完整的安装说明
部署 - Fly.io 部署和管理
架构 - 系统设计和安全性

🔧 技术细节

架构

云/自托管设置

+----------------+          +-------------------+          +----------------+
|                |   SSE    |                   |    WS    |                |
|   AI Client    |<-------->|  Server (Cloud)   |<-------->|     Agent      |
|   (MCP)        |   MCP    |                   |  Relay   |   (Daemon)     |
+----------------+          +-------------------+          +----------------+

使用 ngrok 的本地设置（所有服务在一台设备上）

+----------------+          +-------------------+          +---------------------------+
|                |  HTTPS   |                   |          |      Your Machine         |
|   AI Client    |--------->|   ngrok tunnel    |--------->| +-------+     +-------+   |
|   (MCP)        |          |                   |          | |Server |<--->| Agent |   |
+----------------+          +-------------------+          | +-------+     +-------+   |
                                                           +---------------------------+

数据流

你与 AI 助手（Claude.ai 等）进行聊天。
AI 调用 MCP 工具（run_shell_command、read_file 等）。
服务器将命令排队，并通过 WebSocket 将其发送给连接的代理。
代理在你的设备上执行命令并返回结果。
结果通过 SSE 流回 AI。

HTTPS 设置

MCP 客户端通常需要 HTTPS。如果你使用 Docker 进行自托管，你需要一个反向代理。以下是一个使用 Caddy 的简单示例：

# 安装 Caddy (https://caddyserver.com/docs/install)
# 创建 Caddyfile:
cat > Caddyfile << 'EOF'
your-domain.com {
    reverse_proxy localhost:8080
}
EOF

# 运行 Caddy（通过 Let's Encrypt 自动配置 TLS）
caddy run

其他选项：

nginx：使用 certbot 获取 Let's Encrypt 证书
Traefik：内置 ACME 支持，用于自动 TLS
Cloudflare Tunnel：免费选项，为你处理 TLS

安全性

所有组件之间采用基于令牌的认证。
代理将文件访问限制在主目录、/tmp、/var/tmp。
所有流量通过 HTTPS/WSS 加密。
命令记录到 SQLite 以进行审计跟踪。
沙盒模式：在 Docker 容器中运行代理以实现完全隔离。
Tailscale 集成：将代理连接限制在你的私有 Tailscale 网络。

Tailscale 设置（推荐）

为了增加安全性，你可以配置服务器仅接受来自你的 Tailscale 网络的代理连接。这确保即使你的 AUTH_TOKEN 被泄露，只有你的 Tailnet 上的设备才能作为代理连接。

1. 生成一个 Tailscale 认证密钥：前往 https://login.tailscale.com/admin/settings/keys 并创建一个新的认证密钥：

勾选“可重复使用”（以便服务器在重启后可以重新连接）
可选地勾选“临时”
注意：密钥最长 90 天后过期

2. 将认证密钥设置为 Fly.io 机密：

fly secrets set TAILSCALE_AUTHKEY=tskey-auth-xxxxx -a YOUR-APP-NAME

3. 部署服务器：

cd server
fly deploy

4. 配置代理通过 Tailscale 连接：部署后，在 Fly.io 日志中找到你的服务器的 Tailscale IP：

fly logs -a YOUR-APP-NAME | grep "peerapi: serving"
# 查找：peerapi: serving on http://100.x.x.x:xxxxx

更新你的代理的 .env：

RELAY_URL=ws://100.x.x.x:8080/ws/agent

禁用 Tailscale 要求

要允许来自任何 IP 的代理连接（安全性较低）：

fly secrets set REQUIRE_PRIVATE_NETWORK=false -a YOUR-APP-NAME

📄 许可证

本项目采用 GNU Affero General Public License v3.0（AGPL - 3.0）许可。请参阅 LICENSE。

作者

Drew Cain (@groksrc)

项目结构

code-remote/
├── docker-compose.yml   # 自托管部署
├── .env.example         # 环境模板
│
├── server/              # 服务器（Docker 或 Fly.io）
│   ├── server.py        # 组合的 MCP + 中继服务器
│   ├── start.sh         # 启动脚本（Tailscale + 服务器）
│   ├── Dockerfile
│   ├── fly.toml         # Fly.io 配置（更改应用名称）
│   └── requirements.txt
│
├── agent/               # 代理（原生或容器化）
│   ├── agent.py         # WebSocket 客户端守护进程
│   ├── Dockerfile       # 沙盒 Linux 代理
│   ├── requirements.txt
│   ├── setup.sh         # 设置脚本（提示输入 URL）
│   ├── run.sh           # 运行脚本（带日志轮转）
│   ├── logs/            # 代理日志（自动轮转）
│   └── com.code.remote-agent.plist
│
└── docs/                # 文档
    ├── SETUP.md
    ├── DEPLOYMENT.md
    └── ARCHITECTURE.md

code-remote