trustgraph/docs/tech-specs/mcp-tool-arguments.ru.md

layout	title	parent
default	Спецификация аргументов для инструмента MCP	Russian (Beta)

Спецификация аргументов для инструмента MCP

Beta Translation: This document was translated via Machine Learning and as such may not be 100% accurate. All non-English languages are currently classified as Beta.

Обзор

Имя функции: Поддержка аргументов для инструмента MCP Автор: Claude Code Assistant Дата: 21.08.2025 Статус: Завершено

Краткое описание

Позволить агентам ReACT использовать инструменты MCP (Протокол контекста модели) с правильно определенными аргументами, добавив поддержку спецификации аргументов в конфигурацию инструмента MCP, аналогично тому, как работают инструменты с шаблонами запросов.

Проблема

В настоящее время инструменты MCP в фреймворке агента ReACT не могут указывать ожидаемые аргументы. Метод McpToolImpl.get_arguments() возвращает пустой список, заставляя LLM угадывать правильную структуру параметров, основываясь только на именах и описаниях инструментов. Это приводит к:

• Ненадежным вызовам инструментов из-за угадывания параметров
• Плохой пользовательской опыту, когда инструменты не работают из-за неправильных аргументов
• Отсутствию проверки параметров инструментов перед выполнением
• Отсутствия документации параметров в запросах агента

Цели

• Разрешить конфигурации инструментов MCP указывать ожидаемые аргументы (имя, тип, описание)
• Обновить менеджер агентов, чтобы он предоставлял аргументы инструментов MCP LLM через запросы
• Сохранить обратную совместимость с существующими конфигурациями инструментов MCP
• Поддерживать проверку аргументов, аналогичную инструментам с шаблонами запросов

Нецелевые области

• Динамическое обнаружение аргументов от серверов MCP (будущее улучшение)
• Проверка типов аргументов за пределами базовой структуры
• Сложные схемы аргументов (вложенные объекты, массивы)

Предыстория и контекст

Текущее состояние

Инструменты MCP настраиваются в системе агента ReACT с минимальными метаданными:

{
  "type": "mcp-tool",
  "name": "get_bank_balance",
  "description": "Получить баланс банковского счета",
  "mcp-tool": "get_bank_balance"
}

Метод McpToolImpl.get_arguments() возвращает [], поэтому LLM не получают никаких указаний по аргументам в своих запросах.

Ограничения

1. Отсутствие спецификации аргументов: Инструменты MCP не могут определять ожидаемые параметры
2. Угадывание параметров LLM: Агенты должны выводить параметры из имен/описаний инструментов
3. Отсутствие информации в запросах: Запросы агента не содержат деталей аргументов для инструментов MCP
4. Отсутствие проверки: Неправильные параметры обнаруживаются только во время выполнения инструмента MCP

Связанные компоненты

• trustgraph-flow/agent/react/service.py: Загрузка конфигурации инструментов и создание AgentManager
• trustgraph-flow/agent/react/tools.py: Реализация McpToolImpl
• trustgraph-flow/agent/react/agent_manager.py: Генерация запросов с аргументами инструментов
• tg-invoke-mcp-tool: Клиентские инструменты для управления инструментами MCP
• Workbench: Внешний UI для конфигурации инструментов агента

Требования

Функциональные требования

1. Конфигурация аргументов для инструмента MCP: Конфигурации инструментов MCP ДОЛЖНЫ поддерживать необязательный массив arguments с полями name, type и description
2. Предоставление аргументов: McpToolImpl.get_arguments() ДОЛЖЕН возвращать сконфигурированные аргументы, а не пустой список
3. Интеграция с запросами: Запросы агента ДОЛЖНЫ содержать детали аргументов инструментов MCP, когда аргументы указаны
4. Обратная совместимость: Существующие конфигурации инструментов MCP без аргументов ДОЛЖНЫ продолжать работать
5. Поддержка CLI: Существующие CLI инструменты tg-invoke-mcp-tool поддерживают аргументы (уже реализовано)

Нефункциональные требования

1. Обратная совместимость: Без каких-либо изменений для существующих конфигураций инструментов MCP
2. Производительность: Отсутствие существенного влияния на генерацию запросов агента
3. Согласованность: Обработка аргументов ДОЛЖНА соответствовать шаблонам инструментов с шаблонами запросов

Истории пользователей

1. Как разработчик агента, я хочу указывать аргументы инструментов MCP в конфигурации, чтобы LLM могли вызывать инструменты с правильными параметрами
2. Как пользователь Workbench, я хочу настраивать аргументы инструментов MCP в UI, чтобы агенты использовали инструменты правильно
3. Как LLM в ReACT агенте, я хочу видеть спецификации аргументов инструментов в запросах, чтобы я мог предоставлять правильные параметры

Проектирование

Высокоуровневая архитектура

Расширить конфигурацию инструмента MCP, чтобы соответствовать шаблону инструмента с шаблоном запросов, путем:

1. Добавления необязательного массива arguments в конфигурацию инструментов MCP
2. Модификации McpToolImpl для приема и возврата сконфигурированных аргументов
3. Обновления загрузки конфигурации инструментов для обработки аргументов инструментов MCP
4. Обеспечения включения информации об аргументах инструментов MCP в запросы агента

Схема конфигурации

{
  "type": "mcp-tool",
  "name": "get_bank_balance", 
  "description": "Get bank account balance",
  "mcp-tool": "get_bank_balance",
  "arguments": [
    {
      "name": "account_id",
      "type": "string", 
      "description": "Bank account identifier"
    },
    {
      "name": "date",
      "type": "string",
      "description": "Date for balance query (optional, format: YYYY-MM-DD)"
    }
  ]
}

Поток данных

1. Загрузка конфигурации: Конфигурация инструмента MCP с аргументами загружается с помощью on_tools_config()
2. Создание инструмента: Аргументы парсятся и передаются в McpToolImpl через конструктор
3. Генерация запросов: agent_manager.py вызывает tool.arguments для включения в LLM запросы
4. Вызов инструмента: LLM предоставляет параметры, которые передаются инструменту MCP без изменений

Изменения API

Нет изменений API - это чисто внутренняя конфигурация и обработка аргументов