{
  "cells": [
    {
      "cell_type": "markdown",
      "id": "welcome",
      "metadata": {},
      "source": [
        "# Super ii API and MCP quickstart\n",
        "\n",
        "Read Super ii's production system-state contract and perform a public MCP handshake using only Python's standard library. This notebook sends no credentials and does not execute repository content."
      ]
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "id": "helpers",
      "metadata": {},
      "outputs": [],
      "source": [
        "import json\n",
        "from urllib.request import Request, urlopen\n",
        "\n",
        "ORIGIN = \"https://superii.site\"\n",
        "\n",
        "def get_json(path):\n",
        "    request = Request(f\"{ORIGIN}{path}\", headers={\"Accept\": \"application/json\"})\n",
        "    with urlopen(request, timeout=20) as response:\n",
        "        return json.load(response)"
      ]
    },
    {
      "cell_type": "markdown",
      "id": "system-state-note",
      "metadata": {},
      "source": [
        "## Read capability truth\n",
        "\n",
        "The system-state resource separates implementation status from present availability. Do not infer that a feature is generally available merely because its code exists."
      ]
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "id": "system-state",
      "metadata": {},
      "outputs": [],
      "source": [
        "state = get_json(\"/system-state.json\")\n",
        "print(f\"Snapshot: {state['snapshot']}\")\n",
        "for capability in state['capabilities'][:6]:\n",
        "    print(f\"- {capability['capability']}: {capability['status']} / {capability['availability']}\")"
      ]
    },
    {
      "cell_type": "markdown",
      "id": "mcp-note",
      "metadata": {},
      "source": [
        "## Initialize the public MCP endpoint\n",
        "\n",
        "Super ii's MCP surface is public, stateless, and read-only. The response may use JSON or Server-Sent Events, so the helper handles both representations."
      ]
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "id": "mcp-helper",
      "metadata": {},
      "outputs": [],
      "source": [
        "def mcp_request(method, params=None, request_id=1):\n",
        "    payload = {\"jsonrpc\": \"2.0\", \"id\": request_id, \"method\": method}\n",
        "    if params is not None:\n",
        "        payload[\"params\"] = params\n",
        "    request = Request(\n",
        "        f\"{ORIGIN}/mcp\",\n",
        "        data=json.dumps(payload).encode(\"utf-8\"),\n",
        "        headers={\n",
        "            \"Accept\": \"application/json, text/event-stream\",\n",
        "            \"Content-Type\": \"application/json\",\n",
        "            \"MCP-Protocol-Version\": \"2025-06-18\",\n",
        "        },\n",
        "        method=\"POST\",\n",
        "    )\n",
        "    with urlopen(request, timeout=20) as response:\n",
        "        body = response.read().decode(\"utf-8\")\n",
        "        content_type = response.headers.get(\"content-type\", \"\")\n",
        "    if \"text/event-stream\" in content_type:\n",
        "        events = [line[6:] for line in body.splitlines() if line.startswith(\"data: \")]\n",
        "        if not events:\n",
        "            raise RuntimeError(\"MCP response did not contain a data event\")\n",
        "        body = events[-1]\n",
        "    return json.loads(body)"
      ]
    },
    {
      "cell_type": "code",
      "execution_count": null,
      "id": "mcp-initialize",
      "metadata": {},
      "outputs": [],
      "source": [
        "handshake = mcp_request(\n",
        "    \"initialize\",\n",
        "    {\n",
        "        \"protocolVersion\": \"2025-06-18\",\n",
        "        \"capabilities\": {},\n",
        "        \"clientInfo\": {\"name\": \"super-ii-official-notebook\", \"version\": \"1.0\"},\n",
        "    },\n",
        ")\n",
        "print(json.dumps(handshake.get(\"result\", handshake), indent=2)[:2000])"
      ]
    },
    {
      "cell_type": "markdown",
      "id": "next",
      "metadata": {},
      "source": [
        "## Next steps\n",
        "\n",
        "Use `/api/search?kind=model`, `/api/search?kind=dataset`, or `/api/search?kind=space` for bounded public discovery. Every reviewed repository publishes immutable checksums and machine-readable README, agents, manifest, API, and MCP representations. The catalogs may truthfully return zero items until the first reviewed upload is approved."
      ]
    }
  ],
  "metadata": {
    "kernelspec": {
      "display_name": "Python 3",
      "language": "python",
      "name": "python3"
    },
    "language_info": {
      "name": "python",
      "version": "3.12"
    }
  },
  "nbformat": 4,
  "nbformat_minor": 5
}