本指南将帮助您搭建 MCPHub 的本地开发环境，了解项目结构，并掌握开发工作流。
前提条件：请确保已安装 Node.js 18+ 和 Git。
环境准备
系统要求
在开始开发之前，请确保您的系统满足以下要求：
软件依赖
- Node.js: 18.0+ 版本 - npm: 8.0+ 版本 - Git: 最新版本 - Docker:
可选，用于容器化开发
推荐工具
- VS Code: 推荐的代码编辑器 - Postman: API 测试工具 - TablePlus: 数据库管理工具 -
Docker Desktop: 容器管理
验证环境
# 检查 Node.js 版本
node --version # 应该 >= 18.0.0
# 检查 npm 版本
npm --version # 应该 >= 8.0.0
# 检查 Git 版本
git --version
# 检查 Docker（可选）
docker --version
克隆项目
获取源代码
# 克隆主仓库
git clone https://github.com/samanhappy/mcphub.git
cd mcphub
# 或者克隆您的 fork
git clone https://github.com/YOUR_USERNAME/mcphub.git
cd mcphub
项目结构
mcphub/
├── src/ # 源代码目录
│ ├── controllers/ # 控制器层
│ ├── middleware/ # 中间件
│ ├── models/ # 数据模型
│ ├── routes/ # 路由定义
│ ├── services/ # 业务逻辑层
│ ├── utils/ # 工具函数
│ └── index.ts # 应用入口
├── tests/ # 测试文件
├── docs/ # 文档源码
├── docker/ # Docker 配置
├── scripts/ # 构建脚本
├── prisma/ # 数据库模式
├── package.json # 项目依赖
├── tsconfig.json # TypeScript 配置
├── .env.example # 环境变量示例
└── README.md # 项目说明
安装依赖
安装项目依赖
# 安装生产和开发依赖
npm install
# 仅安装生产依赖
npm ci --only=production
全局工具安装
# 安装 TypeScript 编译器
npm install -g typescript
# 安装开发工具
npm install -g tsx nodemon prisma
# 安装 MCPHub CLI（可选）
npm install -g @mcphub/cli
配置开发环境
环境变量配置
# 复制环境变量模板
cp .env.example .env
# 编辑环境变量
nano .env
.env 配置示例：
# 应用配置
NODE_ENV=development
PORT=3000
HOST=localhost
启动开发服务器
开发模式启动
# 启动开发服务器（带热重载）
npm run dev
# 或者使用 tsx 直接运行
npx tsx watch src/index.ts
后台模式启动
# 使用 PM2 启动（需要先安装 PM2）
npm install -g pm2
npm run dev:pm2
# 查看进程状态
pm2 status
# 查看日志
pm2 logs mcphub-dev
验证启动
访问以下 URL 验证服务是否正常启动：
开发工作流
1. 功能开发流程
# 1. 创建功能分支
git checkout -b feature/your-feature-name
# 2. 进行开发...
# 3. 运行测试
npm test
# 4. 代码格式化
npm run lint:fix
# 5. 提交代码
git add .
git commit -m "feat: add your feature description"
# 6. 推送分支
git push origin feature/your-feature-name
# 7. 创建 Pull Request
2. 代码规范
MCPHub 项目使用以下代码规范工具：
# 代码检查
npm run lint
# 自动修复
npm run lint:fix
# 格式化代码
npm run format
# 类型检查
npm run type-check
3. 测试开发
# 运行所有测试
npm test
# 运行单元测试
npm run test:unit
# 运行集成测试
npm run test:integration
# 运行测试并生成覆盖率报告
npm run test:coverage
# 监听模式运行测试
npm run test:watch
调试技巧
1. VS Code 调试配置
创建 .vscode/launch.json 文件：
{
"version": "0.2.0",
"configurations": [
{
"name": "Debug MCPHub",
"type": "node",
"request": "launch",
"program": "${workspaceFolder}/src/index.ts",
"runtimeArgs": ["-r", "tsx/cjs"],
"env": {
"NODE_ENV": "development"
},
"console": "integratedTerminal",
"skipFiles": ["<node_internals>/**"]
}
]
}
2. 日志调试
使用内置的日志系统进行调试：
import { logger } from '@/utils/logger';
// 不同级别的日志
logger.debug('调试信息', { data });
logger.info('信息日志', { userId });
logger.warn('警告信息', { error });
logger.error('错误信息', { error, stack });
3. 数据库调试
# 查看数据库内容
npx prisma studio
# 重置数据库
npx prisma migrate reset
# 查看迁移状态
npx prisma migrate status
常用开发命令
项目管理
# 安装新依赖
npm install package-name
npm install -D package-name # 开发依赖
# 更新依赖
npm update
# 清理缓存
npm cache clean --force
# 重新安装依赖
rm -rf node_modules package-lock.json
npm install
构建和部署
# 构建项目
npm run build
# 预览构建结果
npm run preview
# 构建 Docker 镜像
npm run docker:build
# 运行 Docker 容器
npm run docker:run
数据库操作
# 创建新迁移
npx prisma migrate dev --name your-migration-name
# 重置数据库
npx prisma migrate reset
# 推送模式变更
npx prisma db push
# 生成客户端
npx prisma generate
常见问题
错误信息: Error: listen EADDRINUSE :::3000解决方案:# 查找占用端口的进程
lsof -i :3000
# 杀死进程
kill -9 PID
# 或者使用不同端口
PORT=3001 npm run dev
可能原因: 数据库文件权限或路径问题 解决方案: bash # 检查数据库文件 ls -la data/ # 重新初始化数据库 rm data/dev.db npx prisma migrate dev
解决方案:# 清理构建缓存
npm run clean
# 重新安装类型定义
npm install @types/node @types/express
# 重新生成 Prisma 客户端
npx prisma generate
进阶主题
