Maksim Totmin
c398045664
forge-toolkit: хелперы для разработки MCP-серверов на Go. - toolkit: args/schema/result/env/probe/server - toolkit/validate: валидаторы синтаксиса - configreload: live-reload конфига по контент-хэшу - docs: ARCHITECTURE, quickstart, mcp-contract - template/ и examples/hello-tool/ - CI (Gitea Actions), лицензия Apache-2.0
72 lines
2.5 KiB
Markdown
72 lines
2.5 KiB
Markdown
# Контракт на проводе
|
||
|
||
Сервер — стандартный MCP-сервер (JSON-RPC 2.0 через stdio). Здесь зафиксировано
|
||
то, что важно для корректной работы с хостом: формат результата и
|
||
forge-специфичный probe.
|
||
|
||
## `CallToolResult`
|
||
|
||
Успех:
|
||
|
||
```json
|
||
{ "content": [ { "type": "text", "text": "..." } ] }
|
||
```
|
||
|
||
Доменная ошибка (модель должна увидеть и исправить):
|
||
|
||
```json
|
||
{ "content": [ { "type": "text", "text": "не найдено: ..." } ], "isError": true }
|
||
```
|
||
|
||
- `isError: true` — ошибка **инструмента**, а не транспорта: цикл агента
|
||
продолжается.
|
||
- Инфраструктурный сбой возвращается как Go-`error` (JSON-RPC error), а не
|
||
как `isError`.
|
||
|
||
Хелперы: `toolkit.Text`, `toolkit.Error`.
|
||
|
||
## Probe: эмитированные permission-паттерны
|
||
|
||
Инструменты с побочными эффектами могут сообщать хосту **канонические
|
||
паттерны** доступа. Хост вызывает инструмент в режиме probe, получает
|
||
паттерны и применяет политику одобрения, **не выполняя действие**.
|
||
|
||
Запрос probe — стандартное поле `_meta` вызова:
|
||
|
||
```json
|
||
{
|
||
"method": "tools/call",
|
||
"params": {
|
||
"name": "write_file",
|
||
"arguments": { "path": "a.txt", "content": "hi" },
|
||
"_meta": { "forge.permission_patterns": true }
|
||
}
|
||
}
|
||
```
|
||
|
||
Ответ probe — паттерны в `_meta`, без побочного эффекта:
|
||
|
||
```json
|
||
{
|
||
"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`.
|