本文档介绍如何在本地设置和启动完整的 MCP Gateway 开发环境，包括启动所有必要的服务组件。

​
前提条件

在开始之前，请确保你的系统已安装以下软件：

Git

版本控制工具

Go 1.24.1+

Go 编程语言环境

Node.js v20.18.0+

JavaScript 运行时环境（包含 npm）

​
项目架构概览

MCP Gateway 项目由以下几个核心组件组成：

​
环境搭建步骤

​
1. 获取源码

1

Fork 项目

访问 MCP Gateway 代码仓库，点击 Fork 按钮，将项目 fork 到你的 GitHub 账户下
2

克隆到本地

git clone https://github.com/your-github-username/unla.git
cd unla

​
2. 安装依赖

1

安装 Go 依赖

go mod tidy
2

安装 Node.js 依赖

cd web
npm i
cd ..

​
3. 配置环境

1

后端配置

cp .env.example .env
2

前端配置

cd web
cp .env.example .env
cd ..
可以不修改任何东西，使用默认配置启动就可以开始开发。你也可以修改配置文件来满足你的环境或开发需求，比如切换 DB、API 等存储方式。

​
启动开发服务

你需要 4 个终端窗口来运行所有服务。这种在宿主机上运行多个服务的方式，在开发过程中可以轻松的重启调试。

​
终端 1: 启动 mcp-gateway

go run cmd/gateway/main.go
mcp-gateway 默认会在 http://localhost:5235 上启动，用于处理 MCP 协议请求。

​
终端 2: 启动 apiserver

go run cmd/apiserver/main.go
apiserver 默认会在 http://localhost:5234 上启动。

​
终端 3: 启动 mock-server

go run cmd/mock-server/main.go
  • mock-server 默认会在 http://localhost:5236 上启动
  • mock-server-sse 默认会在 http://localhost:5237 上启动

​
终端 4: 启动 web 前端

cd web
npm run dev
web 终端运行命令后，会显示访问的地址。

​
访问管理界面

启动完成后，你可以在浏览器中访问终端显示的地址来访问管理界面。

默认登录信息

  • 用户名：根据环境变量 SUPER_ADMIN_USERNAME 决定
  • 密码：根据环境变量 SUPER_ADMIN_PASSWORD 决定

首次登录

登录后可以在管理界面中修改用户名和密码

​
常见问题

​
环境变量设置

某些服务可能需要特定的环境变量才能正常工作。可以在 .env 文件中设置这些变量： 
# 示例环境变量
APISERVER_JWT_SECRET_KEY="changeme-please-generate-a-random-secret"
SUPER_ADMIN_USERNAME="admin"
SUPER_ADMIN_PASSWORD="changeme-please-use-a-secure-password"

​
端口冲突

如果遇到端口冲突，可以在环境变量中修改端口配置： 
MCP_GATEWAY_PORT=5235
APISERVER_PORT=5234
MOCK_SERVER_PORT=5236

​
依赖问题

如果遇到依赖安装问题：

​
开发工作流

​
贡献代码流程

1

添加上游仓库

git remote add upstream git@github.com:amoylab/unla.git
2

同步上游代码

git pull upstream main
3

创建功能分支

git switch -c feat/your-feature-name
4

开发完成后推送

git push origin feat/your-feature-name
5

创建 Pull Request

在 GitHub 上创建 Pull Request，将你的分支合并到主仓库的 main 分支

​
分支命名规范

新功能

使用 feat/ 前缀，如 feat/add-auth-module

Bug 修复

使用 fix/ 前缀，如 fix/memory-leak

​
开发注意事项

​
下一步

成功启动本地开发环境后，你可以：

了解架构

查看架构文档深入了解系统组件

学习配置

阅读配置指南学习如何配置网关