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) # MCP-NG: Сервер на Go для Model Context Protocol MCP-NG — это высокопроизводительная, модульная реализация сервера для **Model Context Protocol (MCP)** от Anthropic. Написанный полностью на Go, этот проект предоставляет надежный и универсальный фреймворк для оркестрации интеллектуальных агентов, предоставляя доступ к разнообразному набору инструментов через единый gRPC API. Ключевая философия этого проекта — создание языконезависимой экосистемы на основе микросервисов. Это позволяет бесшовно интегрировать инструменты, написанные на любом языке — от утилит общего назначения на Go до специализированных инструментов машинного обучения на Python. ## Ключевые особенности * **Высокопроизводительное ядро на Go:** Главный сервер создан на Go, что обеспечивает превосходную производительность, параллелизм и надежность при оркестрации нескольких серверов-инструментов. * **Двойной API: gRPC и HTTP/REST:** Сервер предоставляет свои сервисы как через высокопроизводительный gRPC (порт по умолчанию 8090), так и через стандартный HTTP/REST API (порт по умолчанию 8002) с использованием gRPC-Gateway. Это обеспечивает максимальную гибкость для любого клиента, от системных интеграций до простых веб-скриптов. * **Универсальное взаимодействие на основе gRPC:** Внутренняя коммуникация использует gRPC, что гарантирует языконезависимый, строго типизированный и эффективный протокол для всех взаимодействий с инструментами. * **Микросервисная архитектура:** Каждый инструмент является независимым микросервисом, что позволяет осуществлять независимую разработку, развертывание и масштабирование. * **Продвинутая интеграция с ML-инструментами:** Платформа спроектирована для бесшовной интеграции с ресурсоемкими инструментами машинного обучения (например, для суммаризации текста, семантического поиска), рассматривая их как первоклассные компоненты в наборе инструментов агента. * **Автоматическое обнаружение инструментов и мониторинг состояния:** Сервер автоматически обнаруживает и запускает зарегистрированные инструменты, постоянно отслеживает их состояние с помощью gRPC health checks и гарантирует, что агентам доступны только работоспособные инструменты. ## Архитектура Я спроектировал MCP-NG с упором на модульность и масштабируемость. Ядром системы является **Главный MCP Сервер**, который действует как центральный узел для различных серверов инструментов. Клиентские приложения, такие как чат-боты или другие автономные агенты, взаимодействуют с Главным MCP Сервером для доступа к доступным инструментам через gRPC или HTTP/REST. ```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 ``` ### Ключевые компоненты * **Главный MCP Сервер:** Центральный компонент, который обнаруживает, запускает и направляет запросы от клиентов к соответствующим серверам инструментов. Он также отслеживает состояние каждого инструмента. * **Серверы инструментов:** Автономные gRPC-серверы, каждый из которых предоставляет определенную функциональность (например, `calculator`, `web_search`). Они могут быть написаны на любом языке, хотя текущая реализация включает инструменты на Go и Python. * **Human Bridge:** WebSocket-сервер, который обеспечивает асинхронное взаимодействие с оператором-человеком и используется инструментом `human_input`. * **gRPC Контракт:** API определен в `proto/mcp.proto`, который служит единым источником истины для всех сервисов. ### Проверки состояния (Health Checks) Для обеспечения надежности системы я реализовал комплексный механизм проверки состояния. Главный MCP Сервер отвечает за мониторинг статуса всех зарегистрированных инструментов. * **Протокол:** Система использует стандартный [протокол проверки состояния gRPC](https://github.com/grpc/grpc/blob/master/doc/health-checking.md). * **Реализация:** Каждый инструмент, будь то на Go или Python, предоставляет конечную точку для проверки состояния по gRPC. * **Мониторинг:** Главный MCP Сервер выполняет начальную проверку состояния при обнаружении инструмента и продолжает периодически его отслеживать. Инструменты, которые не находятся в состоянии "SERVING", не включаются в список доступных инструментов, возвращаемый клиентам, что предотвращает маршрутизацию запросов к неработоспособным сервисам. ## Структура папок Проект организован в следующих каталогах: ``` . ├── 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 # Этот файл ``` ## Начало работы Для начала работы с MCP-NG вам потребуется установить Go, Python и Protocol Buffers. ### 1. Клонируйте репозиторий ```bash git clone https://github.com/Lotargo/MCP-NG.git cd MCP-NG ``` ### 2. Установите зависимости **Go:** ```bash go mod tidy ``` **Python:** ```bash pip install -r requirements.txt ``` ### 3. Запустите сервер Главный сервер автоматически запустит все инструменты. **Примечание о R&D модулях:** По умолчанию сервер не запускает ресурсоемкие ML-инструменты на Python (`hybrid_search`, `keyword_extractor`, `text_summarizer`, `text_generator`, `code_interpreter`). Я обозначил их как модули **R&D (Исследования и Разработка)**, чтобы обеспечить быстрый и стабильный запуск основной системы. Их поведение можно изменить в исходном коде сервера. ```bash cd MCP-NG/server/cmd/server go run main.go ``` ### 4. Конфигурация У каждого инструмента есть свой файл `config.json` для конфигурации. Этот файл включает порт, команду для запуска инструмента и любые другие необходимые параметры (например, API-ключи). При развертывании инструмента в новой среде или на другом MCP-сервере вам потребуется обновить его конфигурационный файл. Пожалуйста, обратитесь к подробной документации для каждого инструмента в каталоге `docs_ru/tools` для получения конкретных инструкций по настройке. ## Рабочий процесс ReAct MCP-NG предназначен для работы с большими языковыми моделями (LLM) с использованием паттерна ReAct (Reason and Act). Это позволяет LLM интеллектуально выбирать и использовать доступные инструменты для выполнения поставленной задачи. ```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).