AI Build MCP Server

MCP 服务器，用于唤起浏览器进行 AI 萃取工作，实现 Cursor ↔ 浏览器的交互确认。

功能特性

• ✅ launch_ai_extractor：唤起浏览器打开 AI 萃取页面，等待用户确认后继续
• ✅ WebSocket 实时通信：双向实时通信，更低延迟 🆕
• ✅ 目录结构 API：通过 WebSocket 获取当前 IDE 工作区的目录树 🆕
• ✅ 连接状态可视化：前端实时显示连接状态 🆕
• ✅ 阻塞等待：MCP 工具会阻塞直到用户在浏览器中确认或取消
• ✅ 数据传递：可向浏览器传递任意 JSON 数据
• ✅ 超时控制：可配置超时时间（默认 5 分钟）
• ✅ 会话管理：每次调用使用唯一的 Session ID 🆕

🚀 快速开始（仅需 2 步）

步骤 1：配置 Cursor

在 Cursor MCP 配置中添加（查看 cursor-config-example.json）：

{
  "mcpServers": {
    "ai-build": {
      "command": "node",
      "args": ["/path/to/ai-build-mcp/dist/index.js"]
    }
  }
}

步骤 2：重启 Cursor

完全退出并重新打开 Cursor。

启动信息 🆕

服务器启动时会显示清晰的配置信息：

============================================================
🚀 AI Build MCP Server
============================================================
📌 版本: [email protected]
📁 工作区: /path/to/workspace
🔗 WebSocket 端口: 3100
🌐 前端地址: http://localhost:3000
============================================================

✅ WebSocket 服务器已启动
   端口: 3100
   地址: ws://localhost:3100
✅ MCP Server ready on stdio

这样你可以清楚地看到服务器监听的端口号和配置！

立即测试

在 Cursor 中输入：

请调用 launch_ai_extractor 工具

📖 详细步骤：FINAL_SETUP.md ⭐ 推荐先看

使用示例

AI 萃取器（launch_ai_extractor）

在 Cursor 中调用：

请调用 launch_ai_extractor 工具，传递数据：
{
  "projectName": "RM_MEPO_GUI",
  "action": "analyze"
}

Cursor 会：

1. 自动打开浏览器
2. 显示传入的数据
3. 等待你点击"确认"或"取消"
4. 返回确认结果并继续执行

目录结构 API 🆕

在前端组件中使用：

import { useWebSocket } from '@/composables/useWebSocket'

const { getDirectoryStructure } = useWebSocket()

// 获取当前工作区的目录结构
const result = await getDirectoryStructure({
  maxDepth: 3,
  ignorePatterns: ['node_modules', '.git']
})

console.log('工作区:', result.workspaceRoot)
console.log('目录树:', result.structure)

访问示例页面：http://localhost:3000/directory-explorer

架构说明

┌─────────────┐         ┌──────────────┐         ┌──────────────┐
│   Cursor    │ ──────> │  MCP Server  │ <─────> │   Browser    │
│   (调用)    │         │ (WebSocket)  │  实时   │  (用户确认)   │
│             │ <────── │ (阻塞等待)    │  双向   │  (可视状态)   │
└─────────────┘  返回   └──────────────┘  通信   └──────────────┘
                结果              🆕 WebSocket

📖 文档

推荐阅读顺序

1. WEBSOCKET_UPGRADE.md 🆕 - WebSocket 升级说明（必读）
2. FINAL_SETUP.md ⭐ - 最终配置指南
3. ENV_CONFIG.md 🆕 - 环境变量配置详解
4. QUICK_REFERENCE.md - 快速参考卡片
5. TROUBLESHOOTING.md - 故障排除指南
6. SUMMARY.md - 项目总结

其他文档

• QUICKSTART.md - 5 分钟快速开始
• GETTING_STARTED.md - 详细教程
• USAGE.md - 完整 API 文档
• DIRECTORY_API.md - 目录结构 API 文档 🆕

开发文档 🆕

• DEV_DEBUG_GUIDE.md - 开发调试完整指南 ⭐
• DEV_TOOLS_QUICK_REF.md - 开发工具快速参考
• HOW_TO_STOP.md - 如何停止服务器 🆕

配置

环境变量配置

环境变量（可选）：

FRONTEND_URL=http://localhost:3000    # 前端地址
EXTRACT_PAGE_PATH=/ai-extract         # 萃取页面路径
SERVER_PORT=3100                      # WebSocket 服务器端口
WORKSPACE_ROOT=/path/to/workspace     # 工作区根目录（默认为当前目录）🆕

快速配置：

# 1. 复制环境变量示例文件
cp env.example .env

# 2. 编辑 .env 文件，设置你的 WORKSPACE_ROOT
# WORKSPACE_ROOT=/Users/liujin/Documents/work/ERP3.0/reverse-engineering/abap-projects

# 3. 重新编译
npm run build

📖 详细配置说明：ENV_CONFIG.md - 环境变量完整文档

Cursor 配置

在 ~/.cursor/config.json 或项目的 .cursor/mcp.json 中添加：

{
  "mcpServers": {
    "ai-build": {
      "command": "node",
      "args": ["/path/to/ai-build-mcp/dist/index.js"]
    }
  }
}

依赖前端

此 MCP 服务器需要配合前端页面使用，前端项目位于 packages/ai-build-frontend。

启动前端：

cd packages/ai-build-frontend
npm run dev

⚠️ 常见问题

端口 3100 被占用

这是最常见的问题！快速修复：

lsof -ti:3100 | xargs kill -9

然后在 Cursor 中重新调用工具。

详细故障排除

• 快速修复: QUICK_FIX.md ⚡
• 完整指南: TROUBLESHOOTING.md

开发

# 开发模式（自动编译）
npm run dev

# 构建
npm run build

License

MIT