developer › schema

JSON-RPC схема

EDL OS MCP-сервер общается с AI-клиентом по протоколу JSON-RPC 2.0 поверх Server-Sent Events. Спецификация на 95% совпадает с официальным MCP — расхождения помечены 🔸.

Endpoint

Метод	URL	Назначение
`GET`	`/mcp/v1`	SSE-стрим (long-lived)
`POST`	`/mcp/v1/rpc`	Одиночный RPC-вызов (для отладки)
`GET`	`/mcp/v1/health`	Health-check
`GET`	`/.well-known/oauth-authorization-server`	OAuth metadata

Initialize

Первый обмен после открытия соединения. Клиент объявляет capabilities:

// Request
{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "initialize",
  "params": {
    "protocolVersion": "2025-11-25",
    "capabilities": { "tools": {}, "sampling": {} },
    "clientInfo": { "name": "Claude Desktop", "version": "0.9.2" }
  }
}

// Response
{
  "jsonrpc": "2.0",
  "id": 1,
  "result": {
    "protocolVersion": "2025-11-25",
    "capabilities": { "tools": { "listChanged": true } },
    "serverInfo": { "name": "edl-os", "version": "0.1.0" }
  }
}

tools/list

Получить список доступных инструментов. Возвращается JSON-схема входа каждого tool.

// Request
{ "jsonrpc": "2.0", "id": 2, "method": "tools/list" }

// Response
{
  "jsonrpc": "2.0",
  "id": 2,
  "result": {
    "tools": [
      {
        "name": "founder_score",
        "description": "Расчёт Founder OS Score по 4 слоям",
        "inputSchema": {
          "type": "object",
          "properties": {
            "layers": {
              "type": "array",
              "items": { "enum": ["strategy", "finance", "team", "ops"] }
            }
          }
        }
      }
    ]
  }
}

tools/call

Вызвать конкретный tool. arguments валидируются по inputSchema:

// Request
{
  "jsonrpc": "2.0",
  "id": 3,
  "method": "tools/call",
  "params": {
    "name": "founder_score",
    "arguments": { "layers": ["strategy", "finance"] }
  }
}

// Response
{
  "jsonrpc": "2.0",
  "id": 3,
  "result": {
    "content": [
      {
        "type": "text",
        "text": "{\"strategy\":72,\"finance\":58,\"total\":65}"
      }
    ],
    "isError": false
  }
}

Ошибки

Используются стандартные коды JSON-RPC + расширенные EDL OS:

Code	Message	Когда
`-32700`	Parse error	Невалидный JSON
`-32600`	Invalid request	Не соответствует JSON-RPC 2.0
`-32601`	Method not found	Неизвестный метод (например `tools/foo`)
`-32602`	Invalid params	`arguments` не прошли валидацию `inputSchema`
`-32603`	Internal error	Падение коннектора, сетевой timeout
`-32001` 🔸	Unauthorized	OAuth-токен истёк или не задан
`-32002` 🔸	Rate limited	Превышен per-tool rate-limit
`-32003` 🔸	Subscription required	Tool из managed-cloud не активен в open-core

Авторизация (OAuth 2.1 + PKCE)

Если MCP_AUTH_MODE=oauth, сервер требует Bearer-токен. Discovery:

curl http://localhost:8080/.well-known/oauth-authorization-server

Ответ — стандартный RFC 8414 + extension code_challenge_methods_supported: ["S256"].

Refresh-токены живут 30 дней. Access-токены — 1 час. При истечении access-токена клиент должен вернуть -32001 и предложить пользователю запустить refresh-flow.

Тесты

В корне репо есть fixtures/ с примерами всех методов в формате .http — открываются в IntelliJ HTTP Client / VS Code REST Client:

fixtures/initialize.http
fixtures/tools_list.http
fixtures/tools_call.http
fixtures/errors.http

Что дальше

В 0.2 планируем:

resources/list и resources/read — для подкачки документов в контекст
prompts/list — заранее заготовленные промпт-шаблоны
Streaming-tool результаты для долгих запросов (>10 сек)

← назад

Свой коннектор