WarpEngine Admin API

A WarpEngine 1.0 óta mindaz, amit az ActiveAdmin-erőforrások tudnak, JSON API-ként is elérhető a /api/admin/v1 alatt: a katalógus a kiadásaival, assetjeivel, linkjeivel és képeivel, a státusz- és kategóriaszótár, a platformlinkek, a letöltési statisztika, a pipeline-ok, az artifact-tár és az alkalmazástokenek. Kikapcsolva érkezik, a hoszt kapcsolja be; OpenAPI 3.1 leírást ad magáról, és ugyanezeket a műveleteket MCP-szerverként LLM-ügynököknek is kiszolgálja. A katalógusolvasók olvasó oldala továbbra is a WECP.

Bekapcsolás

RUBY

# config/initializers/warp_engine.rb
WarpEngine.configure do |c|
  c.admin_api.enabled    = true
  c.admin_api.mcp        = true                           # a Gemfile-ba kell a gem "mcp"
  c.admin_api.rate_limit = { to: 300, within: 1.minute }  # tokenenként
end

Kulcs	Alapérték	Jelentés
`enabled`	`false`	Kikapcsolva minden Admin API-cím 404-et ad
`token_owner_class`	`application_token_owner_class`	Az a modell, amelynek tokenje admin scope-ot kaphat
`authenticator`	`:application_token`	Vagy egy callable, amely a kérésből `WarpEngine::AdminApi::Principal`-t csinál
`resources`	`:all`	Vagy egy lista, például `%i[softwares releases downloads]`; a többi 404
`read_only`	`false`	`true`: minden írás 405, és kimarad a leírásból
`page_size` / `max_page_size`	`50` / `200`	A listák lapozása
`rate_limit`	`nil`	`{ to:, within: }` tokenenként, a `Rails.cache`-ben számolva; fölötte 429 `Retry-After`-rel
`openapi_requires_auth`	`true`	`false`: az OpenAPI-leírás nyilvános
`docs_ui`	`false`	`true`: Redoc-oldal a `/api/admin/v1/docs` alatt (a leírás auth-szabályát követi)
`mcp`	`false`	`true`: MCP a `/api/admin/v1/mcp` alatt
`mcp_exclude`	`application_tokens`, `device_grants`	Az MCP-ből kihagyott erőforrások

A teletypegames.org-on az 1.0.0 óta be van kapcsolva az Admin API és az MCP, AdminUser-tokenekkel.

Tokenek és scope-ok

TXT

Authorization: Bearer 3f9c…

Egy alkalmazástoken, amit az admin ad ki (App Tokens → Admin API scope), vagy maga az API. Három scope, egyik sem foglalja magában a másikat:

Scope	Mit nyit
`admin:read`	minden GET
`admin:write`	minden létrehozás, módosítás, törlés, trigger, sync és fájlművelet
`admin:tokens`	az alkalmazástoken- és eszközbelépés-erőforrás, az olvasás is

Csak olyan token kaphatja meg őket, amelynek a tulajdonosa az admin-tulajdonososztály — egy publisher tokenje sosem lesz admin token. Egy token nem adhat olyan admin scope-ot, ami neki nincs, nem adhat unrestricted-et, és nem adhat a sajátjánál későbbi lejáratot; a sajátjánál szélesebb tokent rotálni sem tud, mert a rotáció átadja az új titkot. Publikáló (update, upload) és kliens (catalog) tokent kiadhat.

Alak

JSON, camelCase kulcsok a törzsben, a válaszban és a query-paraméterekben (perPage, needsReview).
Lista: { "data": [ … ], "meta": { "page", "perPage", "total", "totalPages", "nextPage" } }; a page és a perPage választ, a sort=title vagy sort=-createdAt rendez.
Egy rekord: { "data": { … } }. A törlés 204-et ad.
Hiba: { "error": "Validation failed", "details": { "name": ["has already been taken"] } }.
Státuszkódok: 400 rossz paraméter, 401 nincs vagy nem admin token, 403 hiányzó scope, 404 nincs ilyen rekord vagy az erőforrás nincs bekapcsolva, 405 csak olvasható, 409 ütközés, 422 validáció, 429 rate limit, 502 a CI-szerver hibázott, 503 nincs CI konfigurálva.
A törlés azt csinálja, amit az admin: a rekord megsemmisül, a token visszavonódik. Az utolsó írás nyer, mint az adminban; kötegelt művelet nincs.
Minden válasz hordozza a WarpEngine-Version és a WarpEngine-Admin-Api: 1 fejlécet.
Minden sikeres írás után warp_engine.admin_api.write esemény megy a principallal, a művelettel és a via értékkel (http vagy mcp), a hoszt auditnaplójához.

Műveletek

Erőforrás	Műveletek
Szoftverek	`GET/POST /softwares`, `GET/PATCH/DELETE /softwares/{id}` (`include=releases,images,externalLinks,extras`)
Kiadások	`GET/POST /softwares/{softwareId}/releases`, `GET/PATCH/DELETE /releases/{id}`
Kiadási assetek	`GET/POST /releases/{releaseId}/assets`, `GET/PATCH/DELETE /assets/{id}`
Külső linkek	`GET/POST /softwares/{softwareId}/external_links`, `GET/PATCH/DELETE /external_links/{id}`
Szoftverképek	`GET/POST /softwares/{softwareId}/images`, `POST …/images/upload` (multipart), `GET/PATCH/DELETE /software_images/{id}`
További erőforrások	`GET/PATCH /softwares/{softwareId}/extras/{association}` — a hoszt saját rekordjai, lásd lent
Szótár	`/software_statuses`, `/software_categories`, `/platform_links`, mindegyik `GET/POST` és `GET/PATCH/DELETE /{id}`
Letöltések	`GET /downloads`, `GET /downloads/{id}`, `/downloads/summary`, `/downloads/top_files`, `/downloads/top_softwares`, `/softwares/{id}/download_stats`
Pipeline-ok	`GET /pipelines`, `GET/PATCH /pipelines/{id}`, `GET /pipelines/{id}/runs`, `POST /pipelines/{id}/trigger`, `POST /pipelines/sync`
Fájlok	`GET /files?dir=`, `POST /files` (multipart), `POST /files/directories`, `PATCH /files`, `DELETE /files?path=`
Tokenek	`GET/POST /application_tokens`, `GET/PATCH/DELETE /application_tokens/{id}`, `POST /application_tokens/{id}/rotate`, `GET /device_grants[/{id}]`
Meta	`GET /me` — a hívó, a scope-jai és az erőforrások, amiket használhat

A token létrehozása az egyetlen válasz, amelyben benne van a plainToken; többé nem látszik. A hoszt additional_resources elemei akkor jelennek meg az extras alatt, ha a hoszt api_schema-t ad nekik — a teletypegames.org-on ez egy szoftver SEO-metaadata.

OpenAPI

A GET /api/admin/v1/openapi.json (vagy openapi.yaml) ugyanabból a registryből generálódik kérésidőben, amely a kéréseket routolja, így pontosan azt írja le, amit ez a hoszt kiszolgál: a kihagyott erőforrások, a read_only melletti írások, és CI vagy kliensbelépés nélkül a pipeline-ok és az eszközbelépések nincsenek benne. Minden művelet hordozza az x-required-scope-ot, és az operationId egyben az MCP-tool neve. admin:read token kell hozzá, hacsak a hoszt nem tette nyilvánossá.

MCP

c.admin_api.mcp = true mellett a POST /api/admin/v1/mcp állapotmentes Streamable HTTP MCP-szerver — nincs session, nincs stream, kérésenként egy JSON-válasz —, a hivatalos Ruby SDK-ra építve. Ugyanaz a bearer token és ugyanazok a scope-ok érvényesek.

Minden művelet egy tool: software_list, software_update, release_create, pipeline_trigger, download_summary, admin_whoami …, ugyanazzal a JSON Schemával bemenetként és ugyanazzal a válasszal structured contentként. A sikertelen művelet tool-hiba a HTTP-státusszal.
A tools/list csak azt mutatja, amit a token hívhat, a resources, a read_only és a CI- és belépési feltételek után.
A feltöltések kimaradnak, és alapból a tokenerőforrások is: egy friss plain tokennek nincs helye egy modell kontextusában, a transcriptjében és a naplóiban.

TXT

claude mcp add --transport http warp-admin https://teletypegames.org/api/admin/v1/mcp \
  --header "Authorization: Bearer 3f9c…"

Felfedezés

A GET /api/service (WECP) admin kulcsot hordoz: null, amíg az Admin API ki van kapcsolva, különben a verziója, az url, az openapiUrl és az mcpUrl. A címek nyilvánosak; ami mögöttük van, az nem.