VibeCode

针对Claude-Code的真正一键式MCP服务器，具有自动持久域和OAuth认证。

为什么选择VibeCode？

• ⚡ 一键启动: vibecode start - 就这么简单
• 🌐 持久域: 自动创建永不改变的稳定域
• 🔐 OAuth 2.1 认证: 内置的claude.ai认证
• 🔒 默认安全: 每个会话具有唯一的UUID路径
• 🛠️ 零配置: 智能隧道管理
• 📱 无处不在: 可以从任何设备、任何地方使用Claude-Code

安装

方案1：从PyPI安装（即将推出）

pip install vibecode

方案2：从Git安装（当前版本）

# 或者直接从git安装
pip install git+https://github.com/your-username/vibecode.git#subdirectory=vibecode

要求

# 安装cloudflared（macOS）
brew install cloudflared

# 或者安装cloudflared（Linux/Windows）
# 查看：https://developers.cloudflare.com/cloudflare-one/connections/connect-apps/install-and-setup/installation

快速开始

# 一次性设置（可选，用于持久域）
cloudflared tunnel login

# 启动所有服务
vibecode start

首次运行: 获取一个稳定的域名如 https://vibecode-123456.cfargotunnel.com
后续每次运行: 自动使用相同的域名！

只需一次将URL复制到您的Claude.ai MCP配置中——它永远不会改变。

使用VibeCode与Claude.ai

步骤1：启动您的服务器

vibecode start --quick

从终端输出中复制公共URL（例如，https://example.trycloudflare.com/uuid）

查询可用工具

# 检查可用的工具
curl -X POST http://localhost:8300/ \
  -H "Content-Type: application/json" \
  -d '{"jsonrpc":"2.0","id":1,"method":"tools/list","params":{}}

# 或使用包含的脚本
python query_tools.py --info

预期结果：17个工具，包括claude_code（Claude Code CLI集成）

步骤2：访问Claude.ai连接器

1. 前往claude.ai/settings/connectors
2. 点击左侧边栏中的**"连接器"**（高亮显示为红色）
3. 点击底部的**"添加自定义连接器"**按钮

步骤3：配置您的VibeCode连接器

1. 在“添加自定义连接器”对话框中：

   • 名称: 输入vibecode macbookv1（或您喜欢的任何名称）
   • URL: 粘贴您的VibeCode服务器URL（例如，https://sign-returned-poultry-introduction.trycloudflare.com/<uuid>）

2. 重要: 确保只使用基础URL

3. 您会看到一个安全警告：“此连接器尚未由Anthropic验证”

4. 点击**"添加"**继续

步骤4：连接到您的VibeCode服务器

1. 添加连接器后，您将在列表中看到带有自定义名称的连接器
2. 点击您VibeCode连接器旁边的**"连接"**按钮
3. Claude.ai将通过MCP协议建立与您的服务器的连接

您将获得什么

一旦连接，Claude.ai可以：

• 读写文件在您允许的目录中
• 执行命令在您授权的情况下
• 执行代码并查看结果
• 访问您的开发环境通过MCP协议

示例用法

连接后，您可以要求Claude：

使用claude code mcp代理，编写一个简单的Python hello world应用程序

Claude将：

1. 创建Python文件
2. 编写Hello World代码
3. 执行并展示结果

命令

# 主命令（如果有可用的持久域则自动使用）
vibecode start                   # 智能隧道选择

# 选项
vibecode start --quick           # 强制快速隧道（随机域名）
vibecode start --no-tunnel       # 仅本地
vibecode start --port 9000       # 自定义端口

# 设置
vibecode setup                   # 一次性设置指南

工作原理

无需设置（即插即用）：

vibecode start  # → https://abc-random.trycloudflare.com （每次变化）

一次性设置（推荐）：

cloudflared tunnel login         # 仅需一次
vibecode start                   # → https://vibecode-123456.cfargotunnel.com （始终相同）

VibeCode自动：

• ✅ 检测是否已通过Cloudflare身份验证
• ✅ 在首次运行时创建持久隧道
• ✅ 在后续运行中重用相同的隧道（和域名）
• ✅ 如果未进行身份验证，则回退到快速隧道

服务器配置

持久隧道 vs 快速隧道

• 快速隧道（--quick）：快速设置，随机域名，停止时过期
• 持久隧道（默认）：跨重启持续稳定的域名

自定义路径

配置Claude可以访问的目录：

vibecode start --allowed-paths /path/to/project --allowed-paths /another/path

无认证模式

仅用于测试（不建议用于生产）：

vibecode start --no-auth

本地开发

无需隧道进行本地开发：

vibecode start --no-tunnel --port 8300

高级用法

# 获取设置帮助
vibecode setup                   # 简单设置指南
vibecode tunnel guide            # 详细隧道指南

# 隧道管理
vibecode tunnel list             # 列出您的隧道
vibecode start --tunnel my-mcp   # 使用特定隧道

OAuth 2.1 认证

VibeCode实现了OAuth 2.1，带有动态客户端注册（DCR），以便与Claude.ai无缝集成：

• 授权服务器元数据: /.well-known/oauth-authorization-server
• 动态客户端注册: /register
• 授权端点: /authorize
• 令牌端点: /token
• PKCE支持: 所有客户端都需要
• 公开客户端: 不需要客户端密钥

安全特性

• 基于UUID的路径每个会话
• 符合OAuth 2.1，带有动态客户端注册
• Cloudflare隧道加密用于安全通信
• 通过allowed_paths配置的目录访问控制

故障排除

连接问题

如果Claude.ai无法连接：

1. 检查您的服务器是否正在运行：

   # 查找以下输出
   📡 公共URL: https://your-domain.trycloudflare.com/uuid
   

2. 验证OAuth端点是否可访问：

   curl https://your-domain.trycloudflare.com/.well-known/oauth-authorization-server
   

3. 检查服务器日志是否有错误消息

常见问题

• 404错误: 确保在添加连接器时使用的是基础URL（不带UUID）
• 连接超时: 您的隧道可能已过期 - 使用vibecode start重新启动
• 权限被拒绝: 检查您的allowed_paths配置

技术细节

MCP协议支持

VibeCode实现了完整的MCP（模型上下文协议）规范：

• JSON-RPC 2.0消息传递
• 服务器发送事件（SSE）传输
• 工具调用和资源访问
• 实时双向通信

OAuth 2.1 符合性

完整的OAuth 2.1实现包括：

• RFC 8414: 授权服务器元数据
• RFC 9728: 受保护资源元数据
• RFC 7662: 令牌内省
• RFC 7009: 令牌撤销
• 动态客户端注册（DCR）

要求

• Python 3.10+
• cloudflared CLI（安装指南）

开发

对于贡献者，请参阅CLAUDE.md获取技术文档和开发设置。

许可证

MIT