Vpc Sync MCP Server

vpc同步mcp服务器

一个MCP（模型上下文协议）服务器，用于保持您之间的上下文同步 本地克劳德桌面/Claude.ai 和 远程VPC实例 在TMUX会话中运行Claude Code。

起草提示并在本地进行分析，将其推送到VPC执行，并将结果拉回来——所有这些都是通过Claude的原生工具界面完成的。

建筑

┌─────────────────────┐         ┌──────────────────────────────┐
│  LOCAL MACHINE       │         │  VPC (cloud server)          │
│                      │         │                              │
│  Claude Desktop      │◄──SSH──►│  vpc-sync-mcp-server         │
│  (MCP client)        │  tunnel │  (Streamable HTTP on :3847)  │
│                      │         │       │                      │
│  • Draft prompts     │         │       ├── TMUX session A     │
│  • Review results    │         │       │   └── Claude Code    │
│  • Analyze projects  │         │       ├── TMUX session B     │
│                      │         │       │   └── Claude Code    │
│                      │         │       └── Context Store      │
│                      │         │           (SQLite)            │
└─────────────────────┘         └──────────────────────────────┘

工具（14）

先决条件

• 垂直路径计算机：具有Node.js 20+、tmux和SSH访问权限的Linux服务器（Ubuntu推荐）
• 本地：克劳德桌面（macOS或Windows），npm/npx
• 可选的: inotify-tools 用于新项目的自动注册
• 可选的：VPC上安装了Claude Code(npm install -g @anthropic-ai/claude-code)

快速开始

1.在VPC上安装tmux（如果尚未安装）

# Ubuntu/Debian
sudo apt-get update && sudo apt-get install -y tmux

# CentOS/RHEL
sudo yum install -y tmux

# Verify
tmux -V

2.部署MCP服务器

git clone https://github.com/gregdigittal/vpc-sync-mcp-server.git
cd vpc-sync-mcp-server
npm install
npm run build

# Generate an API key
export VPC_SYNC_API_KEY=$(openssl rand -hex 32)
echo "Save this key: $VPC_SYNC_API_KEY"

# Run in a persistent tmux session
tmux new-session -d -s mcp-server \
  "VPC_SYNC_API_KEY=$VPC_SYNC_API_KEY \
   VPC_SYNC_BASE_DIR=$HOME \
   VPC_SYNC_DB_PATH=$HOME/vpc-sync.db \
   node dist/index.js"

# Verify
curl http://127.0.0.1:3847/health

3.为Claude Code设置TMUX会话

MCP服务器管理在TMUX会话中运行的Claude Code实例。即使您断开与SSH的连接，TMUX也会使会话保持活动状态，因此您的Claude Code实例可以全天候运行。

为项目创建Claude Code会话

# Create a named session for a project
tmux new-session -d -s my-project -c ~/projects/my-project

# Launch Claude Code inside it
tmux send-keys -t my-project 'claude' Enter

一次创建多个项目会话

for project in webapp api-service data-pipeline; do
  tmux new-session -d -s "$project" -c ~/projects/"$project"
  tmux send-keys -t "$project" 'claude' Enter
  echo "Created session: $project"
done

基本tmux命令

# List all sessions
tmux list-sessions

# Attach to a session (to see what Claude Code is doing)
tmux attach -t my-project

# Detach without killing the session: press Ctrl+B then D

# Kill a session when done
tmux kill-session -t my-project

关键概念：当您从tmux会话中分离或SSH连接断开时，会话将继续在后台运行。克劳德代码继续工作。您可以随时重新连接，或使用 vpc_session_capture 在没有SSH登录的情况下，从笔记本电脑查看发生了什么。

增加tmux回滚缓冲区

默认情况下，tmux保留2000行历史记录。对于Claude Code输出，您需要更多。添加 ~/.tmux.conf:

cat >> ~/.tmux.conf  这 `-N` 标志表示“没有远程命令”——终端将显示卡住。这很正常。只要此选项卡保持打开状态，隧道就会处于活动状态。

要使隧道持久并自动重新连接，请执行以下操作：

macOS

brew install autossh autossh -M 0 -f -N -L 3847:127.0.0.1:3847 user@your-vpc-ip

Linux

sudo apt-get install -y autossh autossh -M 0 -f -N -L 3847:127.0.0.1:3847 user@your-vpc-ip

### 5.配置克劳德桌面

添加到您的Claude Desktop配置文件中：

- **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
- **视窗**: `%APPDATA%\Claude\claude_desktop_config.json`

如果您已经有一个包含首选项的配置文件，请添加 `mcpServers` 在现有设置旁边进行阻止：

{ "mcpServers": { "vpc-sync": { "command": "npx", "args": [ "mcp-remote", "http://localhost:3847/mcp", "--header", "Authorization: Bearer YOUR_API_KEY", "--allow-http" ] } } }

重新启动克劳德桌面。14 `vpc_*` 工具将会出现。

> **重要提示：** 这 `--allow-http` 标志是强制性的。没有它， `mcp-remote` 尝试OAuth动态客户端注册(`POST /register`)，这会导致404循环和静默工具调用挂起——工具显示为已注册，但所有调用都超时，没有服务器端日志。

### 6.注册您的项目

On the VPC — register all existing projects

VPC_SYNC_API_KEY=your-key ./scripts/register-all-projects.sh

Auto-register new projects going forward (run in tmux)

sudo apt-get install -y inotify-tools # if not installed tmux new-session -d -s project-watcher \ "VPC_SYNC_API_KEY=your-key ./scripts/auto-register-projects.sh"

> **注：** 对MCP服务器的所有curl请求都需要三个标头： `Content-Type: application/json`, `Accept: application/json, text/event-stream`，以及 `Authorization: Bearer KEY`.失踪 `Accept` 返回a `Not Acceptable` 错误。

## 配置

|环境变量|默认值|描述|
|---|---|---|
| `VPC_SYNC_API_KEY` | *（必填）* |用于身份验证的承载令牌|
| `VPC_SYNC_BASE_DIR` | `$HOME` |文件操作的根目录|
| `VPC_SYNC_DB_PATH` | `./vpc-sync.db` |SQLite数据库路径|
| `VPC_SYNC_PROJECTS_DIR` | `$HOME/projects` |自动注册关注目录|
| `PORT` | `3847` |HTTP服务器端口|
| `BIND` | `127.0.0.1` |绑定地址（仅保留SSH的本地主机）|
| `TRANSPORT` | `http` |运输： `http` 或 `stdio` |

## 工作流

### 从笔记本电脑开始一个新项目

1. 集思广益第.ai条中的要求
1. `vpc_sync_context` （推）→ 在VPC上存储项目上下文
1. `vpc_push_prompt` → 发送执行提示
1. `vpc_dispatch_workflow` → 写入文件+发送到Claude Code会话
1. `vpc_pull_results` → 查看已构建的内容
1. `vpc_session_capture` → 检查实时输出

### 审查现有项目

1. `vpc_list_projects` → 查看VPC上的内容
1. `vpc_sync_context` （拉）→ 将上下文加载到本地Claude中
1. `vpc_read_file` → 提取密钥文件
1. 在本地起草反馈
1. `vpc_push_prompt` → 发送评论提示
1. `vpc_dispatch_workflow` → 让克劳德密码来处理

### 监控多个会话

1. `vpc_get_status` → 一切概述
1. `vpc_session_capture` → 检查每个会话
1. `vpc_pull_results` → 抓取已完成的工作

## 安全

- **认证**：持票人代币通过 `Authorization` 头球
- **绑定**：仅限本地主机(`127.0.0.1`)--通过SSH隧道访问
- **路径净化**：所有文件操作仅限于 `VPC_SYNC_BASE_DIR`
- **TMUX净化**：从中删除控制字符 `vpc_send_to_session`
- **速率限制**：每个客户端每分钟100个请求
- **没有OAuth**：使用简单的共享密钥——服务器永远不会暴露在互联网上

## 故障排除

### Claude Desktop显示工具但调用超时

检查 `mcp-remote` 登录您的Mac：

tail -50 ~/Library/Logs/Claude/mcp-server-vpc-sync.log

常见原因：SSH隧道掉线（重启），服务器崩溃（检查 `tmux attach -t mcp-server`)，或服务器和客户端配置之间的API密钥不匹配。

### SSH隧道似乎卡住了

这很正常 `-N` 标志表示“没有远程命令”。隧道正在工作。测试：

curl http://localhost:3847/health

### `Cannot POST /register` 日志中的错误

这意味着 `mcp-remote` 正在尝试OAuth发现。确保 `--allow-http` 位于您的Claude Desktop配置参数中。

### 服务器无法启动--端口正在使用中

lsof -i :3847 # Find what's using the port PORT=3848 node dist/index.js # Use a different port

### TMUX会话终止或Claude Code退出

Check if session still exists

tmux list-sessions

If gone, recreate it

tmux new-session -d -s my-project -c ~/projects/my-project tmux send-keys -t my-project 'claude' Enter

## 发展

npm install npm run dev # Run with tsx (auto-reload) npm run build # Compile TypeScript npm start # Run compiled JS

## 许可证

麻省理工学院——见 [许可证](LICENSE)