github-ops
107 lines
2.6 KiB
Markdown
107 lines
2.6 KiB
Markdown
# MCP Interface
|
|
|
|
Crank Community публикует REST operations как MCP tools поверх Streamable HTTP.
|
|
|
|
## Transport
|
|
|
|
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:
|
|
|
|
```text
|
|
/mcp/v1/{workspace_slug}/{agent_slug}
|
|
```
|
|
|
|
Endpoint определяет:
|
|
|
|
- workspace;
|
|
- published agent;
|
|
- curated tool catalog агента;
|
|
- labels для logs и usage.
|
|
|
|
## Authentication
|
|
|
|
Community использует static agent API keys.
|
|
|
|
Правила:
|
|
|
|
- каждый published agent может иметь собственные API keys;
|
|
- key принадлежит одному workspace и одному agent;
|
|
- `mcp-server` показывает только tools, привязанные к этому agent;
|
|
- unsupported token issuance modes отклоняются.
|
|
|
|
## Tool catalog
|
|
|
|
Одна published REST operation становится одним MCP tool.
|
|
|
|
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`
|
|
|
|
Transport endpoints:
|
|
|
|
- `POST /mcp/v1/{workspace_slug}/{agent_slug}`
|
|
- `GET /mcp/v1/{workspace_slug}/{agent_slug}`
|
|
- `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.
|
|
|
|
## `tools/call`
|
|
|
|
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.
|
|
|
|
## Refresh
|
|
|
|
Published catalog refresh управляется `CRANK_MCP_REFRESH_MS`.
|
|
|
|
После публикации operation или agent `mcp-server` подхватывает новый catalog без
|
|
restart.
|
|
|
|
## Error categories
|
|
|
|
MCP responses различают:
|
|
|
|
- authentication errors;
|
|
- missing workspace или agent;
|
|
- missing tool;
|
|
- schema validation errors;
|
|
- mapping errors;
|
|
- upstream REST errors;
|
|
- internal runtime errors.
|