# Руководство по интеграции
Это руководство содержит подробные инструкции по интеграции новых и существующих инструментов в сервер MCP (Master Control Program). Оно также описывает, как подключать сервер MCP к клиентским приложениям и использовать паттерны ReAct для интеллектуального использования инструментов.
## Добавление нового инструмента на сервер MCP
Интеграция нового инструмента в сервер MCP включает создание gRPC-сервиса для этого инструмента и предоставление файла конфигурации, чтобы главный сервер мог автоматически запускать и управлять им. Я спроектировал систему так, чтобы она была модульной, поэтому добавление новых инструментов — это простой процесс.
### 1. Определите gRPC-контракт инструмента
Сначала обновите gRPC-контракт в `MCP-NG/proto/mcp.proto`, чтобы включить определение вашего нового сервиса. Поддержание единого файла `.proto` служит единым источником истины для всего API.
**Пример: добавление нового инструмента `ImageProcessor`**
```protobuf
// В MCP-NG/proto/mcp.proto
// ... другие сервисы
service ImageProcessor {
rpc ProcessImage (ImageRequest) returns (ImageResponse);
}
message ImageRequest {
bytes image_data = 1;
string operation = 2; // например, "resize", "grayscale"
}
message ImageResponse {
bytes processed_image_data = 1;
}
```
После обновления файла `.proto` перегенерируйте gRPC-код для всех языков, запустив скрипт генерации проекта из корневого каталога:
```bash
./generate_protos.sh
```
Этот скрипт автоматически обрабатывает все зависимости и пути вывода, обеспечивая корректное обновление заглушек для Go и Python.
### 2. Реализуйте gRPC-сервер инструмента
Далее реализуйте gRPC-сервер для вашего нового инструмента. Вы можете сделать это на Go или Python, следуя структуре существующих инструментов.
* **Go:** Создайте новый каталог в `MCP-NG/tools/go/`.
* **Python:** Создайте новый каталог в `MCP-NG/tools/python/`.
Реализация должна включать логику gRPC-сервера и любую бизнес-логику для самого инструмента.
### 3. Реализуйте службу проверки состояния
Ваш инструмент **должен** реализовывать стандартный протокол проверки состояния gRPC. Это позволяет главному серверу MCP отслеживать его состояние и направлять трафик только к работоспособным экземплярам.
* **Go:** Используйте пакет `google.golang.org/grpc/health`.
* **Python:** Используйте пакет `grpc_health.v1`.
Вам следует зарегистрировать службу проверки состояния и установить начальный статус `SERVING`.
### 4. Создайте файл конфигурации
В корневом каталоге вашего инструмента создайте файл `config.json`. Этот файл сообщает главному серверу MCP, как запускать и подключаться к вашему инструменту.
**Пример `config.json`:**
```json
{
"port": 50080,
"command": ["go", "run", "."]
}
```
* `port`: Порт, на котором будет слушать gRPC-сервер вашего инструмента.
* `command`: Команда и аргументы для выполнения вашего инструмента. Главный сервер будет запускать эту команду из каталога вашего инструмента.
## Интеграция с клиентским приложением
Вы можете подключиться к серверу MCP-NG двумя основными способами: через простой HTTP/REST API или через высокопроизводительный нативный интерфейс gRPC. Для большинства случаев, особенно для веб-клиентов или скриптов, я рекомендую начинать с HTTP/REST API.
**Порты по умолчанию:**
* **HTTP/REST:** `http://localhost:8002`
* **gRPC:** `localhost:8090`
### Простой способ: использование HTTP/REST API
gRPC-Gateway предоставляет стандартный RESTful API, с которым вы можете взаимодействовать с помощью любого HTTP-клиента, такого как `curl` или библиотека `requests` в Python.
#### Пример 1: Получение списка доступных инструментов с помощью `curl`
Получите список всех работоспособных, доступных инструментов, сделав `GET`-запрос к конечной точке `/v1/tools`.
```bash
curl http://localhost:8002/v1/tools
```
**Пример ответа:**
```json
{
"tools": [
{
"name": "calculator",
"description": "Инструмент, который вычисляет математические выражения...",
"parameters": {
"type": "object",
"properties": {
"expression": { "type": "string", "description": "Математическое выражение..." }
},
"required": ["expression"]
}
},
{ "name": "web_search", "description": "Выполняет веб-поиск...", "..." }
]
}
```
#### Пример 2: Запуск инструмента с помощью Python `requests`
Чтобы запустить инструмент, отправьте `POST`-запрос к конечной точке `/v1/tools:run` с именем инструмента и аргументами в теле JSON-запроса.
```python
import requests
import json
# Конечная точка для запуска инструмента
url = "http://localhost:8002/v1/tools:run"
# Данные для запроса
payload = {
"name": "calculator",
"arguments": {
"expression": "(10 + 5) * 2"
}
}
# Отправка POST-запроса
response = requests.post(url, json=payload)
# Вывод результата
print(response.json())
```
**Пример ответа:**
```json
{
"result": {
"stringValue": "30"
}
}
```
### Продвинутый способ: использование нативного интерфейса gRPC
Для приложений, требующих максимальной производительности и строгой типизации, рекомендуется подключаться напрямую к gRPC-серверу. Хотя это обычно требует генерации клиентской заглушки, вы можете легко тестировать и отлаживать API с помощью `grpcurl`.
#### Тестирование с помощью `grpcurl`
`grpcurl` — это утилита командной строки, которая позволяет взаимодействовать с gRPC-серверами. Это как `curl`, но для gRPC.
##### 1. Установка
Если у вас его нет, вы можете установить его с помощью `go install`:
```bash
go install github.com/fullstorydev/grpcurl/cmd/grpcurl@latest
```
**Примечание:** Убедитесь, что каталог `bin` вашего Go находится в `PATH` вашей системы. Если нет, вы можете добавить `export PATH=$PATH:$(go env GOPATH)/bin` в ваш файл `.bashrc` или `.zshrc`.
##### 2. Список всех доступных сервисов
Поскольку наш сервер предоставляет сервис gRPC Reflection, вы можете спросить его, какие сервисы он поддерживает.
```bash
grpcurl -plaintext localhost:8090 list
```
**Ожидаемый вывод:**
```
grpc.health.v1.Health
grpc.reflection.v1alpha.ServerReflection
mcp.MCP
```
##### 3. Список методов для сервиса MCP
```bash
grpcurl -plaintext localhost:8090 list mcp.MCP
```
**Ожидаемый вывод:**
```
mcp.MCP.GetHumanInput
mcp.MCP.ListTools
mcp.MCP.ProvideHumanInput
mcp.MCP.RunTool
```
##### 4. Вызов метода `ListTools`
```bash
grpcurl -plaintext localhost:8090 mcp.MCP.ListTools
```
Это вернет тот же JSON-список инструментов, что и в примере с `curl`.
##### 5. Вызов `RunTool` с данными
Используйте флаг `-d` для передачи JSON-нагрузки.
```bash
grpcurl -plaintext -d '{"name": "calculator", "arguments": {"expression": "(10 + 5) * 2"}}' localhost:8090 mcp.MCP.RunTool
```
**Пример ответа:**
```json
{
"result": {
"stringValue": "30"
}
}
```
## Использование паттернов ReAct для выбора инструментов
Паттерн ReAct (Reason and Act) позволяет большой языковой модели (LLM) рассуждать о том, какой инструмент использовать для данной задачи. Это мощный способ создания интеллектуальных и автономных агентов.
### Сценарий: Динамический выбор инструмента
В этом сценарии LLM сначала запрашивает список доступных инструментов у сервера MCP, а затем решает, какой из них использовать, на основе запроса пользователя. Сервер MCP вернет только те инструменты, которые в данный момент работоспособны.
**Запрос пользователя:** "Какая погода в Лондоне?"
**Мысль LLM:**
Мне нужно узнать погоду. Я должен посмотреть, какие инструменты доступны.
[LLM вызывает метод `ListTools` сервера MCP]
Инструмент `web_search` кажется подходящим. Я использую его для поиска "погода в Лондоне".
[LLM вызывает метод `RunTool` сервера MCP с инструментом `web_search`]
Следуя этому руководству, вы сможете расширить сервер MCP новыми возможностями и интегрировать его в различные приложения. Модульная конструкция и двойной API делают его гибкой и масштабируемой платформой для создания интеллектуальных агентов.
