{
  "openapi": "3.1.0",
  "info": {
    "title": "Kingshot Alliance Command API",
    "version": "1.0.0",
    "summary": "MCP server and OAuth endpoints for the Kingshot Alliance Command reference data and your own account.",
    "description": "The public, agent-facing API of Kingshot Alliance Command (kingshotcommand.com), a free, independent companion app for the mobile strategy game Kingshot.\n\nThe API is a Model Context Protocol (MCP) server over Streamable HTTP. It is stateless: every `POST` carries one complete JSON-RPC 2.0 message and gets a plain JSON response. There are no session ids and no server-initiated streams.\n\n- `POST /mcp`: public and read-only, no account needed. Tools: `search_database`, `get_hero`, `get_master`, `get_item`, `get_event`, `get_tier_list`, `governor_gear_cost`, `governor_charm_cost`, `truegold_upgrade_cost`, `hero_shards_cost`, `mastery_forging_cost`.\n- `POST /mcp/account`: the same tools plus `get_my_profile`, `get_my_goals`, `get_my_inventory`, read-only access to the signed-in player's own data. Needs an OAuth 2.1 bearer token (dynamic client registration, PKCE S256, user consent).\n\nCall `tools/list` for each tool's full JSON Schema. Rate limit: 60 requests per minute per client (per user on `/mcp/account`); over the limit you get `429`.\n\n## Versioning and deprecation\n\n- The protocol is versioned by the `MCP-Protocol-Version` header, negotiated in `initialize`. Supported: `2025-11-25`, `2025-06-18`, `2025-03-26`, `2024-11-05`, `2024-10-07`.\n- Tools are versioned with the server (`info.version`, also `serverInfo.version` in `initialize`). Adding a tool, or an optional argument or result field, isn't a breaking change.\n- Before a breaking change (a tool removed or renamed, a required argument added, a result field removed), affected responses carry a `Deprecation` header (RFC 9745) and a `Sunset` header (RFC 8594) with a date at least 90 days later, and the change is listed on the developer page.\n\n## Retries\n\nEvery tool is read-only, so any request can be retried safely. An optional `Idempotency-Key` header is accepted.\n\nDeveloper guide: https://www.kingshotcommand.com/developers",
    "contact": {
      "name": "Kingshot Alliance Command support",
      "email": "support@kingshotcommand.com",
      "url": "https://www.kingshotcommand.com/contact"
    }
  },
  "externalDocs": {
    "description": "Kingshot Alliance Command developer docs",
    "url": "https://www.kingshotcommand.com/developers"
  },
  "servers": [
    {
      "url": "https://api.kingshotcommand.com",
      "description": "Production"
    }
  ],
  "tags": [
    {
      "name": "MCP",
      "description": "Model Context Protocol endpoints (JSON-RPC 2.0 over Streamable HTTP)."
    },
    {
      "name": "OAuth discovery",
      "description": "RFC 9728 and RFC 8414 metadata documents used by MCP clients to find the authorization server."
    }
  ],
  "paths": {
    "/mcp": {
      "post": {
        "tags": ["MCP"],
        "operationId": "callPublicMcp",
        "summary": "Public MCP server (no account)",
        "description": "Send one JSON-RPC 2.0 message: `initialize`, `tools/list`, `tools/call`, `resources/list`, or `resources/read`. All tools are read-only. Clients must accept both `application/json` and `text/event-stream`; responses are always `application/json`.",
        "security": [],
        "parameters": [
          {
            "$ref": "#/components/parameters/Accept"
          },
          {
            "$ref": "#/components/parameters/McpProtocolVersion"
          },
          {
            "$ref": "#/components/parameters/IdempotencyKey"
          }
        ],
        "requestBody": {
          "$ref": "#/components/requestBodies/JsonRpcRequest"
        },
        "responses": {
          "200": {
            "$ref": "#/components/responses/JsonRpcResponse"
          },
          "202": {
            "description": "Accepted. Returned for a JSON-RPC notification, which has no response body."
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/mcp/account": {
      "post": {
        "tags": ["MCP"],
        "operationId": "callAccountMcp",
        "summary": "Account MCP server (OAuth)",
        "description": "The public tools plus read-only access to the signed-in player's own data: `get_my_profile`, `get_my_goals`, `get_my_inventory`. Without a valid token the response is `401` with a `WWW-Authenticate` header whose `resource_metadata` points at the Protected Resource Metadata document.",
        "security": [
          {
            "oauth2": []
          }
        ],
        "parameters": [
          {
            "$ref": "#/components/parameters/Accept"
          },
          {
            "$ref": "#/components/parameters/McpProtocolVersion"
          },
          {
            "$ref": "#/components/parameters/IdempotencyKey"
          }
        ],
        "requestBody": {
          "$ref": "#/components/requestBodies/JsonRpcRequest"
        },
        "responses": {
          "200": {
            "$ref": "#/components/responses/JsonRpcResponse"
          },
          "202": {
            "description": "Accepted. Returned for a JSON-RPC notification, which has no response body."
          },
          "400": {
            "$ref": "#/components/responses/BadRequest"
          },
          "401": {
            "description": "Missing, expired, or invalid access token.",
            "headers": {
              "WWW-Authenticate": {
                "description": "Bearer challenge naming the Protected Resource Metadata URL.",
                "schema": {
                  "type": "string",
                  "example": "Bearer resource_metadata=\"https://api.kingshotcommand.com/.well-known/oauth-protected-resource/mcp/account\""
                }
              }
            },
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/JsonRpcError"
                }
              }
            }
          },
          "429": {
            "$ref": "#/components/responses/RateLimited"
          }
        }
      }
    },
    "/.well-known/oauth-protected-resource/mcp/account": {
      "get": {
        "tags": ["OAuth discovery"],
        "operationId": "getProtectedResourceMetadata",
        "summary": "Protected Resource Metadata (RFC 9728)",
        "description": "Names the authorization server and the scopes the account MCP server accepts.",
        "security": [],
        "responses": {
          "200": {
            "description": "Protected Resource Metadata.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/ProtectedResourceMetadata"
                },
                "example": {
                  "resource": "https://api.kingshotcommand.com/mcp/account",
                  "resource_name": "Kingshot Alliance Command (your account)",
                  "authorization_servers": ["https://api.kingshotcommand.com"],
                  "bearer_methods_supported": ["header"],
                  "scopes_supported": [
                    "openid",
                    "profile",
                    "email",
                    "offline_access"
                  ],
                  "resource_documentation": "https://www.kingshotcommand.com/developers"
                }
              }
            }
          }
        }
      }
    },
    "/.well-known/oauth-authorization-server": {
      "get": {
        "tags": ["OAuth discovery"],
        "operationId": "getAuthorizationServerMetadata",
        "summary": "Authorization Server Metadata (RFC 8414)",
        "description": "Authorization, token, and dynamic client registration endpoints, supported grants, and scopes.",
        "security": [],
        "responses": {
          "200": {
            "description": "Authorization Server Metadata.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "additionalProperties": true,
                  "properties": {
                    "issuer": {
                      "type": "string",
                      "format": "uri"
                    },
                    "authorization_endpoint": {
                      "type": "string",
                      "format": "uri"
                    },
                    "token_endpoint": {
                      "type": "string",
                      "format": "uri"
                    },
                    "registration_endpoint": {
                      "type": "string",
                      "format": "uri"
                    },
                    "scopes_supported": {
                      "type": "array",
                      "items": {
                        "type": "string"
                      }
                    },
                    "code_challenge_methods_supported": {
                      "type": "array",
                      "items": {
                        "type": "string"
                      }
                    },
                    "grant_types_supported": {
                      "type": "array",
                      "items": {
                        "type": "string"
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "oauth2": {
        "type": "oauth2",
        "description": "OAuth 2.1 authorization code flow with PKCE (S256 only). Clients register themselves at the registration endpoint (RFC 7591), then send the user to the authorization endpoint, where they sign in and approve the app on a consent page. Any token the user approves grants the same fixed, read-only access to the account MCP server: the player's own profile, active Progression Goals, and saved inventory. It can't change account data, read alliance data, or spend AI Credits. The scopes below only control what goes into the ID token and whether a refresh token is issued, so for least privilege request `openid` (add `offline_access` to stay connected).",
        "flows": {
          "authorizationCode": {
            "authorizationUrl": "https://api.kingshotcommand.com/api/auth/mcp/authorize",
            "tokenUrl": "https://api.kingshotcommand.com/api/auth/mcp/token",
            "refreshUrl": "https://api.kingshotcommand.com/api/auth/mcp/token",
            "scopes": {
              "openid": "Sign the user in and get an ID token identifying them. Enough to call the account MCP server.",
              "profile": "Add the user's account name to the ID token.",
              "email": "Add the user's email address to the ID token. No tool needs it.",
              "offline_access": "Issue a refresh token so the client stays connected without asking the user to sign in again."
            }
          }
        }
      }
    },
    "parameters": {
      "Accept": {
        "name": "Accept",
        "in": "header",
        "required": true,
        "description": "Streamable HTTP clients must list both media types.",
        "schema": {
          "type": "string",
          "example": "application/json, text/event-stream"
        }
      },
      "McpProtocolVersion": {
        "name": "MCP-Protocol-Version",
        "in": "header",
        "required": false,
        "description": "The API's version header: the MCP protocol version the client negotiated in `initialize`. An unsupported version gets a `400`. Omitted, the server assumes `2025-03-26`.",
        "schema": {
          "type": "string",
          "enum": [
            "2025-11-25",
            "2025-06-18",
            "2025-03-26",
            "2024-11-05",
            "2024-10-07"
          ],
          "example": "2025-11-25"
        }
      },
      "IdempotencyKey": {
        "name": "Idempotency-Key",
        "in": "header",
        "required": false,
        "description": "Optional client-chosen key for safe retries (for example a UUID). Every tool is read-only, so retrying a request, with or without the same key, never creates, changes, or charges anything.",
        "schema": {
          "type": "string",
          "maxLength": 255,
          "example": "5f1c2a8e-3b4d-4e6f-9a0b-1c2d3e4f5a6b"
        }
      }
    },
    "requestBodies": {
      "JsonRpcRequest": {
        "required": true,
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/JsonRpcRequest"
            },
            "examples": {
              "listTools": {
                "summary": "List the available tools",
                "value": {
                  "jsonrpc": "2.0",
                  "id": 1,
                  "method": "tools/list"
                }
              },
              "searchDatabase": {
                "summary": "Search the hero database",
                "value": {
                  "jsonrpc": "2.0",
                  "id": 2,
                  "method": "tools/call",
                  "params": {
                    "name": "search_database",
                    "arguments": {
                      "query": "amadeus",
                      "kind": "heroes"
                    }
                  }
                }
              },
              "governorGearCost": {
                "summary": "Governor Gear upgrade cost",
                "value": {
                  "jsonrpc": "2.0",
                  "id": 3,
                  "method": "tools/call",
                  "params": {
                    "name": "governor_gear_cost",
                    "arguments": {
                      "from": "Gold ★0",
                      "to": "Gold T2 ★3"
                    }
                  }
                }
              },
              "tierList": {
                "summary": "Hero tier list for a role",
                "value": {
                  "jsonrpc": "2.0",
                  "id": 4,
                  "method": "tools/call",
                  "params": {
                    "name": "get_tier_list",
                    "arguments": {
                      "role": "bear_rally_lead",
                      "generation": 3
                    }
                  }
                }
              }
            }
          }
        }
      }
    },
    "responses": {
      "JsonRpcResponse": {
        "description": "A JSON-RPC 2.0 response. Tool results are in `result.content`, as text holding JSON; tool errors set `result.isError`.",
        "content": {
          "application/json": {
            "schema": {
              "oneOf": [
                {
                  "$ref": "#/components/schemas/JsonRpcResult"
                },
                {
                  "$ref": "#/components/schemas/JsonRpcError"
                }
              ]
            }
          }
        },
        "headers": {
          "Deprecation": {
            "$ref": "#/components/headers/Deprecation"
          },
          "Sunset": {
            "$ref": "#/components/headers/Sunset"
          }
        }
      },
      "RateLimited": {
        "description": "Rate limit exceeded (60 requests per minute).",
        "content": {
          "application/json": {
            "schema": {
              "type": "object",
              "properties": {
                "code": {
                  "type": "string",
                  "const": "RATE_LIMITED"
                },
                "message": {
                  "type": "string"
                }
              }
            }
          }
        }
      },
      "BadRequest": {
        "description": "Unsupported `MCP-Protocol-Version`, or a malformed JSON-RPC message.",
        "content": {
          "application/json": {
            "schema": {
              "$ref": "#/components/schemas/JsonRpcError"
            }
          }
        }
      }
    },
    "schemas": {
      "JsonRpcRequest": {
        "type": "object",
        "required": ["jsonrpc", "method"],
        "properties": {
          "jsonrpc": {
            "type": "string",
            "const": "2.0"
          },
          "id": {
            "description": "Omit for a notification.",
            "oneOf": [
              {
                "type": "string"
              },
              {
                "type": "integer"
              }
            ]
          },
          "method": {
            "type": "string",
            "examples": [
              "initialize",
              "tools/list",
              "tools/call",
              "resources/list",
              "resources/read"
            ]
          },
          "params": {
            "type": "object",
            "additionalProperties": true,
            "properties": {
              "name": {
                "type": "string",
                "description": "Tool name, for `tools/call`.",
                "enum": [
                  "search_database",
                  "get_hero",
                  "get_master",
                  "get_item",
                  "get_event",
                  "get_tier_list",
                  "governor_gear_cost",
                  "governor_charm_cost",
                  "truegold_upgrade_cost",
                  "hero_shards_cost",
                  "mastery_forging_cost",
                  "get_my_profile",
                  "get_my_goals",
                  "get_my_inventory"
                ]
              },
              "arguments": {
                "type": "object",
                "additionalProperties": true,
                "description": "Tool arguments. See each tool's `inputSchema` in the `tools/list` result."
              }
            }
          }
        }
      },
      "JsonRpcResult": {
        "type": "object",
        "required": ["jsonrpc", "result"],
        "properties": {
          "jsonrpc": {
            "type": "string",
            "const": "2.0"
          },
          "id": {
            "oneOf": [
              {
                "type": "string"
              },
              {
                "type": "integer"
              }
            ]
          },
          "result": {
            "type": "object",
            "additionalProperties": true,
            "properties": {
              "content": {
                "type": "array",
                "items": {
                  "type": "object",
                  "properties": {
                    "type": {
                      "type": "string"
                    },
                    "text": {
                      "type": "string"
                    }
                  }
                }
              },
              "isError": {
                "type": "boolean"
              }
            }
          }
        }
      },
      "JsonRpcError": {
        "type": "object",
        "required": ["jsonrpc", "error"],
        "properties": {
          "jsonrpc": {
            "type": "string",
            "const": "2.0"
          },
          "id": {
            "oneOf": [
              {
                "type": "string"
              },
              {
                "type": "integer"
              },
              {
                "type": "null"
              }
            ]
          },
          "error": {
            "type": "object",
            "required": ["code", "message"],
            "properties": {
              "code": {
                "type": "integer"
              },
              "message": {
                "type": "string"
              }
            }
          }
        }
      },
      "ProtectedResourceMetadata": {
        "type": "object",
        "required": ["resource", "authorization_servers"],
        "properties": {
          "resource": {
            "type": "string",
            "format": "uri"
          },
          "resource_name": {
            "type": "string"
          },
          "authorization_servers": {
            "type": "array",
            "items": {
              "type": "string",
              "format": "uri"
            }
          },
          "bearer_methods_supported": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "scopes_supported": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "resource_documentation": {
            "type": "string",
            "format": "uri"
          }
        }
      }
    },
    "headers": {
      "Deprecation": {
        "description": "Present when the endpoint, or a tool called in this request, is deprecated (RFC 9745). Value: when it was deprecated, as `@<unix-seconds>`.",
        "schema": {
          "type": "string",
          "example": "@1798761600"
        }
      },
      "Sunset": {
        "description": "When a deprecated endpoint or tool stops working (RFC 8594), at least 90 days after the Deprecation date.",
        "schema": {
          "type": "string",
          "example": "Tue, 01 Jun 2027 00:00:00 GMT"
        }
      }
    }
  },
  "x-api-lifecycle": {
    "versioning": "header",
    "versionHeader": "MCP-Protocol-Version",
    "deprecationHeaders": ["Deprecation", "Sunset"],
    "minimumSunsetNoticeDays": 90,
    "policyUrl": "https://www.kingshotcommand.com/developers#versioning"
  }
}