npm package: @qwe8652591/ai-build-mcp
Description: MCP Server for AI-powered SAP data extraction (WebSocket)
Latest version: 2.0.14

# 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](./cursor-config-example.json)）：

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

### 步骤 2：重启 Cursor

完全退出并重新打开 Cursor。

### 启动信息 🆕

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

```
============================================================
🚀 AI Build MCP Server
============================================================
📌 版本: ai-build-mcp@2.0.0
📁 工作区: /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](./FINAL_SETUP.md) ⭐ 推荐先看

## 使用示例

### AI 萃取器（launch_ai_extractor）

在 Cursor 中调用：

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

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

### 目录结构 API 🆕

在前端组件中使用：

```typescript
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_UPGRADE.md)** 🆕 - WebSocket 升级说明（必读）
2. **[FINAL_SETUP.md](./FINAL_SETUP.md)** ⭐ - 最终配置指南
3. **[ENV_CONFIG.md](./ENV_CONFIG.md)** 🆕 - 环境变量配置详解
4. **[QUICK_REFERENCE.md](./QUICK_REFERENCE.md)** - 快速参考卡片
5. **[TROUBLESHOOTING.md](./TROUBLESHOOTING.md)** - 故障排除指南
6. **[SUMMARY.md](./SUMMARY.md)** - 项目总结

### 其他文档

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

### 开发文档 🆕

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

## 配置

### 环境变量配置

环境变量（可选）：

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

**快速配置**：

```bash
# 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](./ENV_CONFIG.md) - 环境变量完整文档

## Cursor 配置

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

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

## 依赖前端

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

启动前端：

```bash
cd packages/ai-build-frontend
npm run dev
```

## ⚠️ 常见问题

### 端口 3100 被占用

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

```bash
lsof -ti:3100 | xargs kill -9
```

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

### 详细故障排除

- **快速修复**: [QUICK_FIX.md](./QUICK_FIX.md) ⚡
- **完整指南**: [TROUBLESHOOTING.md](./TROUBLESHOOTING.md)

## 开发

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

# 构建
npm run build
```

## License

MIT