Spaces:
Sleeping
Sleeping
| --- | |
| title: '开发环境搭建' | |
| description: '学习如何为 MCPHub 搭建开发环境' | |
| --- | |
| # 开发环境搭建 | |
| 本指南将帮助您搭建 MCPHub 的开发环境，为项目贡献代码。 | |
| ## 先决条件 | |
| 在开始之前，请确保您已安装以下软件： | |
| - **Node.js**（版本 18 或更高） | |
| - **pnpm**（推荐的包管理器） | |
| - **Git** | |
| - **Docker**（可选，用于容器化开发） | |
| ## 搭建开发环境 | |
| ### 1. 克隆仓库 | |
| ```bash | |
| git clone https://github.com/your-username/mcphub.git | |
| cd mcphub | |
| ``` | |
| ### 2. 安装依赖 | |
| ```bash | |
| pnpm install | |
| ``` | |
| ### 3. 环境配置 | |
| 在根目录创建 `.env` 文件： | |
| ```bash | |
| cp .env.example .env | |
| ``` | |
| 配置以下环境变量： | |
| ```env | |
| # 服务器配置 | |
| PORT=3000 | |
| NODE_ENV=development | |
| # 数据库配置 | |
| DATABASE_URL=postgresql://username:password@localhost:5432/mcphub | |
| # JWT 配置 | |
| JWT_SECRET=your-secret-key | |
| JWT_EXPIRES_IN=24h | |
| # OpenAI 配置（用于智能路由） | |
| OPENAI_API_KEY=your-openai-api-key | |
| ``` | |
| ### 4. 数据库设置 | |
| 如果使用 PostgreSQL，创建数据库： | |
| ```bash | |
| createdb mcphub | |
| ``` | |
| ### 5. MCP 服务器配置 | |
| 创建或修改 `mcp_settings.json`： | |
| ```json | |
| { | |
| "mcpServers": { | |
| "fetch": { | |
| "command": "uvx", | |
| "args": ["mcp-server-fetch"] | |
| }, | |
| "playwright": { | |
| "command": "npx", | |
| "args": ["@playwright/mcp@latest", "--headless"] | |
| } | |
| } | |
| } | |
| ``` | |
| ## 开发工作流 | |
| ### 运行开发服务器 | |
| 同时启动后端和前端开发模式： | |
| ```bash | |
| pnpm dev | |
| ``` | |
| 这将启动： | |
| - 后端服务器：`http://localhost:3000` | |
| - 前端开发服务器：`http://localhost:5173` | |
| ### 仅运行后端 | |
| ```bash | |
| pnpm backend:dev | |
| ``` | |
| ### 仅运行前端 | |
| ```bash | |
| pnpm frontend:dev | |
| ``` | |
| ### 构建项目 | |
| 构建后端和前端： | |
| ```bash | |
| pnpm build | |
| ``` | |
| ## 项目结构 | |
| ``` | |
| mcphub/ | |
| ├── src/ # 后端源代码 | |
| │ ├── controllers/ # Express 控制器 | |
| │ ├── routes/ # API 路由 | |
| │ ├── services/ # 业务逻辑 | |
| │ ├── models/ # 数据库模型 | |
| │ └── utils/ # 工具函数 | |
| ├── frontend/ # 前端 React 应用 | |
| │ ├── src/ | |
| │ │ ├── components/ # React 组件 | |
| │ │ ├── pages/ # 页面组件 | |
| │ │ ├── services/ # API 服务 | |
| │ │ └── utils/ # 前端工具 | |
| ├── docs/ # 文档 | |
| ├── bin/ # CLI 脚本 | |
| └── scripts/ # 构建和工具脚本 | |
| ``` | |
| ## 开发工具 | |
| ### 代码检查和格式化 | |
| ```bash | |
| # 运行 ESLint | |
| pnpm lint | |
| # 使用 Prettier 格式化代码 | |
| pnpm format | |
| ``` | |
| ### 测试 | |
| ```bash | |
| # 运行测试 | |
| pnpm test | |
| # 监视模式运行测试 | |
| pnpm test --watch | |
| ``` | |
| ### 调试 | |
| 使用 Node.js 检查器调试后端： | |
| ```bash | |
| pnpm backend:debug | |
| ``` | |
| 然后将调试器连接到 `http://localhost:9229`。 | |
| ## 进行修改 | |
| ### 后端开发 | |
| 1. **控制器**：处理 HTTP 请求和响应 | |
| 2. **服务**：实现业务逻辑 | |
| 3. **模型**：定义数据库架构 | |
| 4. **路由**：定义 API 端点 | |
| ### 前端开发 | |
| 1. **组件**：可重用的 React 组件 | |
| 2. **页面**：特定路由的组件 | |
| 3. **服务**：API 通信 | |
| 4. **钩子**：自定义 React 钩子 | |
| ### 添加新的 MCP 服务器 | |
| 1. 使用新的服务器配置更新 `mcp_settings.json` | |
| 2. 测试服务器集成 | |
| 3. 必要时更新文档 | |
| ## 常见开发任务 | |
| ### 添加新的 API 端点 | |
| 1. 在 `src/controllers/` 中创建控制器 | |
| 2. 在 `src/routes/` 中定义路由 | |
| 3. 添加必要的中间件 | |
| 4. 为新端点编写测试 | |
| ### 添加新的前端功能 | |
| 1. 在 `frontend/src/components/` 中创建组件 | |
| 2. 根据需要添加路由 | |
| 3. 实现 API 集成 | |
| 4. 使用 Tailwind CSS 进行样式设计 | |
| ### 数据库迁移 | |
| 修改数据库架构时： | |
| 1. 更新 `src/models/` 中的模型 | |
| 2. 如果使用 TypeORM，创建迁移脚本 | |
| 3. 在本地测试迁移 | |
| ## 故障排除 | |
| ### 常见问题 | |
| **端口冲突**：确保端口 3000 和 5173 可用 | |
| **数据库连接**：验证 PostgreSQL 正在运行且凭据正确 | |
| **MCP 服务器启动**：检查 `mcp_settings.json` 中的服务器配置 | |
| **权限问题**：确保 MCP 服务器具有必要的权限 | |
| ### 获取帮助 | |
| - 查看[贡献指南](/zh/development/contributing) | |
| - 阅读[架构文档](/zh/development/architecture) | |
| - 在 GitHub 上提交问题报告 bug | |
| - 加入我们的社区讨论 | |
| ## 下一步 | |
| - 阅读[架构概述](/zh/development/architecture) | |
| - 了解[贡献指南](/zh/development/contributing) | |
| - 探索[配置选项](/zh/configuration/environment-variables) | |