Шлюз MCP

Английский |简体中文

Лицензия

Данный проект лицензирован в соответствии с лицензией GNU General Public License v3.0 — более подробную информацию см. в файле LICENSE .

Обзор проекта

MCP Gateway — это приложение, созданное с помощью Python. Он действует как центральный шлюз , который подключается к нескольким внутренним серверам MCP и объединяет их возможности (независимо от того, взаимодействуют ли они через протоколы Stdio или SSE). В конечном итоге он предоставляет эти объединенные возможности клиентам MCP вышестоящего уровня через унифицированную конечную точку SSE ( /sse ).

Основные преимущества:

Упрощенная настройка клиента: клиентам MCP достаточно подключиться к одному адресу шлюза MCP, чтобы получить доступ к функциям всех внутренних служб, что устраняет необходимость в индивидуальной настройке каждого внутреннего сервера.
Агрегация и оркестровка возможностей: объединяет инструменты MCP с разнообразными возможностями из разных источников, обеспечивая основу для создания более мощных, настраиваемых агентов, ориентированных на конкретные области задач.

Структура файла проекта

. ├── config.json # Core configuration file: Defines the backend MCP servers to connect to and manage. ├── main.py # Program entry point: Parses command-line arguments, sets up logging, and starts the web server. ├── bridge_app.py # Starlette application core: Handles forwarding of MCP requests and SSE connection management. ├── client_manager.py # Client manager: Responsible for establishing and maintaining connection sessions with backend MCP servers. ├── capability_registry.py # Capability registry: Dynamically discovers, registers, and manages capabilities provided by all backend MCP servers. ├── config_loader.py # Configuration loader: Responsible for loading and strictly validating the format and content of the `config.json` file. ├── errors.py # Custom exceptions: Defines project-specific error types, such as configuration errors and backend server errors. ├── rich_handler.py # Rich logging handler: Provides beautified, structured console log output. ├── servers/ # Contains built-in/example backend MCP server scripts. │ ├── bash_server.py # <-- Built-in Bash command execution tool (Linux/macOS/WSL) │ ├── cmd_server.py # <-- Built-in Windows CMD command execution tool (Windows Only) │ ├── powershell_server.py # <-- Built-in Windows PowerShell command execution tool (Windows Only) │ └── wmi_server.py # <-- Built-in Windows WMI query tool (Windows Only) └── logs/ # Log directory: Stores runtime log files (created automatically).

Встроенные MCP-серверы

Этот проект поставляется с четырьмя внутренними инструментами MCP Server, которые можно использовать напрямую и включать в config.json без дополнительной настройки:

Инструмент выполнения команд Bash ( : выполняет команды Bash в средах Linux, macOS или WSL.
Средство выполнения команд CMD Windows ( : выполняет команды CMD в средах Windows.
Средство выполнения команд Windows PowerShell ( : выполняет команды PowerShell в средах Windows.
Инструмент запросов Windows WMI ( : выполняет запросы WMI в средах Windows.

Если вы столкнулись со следующей ошибкой в среде Linux:
error: Distribution `pywin32==310 @ registry+https://pypi.org/simple` can't be installed because it doesn't have a source distribution or wheel for the current platform>
Пожалуйста, удалите модуль wmi : uv remove wmi

Установка и настройка

Этот проект написан на Python. Рекомендуется использовать uv для управления окружением и зависимостями.

Клонировать репозиторий
git clone https://github.com/trtyr/MCP-Gateway.git cd MCP-Gateway
Создать и активировать виртуальную среду
# Create virtual environment uv venv # Activate virtual environment # Linux/macOS source .venv/bin/activate # Windows (Command Prompt/PowerShell) .venv\Scripts\activate
Установить зависимости
# Install all required dependencies based on pyproject.toml uv sync

После выполнения этих шагов проект готов к запуску.

Быстрый старт

Получить помощь по проекту

Для просмотра всех доступных параметров запуска можно использовать аргумент -h или --help :

# Windows uv run python .\main.py -h # Linux/macOS uv run python ./main.py -h

Вывод будет примерно таким:

usage: main.py [-h] [--host HOST] [--port PORT] [--log-level {debug,info,warning,error,critical}] Start MCP_Bridge_Server v3.0.0 options: -h, --help show this help message and exit --host HOST Host address (default: 0.0.0.0) --port PORT Port (default: 9000) --log-level {debug,info,warning,error,critical} Set file logging level (default: info)

Начать проект

Используйте uv run python main.py для запуска сервера. Вы можете указать host , port и log-level :

# Listen on all network interfaces on port 9000, set log level to debug uv run python .\main.py --host 0.0.0.0 --port 9000 --log-level debug

После запуска вы увидите богатый, улучшенный вывод консоли, подобный изображению ниже, показывающий состояние сервера, информацию о подключении и загруженные инструменты:

Подключение клиента MCP

После запуска MCP Gateway вы можете использовать любой MCP-совместимый клиент (например, Cline, Cursor, Claude Desktop или пользовательский клиент) для подключения к конечной точке SSE, предоставляемой Gateway.

Адрес по умолчанию: http://<Server_IP_Address>:9000/sse (если используется порт по умолчанию).

Пример (с использованием ChatWise Connect):

Выберите тип подключения SSE .
Введите URL-адрес SSE шлюза (например, http://127.0.0.1:9000/sse ).
Нажмите Connect .

После успешного подключения вы увидите все внутренние инструменты MCP, агрегированные через шлюз в клиенте:

Журналы

Журналы времени выполнения автоматически сохраняются в папке logs в корневом каталоге проекта. Имена файлов журналов включают временные метки и уровни журналов, что упрощает отслеживание проблем.

logs/ ├── log_20240801_103000_INFO.log └── log_20240801_110000_DEBUG.log ...

Файл конфигурации ( `config.json` )

Основной файл конфигурации config.json находится в корневом каталоге проекта. Он определяет внутренние серверы MCP, к которым MCP Gateway должен подключаться и управлять ими.

Каждая запись представляет собой внутренний сервер. Ключ — это уникальное имя, которое вы назначаете этому внутреннему серверу (это имя будет использоваться в качестве префикса для его возможностей), а значение — это объект, содержащий конфигурацию сервера.

Поддерживаются два типа подключений к внутреннему серверу:

stdio : взаимодействует с локально запущенным процессом сервера MCP через стандартный ввод/вывод (stdin/stdout).
sse : взаимодействует с удаленным или локально работающим сервером MCP через протокол Server-Sent Events (SSE).

Конфигурация типа stdio

Подходит для локальных процессов сервера MCP, жизненный цикл которых должен управляться шлюзом.

Поля конфигурации:

type (обязательно): должен быть "stdio" .
command (обязательно): исполняемая команда, используемая для запуска процесса сервера (например, python , uv , node или абсолютный путь к скрипту/исполняемому файлу).
args (обязательно): список аргументов (список строк), передаваемых command .
env (необязательно): Словарь переменных окружения (Dict[str, str]) для установки дочернего процесса. Если не указано, дочерний процесс наследует окружение Gateway.

Пример:

{ "powershell": { "type": "stdio", "command": "python", "args": ["servers/powershell_server.py"] }, "my_custom_tool": { "type": "stdio", "command": "/path/to/my/custom_mcp_server", "args": ["--port", "ignored_for_stdio", "--some-flag"], "env": { "API_KEY": "your_secret_key" } } }

Как это работает: Когда запускается MCP Gateway, он использует указанную command и args (вместе с необязательным env ) для запуска дочернего процесса. Gateway взаимодействует с внутренним сервером MCP через стандартный ввод и вывод этого дочернего процесса. Когда Gateway завершает работу, он пытается завершить эти дочерние процессы.

Конфигурация типа SSE

Подходит для подключения к уже работающим серверам MCP (локальным или удаленным) или в случаях, когда шлюзу необходимо запустить локальный процесс сервера SSE перед подключением.

Поля конфигурации:

type (обязательно): должен быть "sse" .
url (обязательно): URL-адрес конечной точки SSE внутреннего сервера MCP (полный адрес HTTP/HTTPS).
command (необязательно): если указано, шлюз выполнит эту команду при запуске для запуска локального сервера SSE.
args (необязательно, только если указана command ): список аргументов, передаваемых command .
env (необязательно, только если указана command ): переменные среды, которые следует задать для локально запущенного дочернего процесса.

Пример 1: Подключение к уже работающему удаленному серверу SSE

{ "remote_search_service": { "type": "sse", "url": "https://mcp.example.com/search/sse" } }

Пример 2: Шлюз запускает локальный сервер SSE и подключается

{ "local_sse_server": { "type": "sse", "url": "http://127.0.0.1:8080/sse", "command": "uv", "args": ["run", "python", "servers/my_local_sse_app.py", "--port", "8080"], "env": { "MODE": "production" } } }

Как это работает:

Указан только : шлюз напрямую пытается подключиться к указанному url .
url : Сначала шлюз использует command и args для запуска локального процесса (ожидая, что этот процесс будет прослушивать адрес и порт, соответствующие url ). Затем он ждет в течение короткого периода ( LOCAL_SSE_STARTUP_DELAY , определенный в client_manager.py ) перед попыткой подключения к url . Когда шлюз завершает работу, он пытается завершить этот локальный процесс.

Примеры добавления конфигурации

Ниже приведены примеры того, как добавить сторонние MCP-серверы в config.json .

Пример Stdio: Драматург MCP

Предположим, вы хотите интегрировать MCP-сервер Playwright ( @playwright/mcp ).

Понять метод запуска : Playwright MCP обычно запускается с помощью npx @playwright/mcp@latest . Это пакет Node.js, выполняемый через npx .
Настройте :
{ // ... other server configurations ... "playwright": { "type": "stdio", "command": "npx", "args": ["@playwright/mcp@latest"] } // ... other server configurations ... }
Здесь command — npx , а args содержит имя и версию пакета Playwright MCP.
Перезапустите шлюз : сохраните config.json и перезапустите шлюз MCP.

После запуска вы должны увидеть инструменты с именем playwright/... (например, playwright/browse ) в журналах консоли и вашего клиента.

Пример SSE: ENScan_GO (локальный запуск)

Предположим, вы хотите интегрировать ENScan_GO, программу Go, которую можно запустить с помощью ./enscan --mcp и которая предоставляет службу SSE по адресу http://localhost:8080 .

Получить исполняемый файл : Загрузите исполняемый файл ENScan_GO (например, enscan-v1.2.1-windows-amd64.exe ) и поместите его в доступное место (например, в каталог servers/ или в системную переменную PATH).
Настройте :
{ // ... other server configurations ... "enscan": { "type": "sse", "url": "http://127.0.0.1:8080/sse", // Address ENScan_GO listens on // Note: Ensure path separators are correct on Windows, or use an absolute path "command": "servers/enscan-v1.2.1-windows-amd64.exe", // Path to the executable "args": ["--mcp"] // Startup arguments } // ... other server configurations ... }
Здесь мы указываем type как sse , предоставляем url который он прослушивает, и используем command и args чтобы сообщить шлюзу, как запустить этот локальный сервер SSE.
Перезапустите шлюз : сохраните config.json и перезапустите шлюз MCP.