{ "openapi": "3.1.0", "info": { "title": "Universal Helm Chart — read API twin", "version": "0.2.0", "summary": "Read-only HTTP twin of the public MCP knowledge surface.", "description": "Mirrors anonymous MCP read tools and helm:// resources for non-MCP clients. Primary agent interface remains Streamable HTTP MCP at https://helm.networkcat89.com/mcp. Chart source of truth: https://github.com/chaser100/u-helm-chart. Write mutations are MCP-only (Bearer); OpenAPI documents write stubs as auth-required only.", "contact": { "name": "Universal Helm Chart", "url": "https://helm.networkcat89.com/docs/connect-agent/" }, "license": { "name": "See chart repository", "url": "https://github.com/chaser100/u-helm-chart" } }, "servers": [ { "url": "https://helm.networkcat89.com", "description": "Public origin (MCP + static discovery docs)" } ], "tags": [ { "name": "read", "description": "Anonymous chart knowledge (same index as MCP read tools)" }, { "name": "discovery", "description": "Spec and health" }, { "name": "write-stub", "description": "Auth-required stubs; prefer MCP write tools" } ], "paths": { "/healthz": { "get": { "operationId": "healthz", "tags": [ "discovery" ], "summary": "Liveness / index freshness", "responses": { "200": { "description": "Service and index status", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Health" } } } } }, "security": [] } }, "/openapi.json": { "get": { "operationId": "getOpenApi", "tags": [ "discovery" ], "summary": "OpenAPI document", "responses": { "200": { "description": "OpenAPI 3.1 document", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } } }, "security": [] } }, "/api/v1/search": { "get": { "operationId": "search_docs", "tags": [ "read" ], "summary": "Search chart documentation", "description": "HTTP twin of MCP tool `search_docs`.", "parameters": [ { "name": "query", "in": "query", "required": true, "schema": { "type": "string", "minLength": 1 } } ], "responses": { "200": { "description": "Search hits", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SearchResponse" } } } }, "400": { "$ref": "#/components/responses/BadRequest" } }, "security": [] } }, "/api/v1/values-schema": { "get": { "operationId": "get_values_schema", "tags": [ "read" ], "summary": "Get chart values JSON schema", "description": "HTTP twin of MCP tool `get_values_schema`.", "parameters": [ { "name": "pointer", "in": "query", "required": false, "schema": { "type": "string" }, "description": "Optional JSON Pointer / values path fragment" }, { "name": "chartVersion", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "chartChannel", "in": "query", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Values schema fragment or document", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "404": { "$ref": "#/components/responses/NotFound" } }, "security": [] } }, "/api/v1/values/explain": { "get": { "operationId": "explain_value", "tags": [ "read" ], "summary": "Explain a values key", "description": "HTTP twin of MCP tool `explain_value`.", "parameters": [ { "name": "path", "in": "query", "required": true, "schema": { "type": "string", "minLength": 1 } }, { "name": "chartVersion", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "chartChannel", "in": "query", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Field explanation", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "$ref": "#/components/responses/NotFound" } }, "security": [] } }, "/api/v1/examples": { "get": { "operationId": "list_examples", "tags": [ "read" ], "summary": "List published chart examples", "description": "HTTP twin of MCP tool `list_examples`.", "parameters": [ { "name": "tag", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "query", "in": "query", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Example catalog", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExamplesResponse" } } } } }, "security": [] } }, "/api/v1/examples/{id}": { "get": { "operationId": "get_example", "tags": [ "read" ], "summary": "Get a published chart example", "description": "HTTP twin of MCP tool `get_example` (by id). Prefer query `name` on `/api/v1/examples` list first.", "parameters": [ { "name": "id", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Example body", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "404": { "$ref": "#/components/responses/NotFound" } }, "security": [] } }, "/api/v1/checklist": { "get": { "operationId": "get_checklist", "tags": [ "read" ], "summary": "Get the production checklist", "description": "HTTP twin of MCP tool `get_checklist`.", "parameters": [ { "name": "id", "in": "query", "required": false, "schema": { "type": "string", "default": "production" } } ], "responses": { "200": { "description": "Checklist document", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "404": { "$ref": "#/components/responses/NotFound" } }, "security": [] } }, "/api/v1/shapes": { "get": { "operationId": "list_shapes", "tags": [ "read" ], "summary": "List supported workload shapes", "description": "HTTP twin of MCP tool `list_shapes`.", "responses": { "200": { "description": "Shape catalog", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ShapesResponse" } } } } }, "security": [] } }, "/api/v1/shapes/{name}": { "get": { "operationId": "get_shape", "tags": [ "read" ], "summary": "Get a workload shape", "description": "HTTP twin of MCP tool `get_shape`.", "parameters": [ { "name": "name", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Shape document", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": true } } } }, "404": { "$ref": "#/components/responses/NotFound" } }, "security": [] } }, "/api/v1/resources": { "get": { "operationId": "resolve_resource", "tags": [ "read" ], "summary": "Resolve a helm:// resource URI", "description": "HTTP twin of MCP tool `resolve_resource` / MCP `resources/read`.", "parameters": [ { "name": "uri", "in": "query", "required": true, "schema": { "type": "string", "pattern": "^helm://" }, "example": "helm://catalog" } ], "responses": { "200": { "description": "Resource payload", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResourceBody" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "404": { "$ref": "#/components/responses/NotFound" } }, "security": [] } }, "/api/v1/propose-improvement": { "post": { "operationId": "propose_improvement", "tags": [ "write-stub" ], "summary": "Propose a chart improvement (auth required)", "description": "Stub only. Prefer MCP tool `propose_improvement` with Bearer. Unauthenticated calls return 401.", "security": [ { "bearerAuth": [] } ], "responses": { "401": { "$ref": "#/components/responses/Unauthorized" }, "501": { "description": "HTTP write twin is not offered; use MCP write tools with Bearer.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "202": { "description": "Reserved. Writes are MCP-only; HTTP stubs do not mutate state.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/api/v1/feature-branch-pr": { "post": { "operationId": "open_feature_branch_pr", "tags": [ "write-stub" ], "summary": "Open mcp/** draft PR (auth required)", "description": "Stub only. Prefer MCP tool `open_feature_branch_pr` with Bearer. Unauthenticated calls return 401.", "security": [ { "bearerAuth": [] } ], "responses": { "401": { "$ref": "#/components/responses/Unauthorized" }, "501": { "description": "HTTP write twin is not offered; use MCP write tools with Bearer.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "202": { "description": "Reserved. Writes are MCP-only; HTTP stubs do not mutate state.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } } }, "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "description": "Required for write tools. Read paths are anonymous." } }, "schemas": { "Health": { "type": "object", "required": [ "status" ], "properties": { "status": { "type": "string", "enum": [ "ok", "degraded" ] }, "indexBuiltAt": { "type": "string", "format": "date-time" }, "indexChartVersion": { "type": "string" }, "indexChartName": { "type": "string" }, "indexChannel": { "type": "string" }, "resourceCount": { "type": "integer" } }, "additionalProperties": true }, "SearchResponse": { "type": "object", "properties": { "query": { "type": "string" }, "hits": { "type": "array", "items": { "type": "object", "additionalProperties": true } } }, "additionalProperties": true }, "ExamplesResponse": { "type": "object", "properties": { "examples": { "type": "array", "items": { "type": "object", "additionalProperties": true } } }, "additionalProperties": true }, "ShapesResponse": { "type": "object", "properties": { "shapes": { "type": "array", "items": { "type": "object", "additionalProperties": true } } }, "additionalProperties": true }, "ResourceBody": { "type": "object", "properties": { "uri": { "type": "string" }, "mimeType": { "type": "string" }, "text": { "type": "string" } }, "additionalProperties": true }, "Error": { "type": "object", "properties": { "error": { "type": "string" }, "detail": { "type": "string" }, "message": { "type": "string" } }, "additionalProperties": true } }, "responses": { "BadRequest": { "description": "Invalid arguments", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "NotFound": { "description": "Unknown resource or key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "Unauthorized": { "description": "Bearer required for write", "headers": { "WWW-Authenticate": { "schema": { "type": "string" }, "example": "Bearer realm=\"helm-mcp-write\"" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }