forge-toolkit/docs/mcp-contract.md

Контракт на проводе

Сервер — стандартный MCP-сервер (JSON-RPC 2.0 через stdio). Здесь зафиксировано то, что важно для корректной работы с хостом: формат результата и forge-специфичный probe.

CallToolResult

Успех:

{ "content": [ { "type": "text", "text": "..." } ] }

Доменная ошибка (модель должна увидеть и исправить):

{ "content": [ { "type": "text", "text": "не найдено: ..." } ], "isError": true }

• isError: true — ошибка инструмента, а не транспорта: цикл агента продолжается.
• Инфраструктурный сбой возвращается как Go-error (JSON-RPC error), а не как isError.

Хелперы: toolkit.Text, toolkit.Error.

Probe: эмитированные permission-паттерны

Инструменты с побочными эффектами могут сообщать хосту канонические паттерны доступа. Хост вызывает инструмент в режиме probe, получает паттерны и применяет политику одобрения, не выполняя действие.

Запрос probe — стандартное поле _meta вызова:

{
  "method": "tools/call",
  "params": {
    "name": "write_file",
    "arguments": { "path": "a.txt", "content": "hi" },
    "_meta": { "forge.permission_patterns": true }
  }
}

Ответ probe — паттерны в _meta, без побочного эффекта:

{
  "content": [],
  "_meta": {
    "forge.patterns": ["write:a.txt"],
    "forge.always": []
  }
}

Ключи (константы в toolkit/probe.go):

Ключ	Смысл
forge.permission_patterns	флаг запроса probe
forge.patterns	паттерны, зависящие от аргументов
forge.always	паттерны, действующие всегда
forge.supports_permission_patterns	флаг в Tool.Meta: сервер поддерживает probe

Инструменты без побочных эффектов probe не поддерживают — хост не шлёт им probe-вызов.

Хелперы: toolkit.RegisterPatternTool, toolkit.WrapProbe, toolkit.IsProbe.