astrocade-creator-mcp 0.1.0__tar.gz

astrocade_creator_mcp-0.1.0/PKG-INFO

@@ -0,0 +1,58 @@
+Metadata-Version: 2.4
+Name: astrocade-creator-mcp
+Version: 0.1.0
+Summary: Astrocade Creator MCP — pull and edit your Astrocade games locally over MCP (stdio).
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+Requires-Dist: mcp>=1.11.0
+Requires-Dist: pydantic>=2
+Requires-Dist: PyJWT[crypto]>=2.10
+Requires-Dist: requests
+Requires-Dist: aiohttp
+Requires-Dist: html5lib
+Requires-Dist: beautifulsoup4
+Requires-Dist: esprima
+Requires-Dist: tinycss2
+Provides-Extra: dev
+Requires-Dist: pytest; extra == "dev"
+Requires-Dist: pytest-asyncio; extra == "dev"
+Requires-Dist: mypy; extra == "dev"
+
+# Astrocade Creator MCP
+
+A local (stdio) [MCP](https://modelcontextprotocol.io) server that lets a creator pull, edit,
+push, and publish the games already on their Astrocade account — as ordinary local files.
+
+## Install & run
+
+```bash
+uvx astrocade-creator-mcp
+# or
+pip install astrocade-creator-mcp && astrocade-creator-mcp
+```
+
+Targets **prod** by default — a creator sets nothing. To point at stage instead, set
+`ASTROCADE_CREATOR_MCP_ENV=stage`.
+
+### Sign-in
+
+Nothing to configure. The **first tool call** opens a browser for Cognito (Google) login, caches
+the tokens under `~/.astrocade`, and silently refreshes them afterward. Login is lazy (not at
+startup) so the browser flow never blocks the MCP stdio handshake.
+
+Optional — sign in ahead of time so the first call has no delay:
+```bash
+astrocade-creator-mcp login
+```
+Token cache dir: `~/.astrocade` (override with `ASTROCADE_TOKEN_CACHE_DIR`).
+
+## Tools
+
+- `list_my_games` — your games (drafts included).
+- `pull_game` / `push_game` — check a game out (files + metadata, as JSON), save edits back as a draft. `push_game` can also update metadata (`title`, `description`, `thumbnail_url`).
+- `preview_game` — publish the draft and get a playable URL.
+- `check_wish_status` — poll an AI "wish" that's in flight (wishes are submitted on astrocade.com; `push_game`/`pull_game` surface the request id when one is running).
+- `list_lib_apis` / `get_lib_api` — browse the Astrocade `lib` API reference.
+
+Optional JavaScript validation via ESLint runs on push/preview when `eslint` is on `PATH`;
+it's skipped (non-fatal) otherwise.

astrocade_creator_mcp-0.1.0/README.md

@@ -0,0 +1,38 @@
+# Astrocade Creator MCP
+
+A local (stdio) [MCP](https://modelcontextprotocol.io) server that lets a creator pull, edit,
+push, and publish the games already on their Astrocade account — as ordinary local files.
+
+## Install & run
+
+```bash
+uvx astrocade-creator-mcp
+# or
+pip install astrocade-creator-mcp && astrocade-creator-mcp
+```
+
+Targets **prod** by default — a creator sets nothing. To point at stage instead, set
+`ASTROCADE_CREATOR_MCP_ENV=stage`.
+
+### Sign-in
+
+Nothing to configure. The **first tool call** opens a browser for Cognito (Google) login, caches
+the tokens under `~/.astrocade`, and silently refreshes them afterward. Login is lazy (not at
+startup) so the browser flow never blocks the MCP stdio handshake.
+
+Optional — sign in ahead of time so the first call has no delay:
+```bash
+astrocade-creator-mcp login
+```
+Token cache dir: `~/.astrocade` (override with `ASTROCADE_TOKEN_CACHE_DIR`).
+
+## Tools
+
+- `list_my_games` — your games (drafts included).
+- `pull_game` / `push_game` — check a game out (files + metadata, as JSON), save edits back as a draft. `push_game` can also update metadata (`title`, `description`, `thumbnail_url`).
+- `preview_game` — publish the draft and get a playable URL.
+- `check_wish_status` — poll an AI "wish" that's in flight (wishes are submitted on astrocade.com; `push_game`/`pull_game` surface the request id when one is running).
+- `list_lib_apis` / `get_lib_api` — browse the Astrocade `lib` API reference.
+
+Optional JavaScript validation via ESLint runs on push/preview when `eslint` is on `PATH`;
+it's skipped (non-fatal) otherwise.

astrocade_creator_mcp-0.1.0/pyproject.toml

@@ -0,0 +1,41 @@
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "astrocade-creator-mcp"
+version = "0.1.0"
+description = "Astrocade Creator MCP — pull and edit your Astrocade games locally over MCP (stdio)."
+readme = "README.md"
+requires-python = ">=3.12"
+dependencies = [
+    "mcp>=1.11.0",
+    "pydantic>=2",
+    "PyJWT[crypto]>=2.10",
+    "requests",
+    "aiohttp",
+    "html5lib",
+    "beautifulsoup4",
+    "esprima",
+    "tinycss2",
+]
+
+[project.optional-dependencies]
+dev = ["pytest", "pytest-asyncio", "mypy"]
+
+[project.scripts]
+astrocade-creator-mcp = "astrocade_creator_mcp.stdio_main:main"
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+astrocade_creator_mcp = ["eslint.config.js", "astrolib/*.md"]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+pythonpath = ["src"]
+
+[tool.mypy]
+python_version = "3.12"
+ignore_missing_imports = true

astrocade_creator_mcp-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

astrocade_creator_mcp-0.1.0/src/astrocade_creator_mcp/__init__.py

@@ -0,0 +1,4 @@
+"""Astrocade Creator MCP — let creators pull and edit their existing games via MCP.
+
+A slim, self-contained package serving the Creator tools over the local stdio transport.
+"""

astrocade_creator_mcp-0.1.0/src/astrocade_creator_mcp/astrolib/lib-api-reference-animation.md

@@ -0,0 +1,38 @@
+## ANIMATION
+
+### `AnimationPlayer` (Object)
+
+- **update** `function(number): void` — Advances animation based on timestamp
+- **draw** `function(CanvasRenderingContext2D, number, number, number, number): void` — Draws current frame
+- **getCurrentFrame** `function(): {index: number, frame: {x: number, y: number, w: number, h: number}|undefined, total: number}` — Gets current frame info
+- **reset** `function(): void` — Resets animation to first frame
+
+Creates an animation player for sprite sheet animations.
+The assetId should reference an asset with animation data.
+- **assetId** (`string`): The animation asset ID
+
+**Returns:** `AnimationPlayer|null` — The animation player, or null if not found
+
+**Example:**
+```js
+const anim = lib.getAnimationPlayer('player_run');
+function gameLoop(timestamp) {
+  anim.update(timestamp);
+  anim.draw(ctx, x, y, 64, 64);
+  requestAnimationFrame(gameLoop);
+}
+```
+
+```js
+lib.getAnimationPlayer = function(assetId) {};
+```
+
+Preloads an animation's sprite sheet for smoother playback.
+Call during initialization to avoid loading delays.
+- **assetId** (`string`): The animation asset ID
+
+**Returns:** `Promise<void>`
+
+```js
+lib.preloadAnimation = async function(assetId) {};
+```

astrocade_creator_mcp-0.1.0/src/astrocade_creator_mcp/astrolib/lib-api-reference-base.md

@@ -0,0 +1,170 @@
+============================================================================
+ASTROCADE LIBRARY (lib) - API REFERENCE
+============================================================================
+
+The lib object is automatically available in your game code via "lib"
+This is READ-ONLY reference documentation - lib code is owned by Astrocade.
+
+Your game's entry point:
+
+```js
+  function run(mode) {
+    // mode is 'edit' or 'play'
+    // window.gameConfig is already set up before run() is called
+  }
+```
+
+If you remove this function the game will not run.
+
+## TYPE DEFINITIONS
+
+### `LeaderboardEntry` (Object)
+
+- **username** `string` — The player's username
+- **profilePicture** `string|null` — URL to profile picture, or null
+- **score** `number` — The player's score
+
+### `LeaderboardResponse` (Object)
+
+- **entries** `LeaderboardEntry[]` — Array of leaderboard entries
+- **userRank** `number|null` — Current user's rank, or null if not ranked
+- **[success]** `boolean` — Whether the operation succeeded
+
+### `UserGameStateResponse` (Object)
+
+- **userId** `string` — The user's ID
+- **gameId** `string` — The game's ID
+- **state** `Object|null` — The saved state, or null if none exists
+- **[success]** `boolean` — Whether the operation succeeded
+
+## GLOBALS
+
+The game's configuration state.
+Automatically available before run() is called.
+In edit mode, changes are tracked for undo/redo.
+
+*Type:* `Object`
+
+```js
+var gameConfig = window.gameConfig;
+```
+
+Current game mode. Use to conditionally enable editor features.
+
+*Type:* `'edit' | 'play'`
+
+```js
+var mode = window.mode;
+```
+
+## CORE FUNCTIONS
+
+Retrieves an asset by its ID from the asset map.
+- **id** (`string`): The asset ID
+
+**Returns:** `Object|undefined` — The asset object with these properties, or undefined if not found:
+  - url: CDN URL for the asset
+  - type: "image", "audio", or "animation"
+  - aspect_ratio: [width, height] ratio (e.g., [1536, 1024]) - images only
+  - size_hint: suggested display size - images only
+  - view: perspective hint (e.g., "top-down", "side-view", "front-view") - images only
+  - outline: collision/selection shape - images only
+  - box: { type: "box", center: [x, y], size: [w, h] }
+  - circle: { type: "circle", center: [x, y], radius: r }
+  - polygon: { type: "polygon", points: [[x, y], ...] }
+  - loop: "true" or "false" - whether audio should repeat - audio only
+  - duration_secs: duration in seconds - audio only
+
+```js
+lib.getAsset = function(id) {};
+```
+
+Debug logging. Messages are forwarded to the host environment console.
+- **message** (`string`): The message to log
+
+```js
+lib.log = function(message) {};
+```
+
+Displays a game-wide settings panel in the host UI.
+Call once in run() to register persistent game parameters.
+- **options.name** (`string`): Display name for the settings panel
+- **options.params** (`Object`): Map of display names to parameter configs
+Each param config has:
+  - key: path into gameConfig (e.g., 'settings.difficulty')
+  - type: 'slider' | 'dropdown' | 'color' | 'checkbox' | 'string' | 'number'
+  - min, max, step: for 'slider' type
+  - options: [{label, value}] for 'dropdown' type
+  - onChange(value): optional callback; if omitted, auto-updates gameConfig at key
+
+```js
+lib.showGameParameters = function(options) {};
+```
+
+## LEADERBOARD
+
+Submits the current player's score to the game's leaderboard.
+Throws if game is not saved or user is not authenticated.
+- **score** (`number`): The player's score
+- **numEntries** (`number`, optional): Optional: number of top entries to return
+
+**Returns:** `Promise<LeaderboardResponse>`
+
+```js
+lib.addPlayerScoreToLeaderboard = async function(score, numEntries) {};
+```
+
+Retrieves the top N entries from the game's leaderboard.
+- **numEntries** (`number`, optional): Optional: number of entries to retrieve
+
+**Returns:** `Promise<LeaderboardResponse>`
+
+```js
+lib.getTopNEntriesFromLeaderboard = async function(numEntries) {};
+```
+
+## USER GAME STATE (Save/Load)
+
+Persists the user's game progress to the server.
+State must be JSON-serializable (no functions, circular refs, etc).
+Each user has one save slot per game; always pass the full latest state
+(the slot is overwritten, not merged).
+Call whenever meaningful state changes — level complete, item earned,
+settings changed, or a short settle after the player stops interacting.
+Keep state compact and bounded — store what's needed to resume, and never let
+a saved array (inventory, history, gallery) grow without a cap.
+- **state** (`Object`): The full game state to save
+
+**Returns:** `Promise<UserGameStateResponse>`
+
+```js
+lib.saveUserGameState = async function(state) {};
+```
+
+Retrieves the user's previously saved game state.
+
+**Returns:** `Promise<UserGameStateResponse>`
+
+```js
+lib.getUserGameState = async function() {};
+```
+
+Deletes the user's saved game state.
+Use for "New Game" or reset functionality.
+
+**Returns:** `Promise<{success: boolean}>`
+
+```js
+lib.deleteUserGameState = async function() {};
+```
+
+## DEVICE DETECTION
+
+Detects whether touch controls should be used.
+Returns true on mobile/tablet devices (coarse pointer or no hover).
+
+**Returns:** `boolean` — true if touch controls are appropriate
+
+```js
+lib.shouldUseTouchControls = function() {};
+```

astrocade_creator_mcp-0.1.0/src/astrocade_creator_mcp/astrolib/lib-api-reference-llm.md

@@ -0,0 +1,52 @@
+## LLM (Chat Completions)
+
+### `LlmMessage` (Object)
+
+- **role** `'user' | 'assistant'` — Speaker for this turn
+- **content** `string` — Message text
+
+### `LlmConfig` (Object)
+
+- **[temperature]** `number` — 0..2
+- **[maxOutputTokens]** `number` — 1..4,096
+
+Calls a chat-completion LLM with the given conversation. Only use when output
+depends on runtime state that couldn't be authored upfront (free-form player
+input, accumulated in-session choices). Fixed dialogue, flavor text, and
+canned hints belong in code or gameConfig — don't fetch what you could author.
+Don't use for game logic, scoring, physics, per-frame work, or anything
+requiring determinism.
+Async; can throw on rate limit, network failure, timeout, or all-empty
+messages. Wrap in try/catch with a non-LLM fallback so the game keeps working
+when the call fails. Empty/whitespace-only messages are silently dropped
+before sending — safe to feed a running chat history without sanitizing.
+Rate-limited server-side. Debounce user-triggered calls, cache repeated
+prompts, never call per frame.
+result.text is a string. For structured output, instruct the model in
+systemPrompt to reply with JSON and parse defensively (JSON.parse inside
+try/catch with a non-LLM fallback).
+Caps: 100 messages, 50,000 chars/message, 200,000 chars aggregate, 10,000
+chars systemPrompt.
+- **options.messages** (`LlmMessage[]`): Conversation so far
+- **options.systemPrompt** (`string`, optional): Persona / instructions
+- **options.config** (`LlmConfig`, optional): Sampling controls
+
+**Returns:** `Promise<{text: string}>`
+
+**Example:**
+```js
+try {
+  const reply = await lib.llm({
+    messages: [{ role: 'user', content: 'Greet the player as a grumpy wizard.' }],
+    systemPrompt: 'You are a wizard NPC. Reply in one short sentence.',
+    config: { temperature: 0.8, maxOutputTokens: 60 },
+  });
+  showDialogue(reply.text);
+} catch (err) {
+  showDialogue('The wizard grumbles incoherently.');
+}
+```
+
+```js
+lib.llm = async function(options) {};
+```

astrocade_creator_mcp-0.1.0/src/astrocade_creator_mcp/astrolib_ref.py

@@ -0,0 +1,19 @@
+"""Loads the bundled astrolib API reference markdown for the lib-docs tools."""
+
+from pathlib import Path
+
+_DIST_DIR = Path(__file__).parent / "astrolib"
+
+ASTROLIB_API_REFERENCE_BASE: str = (_DIST_DIR / "lib-api-reference-base.md").read_text()
+ASTROLIB_API_REFERENCE_ANIMATION: str = (_DIST_DIR / "lib-api-reference-animation.md").read_text()
+ASTROLIB_API_REFERENCE_LLM: str = (_DIST_DIR / "lib-api-reference-llm.md").read_text()
+
+
+def get_astrolib_api_reference(animation_enabled: bool = True, lib_llm_enabled: bool = True) -> str:
+    """Get the astrolib API reference, optionally including animation and lib.llm docs."""
+    parts = [ASTROLIB_API_REFERENCE_BASE]
+    if animation_enabled:
+        parts.append(ASTROLIB_API_REFERENCE_ANIMATION)
+    if lib_llm_enabled:
+        parts.append(ASTROLIB_API_REFERENCE_LLM)
+    return "\n".join(parts)

astrocade_creator_mcp-0.1.0/src/astrocade_creator_mcp/auth/__init__.py

@@ -0,0 +1 @@
+"""Cognito auth for the Creator MCP: shared JWT helpers and the stdio login flow."""

astrocade_creator_mcp-0.1.0/src/astrocade_creator_mcp/auth/cognito.py

@@ -0,0 +1,71 @@
+"""Cognito JWT helpers used by the stdio login flow.
+
+Verification mirrors the AstroBackend custom authorizer: RS256 against the pool's JWKS, issuer
+match, token_use == "access", client_id match. Cognito access tokens carry no `aud`, so audience
+verification is disabled — the client_id check is the equivalent binding.
+"""
+
+from typing import Any
+
+import jwt
+from jwt import PyJWKClient
+
+from astrocade_creator_mcp.config import CognitoConfig
+
+# One JWKS client per JWKS URL; PyJWKClient caches signing keys and refetches on a key miss.
+_jwks_clients: dict[str, PyJWKClient] = {}
+
+
+def _jwks_client(jwks_url: str) -> PyJWKClient:
+    client = _jwks_clients.get(jwks_url)
+    if client is None:
+        client = PyJWKClient(jwks_url)
+        _jwks_clients[jwks_url] = client
+    return client
+
+
+def verify_access_token(cfg: CognitoConfig, token: str) -> dict[str, Any] | None:
+    """Verify a Cognito ACCESS token's signature and claims.
+
+    Returns the decoded claims on success, or None if the token is invalid, expired, from the
+    wrong pool/issuer, not an access token, or issued for a different client.
+    """
+    try:
+        signing_key = _jwks_client(cfg.jwks_url).get_signing_key_from_jwt(token)
+        claims: dict[str, Any] = jwt.decode(
+            token,
+            signing_key.key,
+            algorithms=["RS256"],
+            issuer=cfg.issuer_url,
+            options={"verify_aud": False},
+        )
+    except Exception:
+        return None
+
+    if claims.get("token_use") != "access":
+        return None
+    if claims.get("client_id") != cfg.client_id:
+        return None
+    return claims
+
+
+def decode_unverified_claims(token: str) -> dict[str, Any]:
+    """Decode a JWT's claims WITHOUT signature verification.
+
+    Used to read the user id out of a token whose signature was already established: one we just
+    obtained from Cognito ourselves. The backend re-verifies the signature on every call regardless.
+    """
+    claims: dict[str, Any] = jwt.decode(token, options={"verify_signature": False})
+    return claims
+
+
+def user_id_from_claims(claims: dict[str, Any]) -> str:
+    """Resolve the Astrocade user id from token claims.
+
+    We only ever see Cognito ACCESS tokens (that's what the frontend forwards as the
+    Authorization header), which carry `username` but not `cognito:username`. The backend
+    resolves the same access token to the same id, so they match. `cognito:username` (present
+    on id tokens) and `sub` are fallbacks for robustness, not the expected path.
+    """
+    user_id = claims.get("username") or claims.get("cognito:username") or claims.get("sub", "")
+    return str(user_id)