MCP Аннотации инструментов

Метаданные безопасности для MCP инструментов — hints read/write/destructive для корректного UI подтверждения клиентом.

Каждый MCP инструмент предоставляемый AACWorkflow аннотирован с метаданными безопасности чтобы MCP клиенты (Claude, ChatGPT, пользовательские инструменты) могли отобразить корректный UI подтверждения и применить необходимые guardrails перед вызовом чувствительных операций.

Типы аннотаций

Аннотация	Значение	Примеры
`ReadOnlyHint`	Не модифицирует состояние	`list_issues`, `get_issue`, `dashboard_usage_daily`
`DestructiveHint`	Может удалять или перезаписывать данные	`delete_issue`, `delete_comment`
`IdempotentHint`	Повторные вызовы не имеют доп. эффекта	`update_issue`, `assign_issue_to_agent`
`OpenWorldHint`	Затрагивает внешние системы	Любой инструмент вызывающий GitHub, Telegram или third-party APIs

Классификация инструментов

Инструмент	ReadOnly	Destructive	Idempotent	Scopes
`list_issues`	✓		✓	`issues:read`
`get_issue`	✓		✓	`issues:read`
`list_comments`	✓		✓	`comments:read`
`dashboard_usage_daily`	✓		✓	`dashboard:read`
`create_issue`				`issues:write`
`update_issue`			✓	`issues:write`
`comment_issue`				`comments:write`
`assign_issue_to_agent`			✓	`agents:write`
`trigger_autopilot`				`autopilot:run`
`delete_issue` (если добавлен)		✓	✓	`issues:write`

Поведение клиента

Read-only инструменты

MCP хосты не требуют подтверждение для read-only операций. Инструмент безопасно вызывать без взаимодействия пользователя.

Destructive инструменты

Перед вызовом destructive инструмента, MCP хосты должны:

Запросить подтверждение пользователя — «Вы уверены что хотите удалить этот issue?»
Передать confirm: true в аргументах инструмента

Сервер валидирует что confirm: true присутствует. Если отсутствует, вызов отрицается с 400 Bad Request:

{
  "error": "confirm: true required for destructive operations"
}

Idempotent инструменты

Idempotent инструменты могут быть безопасно повторены без побочных эффектов. MCP хосты могут вызывать их несколько раз (например, для resilience против транзиентных ошибок) и получать тот же результат.

Read-write инструменты (non-idempotent)

Инструменты вроде create_issue и comment_issue которые создают новые сущности не idempotent. MCP хосты НЕ должны повторять их при ошибке — это создаст дублирующиеся записи.

Применение сервером

Аннотации advisory к клиенту но авторитетные на сервере:

Scopes применяются — destructive вызов всё ещё fails если токен не имеет issues:write, независимо от client-side hints
Destructive флаг проверяется — отсутствие confirm: true на destructive инструменте отрицается server-side
Read-only запросы аудитируются — даже read-only вызовы логируются для compliance, но не требуют подтверждение

Пример: Destructive инструмент вызов

Клиент хочет удалить issue. Поток:

Клиент проверяет аннотации инструмента и видит DestructiveHint: true
Клиент спрашивает пользователя: «Удалить issue AAC-42?»
Пользователь подтверждает
Клиент вызывает инструмент с confirm: true

{
  "name": "delete_issue",
  "arguments": {
    "issue_id": "550e8400-e29b-41d4-a716-446655440000",
    "confirm": true
  }
}

Сервер проверяет:

Токен имеет issues:write scope
confirm: true присутствует
Issue существует и принадлежит workspace'у токена
Пользователь имеет права

Если все проверки пройдены, issue удаляется. Иначе, 400 или 403 ошибка возвращается.

Заметки реализации

Read-only обработчики инструментов никогда не должны вызывать Queries.Update* или Delete* методы. CI тесты применяют этот инвариант для всех инструментов тегированных ReadOnlyHint: true.

Каждый обработчик инструмента помечен его аннотациями
Аннотации встроены в MCP Tool определение при регистрации с MCP серверами
Те же аннотации возвращаются /tools introspection endpoint чтобы клиенты могли обнаружить возможности
Проверка scope происходит на слое токена; аннотации дополняют но не заменяют применение scope

Лог аудита

Каждый вызов инструмента (read или write, успешный или отрицаемый) записывается в connector лог аудита:

{
  "tool": "delete_issue",
  "outcome": "denied",
  "reason": "destructive_flag_missing",
  "scopes_provided": ["issues:write"],
  "timestamp": "2025-06-22T15:30:00Z"
}

Это позволяет админам мониторить какие инструменты вызываются и обнаруживать необычные паттерны.

MCP Аннотации инструментов

Содержание