chore: publish clean community baseline

2026-06-17 06:15:46 +00:00
commit ae09eeba30
318 changed files with 73473 additions and 0 deletions
@@ -0,0 +1,106 @@
+# 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.