npm package: @manwang/mcp
Description: 统一的 MCP 服务器集合
Author: mico
Latest version: 1.0.8

# @manwang/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 接口文档管理服务器

**功能特性：**

- ✅ 读取 Apifox 接口文档（OpenAPI 3.1 规范）
- ✅ 智能缓存系统（混合内存+磁盘持久化）
- ✅ Mock 数据生成（支持真实数据混合）
- ✅ HTTP / CLI 双模式运行

**工具列表：** 9 个工具

- `get-api-by-url` - 通过 URL 获取接口详情
- `get-openapi-doc` - 获取文件夹的 OpenAPI 文档
- `cache-stats` - 查看缓存统计
- `refresh-cache` - 刷新单个接口缓存
- `clear-cache` - 清空缓存
- `generate-mock-data` - 生成 Mock 数据
- `add-real-data` - 添加真实数据到数据池
- `list-real-data` - 查看数据池
- `clear-real-data` - 清空数据池

📖 [详细文档](./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 @manwang/mcp

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

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

**配置中心功能：**

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

**截图：**

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

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

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

# 安装后可简化命令
manwang-mcp gallery
manwang-mcp apifox
manwang-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

# 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", "@manwang/mcp", "apifox"],
      "env": {
        "APIFOX_API_KEY": "APS-你的API密钥",
        "PROJECT_ID": "你的项目ID"
      }
    },
    "figma": {
      "command": "npx",
      "args": ["-y", "@manwang/mcp", "figma"]
    },
    "h5-page": {
      "command": "npx",
      "args": ["-y", "@manwang/mcp", "h5-page"],
      "env": {
        "TARGET_DIR": "/Users/你的用户名/项目路径/src/page"
      }
    }
  }
}
```

**说明：**

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

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

---

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

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

```bash
# 使用 NPM 包
npx @manwang/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 对话中使用：

### Apifox 服务器示例

```
@apifox 这个接口的详情 https://app.apifox.com/link/project/3189010/apis/api-362821568

@apifox 生成登录接口的请求体示例

@apifox 查看缓存统计

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

### Figma 服务器示例

```
@figma 请帮我完成以下任务：

1. 使用 fetch-html-fragment 工具获取 ID 为 "test001" 的 HTML 组件

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

3. 使用 save-vue-component 工具保存组件
   组件名：GameWelcomeModal
   项目路径：/Users/mico/myproject

4. 使用 generate-component-doc 工具生成组件文档

5. 使用 save-component-to-server 工具保存到服务器
```

### H5 Page 服务器示例

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

@h5-page 有哪些可用的业务模板？

@h5-page 查看 soulstar 业务的所有模板

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

### 命令行测试

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

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

---

## 🛠️ 开发指南

### 项目结构（Monorepo）

```
@manwang/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 @manwang/mcp

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

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

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

---

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

#### Gallery 核心命令

```bash
pnpm start              # 启动配置中心（http://localhost:8888）
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 @manwang/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 @manwang/mcp gallery

# 或本地开发
pnpm start

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

**功能：**

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

**API 端点：**

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

---

## ❓ 常见问题

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

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

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

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

```bash
npm install -g @manwang/mcp
manwang-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 @manwang/mcp gallery
```

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

```bash
# 查看 NPM 包帮助
npx @manwang/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", "@manwang/mcp", "apifox"],
         "env": { "APIFOX_API_KEY": "..." }
       }
     }
   }
   ```

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

   ```bash
   npx @manwang/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)

---

## 📝 更新日志

### v1.0.0 - Monorepo 架构

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

Made with ❤️ by zackshi@micous.com