crank/docs/architecture.md

Архитектура

Crank Community публикует REST API как MCP tools.

Сервисы

• ui — web-интерфейс.
• admin-api — HTTP API для авторизации, operations, agents, secrets, logs и settings.
• mcp-server — MCP Streamable HTTP endpoint для published agents.

Основные сущности

• Workspace — граница данных.
• Operation — REST integration contract.
• Agent — опубликованный MCP surface с ограниченным набором tools.
• Secret и AuthProfile — безопасное применение upstream credentials.
• InvocationLog и UsageRollup — observability.

Flow

1. Пользователь создает REST operation.
2. Пользователь настраивает target, schemas и mapping.
3. admin-api сохраняет draft и version.
4. Runtime выполняет test call через REST adapter.
5. Пользователь публикует operation.
6. Пользователь привязывает operation к agent.
7. mcp-server открывает published operation как MCP tool.

Runtime path

MCP client
  -> mcp-server
  -> crank-runtime
  -> crank-adapter-rest
  -> upstream REST API

Input mapping переводит MCP arguments в REST request. Output mapping переводит REST response в MCP tool result.

Хранилище

PostgreSQL хранит:

• users и sessions;
• workspaces;
• operations и versions;
• agents и bindings;
• secrets и auth profiles;
• logs и usage.

Файловое хранилище используется для samples и YAML import payloads.