<h1>Руководство по интеграции</h1>
<p>Это руководство содержит подробные инструкции по интеграции новых и существующих инструментов в сервер MCP-NG. Оно также описывает, как подключать сервер к клиентским приложениям и использовать паттерны ReAct для интеллектуального использования инструментов.</p>
<h2>Добавление нового инструмента на сервер</h2>
<p>Интеграция нового инструмента включает создание gRPC-сервиса и предоставление простого файла конфигурации. Главный сервер спроектирован так, чтобы автоматически обнаруживать, запускать и управлять любым инструментом, который следует этой структуре.</p>
<h3>1. Определите gRPC-контракт инструмента</h3>
<p>Все определения сервисов централизованы в файле <code>MCP-NG/proto/mcp.proto</code>, который служит единым источником истины для всего API.</p>
<p>Для добавления нового инструмента, как правило, вы будете реализовывать уже существующий интерфейс сервиса <code>Tool</code>, а не определять совершенно новый сервис. Ключевые методы уже определены:</p>
<ul>
<li><code>GetDescription</code>: Возвращает имя, описание и ожидаемые параметры инструмента.</li>
<li><code>Run</code>: Выполняет инструмент с предоставленными аргументами.</li>
</ul>
<p>Если ваш инструмент требует совершенно нового шаблона взаимодействия, вы можете добавить новый сервис в файл <code>.proto</code>. После его обновления, перегенерируйте gRPC-код для всех языков, запустив скрипт генерации из корневого каталога проекта:</p>
<pre><code>./generate_protos.sh</code></pre>
<p>Этот скрипт автоматически обрабатывает все зависимости и пути вывода, обеспечивая корректное обновление заглушек для Go и Python.</p>
<h3>2. Реализуйте gRPC-сервер инструмента</h3>
<p>Далее, реализуйте gRPC-сервер для вашего нового инструмента. Вы можете сделать это на Go или Python, следуя структуре существующих инструментов.</p>
<ul>
<li><strong>Go:</strong> Создайте новый каталог в <code>MCP-NG/tools/go/</code>.</li>
<li><strong>Python:</strong> Создайте новый каталог в <code>MCP-NG/tools/python/</code>.</li>
</ul>
<p>Ваша реализация должна определять логику для методов <code>GetDescription</code> и <code>Run</code>.</p>
<h3>3. Реализуйте службу проверки состояния</h3>
<p>Ваш инструмент <strong>должен</strong> реализовывать стандартный протокол проверки состояния gRPC. Это позволяет главному серверу MCP отслеживать его состояние и направлять трафик только к работоспособным экземплярам.</p>
<ul>
<li><strong>Go:</strong> Используйте пакет <code>google.golang.org/grpc/health</code>.</li>
<li><strong>Python:</strong> Используйте пакет <code>grpc_health.v1</code>.</li>
</ul>
<p>Зарегистрируйте службу проверки состояния и установите начальный статус <code>SERVING</code>.</p>
<h3>4. Создайте файл конфигурации</h3>
<p>В корневом каталоге вашего инструмента создайте файл <code>config.json</code>. Этот файл сообщает главному серверу, как запускать ваш инструмент. Конфигурация теперь универсальна для локальной среды и Docker.</p>
<p><strong>Пример для инструмента на Go (`api_caller/config.json`):</strong></p>
<pre><code>{
"port": 50051,
"command": ["api_caller"]
}
</code></pre>
<p><strong>Пример для инструмента на Python (`code_interpreter/config.json`):</strong></p>
<pre><code>{
"port": 50071,
"command": ["server.py"]
}
</code></pre>
<ul>
<li><code>port</code>: Порт, на котором будет слушать gRPC-сервер вашего инструмента.</li>
<li><code>command</code>: Массив из одного элемента, содержащий имя исполняемого файла (для Go) или скрипта-точки входа (для Python). Главный сервер сам интеллектуально построит полный путь к команде в зависимости от окружения.</li>
</ul>
<h2>Интеграция с клиентским приложением</h2>
<p>Вы можете подключиться к серверу MCP-NG двумя основными способами: через простой HTTP/REST API или через высокопроизводительный нативный интерфейс gRPC. Для большинства случаев, особенно для веб-клиентов или скриптов, рекомендуется начинать с HTTP/REST API.</p>
<p><strong>Порты по умолчанию:</strong></p>
<ul>
<li><strong>HTTP/REST:</strong> <code>http://localhost:8002</code></li>
<li><strong>gRPC:</strong> <code>localhost:8090</code></li>
</ul>
<h3>Простой способ: использование HTTP/REST API</h3>
<p>gRPC-Gateway предоставляет стандартный RESTful API, с которым вы можете взаимодействовать с помощью любого HTTP-клиента, такого как <code>curl</code> или библиотека <code>requests</code> в Python.</p>
<h4>Пример 1: Получение списка доступных инструментов с помощью `curl`</h4>
<p>Получите список всех работоспособных, доступных инструментов, сделав <code>GET</code>-запрос к конечной точке <code>/v1/tools</code>.</p>
<pre><code>curl http://localhost:8002/v1/tools</code></pre>
<p><strong>Пример ответа:</strong></p>
<pre><code>{
"tools": [
{
"name": "calculator",
"description": "Инструмент для вычисления математических выражений...",
"parameters": {
"type": "object",
"properties": { "expression": { "type": "string", "description": "..." } },
"required": ["expression"]
}
},
{ "name": "web_search", "description": "Выполняет веб-поиск...", "..." }
]
}
</code></pre>
<h4>Пример 2: Выполнение инструмента с помощью Python `requests`</h4>
<p>Чтобы запустить инструмент, отправьте <code>POST</code>-запрос к конечной точке <code>/v1/tools/execute</code> с именем инструмента и аргументами в теле JSON-запроса.</p>
<pre><code>import requests
import json
url = "http://localhost:8002/v1/tools/execute"
payload = {
"tool_name": "calculator",
"arguments": {
"expression": "(10 + 5) * 2"
}
}
response = requests.post(url, json=payload)
print(response.json())
</code></pre>
<p><strong>Пример ответа:</strong></p>
<pre><code>{
"result": {
"result": { "numberValue": 30 }
}
}
</code></pre>
<h3>Продвинутый способ: использование нативного интерфейса gRPC</h3>
<p>Для приложений, требующих максимальной производительности, рекомендуется подключаться напрямую к gRPC-серверу. Вы можете легко тестировать API с помощью <code>grpcurl</code>.</p>
<h4>Тестирование с помощью `grpcurl`</h4>
<p><code>grpcurl</code> — это утилита командной строки, которая позволяет взаимодействовать с gRPC-серверами, аналогично `curl` для HTTP.</p>
<h5>1. Установка</h5>
<p>Самый простой способ установки — через менеджер пакетов вашей системы (например, <code>brew install grpcurl</code> на macOS, <code>choco install grpcurl</code> на Windows).</p>
<h5>2. Список всех доступных сервисов</h5>
<p>Поскольку наш сервер предоставляет сервис gRPC Reflection, вы можете спросить его, какие сервисы он поддерживает.</p>
<pre><code>grpcurl -plaintext localhost:8090 list</code></pre>
<p><strong>Ожидаемый вывод:</strong></p>
<pre><code>grpc.health.v1.Health
grpc.reflection.v1alpha.ServerReflection
mcp.MCP
</code></pre>
<h5>3. Список методов для сервиса MCP</h5>
<pre><code>grpcurl -plaintext localhost:8090 list mcp.MCP</code></pre>
<h5>4. Вызов метода `ListTools`</h5>
<pre><code>grpcurl -plaintext localhost:8090 mcp.MCP.ListTools</code></pre>
<h5>5. Вызов `ExecuteTool` с данными</h5>
<p>Используйте флаг <code>-d</code> для передачи JSON-нагрузки.</p>
<pre><code>grpcurl -plaintext -d '{"tool_name": "calculator", "arguments": {"expression": "(10 + 5) * 2"}}' localhost:8090 mcp.MCP.ExecuteTool</code></pre>
<p><strong>Пример ответа:</strong></p>
<pre><code>{
"result": {
"result": {
"numberValue": 30
}
}
}
</code></pre>
<h2>Использование паттернов ReAct для выбора инструментов</h2>
<p>Паттерн ReAct (Reason and Act) позволяет большой языковой модели (LLM) рассуждать о том, какой инструмент использовать для данной задачи, создавая цикл из мысли, действия и наблюдения.</p>
<p><strong>Запрос пользователя:</strong> "Какой результат у 15 умножить на 3, и кто сейчас президент Франции?"</p>
<p><strong>Пример цикла ReAct:</strong></p>
<ol>
<li><strong>Мысль:</strong> У пользователя два вопроса. Сначала я решу математическую задачу. Я поищу инструмент-калькулятор.
<ul><li><strong>Действие:</strong> Вызвать <code>ListTools()</code> на сервере MCP.</li></ul>
</li>
<li><strong>Наблюдение:</strong> Сервер возвращает список, включающий инструмент "calculator".</li>
<li><strong>Мысль:</strong> Отлично, я использую инструмент "calculator" с выражением "15 * 3".
<ul><li><strong>Действие:</strong> Вызвать <code>ExecuteTool(tool_name="calculator", arguments={"expression": "15 * 3"})</code>.</li></ul>
</li>
<li><strong>Наблюдение:</strong> Инструмент возвращает результат <code>{"result": 45}</code>.</li>
<li><strong>Мысль:</strong> Первая часть выполнена. Теперь мне нужно найти президента Франции. Инструмент "web_search" кажется подходящим.
<ul><li><strong>Действие:</strong> Вызвать <code>ExecuteTool(tool_name="web_search", arguments={"query": "current president of France"})</code>.</li></ul>
</li>
<li><strong>Наблюдение:</strong> Инструмент возвращает текстовый фрагмент: "Эммануэль Макрон — действующий президент Франции."</li>
<li><strong>Мысль:</strong> У меня есть оба ответа. Теперь я могу сформировать окончательный ответ.
<ul><li><strong>Финальный ответ пользователю:</strong> Результат 15 умножить на 3 равен 45. Действующий президент Франции — Эммануэль Макрон.</li></ul>
</li>
</ol>
<p>Следуя этому руководству, вы сможете расширить сервер MCP новыми возможностями и интегрировать его в различные приложения для создания мощных и гибких интеллектуальных агентов.</p>
