5.8 KiB

Raw Blame History

MCP Swagger Server - 快速入门指南

项目概述

本项目是一个基于 monorepo 架构的 OpenAPI/Swagger 到 MCP (Model Context Protocol) 转换工具集，包含解析器、服务器和前端界面三个主要组件。

项目结构

mcp-swagger-server/
├── packages/
│   ├── mcp-swagger-parser/    # 核心解析器包
│   ├── mcp-swagger-server/    # MCP 服务器
│   └── mcp-swagger-ui/        # Vue.js 前端界面
├── scripts/
│   ├── build.js              # 统一构建脚本
│   ├── dev.js                # 开发环境脚本
│   ├── clean.js              # 清理脚本
│   └── diagnostic.js         # 诊断脚本
├── docs/                     # 技术文档
└── README.md

环境要求

Node.js: >=18.0.0
pnpm: 最新版本（推荐使用 pnpm 作为包管理器）
操作系统: macOS, Linux, Windows

安装指南

1. 安装 pnpm

选择以下任一方式安装 pnpm：

方式一：使用 Homebrew（macOS 推荐）

brew install pnpm

方式二：使用 npm

# 配置 npm 全局目录（避免权限问题）
mkdir ~/.npm-global
npm config set prefix '~/.npm-global'
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.zshrc
source ~/.zshrc

# 安装 pnpm
npm install -g pnpm

方式三：使用 Corepack（Node.js 16.10+）

corepack enable
corepack prepare pnpm@latest --activate

2. 克隆并安装项目

# 克隆项目
git clone <repository-url>
cd mcp-swagger-server

# 安装依赖（会自动构建依赖包）
pnpm install

开发指南

快速启动开发环境

# 启动完整开发环境
pnpm run dev

这个命令会：

构建所有依赖包
启动依赖包的 watch 模式
启动前端开发服务器

仅启动前端开发

# 仅启动 UI 开发服务器
pnpm run dev:ui

构建项目

# 构建所有包
pnpm run build

# 仅构建依赖包（不包括前端）
pnpm run build:packages

清理项目

# 清理所有构建产物和 node_modules
pnpm run clean

# 仅清理构建产物
pnpm run clean:build

项目诊断

# 运行项目健康检查
pnpm run diagnostic

包管理说明

依赖关系图

mcp-swagger-ui
    ↓ depends on
mcp-swagger-parser
    ↓ depends on
External packages (axios, swagger-parser, etc.)

为什么需要预先构建

TypeScript 编译链: 源码在 src/，但包入口指向编译后的 dist/
模块解析机制: Vite 等构建工具需要找到实际的入口文件
类型检查: TypeScript 需要 .d.ts 类型定义文件

自动化构建的优势

依赖拓扑排序: 自动按正确顺序构建包
并行优化: 无依赖关系的包可并行构建
增量构建: 只构建变更的包及其依赖者
错误处理: 构建失败时提供详细诊断信息

开发最佳实践

1. 开发新功能

# 1. 确保环境干净
pnpm run clean:build

# 2. 安装最新依赖
pnpm install

# 3. 启动开发环境
pnpm run dev

2. 添加新包

在 packages/ 目录下创建新包
添加 package.json 文件
如果有构建需求，确保包含 build 脚本
运行 pnpm run diagnostic 验证配置

3. 处理依赖问题

# 1. 运行诊断
pnpm run diagnostic

# 2. 检查特定包的构建状态
cd packages/mcp-swagger-parser
pnpm run build

# 3. 清理并重新构建
pnpm run clean
pnpm install

4. 性能优化

使用 pnpm run build:packages 跳过前端构建
利用 watch 模式进行增量编译
定期清理构建缓存

故障排除

常见问题

1. 权限错误

Error: EACCES: permission denied

解决方案: 使用 Homebrew 安装 pnpm 或配置 npm 全局目录

2. 依赖解析失败

Failed to resolve entry for package "mcp-swagger-parser"

解决方案:

pnpm run build:packages

3. 类型检查错误

Cannot find module 'mcp-swagger-parser'

解决方案: 确保包已构建并生成类型定义文件

4. 开发服务器启动失败