使用说明

应答MCP WebSocket网桥

热潮实验室摇滚乐！

⚠️ 重要通知：此扩展尚未发布到Replit扩展市场，因为我们正在处理Replit的审批流程。目前，您需要按照以下设置说明在Replit工作区中手动安装扩展。

一种模型上下文协议（MCP）服务器，通过WebSocket连接将Cursor IDE与Replit的生态系统连接起来。这种创新的解决方案使AI助手能够直接从Cursor与您的Replit工作区、文件和服务进行交互，而不管网络边界如何。

🌟 架构概述

此实现使用三个组件架构：

MCP服务器 (replit-mcp-assignment/)-在本地计算机上运行，通过MCP协议与Cursor通信
WebSocket网桥 -在MCP服务器和Replit之间转发命令的安全隧道
回复扩展 (replit-extension-code/)-在您的Replit工作区中运行，执行实际的Replit API调用

┌─────────────┐    MCP/stdio    ┌──────────────┐    WebSocket    ┌─────────────┐    Replit API    ┌──────────┐
│   Cursor    │ ◄────────────► │ MCP Server   │ ◄────────────► │ Replit Ext  │ ◄────────────► │ Replit   │
│    IDE      │                │ (local)      │  (ngrok tunnel)│ (workspace) │                │ Services │
└─────────────┘                └──────────────┘                └─────────────┘                └──────────┘

🚀 快速开始

先决条件

Node.js 16+本地安装
回复帐户
光标IDE
ngrok帐户（用于隧道）

1.设置MCP服务器

# Clone this repository
git clone <repository-url>
cd replit-mcp-assignment

# Install dependencies
npm install

# Build the server
npm run build

2.设置答复扩展

在您的Replit帐户中创建新的Repli
上传 replit-extension-code/ 目录到您的代表
在Repl中安装依赖项：
```
cd replit-extension-code
npm install
```

3.启动WebSocket网桥

你有两个选择来运行这座桥：

选项A：独立模式（推荐）

# In your Replit terminal
cd replit-extension-code
node run-bridge.js

选项B：完全扩展模式

# In your Replit terminal
cd replit-extension-code
npm run dev

大桥将：

启动WebSocket服务器
通过ngrok连接到本地MCP服务器
显示连接状态和身份验证详细信息

4.配置光标

将MCP服务器添加到Cursor的设置中(settings.json):

{
  "mcpServers": {
    "replit-bridge": {
      "command": "node",
      "args": ["/path/to/replit-mcp-assignment/build/index.js"],
      "env": {
        "NODE_ENV": "production"
      }
    }
  }
}

5.开始使用

重新启动游标IDE
打开MCP面板（Cmd+Shift+P→ “MCP：显示工具”）
在可用服务器中查找“replit桥”
直接在Cursor中开始使用Replit工具！

📋 可用特征

核心功能

功能	描述	状态
认证	基于JWT的身份验证与Replit	✅ 已执行
文件操作	在Replit中读取、写入和列出文件	✅ 已执行
命令执行	在Replit中运行shell命令	✅ 已执行
实时通信	基于WebSocket的消息传递	✅ 已执行
Ngrok隧道	安全远程连接	✅ 已执行

MCP工具可用

工具名称	描述	参数
`replit_list_files`	列出目录中的文件	`path?: string`
`replit_read_file`	读取文件内容	`path: string`
`replit_write_file`	写入文件	`path: string, content: string`
`replit_run_command`	执行shell命令	`command: string`
`replit_get_auth_status`	检查身份验证状态	-
`replit_get_workspace_info`	获取工作区详细信息	-

🔧 配置

环境变量

MCP服务器支持以下环境变量：

# Node environment
NODE_ENV=development

# Enable debug logging
DEBUG=replit-mcp:*

# Custom ngrok URL (if running your own tunnel)
NGROK_URL=wss://your-tunnel.ngrok.io

自定义Ngrok设置

如果你想使用自己的ngrok隧道：

在本地安装ngrok
创建隧道：
```
ngrok http 8765
```
在中更新WebSocket URL replit-extension-code/src/bridge.ts:
```
const wsUrl = `wss://your-ngrok-id.ngrok-free.app`;
```

🛠️ 发展

地方发展

# Development mode with watch
npm run dev

# Build for production
npm run build

# Start production server
npm start

# Clean build artifacts
npm run clean

测试桥梁

在您的回复中启动桥接
验证控制台中的连接状态
使用Cursor的MCP工具进行测试
检查调试日志

调试模式

启用详细日志记录：

# On the MCP server
DEBUG=replit-mcp:* npm start

# On the Replit extension
DEBUG=replit-bridge:* node run-bridge.js

📁 项目结构

replit-mcp-assignment/
├── src/                          # MCP Server Source
│   ├── index.ts                  # MCP server entry point
│   ├── server.ts                 # Server configuration
│   ├── websocket-client.ts       # WebSocket client for bridge
│   ├── tools/                    # MCP tool implementations
│   │   ├── auth.ts              # Authentication tools
│   │   ├── filesystem.ts        # File operation tools
│   │   └── index.ts             # Tool registry
│   ├── types/                    # TypeScript definitions
│   │   ├── bridge.ts            # Bridge message types
│   │   └── replit.ts            # Replit API types
│   └── utils/                    # Utilities
│       ├── logger.ts            # Logging utilities
│       └── errors.ts            # Error handling
├── build/                        # Compiled JavaScript
├── replit-extension-code/        # Replit Extension Code
│   ├── src/
│   │   ├── bridge.ts            # WebSocket bridge implementation
│   │   └── extension.ts         # Replit extension logic
│   ├── run-bridge.js            # Standalone bridge runner
│   ├── package.json             # Extension dependencies
│   └── extension.json           # Extension manifest
└── README.md                     # This file

🔐 安全考虑

认证流程

回复扩展 使用以下命令生成JWT令牌 auth.getAuthToken()
桥将令牌发送到MCP服务器进行验证
MCP服务器 对令牌进行解码和验证
所有命令 使用经过身份验证的用户的权限执行

安全特性

JWT身份验证：所有请求都需要有效的Replit JWT令牌
安全WebSocket：使用WSS（WebSocket安全）进行加密通信
令牌验证：自动过期检查和令牌刷新
本地执行：MCP服务器在本地运行，不依赖于云
许可边界：网桥只能访问用户可以访问的内容

最佳实践

永远不要公开分享你的ngrok网址
定期重新生成JWT令牌
监控网桥连接日志
使用HTTPS进行所有通信
保持依赖关系更新

🚨 故障排除

常见问题

1.“WebSocket连接失败”

# Check if ngrok is running
curl https://5c920f0293a4.ngrok-free.app/health

# Restart the bridge in your Replit
node run-bridge.js

2.“身份验证失败”

# Check JWT token in Replit
# Run this in your Replit console
import { auth } from '@replit/extensions';
await auth.init();
const token = await auth.getAuthToken();
console.log('Token valid:', token ? 'Yes' : 'No');

3.“在游标中找不到MCP服务器”

验证游标设置中的路径
检查服务器是否成功构建： npm run build
更新设置后重新启动Cursor

4.“命令超时”

检查您的回复的互联网连接
验证ngrok隧道是否处于活动状态
检查Replit扩展日志是否有错误

调试命令

# Test WebSocket connection
wscat -c wss://5c920f0293a4.ngrok-free.app

# Check MCP server
npm run build && node build/index.js

# Enable full debug
DEBUG=* npm start

🗺️ 路线图

第一阶段：核心桥✅

[x] WebSocket通信
[x] JWT身份验证
[x] 基本文件操作
[x] 命令执行
[x] Ngrok隧道

第2阶段：增强功能（进行中）

[]批处理文件操作
[]目录监视
[]环境管理
[]项目模板

第三阶段：高级集成

[]ReplDB数据库访问
[]多回复管理
[]团队协作功能
[]部署管道

第四阶段：生产特点

[]连接池
[]缓存层
[]速率限制
[]指标和监测

🤝 贡献

我们欢迎捐款！以下是如何开始：

分叉存储库
创建特征分支： git checkout -b feature/amazing-feature
制造您的更改
测试彻底：
```
npm run test
npm run build
```
提交您的更改
推到你的叉子
打开拉取请求

开发环境设置

# Install all dependencies
npm install

# Run tests
npm test

# Start development mode
npm run dev

# Type checking
npm run type-check

📚 API 参考

Websocket消息格式

interface BridgeMessage {
  id: string;          // Unique message ID
  action: string;      // Action to perform
  params?: any;        // Action parameters
  result?: any;        // Response data
  error?: string;      // Error message
  workspaceId?: string; // Replit workspace ID
}

MCP工具签名

// Example: Read a file
interface ReplitReadFileParams {
  path: string;
}

// Response
interface ReplitResponse {
  success: boolean;
  data?: any;
  error?: string;
}

📄 许可证

此项目根据ISC许可证获得许可-请参阅许可证文件以获取详细信息。

🔗 相关链接

📞 支持

如果您遇到问题：

检查日志 -MCP服务器和Replit扩展都提供详细的日志
验证连接 -确保ngrok隧道处于活动状态
检查身份验证 -验证JWT令牌是否有效
创建问题 -包括：
- 日志中的错误消息
- 操作系统和光标版本
- 重现步骤
- 网络环境详细信息

🎯 用例

面向开发者

远程开发：从本地Cursor IDE处理Replit项目
批量操作：跨多个Repl执行批量文件操作
自动化：自动化Replit工作区中的重复任务
整合：将Replit与外部工具和服务连接

对于团队

代码评审：在不离开游标的情况下查看代码
入职：使用项目模板快速设置新团队成员
文档：从Replit项目生成文档
部署：直接从Cursor管理部署

面向教育工作者

教学：在Replit中实时演示编码概念
作业：创建编码作业并对其进行评分
协作：实现实时学生协作
进度跟踪：监控各代表的学生进度