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

---
layout: default
title: "Спецификация аргументов для инструмента MCP"
parent: "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 с минимальными метаданными:
```json
{
  "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 в запросы агента

### Схема конфигурации
```json
{
  "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 - это чисто внутренняя конфигурация и обработка аргументов