Skip to content
This repository was archived by the owner on Jul 14, 2025. It is now read-only.

Commit 10760c9

Browse files
committed
docs: Add local dev tutorial
1 parent 3f823bd commit 10760c9

File tree

8 files changed

+938
-0
lines changed

8 files changed

+938
-0
lines changed

docs/development/local-development.md

Lines changed: 119 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,119 @@
1+
# 本地开发环境搭建指南
2+
3+
本文档介绍如何在本地设置和启动完整的 MCP Gateway 开发环境,包括启动所有必要的服务组件。
4+
5+
## 前提条件
6+
7+
在开始之前,请确保你的系统已安装以下软件:
8+
9+
- Git
10+
- Go 1.24.1 或更高版本
11+
- Node.js v20.18.0 或更高版本
12+
- npm
13+
14+
## 项目架构概览
15+
16+
MCP Gateway 项目由以下几个核心组件组成:
17+
18+
1. **apiserver** - 提供配置管理、用户接口等 API 服务
19+
2. **mcp-gateway** - 核心网关服务,处理 MCP 协议转换
20+
3. **mock-user-svc** - 模拟用户服务,用于开发测试
21+
4. **web** - 管理界面前端
22+
23+
## 启动开发环境
24+
25+
### 1. 克隆项目
26+
27+
访问 [MCP Gateway 代码仓库](https://github.com/mcp-ecosystem/mcp-gateway),点击 `Fork` 按钮,将项目 fork 到你的 GitHub 账户下。
28+
29+
### 2. 克隆到本地
30+
31+
克隆你 fork 的仓库到本地:
32+
33+
```bash
34+
git clone https://github.com/your-github-username/mcp-gateway.git
35+
```
36+
37+
### 3. 初始化环境依赖
38+
39+
进入项目目录:
40+
```bash
41+
cd mcp-gateway
42+
```
43+
44+
安装依赖:
45+
46+
```bash
47+
go mod tidy
48+
cd web
49+
npm i
50+
```
51+
52+
### 4. 启动开发环境
53+
54+
```bash
55+
cp .env.example .env
56+
cd web
57+
cp .env.example .env
58+
```
59+
60+
**注意**:可以不修改任何东西,使用默认配置启动就可以开始开发,但是你同样可以修改配置文件来满足你的环境或者开发需求,比如里面可以切换Disk、DB等
61+
62+
63+
**注意**:你可能需要4个终端窗口来运行所有服务,这种在宿主机上运行多个服务的方式,在开发过程中可以轻松的重启调试等
64+
65+
#### 4.1 启动 mcp-gateway
66+
67+
```bash
68+
go run cmd/gateway/main.go
69+
```
70+
71+
mcp-gateway 默认会在 `http://localhost:5235` 上启动,用于处理 MCP 协议请求。
72+
73+
#### 4.2 启动 apiserver
74+
75+
```bash
76+
go run cmd/apiserver/main.go
77+
```
78+
79+
apiserver 默认会在 `http://localhost:5234` 上启动。
80+
81+
#### 4.3 启动 mock-user-svc
82+
83+
```bash
84+
go run cmd/mock-user-svc/main.go
85+
```
86+
87+
mock-user-svc 默认会在 `http://localhost:5235` 上启动。
88+
89+
#### 4.4 启动 web 前端
90+
91+
```bash
92+
npm run dev
93+
```
94+
95+
web 前端默认会在 `http://localhost:5236` 上启动。
96+
97+
此时你就可以在浏览器中访问 http://localhost:5236 来访问管理界面了,默认用户名和密码根据你环境变量(根目录的.env文件)来决定,环境变量是`SUPER_ADMIN_USERNAME``SUPER_ADMIN_PASSWORD`,登录后可以在管理界面中修改用户名和密码
98+
99+
100+
## 常见问题
101+
102+
### 环境变量设置
103+
104+
某些服务可能需要特定的环境变量才能正常工作。可以创建 `.env` 文件或在启动命令前设置这些变量:
105+
106+
```bash
107+
# 示例
108+
export OPENAI_API_KEY="your_api_key"
109+
export OPENAI_MODEL="gpt-4o-mini"
110+
export APISERVER_JWT_SECRET_KEY="your_secret_key"
111+
```
112+
113+
## 下一步
114+
115+
成功启动本地开发环境后,你可以:
116+
117+
- 查看 [架构文档](./architecture.md) 深入了解系统组件
118+
- 阅读 [配置指南](/docs/configuration/) 学习如何配置网关
119+
- 查看 [客户端使用文档](/docs/client-usage/) 了解如何与网关交互
Lines changed: 117 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,117 @@
1+
# Einrichtungsleitfaden für lokale Entwicklungsumgebung
2+
3+
Dieses Dokument beschreibt, wie Sie eine vollständige MCP Gateway-Entwicklungsumgebung lokal einrichten und starten können, einschließlich aller erforderlichen Servicekomponenten.
4+
5+
## Voraussetzungen
6+
7+
Bevor Sie beginnen, stellen Sie sicher, dass Ihr System die folgende Software installiert hat:
8+
9+
- Git
10+
- Go 1.24.1 oder höher
11+
- Node.js v20.18.0 oder höher
12+
- npm
13+
14+
## Überblick über die Projektarchitektur
15+
16+
Das MCP Gateway-Projekt besteht aus den folgenden Kernkomponenten:
17+
18+
1. **apiserver** - Bietet Konfigurationsmanagement, Benutzeroberfläche und andere API-Dienste
19+
2. **mcp-gateway** - Kern-Gateway-Dienst, behandelt MCP-Protokollkonvertierung
20+
3. **mock-user-svc** - Simuliert Benutzerdienst für Entwicklungstests
21+
4. **web** - Management-Interface-Frontend
22+
23+
## Starten der Entwicklungsumgebung
24+
25+
### 1. Projekt klonen
26+
27+
Besuchen Sie das [MCP Gateway-Code-Repository](https://github.com/mcp-ecosystem/mcp-gateway), klicken Sie auf den `Fork`-Button, um das Projekt in Ihr GitHub-Konto zu forken.
28+
29+
### 2. Lokal klonen
30+
31+
Klonen Sie Ihr geforktes Repository lokal:
32+
33+
```bash
34+
git clone https://github.com/ihr-github-benutzername/mcp-gateway.git
35+
```
36+
37+
### 3. Umgebungsabhängigkeiten initialisieren
38+
39+
Wechseln Sie in das Projektverzeichnis:
40+
```bash
41+
cd mcp-gateway
42+
```
43+
44+
Installieren Sie die Abhängigkeiten:
45+
46+
```bash
47+
go mod tidy
48+
cd web
49+
npm i
50+
```
51+
52+
### 4. Entwicklungsumgebung starten
53+
54+
```bash
55+
cp .env.example .env
56+
cd web
57+
cp .env.example .env
58+
```
59+
60+
**Hinweis**: Sie können die Entwicklung mit der Standardkonfiguration ohne Änderungen starten, aber Sie können auch die Konfigurationsdateien anpassen, um Ihre Umgebungs- oder Entwicklungsanforderungen zu erfüllen, wie z.B. Wechsel von Disk, DB usw.
61+
62+
**Hinweis**: Sie benötigen möglicherweise 4 Terminalfenster, um alle Dienste auszuführen. Dieser Ansatz, mehrere Dienste auf dem Host-Rechner auszuführen, erleichtert das Neustarten und Debuggen während der Entwicklung.
63+
64+
#### 4.1 mcp-gateway starten
65+
66+
```bash
67+
go run cmd/gateway/main.go
68+
```
69+
70+
mcp-gateway wird standardmäßig unter `http://localhost:5235` gestartet und bearbeitet MCP-Protokollanfragen.
71+
72+
#### 4.2 apiserver starten
73+
74+
```bash
75+
go run cmd/apiserver/main.go
76+
```
77+
78+
apiserver wird standardmäßig unter `http://localhost:5234` gestartet.
79+
80+
#### 4.3 mock-user-svc starten
81+
82+
```bash
83+
go run cmd/mock-user-svc/main.go
84+
```
85+
86+
mock-user-svc wird standardmäßig unter `http://localhost:5235` gestartet.
87+
88+
#### 4.4 Web-Frontend starten
89+
90+
```bash
91+
npm run dev
92+
```
93+
94+
Das Web-Frontend wird standardmäßig unter `http://localhost:5236` gestartet.
95+
96+
Sie können jetzt auf die Verwaltungsoberfläche in Ihrem Browser unter http://localhost:5236 zugreifen. Der Standardbenutzername und das Standardpasswort werden durch Ihre Umgebungsvariablen (in der .env-Datei im Stammverzeichnis) bestimmt, insbesondere `SUPER_ADMIN_USERNAME` und `SUPER_ADMIN_PASSWORD`. Nach der Anmeldung können Sie den Benutzernamen und das Passwort in der Verwaltungsoberfläche ändern.
97+
98+
## Häufige Probleme
99+
100+
### Umgebungsvariablen-Einstellungen
101+
102+
Einige Dienste benötigen möglicherweise spezifische Umgebungsvariablen, um ordnungsgemäß zu funktionieren. Sie können eine `.env`-Datei erstellen oder diese Variablen vor dem Start des Befehls festlegen:
103+
104+
```bash
105+
# Beispiel
106+
export OPENAI_API_KEY="ihr_api_schlüssel"
107+
export OPENAI_MODEL="gpt-4o-mini"
108+
export APISERVER_JWT_SECRET_KEY="ihr_geheimer_schlüssel"
109+
```
110+
111+
## Nächste Schritte
112+
113+
Nach dem erfolgreichen Start der lokalen Entwicklungsumgebung können Sie:
114+
115+
- Die [Architekturdokumentation](./architecture.md) überprüfen, um die Systemkomponenten im Detail zu verstehen
116+
- Den [Konfigurationsleitfaden](/docs/configuration/) lesen, um zu erfahren, wie Sie das Gateway konfigurieren
117+
- Die [Client-Nutzungsdokumentation](/docs/client-usage/) ansehen, um zu verstehen, wie Sie mit dem Gateway interagieren
Lines changed: 117 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,117 @@
1+
# Local Development Environment Setup Guide
2+
3+
This document describes how to set up and start a complete MCP Gateway development environment locally, including all necessary service components.
4+
5+
## Prerequisites
6+
7+
Before starting, make sure your system has the following software installed:
8+
9+
- Git
10+
- Go 1.24.1 or higher
11+
- Node.js v20.18.0 or higher
12+
- npm
13+
14+
## Project Architecture Overview
15+
16+
The MCP Gateway project consists of the following core components:
17+
18+
1. **apiserver** - Provides configuration management, user interface, and other API services
19+
2. **mcp-gateway** - Core gateway service, handles MCP protocol conversion
20+
3. **mock-user-svc** - Simulates user service for development testing
21+
4. **web** - Management interface frontend
22+
23+
## Starting the Development Environment
24+
25+
### 1. Clone the Project
26+
27+
Visit the [MCP Gateway code repository](https://github.com/mcp-ecosystem/mcp-gateway), click the `Fork` button to fork the project to your GitHub account.
28+
29+
### 2. Clone to Local
30+
31+
Clone your forked repository locally:
32+
33+
```bash
34+
git clone https://github.com/your-github-username/mcp-gateway.git
35+
```
36+
37+
### 3. Initialize Environment Dependencies
38+
39+
Enter the project directory:
40+
```bash
41+
cd mcp-gateway
42+
```
43+
44+
Install dependencies:
45+
46+
```bash
47+
go mod tidy
48+
cd web
49+
npm i
50+
```
51+
52+
### 4. Start the Development Environment
53+
54+
```bash
55+
cp .env.example .env
56+
cd web
57+
cp .env.example .env
58+
```
59+
60+
**Note**: You can start development with the default configuration without modifying anything, but you can also modify the configuration files to meet your environment or development needs, such as switching Disk, DB, etc.
61+
62+
**Note**: You may need 4 terminal windows to run all services. This approach of running multiple services on the host machine makes it easy to restart and debug during development.
63+
64+
#### 4.1 Start mcp-gateway
65+
66+
```bash
67+
go run cmd/gateway/main.go
68+
```
69+
70+
mcp-gateway will start on `http://localhost:5235` by default, handling MCP protocol requests.
71+
72+
#### 4.2 Start apiserver
73+
74+
```bash
75+
go run cmd/apiserver/main.go
76+
```
77+
78+
apiserver will start on `http://localhost:5234` by default.
79+
80+
#### 4.3 Start mock-user-svc
81+
82+
```bash
83+
go run cmd/mock-user-svc/main.go
84+
```
85+
86+
mock-user-svc will start on `http://localhost:5235` by default.
87+
88+
#### 4.4 Start web frontend
89+
90+
```bash
91+
npm run dev
92+
```
93+
94+
The web frontend will start on `http://localhost:5236` by default.
95+
96+
You can now access the management interface in your browser at http://localhost:5236. The default username and password are determined by your environment variables (in the root directory's .env file), specifically `SUPER_ADMIN_USERNAME` and `SUPER_ADMIN_PASSWORD`. After logging in, you can change the username and password in the management interface.
97+
98+
## Common Issues
99+
100+
### Environment Variable Settings
101+
102+
Some services may require specific environment variables to work properly. You can create a `.env` file or set these variables before starting the command:
103+
104+
```bash
105+
# Example
106+
export OPENAI_API_KEY="your_api_key"
107+
export OPENAI_MODEL="gpt-4o-mini"
108+
export APISERVER_JWT_SECRET_KEY="your_secret_key"
109+
```
110+
111+
## Next Steps
112+
113+
After successfully starting the local development environment, you can:
114+
115+
- Check the [Architecture Documentation](./architecture.md) to understand system components in depth
116+
- Read the [Configuration Guide](/docs/configuration/) to learn how to configure the gateway
117+
- View the [Client Usage Documentation](/docs/client-usage/) to understand how to interact with the gateway

0 commit comments

Comments
 (0)