Шлюз MCP

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

Лицензия

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

Related MCP server: Maya MCP

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

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

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

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

2. Агрегация и оркестровка возможностей: объединяет инструменты 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_server.py ) : выполняет команды Bash в средах Linux, macOS или WSL.

• Средство выполнения команд CMD Windows ( cmd_server.py ) : выполняет команды CMD в средах Windows.

• Средство выполнения команд Windows PowerShell ( powershell_server.py ) : выполняет команды PowerShell в средах Windows.

• Инструмент запросов Windows WMI ( wmi_server.py ) : выполняет запросы 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 для управления окружением и зависимостями.

1. Клонировать репозиторий

   git clone https://github.com/trtyr/MCP-Gateway.git
   cd MCP-Gateway

2. Создать и активировать виртуальную среду

   # Create virtual environment
   uv venv
   
   # Activate virtual environment
   # Linux/macOS
   source .venv/bin/activate
   # Windows (Command Prompt/PowerShell)
   .venv\Scripts\activate

3. Установить зависимости

   # 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):

1. Выберите тип подключения SSE .

2. Введите URL-адрес SSE шлюза (например, http://127.0.0.1:9000/sse ).

3. Нажмите 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 .

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

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

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

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

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

1. Понять метод запуска : Playwright MCP обычно запускается с помощью npx @playwright/mcp@latest . Это пакет Node.js, выполняемый через npx .

2. Настройте config.json :

   {
     // ... other server configurations ...
     "playwright": {
       "type": "stdio",
       "command": "npx",
       "args": ["@playwright/mcp@latest"]
     }
     // ... other server configurations ...
   }

   Здесь command — npx , а args содержит имя и версию пакета Playwright MCP.

3. Перезапустите шлюз : сохраните config.json и перезапустите шлюз MCP.

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

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

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

1. Получить исполняемый файл : Загрузите исполняемый файл ENScan_GO (например, enscan-v1.2.1-windows-amd64.exe ) и поместите его в доступное место (например, в каталог servers/ или в системную переменную PATH).

2. Настройте config.json :

   {
     // ... 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.

3. Перезапустите шлюз : сохраните config.json и перезапустите шлюз MCP.

Сначала шлюз запустит процесс ENScan_GO, затем подключится к http://127.0.0.1:8080/sse . После запуска вы должны увидеть инструменты с именем enscan/... .