MCP-NG

<div align="center"> <img src="https://github.com/Lotargo/MCP-NG/blob/main/docs/logo/logo.png?raw=true" alt="MCP-NG Logo" width="350"/> <h1>MCP-NG</h1> <p>A Go-Powered Universal Server for the Model Context Protocol (MCP)</p> <p> <img src="https://img.shields.io/badge/Project%20Status-Active-brightgreen" alt="Project Status: Active"/> <img src="https://img.shields.io/badge/License-Apache_2.0-blue.svg" alt="License: Apache 2.0"/> <img src="https://img.shields.io/badge/Go-1.24+-00ADD8.svg?logo=go&logoColor=white" alt="Go Version"/> <img src="https://img.shields.io/badge/Python-3.11+-3776AB.svg?logo=python&logoColor=white" alt="Python Version"/> <img src="https://img.shields.io/badge/gRPC-v1.64-00D4B1.svg?logo=grpc&logoColor=white" alt="gRPC"/> </p> </div> [Read in English](README.md) <h1>MCP-NG: Сервер на Go для Model Context Protocol</h1> <p>MCP-NG — это высокопроизводительная, модульная реализация сервера для Model Context Protocol (MCP) от Anthropic. Написанный полностью на Go, этот проект предоставляет надежный и универсальный фреймворк для оркестрации интеллектуальных агентов, предоставляя доступ к разнообразному набору инструментов через единый gRPC API.</p> <p>Ключевая философия этого проекта — создание языконезависимой экосистемы на основе микросервисов. Это позволяет бесшовно интегрировать инструменты, написанные на любом языке — от утилит общего назначения на Go до специализированных инструментов машинного обучения на Python.</p> <h2>Ключевые особенности</h2> <ul> <li><strong>Высокопроизводительное ядро на Go:</strong> Главный сервер создан на Go, что обеспечивает превосходную производительность, параллелизм и надежность при оркестрации нескольких серверов-инструментов.</li> <li><strong>Двойной API: gRPC и HTTP/REST:</strong> Сервер предоставляет свои сервисы как через высокопроизводительный gRPC (порт по умолчанию 8090), так и через стандартный HTTP/REST API (порт по умолчанию 8002) с использованием gRPC-Gateway. Это обеспечивает максимальную гибкость для любого клиента, от системных интеграций до простых веб-скриптов.</li> <li><strong>Универсальное взаимодействие на основе gRPC:</strong> Внутренняя коммуникация использует gRPC, что гарантирует языконезависимый, строго типизированный и эффективный протокол для всех взаимодействий с инструментами.</li> <li><strong>Микросервисная архитектура:</strong> Каждый инструмент является независимым микросервисом, что позволяет осуществлять независимую разработку, развертывание и масштабирование.</li> <li><strong>Продвинутая интеграция с ML-инструментами:</strong> Платформа спроектирована для бесшовной интеграции с ресурсоемкими инструментами машинного обучения (например, для суммаризации текста, семантического поиска), рассматривая их как первоклассные компоненты в наборе инструментов агента.</li> <li><strong>Автоматическое обнаружение инструментов и мониторинг состояния:</strong> Сервер автоматически обнаруживает и запускает зарегистрированные инструменты, постоянно отслеживает их состояние с помощью gRPC health checks и гарантирует, что агентам доступны только работоспособные инструменты.</li> </ul> <h2>Архитектура</h2> <p>Я спроектировал MCP-NG с упором на модульность и масштабируемость. Ядром системы является Главный MCP Сервер, который действует как центральный узел для различных серверов инструментов. Клиентские приложения, такие как чат-боты или другие автономные агенты, взаимодействуют с Главным MCP Сервером для доступа к доступным инструментам через gRPC или HTTP/REST.</p> ```mermaid graph TD subgraph "Клиентские приложения" A[gRPC Клиент] H[HTTP/REST Клиент] end A -->|gRPC Запрос на порт 8090| B(Главный MCP Сервер); H -->|HTTP/REST Запрос на порт 8002| B; B -->|gRPC Прокси| C{Инструмент 1 Go}; B -->|gRPC Прокси| D{Инструмент 2 Go}; B -->|gRPC Прокси| E{Инструмент 3 Python}; B -->|gRPC Прокси| F[Human Bridge]; subgraph "Серверы инструментов" C D E F end style B fill:#ffa500,stroke:#333,stroke-width:2px,color:#000 ``` <h3>Ключевые компоненты</h3> <ul> <li><strong>Главный MCP Сервер:</strong> Центральный компонент, который обнаруживает, запускает и направляет запросы от клиентов к соответствующим серверам инструментов. Он также отслеживает состояние каждого инструмента.</li> <li><strong>Серверы инструментов:</strong> Автономные gRPC-серверы, каждый из которых предоставляет определенную функциональность (например, <code>calculator</code>, <code>web_search</code>). Они могут быть написаны на любом языке, хотя текущая реализация включает инструменты на Go и Python.</li> <li><strong>Human Bridge:</strong> WebSocket-сервер, который обеспечивает асинхронное взаимодействие с оператором-человеком и используется инструментом <code>human_input</code>.</li> <li><strong>gRPC Контракт:</strong> API определен в <code>proto/mcp.proto</code>, который служит единым источником истины для всех сервисов.</li> </ul> <h3>Проверки состояния (Health Checks)</h3> <p>Для обеспечения надежности системы я реализовал комплексный механизм проверки состояния. Главный MCP Сервер отвечает за мониторинг статуса всех зарегистрированных инструментов.</p> <ul> <li><strong>Протокол:</strong> Система использует стандартный протокол проверки состояния gRPC.</li> <li><strong>Реализация:</strong> Каждый инструмент, будь то на Go или Python, предоставляет конечную точку для проверки состояния по gRPC.</li> <li><strong>Мониторинг:</strong> Главный MCP Сервер выполняет начальную проверку состояния при обнаружении инструмента и продолжает периодически его отслеживать. Инструменты, которые не находятся в состоянии "SERVING", не включаются в список доступных инструментов, возвращаемый клиентам, что предотвращает маршрутизацию запросов к неработоспособным сервисам.</li> </ul> <h2>Структура папок</h2> <p>Проект организован в следующих каталогах:</p> <pre><code> . ├── MCP-NG/ │ ├── human_bridge/ # WebSocket-сервер для взаимодействия с человеком │ ├── integration_tests/ # Интеграционные тесты для инструментов │ ├── proto/ # Определения protocol buffer для gRPC │ ├── server/ # Реализация главного MCP сервера │ └── tools/ # Исходный код для отдельных инструментов │ ├── go/ # Инструменты на Go │ └── python/ # Инструменты на Python ├── docs/ # Документация на английском │ └── tools/ # Подробная документация для каждого инструмента ├── docs_ru/ # Документация на русском │ └── tools/ # Подробная документация для каждого инструмента на русском ├── README.md # Файл README на английском └── README_ru.md # Этот файл </code></pre> <h2>Начало работы</h2> <p>Проект MCP-NG поддерживает запуск в трех основных средах: через Docker, нативно в Windows и нативно в Linux/WSL. Рекомендуемым и самым простым способом является использование Docker.</p> <h3>1. Запуск с помощью Docker (Рекомендуемый способ)</h3> <p>Благодаря Docker, вы можете собрать и запустить всю экосистему MCP-NG, включая главный сервер и все инструменты, одной командой. Этот способ гарантирует идентичность окружения разработки и развертывания.</p> <ol> <li><strong>Убедитесь, что Docker и Docker Compose установлены и запущены.</strong></li> <li>Из корневого каталога проекта выполните следующую команду:</li> </ol> <pre><code>docker-compose up --build -d</code></pre> <p>Эта команда соберет многоступенчатый Docker-образ, который скомпилирует все бинарные файлы Go, установит все зависимости Python и запустит контейнер в фоновом режиме. Сервер будет доступен по адресам <code>grpc://localhost:8090</code> и <code>http://localhost:8002</code>.</p> <p>Чтобы остановить сервисы, выполните <code>docker-compose down</code>.</p> <h3>2. Ручная настройка в Windows (Native)</h3> <p>Этот гайд предназначен для запуска проекта напрямую в Windows без использования WSL. Этот способ обеспечивает максимальную производительность для локальной разработки.</p> <h4>a. Установка необходимого ПО (выполняется один раз)</h4> <ul> <li><strong>Go:</strong> Скачайте и установите Go с официального сайта <a href="https://go.dev">go.dev</a>.</li> <li><strong>Python:</strong> Скачайте и установите Python <a href="https://python.org">python.org</a>. Во время установки обязательно поставьте галочку "Add Python to PATH".</li> <li><strong>Git for Windows:</strong> Установите Git <a href="https://git-scm.com">git-scm.com</a>.</li> <li><strong>MinGW (C/C++ компилятор):</strong> Необходим для некоторых Go-пакетов (например, <code>go-sqlite3</code>). <ul> <li>Установите MSYS2 с <a href="https://msys2.org">msys2.org</a>.</li> <li>Запустите терминал MSYS2 MINGW64 и выполните <code>pacman -Syu</code>, а затем <code>pacman -S --needed base-devel mingw-w64-ucrt-x86_64-toolchain</code>.</li> <li>Добавьте путь <code>C:\msys64\ucrt64\bin</code> в системную переменную PATH.</li> </ul> </li> </ul> <h4>b. Клонирование репозитория</h4> <pre><code>git clone https://github.com/Lotargo/MCP-NG.git cd MCP-NG</code></pre> <h4>c. Автоматическая настройка среды</h4> <p>Этот шаг автоматизирован с помощью специального скрипта PowerShell. Он создаст виртуальное окружение, установит все зависимости, скомпилирует все Go-приложения (включая главный сервер) в папку <code>bin</code> и автоматически настроит правила Брандмауэра Windows.</p> <ol> <li>Откройте терминал PowerShell **от имени Администратора**.</li> <li>Перейдите в корневую папку проекта.</li> <li>Создайте виртуальное окружение (выполняется один раз):</li> </ol> <pre><code>python -m venv .venv</code></pre> <ol start="4"> <li>Запустите скрипт автоматической настройки:</li> </ol> <pre><code>PowerShell -ExecutionPolicy Bypass -File .\install_deps.ps1</code></pre> <p>Этот скрипт подготовит всё необходимое для запуска. Выполняйте его повторно после скачивания обновлений из Git, которые изменяют зависимости или добавляют новые инструменты.</p> <h4>d. Запуск сервера</h4> <p>После завершения работы скрипта <code>install_deps.ps1</code> ваш проект готов к запуску.</p> <ol> <li>Откройте **новый, обычный** терминал PowerShell (не от администратора).</li> <li>Перейдите в корневую папку проекта.</li> <li>Выполните команду для запуска скомпилированного сервера:</li> </ol> <pre><code>.\bin\server.exe</code></pre> <p>Сервер запустится и автоматически поднимет все скомпилированные микросервисы.</p> <h3>3. Ручная настройка в Linux / WSL</h3> <p>Процесс аналогичен настройке в Windows и следует принципу "сначала собери, потом запусти".</p> <h4>a. Установка необходимого ПО</h4> <p>Установите Go, Python 3.11+, Git, и GCC (например, через <code>sudo apt install build-essential</code>).</p> <h4>b. Клонирование и настройка зависимостей</h4> <pre><code>git clone https://github.com/Lotargo/MCP-NG.git cd MCP-NG python3 -m venv .venv source .venv/bin/activate pip install -r requirements_for_linux.txt</code></pre> <h4>c. Сборка проекта</h4> <p>Скомпилируйте главный сервер и все Go-инструменты в папку <code>bin</code>.</p> <pre><code>mkdir bin go build -o ./bin/server ./MCP-NG/server/cmd/server # Повторите для каждого Go-инструмента go build -o ./bin/api_caller ./MCP-NG/tools/go/api_caller # ... и так далее </code></pre> <h4>d. Запуск сервера</h4> <p>Запустите скомпилированный бинарный файл.</p> <pre><code>./bin/server</code></pre> <h3>Примечание о R&amp;D модулях</h3> <p>По умолчанию сервер не запускает ресурсоемкие ML-инструменты на Python (<code>hybrid_search</code> и другие). Я обозначил их как модули <strong>R&amp;D (Исследования и Разработка)</strong>, чтобы обеспечить быстрый и стабильный запуск основной системы. Их поведение можно изменить в исходном коде сервера.</p> <h3>Конфигурация инструментов</h3> <p>У каждого инструмента есть свой файл <code>config.json</code>. После всех наших изменений, конфигурация теперь универсальна. В ней указывается только имя исполняемого файла (например, <code>"command": ["api_caller"]</code>) или скрипта (<code>"command": ["server.py"]</code>). Главный сервер сам строит правильные пути для запуска в зависимости от операционной системы.</p> <p>Пожалуйста, обратитесь к подробной <a href= "https://github.com/Lotargo/MCP-NG/tree/main/docs_ru/tools">документации</a></li> для каждого инструмента для получения конкретных инструкций по настройке.</p> <h2>Рабочий процесс ReAct</h2> <p>MCP-NG предназначен для работы с большими языковыми моделями (LLM) с использованием паттерна ReAct (Reason and Act). Это позволяет LLM интеллектуально выбирать и использовать доступные инструменты для выполнения поставленной задачи.</p> ```mermaid sequenceDiagram participant Пользователь participant LLM participant "MCP Сервер (gRPC/HTTP)" participant Инструменты Пользователь->>LLM: Промпт LLM->>"MCP Сервер (gRPC/HTTP)": ListTools() через GET /v1/tools "MCP Сервер (gRPC/HTTP)"-->>LLM: Список доступных инструментов LLM->>LLM: Рассуждение, какой инструмент использовать LLM->>"MCP Сервер (gRPC/HTTP)": RunTool(имя_инструмента, аргументы) через POST /v1/tools:run "MCP Сервер (gRPC/HTTP)"->>Инструменты: Выполнить инструмент через gRPC Инструменты-->>"MCP Сервер (gRPC/HTTP)": Вывод инструмента "MCP Сервер (gRPC/HTTP)"-->>LLM: Наблюдение (результат инструмента) LLM->>Пользователь: Окончательный ответ ``` Для получения дополнительной информации о том, как интегрировать MCP-NG с LLM и использовать паттерн ReAct, пожалуйста, обратитесь к [Руководству по интеграции](docs_ru/integration_guide.md).