Skip to main content
This document describes how to set up and start a complete MCP Gateway development environment locally, including starting all necessary service components.

​
Prerequisites

Before getting started, please ensure your system has the following software installed:

Git

Version control tool

Go 1.24.1+

Go programming language environment

Node.js v20.18.0+

JavaScript runtime environment (includes npm)

​
Project Architecture Overview

The MCP Gateway project consists of the following core components:
Provides API services for configuration management, user interfaces, etc.
Core gateway service that handles MCP protocol conversion
Mock user service for development testing
Management interface frontend

​
Environment Setup Steps

​
1. Get Source Code

1

Fork Project

Visit the MCP Gateway code repository, click the Fork button to fork the project to your GitHub account
2

Clone Locally

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

​
2. Install Dependencies

1

Install Go Dependencies

go mod tidy
2

Install Node.js Dependencies

cd web
npm i
cd ..

​
3. Configure Environment

1

Backend Configuration

cp .env.example .env
2

Frontend Configuration

cd web
cp .env.example .env
cd ..
You can start development without modifying anything, using the default configuration. You can also modify configuration files to meet your environment or development needs, such as switching between DB and API storage methods.

​
Start Development Services

You need 4 terminal windows to run all services. This approach of running multiple services on the host machine allows for easy restart and debugging during development.

​
Terminal 1: Start mcp-gateway

go run cmd/gateway/main.go
mcp-gateway will start by default on http://localhost:5235 for handling MCP protocol requests.

​
Terminal 2: Start apiserver

go run cmd/apiserver/main.go
apiserver will start by default on http://localhost:5234.

​
Terminal 3: Start mock-server

go run cmd/mock-server/main.go
  • mock-server will start by default on http://localhost:5236
  • mock-server-sse will start by default on http://localhost:5237

​
Terminal 4: Start web frontend

cd web
npm run dev
After running the command in the web terminal, it will display the access address.

​
Access Management Interface

After startup is complete, you can access the management interface in your browser using the address shown in the terminal.

Default Login Information

  • Username: Determined by environment variable SUPER_ADMIN_USERNAME
  • Password: Determined by environment variable SUPER_ADMIN_PASSWORD

First Login

After logging in, you can modify the username and password in the management interface

​
Common Issues

​
Environment Variable Settings

Some services may require specific environment variables to work properly. You can set these variables in the .env file: 
# Example environment variables
APISERVER_JWT_SECRET_KEY="changeme-please-generate-a-random-secret"
SUPER_ADMIN_USERNAME="admin"
SUPER_ADMIN_PASSWORD="changeme-please-use-a-secure-password"

​
Port Conflicts

If you encounter port conflicts, you can modify port configuration in environment variables: 
MCP_GATEWAY_PORT=5235
APISERVER_PORT=5234
MOCK_SERVER_PORT=5236

​
Dependency Issues

If you encounter dependency installation issues: 
go clean -modcache
go mod tidy

cd web
rm -rf node_modules package-lock.json
npm install

​
Development Workflow

​
Code Contribution Process

1

Add Upstream Repository

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

Sync Upstream Code

git pull upstream main
3

Create Feature Branch

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

Push After Development

git push origin feat/your-feature-name
5

Create Pull Request

Create a Pull Request on GitHub to merge your branch into the main repository’s main branch

​
Branch Naming Conventions

New Features

Use feat/ prefix, such as feat/add-auth-module

Bug Fixes

Use fix/ prefix, such as fix/memory-leak

​
Development Considerations

Before submitting a PR, ensure your code passes all tests
Keep your fork repository synchronized with the upstream repository to avoid code conflicts
Follow the project’s code standards and commit message format

​
Next Steps

After successfully starting the local development environment, you can:

Understand Architecture

View architecture documentation to deeply understand system components

Learn Configuration

Read configuration guide to learn how to configure the gateway
⌘I