# @mico_fe/mcp - 统一 MCP 服务器集合

🚪 **将多个 MCP 服务器整合到一个项目中，通过统一命令行和配置中心管理**

[![Node.js](https://img.shields.io/badge/Node.js-%3E=18.0.0-brightgreen.svg)](https://nodejs.org/)[![pnpm](https://img.shields.io/badge/pnpm-%3E=8.0.0-orange.svg)](https://pnpm.io/)

[快速开始](#-快速开始) • [配置指南](#️-配置到-cursor) • [服务器列表](#-包含的服务器) • [开发指南](#️-开发指南)

---

## 📦 包含的服务器

### 1. Apifox MCP Server (`apifox`)

Apifox 接口文档 + Mock 代理一体化服务

**核心能力：**

- ✅ **接口文档读取** — 通过 Apifox 链接或文件夹 ID 获取 OpenAPI 3.1 文档
- ✅ **Mock 数据生成** — 基于 Schema 自动生成，支持真实数据池混合、中文语义推断
- ✅ **Mock 代理拦截** — 本地 Express 代理服务器，拦截 fetch/XHR 返回 Mock 响应，支持多场景切换
- ✅ **Web UI Dashboard**（`http://localhost:端口/__mock__`）— 可视化管理规则、分组归档、导入导出
- ✅ **智能缓存** — LRU 内存 + 磁盘持久化，多索引查询
- ✅ **双鉴权** — API Key（推荐）/ Cookie Token

**工具列表：** 16 个

| 分类 | 工具 | 说明 |
|------|------|------|
| 接口文档 | `get-api-by-url` | 通过 Apifox 链接获取接口详情 |
| | `get-openapi-doc` | 获取文件夹的 OpenAPI 文档 |
| Mock 代理 | `add-mock-rule` | 基于接口自动创建拦截规则（含多场景） |
| | `list-mock-rules` | 列出所有拦截规则 |
| | `toggle-mock-rule` | 启用/禁用规则 |
| | `switch-mock-scenario` | 切换激活场景 |
| | `update-mock-scenario` | 修改场景响应数据 |
| | `delete-mock-rule` | 删除规则 |
| | `get-proxy-status` | 查看代理服务器状态 |
| Mock 数据 | `generate-mock-data` | 生成 Mock 数据（支持真实数据混合） |
| | `add-real-data` | 添加真实数据到数据池 |
| | `list-real-data` | 查看数据池 |
| | `clear-real-data` | 清空数据池 |
| 缓存管理 | `cache-stats` | 查看缓存统计 |
| | `refresh-cache` | 刷新接口缓存 |
| | `clear-cache` | 清空缓存 |

📖 [详细文档](./servers/apifox/README.md)

---

### 2. Figma to Code MCP Server (`figma`)

Figma HTML 片段转 Vue 组件服务器

**功能特性：**

- ✅ 自动从数据库获取 HTML 设计稿
- ✅ AI 智能转换为规范的 Vue 3 组件
- ✅ 自动保存到项目指定目录
- ✅ 自动生成组件文档（支持 Props 表格、组件预览）
- ✅ 使用 VitePress 构建静态文档页面并保存到服务器

**工具列表：** 4 个工具

- `fetch-html-fragment` - 根据 ID 获取 HTML 片段
- `save-vue-component` - 保存 Vue 组件到本地
- `generate-component-doc` - 生成组件文档
- `save-component-to-server` - 保存组件到服务器

📖 [详细文档](./servers/figma/README.md)

---

### 3. H5 Page Scaffold MCP Server (`h5-page`)

H5 页面脚手架生成服务器

**功能特性：**

- ✅ 业务分类的模板管理（从 npm 包加载）
- ✅ 支持多级页面路径（如 `2025/activity`）
- ✅ 自动占位符替换（组件名、路由、多语言）
- ✅ 集成 Vue Router 和 i18n 配置

**工具列表：** 4 个工具

- `list-businesses` - 列出所有可用的业务分类
- `list-templates` - 列出指定业务的模板
- `create-page` - 从模板创建新页面
- `get-template-info` - 获取模板详细信息

📖 [详细文档](./servers/h5-page/README.md)

---

## 🚀 快速开始

### 前置要求

- **Node.js** >= 18.0.0

### 方式 1: 使用 NPM 包（推荐）✨

直接使用 npx 运行，无需安装：

```bash
# 查看帮助
npx @mico_fe/mcp

# 启动配置中心
npx @mico_fe/mcp gallery
# 浏览器访问 http://localhost:8888

# 测试服务器
npx @mico_fe/mcp apifox
npx @mico_fe/mcp figma
npx @mico_fe/mcp h5-page
```

**配置中心功能：**

- 📦 所有可用的 MCP 服务器列表
- 🛠️ 每个服务器的功能说明
- ⚙️ 环境变量配置指南
- 📋 一键复制 Cursor 配置

**截图：**

![配置中心主页](./docs/imgs/1111.png)
![服务器详情](./docs/imgs/2222.png)

**全局安装（可选）：**

```bash
npm install -g @mico_fe/mcp

# 安装后可简化命令
mcp gallery
mcp apifox
mcp figma
```

---

### 方式 2: 本地开发使用

如果你需要修改源码或添加自定义服务器：

**前置要求：** pnpm >= 8.0.0

```bash
# 1. 克隆项目
git clone <your-repo-url>
cd mcp

# 2. 安装依赖（自动构建）
pnpm install

# 3. 启动配置中心
pnpm start
# 访问 http://localhost:8888

# 3.1 启动配置中心（Debug 模式）
pnpm start:debug
# Debug 模式会生成使用本地路径的 Cursor 配置，方便开发调试

# 4. 测试服务器
pnpm test           # 显示帮助
pnpm test apifox    # 测试 Apifox
pnpm test figma     # 测试 Figma
pnpm test h5-page   # 测试 H5 Page
```

---

## ⚙️ 配置到 Cursor

### 🌟 方式 1: 使用 NPM 包（推荐）✨

编辑 `~/.cursor/mcp.json`：

```json
{
  "mcpServers": {
    "apifox": {
      "command": "npx",
      "args": ["-y", "@mico_fe/mcp", "apifox"],
      "env": {
        "APIFOX_API_KEY": "APS-你的API密钥",
        "PROJECT_ID": "你的项目ID"
      }
    },
    "figma": {
      "command": "npx",
      "args": ["-y", "@mico_fe/mcp", "figma"]
    },
    "h5-page": {
      "command": "npx",
      "args": ["-y", "@mico_fe/mcp", "h5-page"],
      "env": {
        "TARGET_DIR": "/Users/你的用户名/项目路径/src/page"
      }
    }
  }
}
```

**说明：**

- ✅ 使用 `npx` 无需安装，自动使用最新版本
- ✅ `-y` 参数跳过确认提示
- ✅ 无需配置路径，适用于所有机器

**重启 Cursor** 让配置生效。

---

### 方式 2: 使用配置中心

启动配置中心，在浏览器中一键复制配置：

```bash
# 使用 NPM 包
npx @mico_fe/mcp gallery

# 或本地开发
pnpm start

# 浏览器打开 http://localhost:8888
```

**配置中心提供：**

- 📦 所有 MCP 服务器的详细信息
- 🛠️ 功能列表和使用说明
- ⚙️ 环境变量配置指南
- 📋 一键复制 Cursor 配置
- 🎨 美观的 Web 界面

---

### 方式 3: 本地开发模式

如果你克隆了项目并进行本地开发，可以使用本地路径：

```json
{
  "mcpServers": {
    "apifox": {
      "command": "node",
      "args": ["/path/to/mcp/src/cli.js", "apifox"],
      "env": {
        "APIFOX_API_KEY": "APS-你的API密钥",
        "PROJECT_ID": "你的项目ID"
      }
    },
    "figma": {
      "command": "node",
      "args": ["/path/to/mcp/src/cli.js", "figma"]
    },
    "h5-page": {
      "command": "node",
      "args": ["/path/to/mcp/src/cli.js", "h5-page"],
      "env": {
        "TARGET_DIR": "/Users/你的用户名/项目路径/src/page"
      }
    }
  }
}
```

**⚠️ 注意：** 请将 `/path/to/mcp` 替换为你的实际项目路径。

---

## 📖 使用示例

配置到 Cursor 后，可以直接在 AI 对话中使用。

> ⚠️ **重要提示：** 使用 MCP 工具前，请确保 Cursor 已切换到 **Agent 模式**（在 Chat 区域底部切换）。

### Apifox 服务器示例

```
使用 MCP 服务 apifox，获取这个接口的详情 https://app.apifox.com/link/project/3189010/apis/api-362821568

使用 MCP 服务 apifox，生成登录接口的请求体 Mock 数据

使用 MCP 服务 apifox，查看当前缓存统计信息

使用 MCP 服务 apifox，添加真实数据到全局数据池：{"uid": "313012040519936", "nickname": "测试用户"}
```

### Figma 服务器示例

```
使用 MCP 服务 figma，请帮我完成以下任务：

1. 获取 ID 为 "test001" 的 HTML 组件片段

2. 分析这个 HTML，将它转换为一个优化的 Vue 3 组件

3. 保存组件到本地项目
   组件名：GameWelcomeModal
   项目路径：/Users/mico/myproject

4. 生成组件的 Markdown 文档

5. 将组件保存到服务器数据库
```

### H5 Page 服务器示例

```
使用 MCP 服务 h5-page，创建一个新页面，使用 soulstar 的 base 模板，路径为 2025/activity

使用 MCP 服务 h5-page，列出所有可用的业务分类和模板

使用 MCP 服务 h5-page，查看 soulstar 业务的所有模板详情

使用 MCP 服务 h5-page，创建多级页面 2025/12/christmas，使用 base 模板
```

### 命令行测试

```bash
# 使用 NPM 包（推荐）
npx @mico_fe/mcp gallery      # 启动配置中心
npx @mico_fe/mcp apifox       # 测试 Apifox 服务器
npx @mico_fe/mcp figma        # 测试 Figma 服务器
npx @mico_fe/mcp h5-page      # 测试 H5 Page 服务器

# 本地开发
pnpm start                    # 启动配置中心
pnpm test apifox              # 测试 Apifox 服务器
pnpm test figma               # 测试 Figma 服务器
pnpm test h5-page             # 测试 H5 Page 服务器
```

---

## 🛠️ 开发指南

### 项目结构（Monorepo）

```
@mico_fe/mcp/
├── 📄 pnpm-workspace.yaml      # pnpm workspace 配置
├── 📦 package.json             # 根目录配置（workspace 根）
├── 📋 servers.json             # 服务器注册表
├── 🎨 src/                     # Gallery 入口层
│   ├── cli.js                 # 统一 CLI 路由
│   └── gallery-server.js      # 配置中心 Web UI
└── 🚀 servers/                 # MCP 服务器集合
    ├── apifox/                # Apifox 服务器（独立项目）
    │   ├── package.json       # @mico/apifox-server
    │   ├── build/             # 构建产物
    │   ├── src/               # TypeScript 源码
    │   └── README.md
    ├── figma/                 # Figma 服务器（独立项目）
    │   ├── package.json       # @mico/figma-server
    │   ├── dist/              # 构建产物
    │   ├── src/               # TypeScript 源码
    │   └── README.md
    └── h5-page/               # H5 Page 服务器（独立项目）
        ├── package.json       # @mico/h5-page-server
        ├── build/             # 构建产物
        ├── src/               # TypeScript 源码
        └── README.md
```

### NPM 包命令（推荐用户使用）

```bash
# 查看帮助
npx @mico_fe/mcp

# 启动配置中心
npx @mico_fe/mcp gallery

# 启动服务器
npx @mico_fe/mcp apifox
npx @mico_fe/mcp figma
npx @mico_fe/mcp h5-page

# 全局安装（可选）
npm install -g @mico_fe/mcp
mcp gallery
mcp apifox
```

---

### 本地开发命令（开发者使用）

#### Gallery 核心命令

```bash
pnpm start              # 启动配置中心（http://localhost:8888）
pnpm start:debug        # 启动配置中心（Debug 模式，生成本地路径配置）
pnpm test               # 显示帮助信息
pnpm test <server>      # 测试指定服务器
```

#### 构建命令

```bash
pnpm build              # 构建所有子项目（并行）
pnpm install            # 安装依赖 + 自动构建（prepare 钩子）

# 构建单个子项目
pnpm --filter @mico/apifox-server build
pnpm --filter @mico/figma-server build
pnpm --filter @mico/h5-page-server build
```

#### 开发命令

```bash
pnpm dev                # 所有子项目并行开发模式（热重载）

# 开发单个子项目
pnpm --filter @mico/apifox-server dev
pnpm --filter @mico/figma-server dev
pnpm --filter @mico/h5-page-server dev
```

#### 清理命令

```bash
pnpm clean              # 清理所有（包括 node_modules）
pnpm clean:builds       # 仅清理构建产物
```

#### 维护命令

```bash
pnpm port:check         # 检查 8888 端口状态
pnpm port:kill          # 清理 8888 端口占用
```

---

### 添加新服务器

#### 1. 创建服务器项目

在 `servers/` 目录创建新的服务器项目：

```bash
cd servers
mkdir my-new-server
cd my-new-server
pnpm init
```

#### 2. 配置 package.json

```json
{
  "name": "@mico/my-new-server",
  "version": "1.0.0",
  "type": "module",
  "main": "dist/index.js",
  "scripts": {
    "build": "tsc",
    "clean": "rm -rf dist",
    "dev": "tsx watch src/index.ts"
  }
}
```

#### 3. 在 servers.json 中注册

编辑根目录的 `servers.json`：

```json
{
  "servers": [
    {
      "name": "my-new-server",
      "displayName": "My New Server",
      "description": "描述你的服务器功能",
      "file": "../servers/my-new-server/dist/index.js",
      "type": "node",
      "features": ["tool-1 - 工具 1 说明", "tool-2 - 工具 2 说明"],
      "env": {
        "API_KEY": "你的 API Key（可选）"
      }
    }
  ]
}
```

#### 4. 安装依赖并构建

```bash
cd /Users/mico/mcp
pnpm install          # 自动链接到 workspace
pnpm build            # 构建所有项目（包括新项目）
```

#### 5. 测试运行

```bash
# 本地开发测试
pnpm test my-new-server

# 或使用 NPM 包测试（发布后）
npx @mico_fe/mcp my-new-server
```

---

## 🎯 架构特点

### 1. **Monorepo 架构**

- 使用 **pnpm workspace** 管理多个子项目
- 共享依赖提升到根目录（节省空间）
- 子项目独立构建，互不影响

### 2. **配置驱动**

- 通过 `servers.json` 集中管理所有服务器
- 动态加载服务器，无需预加载
- 易于扩展，添加新服务器只需配置即可

### 3. **自动构建**

- `pnpm install` 自动触发构建（postinstall 钩子）
- 首次克隆项目无需手动构建步骤
- 开发模式支持热重载

### 4. **统一入口**

- 单一 CLI 管理所有服务器
- 配置中心提供可视化管理界面
- 一键复制 Cursor 配置

### 执行流程

```
Cursor 调用
    ↓
src/cli.js 读取 servers.json
    ↓
查找 name="apifox" 的配置
    ↓
找到 file="../servers/apifox/build/index.js"
    ↓
动态 import 并启动服务器
```

---

## 🔧 技术栈

### 运行时

- **Node.js** >= 18.0.0
- **包管理器**: pnpm >= 8.0.0
- **模块系统**: ESM (`"type": "module"`)

### 核心框架

- **MCP SDK**: @modelcontextprotocol/sdk ^1.22.0
- **HTTP 服务**: Express.js（Apifox 服务器）
- **传输层**: Stdio / SSE（Server-Sent Events）

### 开发工具

- **TypeScript**: ^5.7.2
- **构建工具**: tsc + tsc-alias
- **热重载**: tsx watch

---

## 📊 依赖管理

### Workspace 优势

**之前（独立项目）：**

```
foxy-mcp/node_modules/          # 独立依赖
fetchFigmaData/node_modules/    # 独立依赖
```

**之后（Monorepo）：**

```
node_modules/                   # 共享依赖（提升）
servers/apifox/node_modules/    # 仅特有依赖
servers/figma/node_modules/     # 仅特有依赖
```

**收益：**

- ✅ 节省磁盘空间（共享依赖）
- ✅ 依赖版本统一（MCP SDK 1.22.0）
- ✅ 安装速度更快（pnpm 符号链接）

---

## 🎨 配置中心特性

启动配置中心：

```bash
# 使用 NPM 包（推荐）
npx @mico_fe/mcp gallery

# 或本地开发
pnpm start

# 访问 http://localhost:8888
```

**Debug 模式：**

本地开发时，可以使用 `--debug` 参数启动配置中心，生成的配置将使用本地路径：

```bash
# 使用 NPM 包
npx @mico_fe/mcp gallery --debug

# 或本地开发
pnpm start:debug
```

Debug 模式下生成的配置示例：

```json
{
  "apifox": {
    "command": "node",
    "args": ["/your/project/path/src/cli.js", "apifox"],
    "env": { ... }
  }
}
```

> 💡 **提示：** 普通模式生成 `npx` 配置，Debug 模式生成本地 `node` 路径配置。

**功能：**

- 📦 展示所有 MCP 服务器卡片
- 🛠️ 查看每个服务器的工具列表
- ⚙️ 查看环境变量配置说明
- 📋 一键复制 Cursor 配置（包含实际路径）
- 💾 下载配置文件（JSON 格式）
- 🔗 Cursor Deep Link（点击安装）
- 🎯 健康检查 API（`/health`）
- 🚀 优雅关闭（SIGTERM/SIGINT 处理）

**API 端点：**

- `GET /` - 主页（服务器列表）
- `GET /api/servers` - JSON API（获取服务器配置）
- `GET /health` - 健康检查

---

## ❓ 常见问题

### Q: 如何使用 NPM 包？

**推荐方式：** 使用 `npx` 无需安装

```bash
npx @mico_fe/mcp gallery      # 启动配置中心
npx @mico_fe/mcp apifox       # 启动 Apifox 服务器
npx @mico_fe/mcp figma        # 启动 Figma 服务器
npx @mico_fe/mcp h5-page      # 启动 H5 Page 服务器
```

**全局安装（可选）：**

```bash
npm install -g @mico_fe/mcp
mcp gallery
```

### Q: 本地开发需要手动构建吗？

**不需要！** `prepare` 钩子会自动构建所有子项目。

```bash
pnpm install    # 安装依赖 + 自动构建
pnpm start      # 直接启动
```

### Q: 如何只构建单个服务器？

使用 `--filter` 参数：

```bash
pnpm --filter @mico/apifox-server build
pnpm --filter @mico/figma-server build
```

### Q: 如何在开发模式运行？

```bash
# 所有服务器并行开发
pnpm dev

# 单个服务器开发
pnpm --filter @mico/apifox-server dev
```

### Q: 配置中心启动失败（端口被占用）？

```bash
# 本地开发方式
pnpm port:check     # 检查端口
pnpm port:kill      # 清理端口
pnpm start          # 重新启动

# NPM 包方式
npx @mico_fe/mcp gallery
```

### Q: 如何查看所有可用命令？

```bash
# 查看 NPM 包帮助
npx @mico_fe/mcp

# 本地开发
pnpm run            # 查看所有脚本命令
pnpm test           # 查看可用的 MCP 服务器
```

### Q: 如何添加新的 MCP 服务器？

参考 [添加新服务器](#添加新服务器) 章节。

### Q: 子项目可以独立运行吗？

可以！每个子项目都是独立的：

```bash
cd servers/apifox
pnpm install    # 会自动链接到 workspace
pnpm build
pnpm start
```

### Q: 如何更新 Cursor 配置？

1. **推荐：使用 npx 方式**（无需配置路径）：

   ```json
   {
     "mcpServers": {
       "apifox": {
         "command": "npx",
         "args": ["-y", "@mico_fe/mcp", "apifox"],
         "env": { "APIFOX_API_KEY": "..." }
       }
     }
   }
   ```

2. **使用配置中心**：

   ```bash
   npx @mico_fe/mcp gallery
   # 访问 http://localhost:8888，点击 "ⓘ" 图标查看详细配置
   ```

3. **重启 Cursor**

---

## 🔗 相关链接

- [Model Context Protocol (MCP) 文档](https://modelcontextprotocol.io/)
- [Apifox - 开放 API](https://apifox-openapi.apifox.cn/)
- [pnpm Workspace 文档](https://pnpm.io/workspaces)
- [mcp-test-servers 参考项目](https://github.com/msfeldstein/mcp-test-servers)

---

## 📝 更新日志

### v2.1.0 - Apifox Mock 代理增强

- ✅ Web UI：规则总开关、分组管理（折叠/归档/重命名/移动）、导入导出（含冲突策略）
- ✅ 规则编辑、FAB 添加按钮、延迟排序
- ✅ 代理服务启动优化：端口冲突自动清理、ESM 兼容修复

### v2.0.0 - Mock 代理拦截服务

- ✅ 本地 Mock 代理服务器（Express），拦截前端 API 请求返回 Mock 响应
- ✅ 多场景管理、Web UI Dashboard、规则持久化
- ✅ 新增 7 个 Mock 相关 MCP 工具

### v1.0.0 - Monorepo 架构

- ✅ 迁移到 pnpm workspace 架构
- ✅ 统一依赖管理（MCP SDK 1.22.0）
- ✅ 自动构建（postinstall 钩子）
- ✅ 简化命令（从 11 个减少到 8 个）
- ✅ 优化 CLI 路由（支持帮助信息）
- ✅ 配置中心 Web UI

Made with ❤️ by zackshi@micous.com