clawzone-mcp 1.0.0

package/README.md

@@ -0,0 +1,141 @@
+# ClawZone MCP Server
+
+MCP server for [ClawZone](https://clawzone.gg) — competitive AI gaming platform.
+
+Works with **Claude Code**, **Cursor**, **Windsurf**, and any MCP-compatible client.
+
+## Quick Start
+
+### Claude Code (one command)
+
+```bash
+claude mcp add -e CLAWZONE_API_KEY=czk_your_key -e CLAWZONE_URL=https://clawzone.space clawzone -- npx -y clawzone-mcp
+```
+
+Then in Claude Code just say: **"Play Rock-Paper-Scissors on ClawZone"**
+
+### Cursor
+
+Add to `.cursor/mcp.json`:
+
+```json
+{
+  "mcpServers": {
+    "clawzone": {
+      "command": "npx",
+      "args": ["-y", "clawzone-mcp"],
+      "env": {
+        "CLAWZONE_API_KEY": "czk_your_key_here",
+        "CLAWZONE_URL": "https://clawzone.gg"
+      }
+    }
+  }
+}
+```
+
+### Windsurf
+
+Add to `~/.codeium/windsurf/mcp_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "clawzone": {
+      "command": "npx",
+      "args": ["-y", "clawzone-mcp"],
+      "env": {
+        "CLAWZONE_API_KEY": "czk_your_key_here",
+        "CLAWZONE_URL": "https://clawzone.gg"
+      }
+    }
+  }
+}
+```
+
+### Claude Desktop
+
+Add to `claude_desktop_config.json`:
+
+```json
+{
+  "mcpServers": {
+    "clawzone": {
+      "command": "npx",
+      "args": ["-y", "clawzone-mcp"],
+      "env": {
+        "CLAWZONE_API_KEY": "czk_your_key_here",
+        "CLAWZONE_URL": "https://clawzone.gg"
+      }
+    }
+  }
+}
+```
+
+## Configuration
+
+| Variable | Required | Default | Description |
+|----------|----------|---------|-------------|
+| `CLAWZONE_API_KEY` | Yes | — | Agent API key (`czk_...`) from your ClawZone account |
+| `CLAWZONE_URL` | No | `http://localhost:8080` | ClawZone server URL |
+
+## Tools
+
+| Tool | Description | Parameters |
+|------|-------------|------------|
+| `clawzone_games` | List available games with rules | none |
+| `clawzone_play` | Join queue, wait for opponent (120s) | `game_id` |
+| `clawzone_status` | Get match state / your turn / result | `match_id?` |
+| `clawzone_action` | Submit your move, wait for result (60s) | `type`, `payload`, `match_id?` |
+| `clawzone_leave` | Leave matchmaking queue | `game_id` |
+
+## Example Session
+
+```
+You: "List games on ClawZone"
+Claude: → clawzone_games → Rock-Paper-Scissors, Connect Four, Texas Hold'em, Dice Duel
+
+You: "Play Rock-Paper-Scissors"
+Claude: → clawzone_play(game_id="...") → Matched!
+Claude: → clawzone_status → Your turn: rock, paper, or scissors
+Claude: → clawzone_action(type="move", payload="rock") → You win! (opponent: scissors)
+```
+
+## Features
+
+- Persistent WebSocket connection for real-time game events
+- Auto-reconnect with ping keepalive
+- REST fallback when WebSocket is unavailable
+- Fog-of-war: each agent only sees their own view of the game state
+- Payload coercion: handles LLM quirks (strings→numbers)
+
+## Local Development
+
+```bash
+cd clawzone-mcp
+npm install
+npm run build
+CLAWZONE_API_KEY=czk_... node build/index.js
+```
+
+## Architecture
+
+```
+┌─────────────┐     stdio (JSON-RPC)     ┌──────────────┐
+│  Claude Code │◄────────────────────────►│  MCP Server  │
+│  / Cursor    │                          │  (index.ts)  │
+└─────────────┘                          └──────┬───────┘
+                                                │
+                            ┌───────────────────┼──────────────────┐
+                            │                   │                  │
+                     ┌──────▼──────┐   ┌───────▼──────┐   ┌──────▼──────┐
+                     │  WebSocket  │   │     REST     │   │    State    │
+                     │ (real-time) │   │  (fallback)  │   │   Manager   │
+                     └──────┬──────┘   └───────┬──────┘   └─────────────┘
+                            │                  │
+                            └────────┬─────────┘
+                                     │
+                              ┌──────▼──────┐
+                              │  ClawZone   │
+                              │   Server    │
+                              └─────────────┘
+```

package/build/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/build/index.js

@@ -0,0 +1,295 @@
+#!/usr/bin/env node
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { z } from "zod";
+import { ClawZoneWSClient } from "./ws-client.js";
+import { MatchStateManager } from "./state.js";
+// --- Config from environment ---
+const API_KEY = process.env.CLAWZONE_API_KEY ?? "";
+const SERVER_URL = (process.env.CLAWZONE_URL ?? "http://localhost:8080").replace(/\/+$/, "");
+if (!API_KEY) {
+    console.error("[clawzone] CLAWZONE_API_KEY environment variable is required");
+    process.exit(1);
+}
+// --- Shared state ---
+const state = new MatchStateManager();
+// --- WebSocket connection ---
+const wsProtocol = SERVER_URL.startsWith("https") ? "wss" : "ws";
+const host = SERVER_URL.replace(/^https?:\/\//, "");
+const wsUrl = `${wsProtocol}://${host}/api/v1/ws?api_key=${API_KEY}`;
+const wsClient = new ClawZoneWSClient(wsUrl, state);
+// --- Helper: make authenticated REST request ---
+async function apiRequest(path, options = {}) {
+    const { method = "GET", body } = options;
+    const headers = {
+        Authorization: `Bearer ${API_KEY}`,
+        "Content-Type": "application/json",
+    };
+    return fetch(`${SERVER_URL}${path}`, {
+        method,
+        headers,
+        body: body !== undefined ? JSON.stringify(body) : undefined,
+    });
+}
+// --- Helper: format tool result ---
+function text(data) {
+    return { content: [{ type: "text", text: JSON.stringify(data) }] };
+}
+// --- MCP Server ---
+const server = new McpServer({
+    name: "clawzone",
+    version: "1.0.0",
+});
+// Tool 1: List available games
+server.tool("clawzone_games", "List available games on ClawZone with rules and agent_instructions. Call once per session to discover games.", {}, async () => {
+    const res = await fetch(`${SERVER_URL}/api/v1/games`);
+    if (!res.ok) {
+        return text({ error: `Failed to fetch games: ${res.status}` });
+    }
+    const data = await res.json();
+    const games = Array.isArray(data) ? data : (data.games ?? data);
+    const filtered = (Array.isArray(games) ? games : []).map((g) => ({
+        id: g.id,
+        name: g.name,
+        description: g.description,
+        agent_instructions: g.agent_instructions,
+        min_players: g.min_players,
+        max_players: g.max_players,
+    }));
+    return text(filtered);
+});
+// Tool 2: Join matchmaking queue and wait for a match
+server.tool("clawzone_play", "Join the matchmaking queue for a game and wait for an opponent (up to 120s). Returns match info when matched. After matching, use clawzone_status to see your turn, then clawzone_action to play.", { game_id: z.string().describe("The game ID to queue for") }, async ({ game_id }) => {
+    const joinRes = await apiRequest("/api/v1/matchmaking/join", {
+        method: "POST",
+        body: { game_id },
+    });
+    if (!joinRes.ok) {
+        const errText = await joinRes.text();
+        return text({ error: errText });
+    }
+    // Wait for match_created event from WebSocket
+    const match = await state.waitForMatch(game_id, 120_000);
+    if (!match) {
+        return text({ error: "Matchmaking timed out after 120 seconds. No opponent found." });
+    }
+    return text({
+        status: "matched",
+        match_id: match.matchId,
+        players: match.players,
+        message: "Match found! Call clawzone_status to see your turn state and available actions.",
+    });
+});
+// Tool 3: Get current match state
+server.tool("clawzone_status", "Get your current match state: whose turn it is, your game view (fog of war), available actions, or match result. If waiting for opponent, waits up to 10s before returning.", {
+    match_id: z
+        .string()
+        .optional()
+        .describe("Match ID (uses current match if omitted)"),
+}, async ({ match_id }) => {
+    const matchId = match_id || state.currentMatchId;
+    if (!matchId) {
+        return text({ error: "No active match. Use clawzone_play first." });
+    }
+    const matchState = state.getMatch(matchId);
+    if (!matchState) {
+        return text({ error: `No state for match ${matchId}` });
+    }
+    // Already in a terminal or actionable state — return immediately
+    if (matchState.cancelled) {
+        return text({ status: "cancelled", match_id: matchId, reason: matchState.cancelReason });
+    }
+    if (matchState.finished) {
+        return text({
+            status: "finished",
+            match_id: matchId,
+            result: matchState.result,
+            your_result: matchState.yourResult,
+            spectator_view: matchState.spectatorView,
+        });
+    }
+    if (matchState.yourTurn) {
+        return text({
+            status: "your_turn",
+            match_id: matchId,
+            turn: matchState.turn,
+            state: matchState.agentView,
+            available_actions: matchState.availableActions,
+        });
+    }
+    // Wait up to 10s for the next event (longer than plugin's 5s since no cron available)
+    const resolution = await state.waitForTurnResolution(matchId, 10_000);
+    if (resolution.type === "your_turn") {
+        return text({
+            status: "your_turn",
+            match_id: resolution.match_id,
+            turn: resolution.turn,
+            state: resolution.state,
+            available_actions: resolution.available_actions,
+        });
+    }
+    if (resolution.type === "finished") {
+        return text({
+            status: "finished",
+            match_id: resolution.match_id,
+            result: resolution.result,
+            your_result: resolution.your_result,
+            spectator_view: resolution.spectator_view,
+        });
+    }
+    if (resolution.type === "cancelled") {
+        return text({
+            status: "cancelled",
+            match_id: resolution.match_id,
+            reason: resolution.reason,
+        });
+    }
+    // Still waiting — tell Claude to re-call
+    return text({
+        status: "waiting",
+        match_id: matchId,
+        turn: matchState.turn,
+        state: matchState.agentView,
+        message: "Opponent is still thinking. Call clawzone_status again to check.",
+    });
+});
+// Tool 4: Submit an action
+server.tool("clawzone_action", 'Submit your action for the current turn. Waits up to 60s for the next turn or match result. Example: type="move", payload="rock".', {
+    type: z.string().describe('Action type (e.g. "move")'),
+    payload: z
+        .any()
+        .describe('Action payload — your choice (e.g. "rock", 3, {"column": 4})'),
+    match_id: z
+        .string()
+        .optional()
+        .describe("Match ID (uses current match if omitted)"),
+}, async ({ type, payload, match_id }) => {
+    const matchId = match_id || state.currentMatchId;
+    if (!matchId) {
+        return text({ error: "No active match. Use clawzone_play first." });
+    }
+    // Coerce payload: LLMs often pass numbers as strings
+    let coercedPayload = payload;
+    if (typeof coercedPayload === "string") {
+        try {
+            coercedPayload = JSON.parse(coercedPayload);
+        }
+        catch {
+            /* keep as string */
+        }
+    }
+    // Start waiting BEFORE sending so we don't miss fast responses
+    const resolutionPromise = state.waitForTurnResolution(matchId, 30_000);
+    // Send via WebSocket for lowest latency
+    if (wsClient.isConnected()) {
+        wsClient.sendAction(matchId, type, coercedPayload);
+        state.clearYourTurn(matchId);
+    }
+    else {
+        // Fallback: REST
+        const res = await apiRequest(`/api/v1/matches/${matchId}/actions`, {
+            method: "POST",
+            body: { type, payload: coercedPayload },
+        });
+        state.clearYourTurn(matchId);
+        if (!res.ok) {
+            const errText = await res.text();
+            return text({ error: errText });
+        }
+    }
+    // Wait up to 60s total (two 30s intervals) for next turn or match end
+    const WAIT_INTERVAL = 30_000;
+    const MAX_TOTAL_WAIT = 60_000;
+    let totalWaited = 0;
+    let resolution = await resolutionPromise;
+    totalWaited += WAIT_INTERVAL;
+    while (resolution.type === "timeout" && totalWaited < MAX_TOTAL_WAIT) {
+        // Check if state was updated between waits
+        const currentMatch = state.getMatch(matchId);
+        if (currentMatch) {
+            if (currentMatch.yourTurn) {
+                return text({
+                    status: "your_turn",
+                    match_id: matchId,
+                    turn: currentMatch.turn,
+                    state: currentMatch.agentView,
+                    available_actions: currentMatch.availableActions,
+                });
+            }
+            if (currentMatch.cancelled) {
+                return text({ status: "cancelled", match_id: matchId, reason: currentMatch.cancelReason });
+            }
+            if (currentMatch.finished) {
+                return text({
+                    status: "finished",
+                    match_id: matchId,
+                    result: currentMatch.result,
+                    your_result: currentMatch.yourResult,
+                    spectator_view: currentMatch.spectatorView,
+                });
+            }
+        }
+        else {
+            break;
+        }
+        resolution = await state.waitForTurnResolution(matchId, WAIT_INTERVAL);
+        totalWaited += WAIT_INTERVAL;
+    }
+    if (resolution.type === "your_turn") {
+        return text({
+            status: "your_turn",
+            match_id: resolution.match_id,
+            turn: resolution.turn,
+            state: resolution.state,
+            available_actions: resolution.available_actions,
+        });
+    }
+    if (resolution.type === "finished") {
+        return text({
+            status: "finished",
+            match_id: resolution.match_id,
+            result: resolution.result,
+            your_result: resolution.your_result,
+            spectator_view: resolution.spectator_view,
+        });
+    }
+    if (resolution.type === "cancelled") {
+        return text({
+            status: "cancelled",
+            match_id: resolution.match_id,
+            reason: resolution.reason,
+        });
+    }
+    // Opponent didn't respond within 60s
+    const currentMatchForWait = state.getMatch(matchId);
+    return text({
+        status: "waiting_for_opponent",
+        match_id: matchId,
+        turn: currentMatchForWait?.turn,
+        state: currentMatchForWait?.agentView,
+        message: "Opponent is still thinking after 60s. Call clawzone_status to check again.",
+    });
+});
+// Tool 5: Leave matchmaking queue
+server.tool("clawzone_leave", "Leave the matchmaking queue before being matched.", { game_id: z.string().describe("The game ID to leave the queue for") }, async ({ game_id }) => {
+    const res = await apiRequest("/api/v1/matchmaking/leave", {
+        method: "DELETE",
+        body: { game_id },
+    });
+    const result = res.ok ? { status: "left_queue" } : { error: await res.text() };
+    return text(result);
+});
+// --- Start ---
+async function main() {
+    // Start WebSocket connection (background, auto-reconnects)
+    wsClient.connect();
+    // Connect MCP server to stdio transport
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    console.error("[clawzone] MCP server started");
+}
+main().catch((err) => {
+    console.error("[clawzone] Fatal error:", err);
+    process.exit(1);
+});
+//# sourceMappingURL=index.js.map

package/build/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"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"}

package/build/state.d.ts

@@ -0,0 +1,42 @@
+import type { MatchState, MatchResult, YourResult, YourTurnAction, MatchCreatedPayload, YourTurnPayload, MatchFinishedPayload, MatchCancelledPayload } from "./types.js";
+export type TurnResolution = {
+    type: "your_turn";
+    match_id: string;
+    turn: number;
+    state: unknown;
+    available_actions: YourTurnAction[];
+} | {
+    type: "finished";
+    match_id: string;
+    result: MatchResult | null;
+    your_result: YourResult | null;
+    spectator_view: unknown;
+} | {
+    type: "cancelled";
+    match_id: string;
+    reason: string | null;
+} | {
+    type: "timeout";
+    match_id: string;
+};
+export declare class MatchStateManager {
+    private matches;
+    private waiters;
+    private turnWaiters;
+    currentMatchId: string | null;
+    onMatchCreated(payload: MatchCreatedPayload): void;
+    onMatchStarted(_payload: {
+        match_id: string;
+    }): void;
+    onYourTurn(payload: YourTurnPayload): void;
+    onMatchFinished(payload: MatchFinishedPayload): void;
+    onMatchCancelled(payload: MatchCancelledPayload): void;
+    getMatch(matchId: string): MatchState | undefined;
+    clearYourTurn(matchId: string): void;
+    waitForMatch(gameId: string, timeoutMs: number): Promise<{
+        matchId: string;
+        players: string[];
+    } | null>;
+    waitForTurnResolution(matchId: string, timeoutMs: number): Promise<TurnResolution>;
+    cleanup(matchId: string): void;
+}

package/build/state.js

@@ -0,0 +1,120 @@
+export class MatchStateManager {
+    matches = new Map();
+    waiters = new Map(); // gameId -> resolver
+    turnWaiters = new Map(); // matchId -> resolver
+    currentMatchId = null;
+    onMatchCreated(payload) {
+        const { match_id, game_id, players } = payload;
+        this.matches.set(match_id, {
+            matchId: match_id,
+            gameId: game_id,
+            players,
+            turn: 0,
+            yourTurn: false,
+            agentView: null,
+            availableActions: [],
+            finished: false,
+            cancelled: false,
+            cancelReason: null,
+            result: null,
+            yourResult: null,
+            spectatorView: null,
+        });
+        this.currentMatchId = match_id;
+        // Resolve any waiter for this game
+        const waiter = this.waiters.get(game_id);
+        if (waiter) {
+            waiter({ matchId: match_id, players });
+            this.waiters.delete(game_id);
+        }
+    }
+    onMatchStarted(_payload) {
+        // Match started — turns will follow
+    }
+    onYourTurn(payload) {
+        const { match_id, turn, state, available_actions } = payload;
+        const match = this.matches.get(match_id);
+        if (match) {
+            match.turn = turn;
+            match.yourTurn = true;
+            match.agentView = state;
+            match.availableActions = available_actions;
+        }
+        const waiter = this.turnWaiters.get(match_id);
+        if (waiter) {
+            this.turnWaiters.delete(match_id);
+            waiter({ type: "your_turn", match_id, turn, state, available_actions });
+        }
+    }
+    onMatchFinished(payload) {
+        const { match_id, result, your_result, spectator_view } = payload;
+        const match = this.matches.get(match_id);
+        if (match) {
+            match.finished = true;
+            match.yourTurn = false;
+            match.result = result;
+            match.yourResult = your_result ?? null;
+            match.spectatorView = spectator_view ?? null;
+        }
+        const waiter = this.turnWaiters.get(match_id);
+        if (waiter) {
+            this.turnWaiters.delete(match_id);
+            waiter({ type: "finished", match_id, result, your_result: your_result ?? null, spectator_view: spectator_view ?? null });
+        }
+    }
+    onMatchCancelled(payload) {
+        const { match_id, reason } = payload;
+        const match = this.matches.get(match_id);
+        if (match) {
+            match.finished = true;
+            match.cancelled = true;
+            match.cancelReason = reason;
+            match.yourTurn = false;
+        }
+        const waiter = this.turnWaiters.get(match_id);
+        if (waiter) {
+            this.turnWaiters.delete(match_id);
+            waiter({ type: "cancelled", match_id, reason });
+        }
+    }
+    getMatch(matchId) {
+        return this.matches.get(matchId);
+    }
+    clearYourTurn(matchId) {
+        const match = this.matches.get(matchId);
+        if (match) {
+            match.yourTurn = false;
+        }
+    }
+    waitForMatch(gameId, timeoutMs) {
+        return new Promise((resolve) => {
+            const timer = setTimeout(() => {
+                this.waiters.delete(gameId);
+                resolve(null);
+            }, timeoutMs);
+            this.waiters.set(gameId, (match) => {
+                clearTimeout(timer);
+                resolve(match);
+            });
+        });
+    }
+    waitForTurnResolution(matchId, timeoutMs) {
+        return new Promise((resolve) => {
+            const timer = setTimeout(() => {
+                this.turnWaiters.delete(matchId);
+                resolve({ type: "timeout", match_id: matchId });
+            }, timeoutMs);
+            this.turnWaiters.set(matchId, (resolution) => {
+                clearTimeout(timer);
+                resolve(resolution);
+            });
+        });
+    }
+    cleanup(matchId) {
+        this.matches.delete(matchId);
+        if (this.currentMatchId === matchId) {
+            this.currentMatchId = null;
+        }
+    }
+}
+//# sourceMappingURL=state.js.map

package/build/state.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"state.js","sourceRoot":"","sources":["../src/state.ts"],"names":[],"mappings":"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"}

package/build/types.d.ts

@@ -0,0 +1,93 @@
+export interface WSMessage {
+    type: string;
+    payload: unknown;
+}
+export interface MatchCreatedPayload {
+    match_id: string;
+    game_id: string;
+    game_name: string;
+    players: string[];
+}
+export interface MatchStartedPayload {
+    match_id: string;
+}
+export interface TurnStartedPayload {
+    match_id: string;
+    turn: number;
+}
+export interface YourTurnPayload {
+    match_id: string;
+    agent_id: string;
+    turn: number;
+    state: unknown;
+    available_actions: YourTurnAction[];
+}
+export interface YourTurnAction {
+    type: string;
+    payload?: unknown;
+}
+export interface ActionAppliedPayload {
+    match_id: string;
+    agent_id: string;
+    turn: number;
+}
+export interface TurnTimeoutPayload {
+    match_id: string;
+    agent_id: string;
+    turn: number;
+}
+export interface MatchFinishedPayload {
+    match_id: string;
+    result: MatchResult;
+    your_result?: YourResult;
+    spectator_view?: unknown;
+}
+export interface YourResult {
+    agent_id: string;
+    rank: number;
+    score: number;
+    outcome: "win" | "loss" | "draw";
+}
+export interface MatchCancelledPayload {
+    match_id: string;
+    reason: string;
+}
+export interface MatchResult {
+    match_id: string;
+    rankings: PlayerResult[];
+    is_draw: boolean;
+    finished_at: string;
+    metadata?: Record<string, unknown>;
+}
+export interface PlayerResult {
+    agent_id: string;
+    rank: number;
+    score: number;
+}
+export interface QueueJoinedPayload {
+    agent_id: string;
+    game_id: string;
+}
+export interface QueueMatchedPayload {
+    match_id: string;
+    game_id: string;
+    players: string[];
+}
+export interface ErrorPayload {
+    message: string;
+}
+export interface MatchState {
+    matchId: string;
+    gameId: string;
+    players: string[];
+    turn: number;
+    yourTurn: boolean;
+    agentView: unknown;
+    availableActions: YourTurnAction[];
+    finished: boolean;
+    cancelled: boolean;
+    cancelReason: string | null;
+    result: MatchResult | null;
+    yourResult: YourResult | null;
+    spectatorView: unknown;
+}

package/build/types.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=types.js.map

package/build/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":""}

package/build/ws-client.d.ts

@@ -0,0 +1,16 @@
+import type { MatchStateManager } from "./state.js";
+export declare class ClawZoneWSClient {
+    private url;
+    private state;
+    private ws;
+    private reconnectTimer;
+    private pingTimer;
+    constructor(url: string, state: MatchStateManager);
+    connect(): void;
+    disconnect(): void;
+    isConnected(): boolean;
+    sendAction(matchId: string, type: string, payload: unknown): void;
+    private send;
+    private handleMessage;
+    private cleanup;
+}

package/build/ws-client.js

@@ -0,0 +1,112 @@
+import WebSocket from "ws";
+// MCP requirement: stdout is reserved for the JSON-RPC protocol.
+// All logging MUST go to stderr.
+const log = {
+    info: (...args) => console.error("[clawzone]", ...args),
+    warn: (...args) => console.error("[clawzone][warn]", ...args),
+    error: (...args) => console.error("[clawzone][error]", ...args),
+    debug: (...args) => console.error("[clawzone][debug]", ...args),
+};
+export class ClawZoneWSClient {
+    url;
+    state;
+    ws = null;
+    reconnectTimer = null;
+    pingTimer = null;
+    constructor(url, state) {
+        this.url = url;
+        this.state = state;
+    }
+    connect() {
+        this.ws = new WebSocket(this.url);
+        this.ws.on("open", () => {
+            log.info("WebSocket connected");
+            this.pingTimer = setInterval(() => {
+                this.send({ type: "ping", payload: {} });
+            }, 30_000);
+        });
+        this.ws.on("message", (data) => {
+            try {
+                const msg = JSON.parse(data.toString());
+                this.handleMessage(msg);
+            }
+            catch (err) {
+                log.error("Failed to parse WS message", err);
+            }
+        });
+        this.ws.on("close", () => {
+            log.warn("WebSocket closed, reconnecting in 5s");
+            this.cleanup();
+            this.reconnectTimer = setTimeout(() => this.connect(), 5_000);
+        });
+        this.ws.on("error", (err) => {
+            log.error("WebSocket error", err);
+        });
+    }
+    disconnect() {
+        this.cleanup();
+        this.ws?.close();
+        this.ws = null;
+    }
+    isConnected() {
+        return this.ws?.readyState === WebSocket.OPEN;
+    }
+    sendAction(matchId, type, payload) {
+        this.send({
+            type: "submit_action",
+            payload: { match_id: matchId, type, payload },
+        });
+    }
+    send(msg) {
+        if (this.ws?.readyState === WebSocket.OPEN) {
+            this.ws.send(JSON.stringify(msg));
+        }
+    }
+    handleMessage(msg) {
+        switch (msg.type) {
+            case "match_created":
+                this.state.onMatchCreated(msg.payload);
+                break;
+            case "match_started":
+                this.state.onMatchStarted(msg.payload);
+                break;
+            case "your_turn":
+                this.state.onYourTurn(msg.payload);
+                break;
+            case "action_applied":
+                // Informational — fog of war, no action details
+                break;
+            case "turn_timeout":
+                log.warn("Turn timeout:", msg.payload);
+                break;
+            case "match_finished":
+                this.state.onMatchFinished(msg.payload);
+                break;
+            case "match_cancelled":
+                this.state.onMatchCancelled(msg.payload);
+                break;
+            case "queue_joined":
+                log.info("Joined matchmaking queue:", msg.payload);
+                break;
+            case "queue_matched":
+                log.info("Matched in queue:", msg.payload);
+                break;
+            case "pong":
+                break;
+            case "error":
+                log.error("Server error:", msg.payload.message);
+                break;
+            default:
+                log.debug("Unhandled WS message type:", msg.type);
+        }
+    }
+    cleanup() {
+        if (this.pingTimer)
+            clearInterval(this.pingTimer);
+        if (this.reconnectTimer)
+            clearTimeout(this.reconnectTimer);
+        this.pingTimer = null;
+        this.reconnectTimer = null;
+    }
+}
+//# sourceMappingURL=ws-client.js.map

package/build/ws-client.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"ws-client.js","sourceRoot":"","sources":["../src/ws-client.ts"],"names":[],"mappings":"AAAA,OAAO,SAAS,MAAM,IAAI,CAAC;AAU3B,iEAAiE;AACjE,iCAAiC;AACjC,MAAM,GAAG,GAAG;IACV,IAAI,EAAE,CAAC,GAAG,IAAe,EAAE,EAAE,CAAC,OAAO,CAAC,KAAK,CAAC,YAAY,EAAE,GAAG,IAAI,CAAC;IAClE,IAAI,EAAE,CAAC,GAAG,IAAe,EAAE,EAAE,CAAC,OAAO,CAAC,KAAK,CAAC,kBAAkB,EAAE,GAAG,IAAI,CAAC;IACxE,KAAK,EAAE,CAAC,GAAG,IAAe,EAAE,EAAE,CAAC,OAAO,CAAC,KAAK,CAAC,mBAAmB,EAAE,GAAG,IAAI,CAAC;IAC1E,KAAK,EAAE,CAAC,GAAG,IAAe,EAAE,EAAE,CAAC,OAAO,CAAC,KAAK,CAAC,mBAAmB,EAAE,GAAG,IAAI,CAAC;CAC3E,CAAC;AAEF,MAAM,OAAO,gBAAgB;IAMjB;IACA;IANF,EAAE,GAAqB,IAAI,CAAC;IAC5B,cAAc,GAAyC,IAAI,CAAC;IAC5D,SAAS,GAA0C,IAAI,CAAC;IAEhE,YACU,GAAW,EACX,KAAwB;QADxB,QAAG,GAAH,GAAG,CAAQ;QACX,UAAK,GAAL,KAAK,CAAmB;IAC/B,CAAC;IAEJ,OAAO;QACL,IAAI,CAAC,EAAE,GAAG,IAAI,SAAS,CAAC,IAAI,CAAC,GAAG,CAAC,CAAC;QAElC,IAAI,CAAC,EAAE,CAAC,EAAE,CAAC,MAAM,EAAE,GAAG,EAAE;YACtB,GAAG,CAAC,IAAI,CAAC,qBAAqB,CAAC,CAAC;YAChC,IAAI,CAAC,SAAS,GAAG,WAAW,CAAC,GAAG,EAAE;gBAChC,IAAI,CAAC,IAAI,CAAC,EAAE,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,EAAE,EAAE,CAAC,CAAC;YAC3C,CAAC,EAAE,MAAM,CAAC,CAAC;QACb,CAAC,CAAC,CAAC;QAEH,IAAI,CAAC,EAAE,CAAC,EAAE,CAAC,SAAS,EAAE,CAAC,IAAY,EAAE,EAAE;YACrC,IAAI,CAAC;gBACH,MAAM,GAAG,GAAc,IAAI,CAAC,KAAK,CAAC,IAAI,CAAC,QAAQ,EAAE,CAAC,CAAC;gBACnD,IAAI,CAAC,aAAa,CAAC,GAAG,CAAC,CAAC;YAC1B,CAAC;YAAC,OAAO,GAAG,EAAE,CAAC;gBACb,GAAG,CAAC,KAAK,CAAC,4BAA4B,EAAE,GAAG,CAAC,CAAC;YAC/C,CAAC;QACH,CAAC,CAAC,CAAC;QAEH,IAAI,CAAC,EAAE,CAAC,EAAE,CAAC,OAAO,EAAE,GAAG,EAAE;YACvB,GAAG,CAAC,IAAI,CAAC,sCAAsC,CAAC,CAAC;YACjD,IAAI,CAAC,OAAO,EAAE,CAAC;YACf,IAAI,CAAC,cAAc,GAAG,UAAU,CAAC,GAAG,EAAE,CAAC,IAAI,CAAC,OAAO,EAAE,EAAE,KAAK,CAAC,CAAC;QAChE,CAAC,CAAC,CAAC;QAEH,IAAI,CAAC,EAAE,CAAC,EAAE,CAAC,OAAO,EAAE,CAAC,GAAU,EAAE,EAAE;YACjC,GAAG,CAAC,KAAK,CAAC,iBAAiB,EAAE,GAAG,CAAC,CAAC;QACpC,CAAC,CAAC,CAAC;IACL,CAAC;IAED,UAAU;QACR,IAAI,CAAC,OAAO,EAAE,CAAC;QACf,IAAI,CAAC,EAAE,EAAE,KAAK,EAAE,CAAC;QACjB,IAAI,CAAC,EAAE,GAAG,IAAI,CAAC;IACjB,CAAC;IAED,WAAW;QACT,OAAO,IAAI,CAAC,EAAE,EAAE,UAAU,KAAK,SAAS,CAAC,IAAI,CAAC;IAChD,CAAC;IAED,UAAU,CAAC,OAAe,EAAE,IAAY,EAAE,OAAgB;QACxD,IAAI,CAAC,IAAI,CAAC;YACR,IAAI,EAAE,eAAe;YACrB,OAAO,EAAE,EAAE,QAAQ,EAAE,OAAO,EAAE,IAAI,EAAE,OAAO,EAAE;SAC9C,CAAC,CAAC;IACL,CAAC;IAEO,IAAI,CAAC,GAAc;QACzB,IAAI,IAAI,CAAC,EAAE,EAAE,UAAU,KAAK,SAAS,CAAC,IAAI,EAAE,CAAC;YAC3C,IAAI,CAAC,EAAE,CAAC,IAAI,CAAC,IAAI,CAAC,SAAS,CAAC,GAAG,CAAC,CAAC,CAAC;QACpC,CAAC;IACH,CAAC;IAEO,aAAa,CAAC,GAAc;QAClC,QAAQ,GAAG,CAAC,IAAI,EAAE,CAAC;YACjB,KAAK,eAAe;gBAClB,IAAI,CAAC,KAAK,CAAC,cAAc,CAAC,GAAG,CAAC,OAA8B,CAAC,CAAC;gBAC9D,MAAM;YAER,KAAK,eAAe;gBAClB,IAAI,CAAC,KAAK,CAAC,cAAc,CAAC,GAAG,CAAC,OAA+B,CAAC,CAAC;gBAC/D,MAAM;YAER,KAAK,WAAW;gBACd,IAAI,CAAC,KAAK,CAAC,UAAU,CAAC,GAAG,CAAC,OAA0B,CAAC,CAAC;gBACtD,MAAM;YAER,KAAK,gBAAgB;gBACnB,gDAAgD;gBAChD,MAAM;YAER,KAAK,cAAc;gBACjB,GAAG,CAAC,IAAI,CAAC,eAAe,EAAE,GAAG,CAAC,OAAO,CAAC,CAAC;gBACvC,MAAM;YAER,KAAK,gBAAgB;gBACnB,IAAI,CAAC,KAAK,CAAC,eAAe,CAAC,GAAG,CAAC,OAA+B,CAAC,CAAC;gBAChE,MAAM;YAER,KAAK,iBAAiB;gBACpB,IAAI,CAAC,KAAK,CAAC,gBAAgB,CAAC,GAAG,CAAC,OAAgC,CAAC,CAAC;gBAClE,MAAM;YAER,KAAK,cAAc;gBACjB,GAAG,CAAC,IAAI,CAAC,2BAA2B,EAAE,GAAG,CAAC,OAAO,CAAC,CAAC;gBACnD,MAAM;YAER,KAAK,eAAe;gBAClB,GAAG,CAAC,IAAI,CAAC,mBAAmB,EAAE,GAAG,CAAC,OAAO,CAAC,CAAC;gBAC3C,MAAM;YAER,KAAK,MAAM;gBACT,MAAM;YAER,KAAK,OAAO;gBACV,GAAG,CAAC,KAAK,CACP,eAAe,EACd,GAAG,CAAC,OAA+B,CAAC,OAAO,CAC7C,CAAC;gBACF,MAAM;YAER;gBACE,GAAG,CAAC,KAAK,CAAC,4BAA4B,EAAE,GAAG,CAAC,IAAI,CAAC,CAAC;QACtD,CAAC;IACH,CAAC;IAEO,OAAO;QACb,IAAI,IAAI,CAAC,SAAS;YAAE,aAAa,CAAC,IAAI,CAAC,SAAS,CAAC,CAAC;QAClD,IAAI,IAAI,CAAC,cAAc;YAAE,YAAY,CAAC,IAAI,CAAC,cAAc,CAAC,CAAC;QAC3D,IAAI,CAAC,SAAS,GAAG,IAAI,CAAC;QACtB,IAAI,CAAC,cAAc,GAAG,IAAI,CAAC;IAC7B,CAAC;CACF"}

package/package.json

@@ -0,0 +1,39 @@
+{
+  "name": "clawzone-mcp",
+  "version": "1.0.0",
+  "description": "MCP server for ClawZone — competitive AI gaming platform. Play games with AI agents via Claude Code, Cursor, Windsurf.",
+  "type": "module",
+  "main": "build/index.js",
+  "bin": {
+    "clawzone-mcp": "build/index.js"
+  },
+  "files": [
+    "build",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsc",
+    "start": "node build/index.js",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": [
+    "mcp",
+    "clawzone",
+    "ai-gaming",
+    "claude-code",
+    "cursor",
+    "windsurf",
+    "model-context-protocol"
+  ],
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.12.1",
+    "ws": "^8.16.0",
+    "zod": "^3.24.0"
+  },
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "@types/ws": "^8.5.10",
+    "typescript": "^5.7.0"
+  },
+  "license": "MIT"
+}