Complete markdown documentation
This commit is contained in:
github-ops
+146
-75
@@ -1,106 +1,177 @@
|
||||
# MCP Interface
|
||||
# MCP-интерфейс
|
||||
|
||||
Crank Community публикует REST operations как MCP tools поверх Streamable HTTP.
|
||||
Crank публикует REST-операции как MCP-инструменты через Streamable HTTP.
|
||||
|
||||
## Transport
|
||||
## Endpoint агента
|
||||
|
||||
MCP server запускается отдельным приложением `mcp-server`.
|
||||
|
||||
Поддерживается:
|
||||
|
||||
- MCP Streamable HTTP;
|
||||
- JSON-RPC requests через `POST`;
|
||||
- optional server-to-client stream через `GET`;
|
||||
- explicit session close через `DELETE`.
|
||||
|
||||
`stdio` не входит в Community deployment.
|
||||
|
||||
## Endpoint model
|
||||
|
||||
Canonical endpoint:
|
||||
Каждый агент имеет собственный MCP endpoint:
|
||||
|
||||
```text
|
||||
/mcp/v1/{workspace_slug}/{agent_slug}
|
||||
```
|
||||
|
||||
Endpoint определяет:
|
||||
Для demo seed:
|
||||
|
||||
- workspace;
|
||||
- published agent;
|
||||
- curated tool catalog агента;
|
||||
- labels для logs и usage.
|
||||
```text
|
||||
/mcp/v1/default/currency-rates
|
||||
```
|
||||
|
||||
## Authentication
|
||||
Полный URL зависит от вашего домена:
|
||||
|
||||
Community использует static agent API keys.
|
||||
```text
|
||||
https://crank.example.com/mcp/v1/default/currency-rates
|
||||
```
|
||||
|
||||
Правила:
|
||||
## Авторизация
|
||||
|
||||
- каждый published agent может иметь собственные API keys;
|
||||
- key принадлежит одному workspace и одному agent;
|
||||
- `mcp-server` показывает только tools, привязанные к этому agent;
|
||||
- unsupported token issuance modes отклоняются.
|
||||
MCP-клиент должен передавать API-ключ агента:
|
||||
|
||||
## Tool catalog
|
||||
```http
|
||||
Authorization: Bearer <agent_api_key>
|
||||
```
|
||||
|
||||
Одна published REST operation становится одним MCP tool.
|
||||
Ключ выдается в разделе **API ключи**. Полное значение показывается только один раз при создании.
|
||||
|
||||
Tool definition строится из:
|
||||
|
||||
- operation name или binding-level tool name;
|
||||
- tool title и description;
|
||||
- input schema;
|
||||
- published operation version.
|
||||
|
||||
Draft operations никогда не публикуются через MCP.
|
||||
|
||||
## Supported methods
|
||||
## Поддерживаемые методы
|
||||
|
||||
MCP methods:
|
||||
|
||||
- `initialize`
|
||||
- `notifications/initialized`
|
||||
- `ping`
|
||||
- `tools/list`
|
||||
- `tools/call`
|
||||
- `initialize`;
|
||||
- `notifications/initialized`;
|
||||
- `ping`;
|
||||
- `tools/list`;
|
||||
- `tools/call`.
|
||||
|
||||
Transport endpoints:
|
||||
HTTP transport:
|
||||
|
||||
- `POST /mcp/v1/{workspace_slug}/{agent_slug}`
|
||||
- `GET /mcp/v1/{workspace_slug}/{agent_slug}`
|
||||
- `DELETE /mcp/v1/{workspace_slug}/{agent_slug}`
|
||||
- `POST /mcp/v1/{workspace_slug}/{agent_slug}` - JSON-RPC запросы;
|
||||
- `GET /mcp/v1/{workspace_slug}/{agent_slug}` - server-to-client stream;
|
||||
- `DELETE /mcp/v1/{workspace_slug}/{agent_slug}` - закрытие сессии.
|
||||
|
||||
## `tools/list`
|
||||
## Обязательные заголовки
|
||||
|
||||
1. Client authenticates через agent API key.
|
||||
2. `mcp-server` resolves workspace и agent из path.
|
||||
3. Server loads published agent catalog.
|
||||
4. Server returns only tools bound to that agent.
|
||||
Для `POST`:
|
||||
|
||||
## `tools/call`
|
||||
```http
|
||||
Authorization: Bearer <agent_api_key>
|
||||
Content-Type: application/json
|
||||
Accept: application/json, text/event-stream
|
||||
```
|
||||
|
||||
1. Client вызывает tool.
|
||||
2. `mcp-server` валидирует input по tool schema.
|
||||
3. Runtime maps MCP input в REST request.
|
||||
4. REST adapter вызывает upstream API.
|
||||
5. Runtime maps REST response в tool output.
|
||||
6. `mcp-server` возвращает normalized result.
|
||||
Для `GET`:
|
||||
|
||||
## Refresh
|
||||
```http
|
||||
Authorization: Bearer <agent_api_key>
|
||||
Accept: text/event-stream
|
||||
MCP-Session-Id: <session_id>
|
||||
```
|
||||
|
||||
Published catalog refresh управляется `CRANK_MCP_REFRESH_MS`.
|
||||
После `initialize` сервер возвращает заголовок:
|
||||
|
||||
После публикации operation или agent `mcp-server` подхватывает новый catalog без
|
||||
restart.
|
||||
```http
|
||||
MCP-Session-Id: <session_id>
|
||||
```
|
||||
|
||||
## Error categories
|
||||
Если клиент передает `MCP-Protocol-Version`, он должен совпадать с версией, согласованной при инициализации.
|
||||
|
||||
MCP responses различают:
|
||||
## Пример `initialize`
|
||||
|
||||
- authentication errors;
|
||||
- missing workspace или agent;
|
||||
- missing tool;
|
||||
- schema validation errors;
|
||||
- mapping errors;
|
||||
- upstream REST errors;
|
||||
- internal runtime errors.
|
||||
```bash
|
||||
curl -i https://crank.example.com/mcp/v1/default/currency-rates \
|
||||
-H 'Authorization: Bearer <agent_api_key>' \
|
||||
-H 'Content-Type: application/json' \
|
||||
-H 'Accept: application/json, text/event-stream' \
|
||||
--data '{
|
||||
"jsonrpc": "2.0",
|
||||
"id": 1,
|
||||
"method": "initialize",
|
||||
"params": {
|
||||
"protocolVersion": "2025-06-18",
|
||||
"capabilities": {},
|
||||
"clientInfo": {
|
||||
"name": "curl",
|
||||
"version": "1.0.0"
|
||||
}
|
||||
}
|
||||
}'
|
||||
```
|
||||
|
||||
Сохраните `MCP-Session-Id` из ответа.
|
||||
|
||||
## Пример `tools/list`
|
||||
|
||||
```bash
|
||||
curl https://crank.example.com/mcp/v1/default/currency-rates \
|
||||
-H 'Authorization: Bearer <agent_api_key>' \
|
||||
-H 'Content-Type: application/json' \
|
||||
-H 'Accept: application/json' \
|
||||
-H 'MCP-Session-Id: <session_id>' \
|
||||
--data '{
|
||||
"jsonrpc": "2.0",
|
||||
"id": 2,
|
||||
"method": "tools/list",
|
||||
"params": {}
|
||||
}'
|
||||
```
|
||||
|
||||
Ожидаемый результат для demo seed содержит инструмент:
|
||||
|
||||
```text
|
||||
frankfurter_latest_rate
|
||||
```
|
||||
|
||||
## Пример `tools/call`
|
||||
|
||||
```bash
|
||||
curl https://crank.example.com/mcp/v1/default/currency-rates \
|
||||
-H 'Authorization: Bearer <agent_api_key>' \
|
||||
-H 'Content-Type: application/json' \
|
||||
-H 'Accept: application/json' \
|
||||
-H 'MCP-Session-Id: <session_id>' \
|
||||
--data '{
|
||||
"jsonrpc": "2.0",
|
||||
"id": 3,
|
||||
"method": "tools/call",
|
||||
"params": {
|
||||
"name": "frankfurter_latest_rate",
|
||||
"arguments": {
|
||||
"base": "USD",
|
||||
"quote": "EUR"
|
||||
}
|
||||
}
|
||||
}'
|
||||
```
|
||||
|
||||
Crank выполнит REST-запрос:
|
||||
|
||||
```text
|
||||
GET https://api.frankfurter.dev/v1/latest?base=USD&symbols=EUR
|
||||
```
|
||||
|
||||
## Как формируется каталог инструментов
|
||||
|
||||
MCP-клиент видит только опубликованные операции, которые привязаны к опубликованному агенту.
|
||||
|
||||
Черновики операций не попадают в MCP-каталог. Если два пользователя работают в одном workspace, один может редактировать черновик, а второй публиковать агента. В опубликованный каталог попадут только опубликованные версии операций.
|
||||
|
||||
## Обновление каталога
|
||||
|
||||
`mcp-server` периодически обновляет опубликованный каталог. Интервал задается:
|
||||
|
||||
```env
|
||||
CRANK_MCP_REFRESH_MS=5000
|
||||
```
|
||||
|
||||
После публикации операции или агента подождите один интервал обновления или перезапустите `mcp-server`.
|
||||
|
||||
## Ошибки
|
||||
|
||||
Частые причины ошибок:
|
||||
|
||||
- `401 Unauthorized` - отсутствует или неверен API-ключ агента.
|
||||
- `403 Forbidden` - ключ не имеет нужного доступа.
|
||||
- `404 Not Found` - workspace, агент или инструмент не опубликованы.
|
||||
- `400 Bad Request` - неверный MCP-заголовок, session id или JSON-RPC payload.
|
||||
- `429 Too Many Requests` - сработал rate limit.
|
||||
|
||||
Runtime-ошибки инструмента возвращаются как структурированный MCP tool error с кодом, сообщением и `request_id`.
|
||||
|
||||
Reference in New Issue
Block a user