@vibevibes/mcp 0.1.0

package/bin/cli.js

@@ -0,0 +1,11 @@
+#!/usr/bin/env node
+
+/**
+ * @vibevibes/mcp CLI
+ *
+ * Usage:
+ *   npx @vibevibes/mcp                                    # localhost:4321
+ *   npx @vibevibes/mcp https://xyz.trycloudflare.com      # remote shared room
+ */
+
+import "../dist/index.js";

package/dist/index.d.ts

@@ -0,0 +1,13 @@
+/**
+ * vibevibes-mcp — standalone MCP server for joining vibevibes experiences.
+ *
+ * Works with both local dev servers and remote shared tunnels.
+ *
+ * Usage:
+ *   npx vibevibes-mcp                          # defaults to http://localhost:4321
+ *   npx vibevibes-mcp https://xyz.trycloudflare.com  # join a shared room
+ *   VIBEVIBES_SERVER_URL=https://... npx vibevibes-mcp
+ *
+ * 5 tools: connect, watch, act, memory, screenshot
+ */
+export {};

package/dist/index.js

@@ -0,0 +1,319 @@
+/**
+ * vibevibes-mcp — standalone MCP server for joining vibevibes experiences.
+ *
+ * Works with both local dev servers and remote shared tunnels.
+ *
+ * Usage:
+ *   npx vibevibes-mcp                          # defaults to http://localhost:4321
+ *   npx vibevibes-mcp https://xyz.trycloudflare.com  # join a shared room
+ *   VIBEVIBES_SERVER_URL=https://... npx vibevibes-mcp
+ *
+ * 5 tools: connect, watch, act, memory, screenshot
+ */
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { z } from "zod";
+// Resolve server URL: CLI arg > env var > localhost default
+const RAW_SERVER_URL = process.argv[2] ||
+    process.env.VIBEVIBES_SERVER_URL ||
+    "http://localhost:4321";
+// Extract room token from the URL query param (e.g. https://xyz.trycloudflare.com?token=abc123)
+const parsedUrl = new URL(RAW_SERVER_URL);
+const ROOM_TOKEN = parsedUrl.searchParams.get("token");
+// Strip the token param from the base URL so it isn't duplicated in request paths
+parsedUrl.searchParams.delete("token");
+const SERVER_URL = parsedUrl.toString().replace(/\/$/, ""); // remove trailing slash
+// ── State ──────────────────────────────────────────────────
+let currentActorId = null;
+let lastEventTs = 0;
+let connected = false;
+// ── Helpers ────────────────────────────────────────────────
+async function fetchJSON(path, opts) {
+    const headers = {
+        "Content-Type": "application/json",
+        ...(opts?.headers || {}),
+    };
+    // Attach room token as Authorization header when available
+    if (ROOM_TOKEN) {
+        headers["Authorization"] = `Bearer ${ROOM_TOKEN}`;
+    }
+    const res = await fetch(`${SERVER_URL}${path}`, {
+        ...opts,
+        headers,
+    });
+    const text = await res.text();
+    try {
+        return JSON.parse(text);
+    }
+    catch {
+        throw new Error(`Server returned non-JSON: ${text.slice(0, 200)}`);
+    }
+}
+function formatToolList(tools) {
+    if (!tools?.length)
+        return "No tools available.";
+    return tools
+        .map((t) => {
+        const schema = t.input_schema?.properties
+            ? Object.entries(t.input_schema.properties)
+                .map(([k, v]) => `${k}: ${v.type || "any"}`)
+                .join(", ")
+            : "{}";
+        return `  ${t.name} (${t.risk || "low"}) — ${t.description}\n    input: { ${schema} }`;
+    })
+        .join("\n");
+}
+async function joinRoom() {
+    const join = await fetchJSON("/join", {
+        method: "POST",
+        body: JSON.stringify({ username: "claude", actorType: "ai" }),
+    });
+    if (join.error)
+        throw new Error(join.error);
+    currentActorId = join.actorId;
+    lastEventTs = Date.now();
+    connected = true;
+    return join;
+}
+async function ensureConnected() {
+    if (connected)
+        return;
+    await joinRoom();
+}
+// ── MCP Server ─────────────────────────────────────────────
+const server = new McpServer({
+    name: "vibevibes",
+    version: "0.1.0",
+});
+// ── Tool: connect ──────────────────────────────────────────
+server.tool("connect", `Connect to the running experience.
+
+Returns: available tools, current state, participants, and the browser URL.
+
+Call this first before using watch or act.`, {}, async () => {
+    try {
+        const join = await joinRoom();
+        const output = [
+            `Connected as ${currentActorId}`,
+            `Experience: ${join.experienceId}`,
+            `Browser: ${join.browserUrl}`,
+            `Server: ${SERVER_URL}`,
+            ``,
+            `State: ${JSON.stringify(join.sharedState, null, 2)}`,
+            `Participants: ${join.participants?.join(", ")}`,
+            ``,
+            `Tools:`,
+            formatToolList(join.tools),
+        ].join("\n");
+        return { content: [{ type: "text", text: output }] };
+    }
+    catch (err) {
+        return {
+            content: [{
+                    type: "text",
+                    text: `Failed to connect to ${SERVER_URL}.\n\nIs the dev server running? (npm run dev)\n\nError: ${err.message}`,
+                }],
+        };
+    }
+});
+// ── Tool: watch ────────────────────────────────────────────
+server.tool("watch", `Wait for activity in the experience. Blocks until events arrive or timeout.
+
+Use predicate to wait for a condition, e.g. "state.count > 5".
+Use filterTools to only wake for specific tools, e.g. ["pixel.place"].
+Use filterActors to only wake for specific actors.
+
+Auto-connects if not already connected.`, {
+    timeout: z.number().optional().describe("Max wait ms (default 30000, max 55000)"),
+    predicate: z.string().optional().describe('JS expression, e.g. "state.count > 5"'),
+    filterTools: z.array(z.string()).optional().describe("Only wake for these tools"),
+    filterActors: z.array(z.string()).optional().describe("Only wake for these actors"),
+}, async ({ timeout, predicate, filterTools, filterActors }) => {
+    try {
+        await ensureConnected();
+    }
+    catch (err) {
+        return { content: [{ type: "text", text: `Not connected: ${err.message}` }] };
+    }
+    const t = Math.min(timeout || 30000, 55000);
+    // Check if predicate already matches
+    if (predicate) {
+        try {
+            const current = await fetchJSON("/state");
+            const fn = new Function("state", "actorId", `return ${predicate}`);
+            if (fn(current.sharedState, currentActorId)) {
+                return {
+                    content: [{
+                            type: "text",
+                            text: [
+                                `Predicate already true: ${predicate}`,
+                                `State: ${JSON.stringify(current.sharedState, null, 2)}`,
+                                `Participants: ${current.participants?.join(", ")}`,
+                            ].join("\n"),
+                        }],
+                };
+            }
+        }
+        catch {
+            // Predicate eval failed, continue to long-poll
+        }
+    }
+    // Long-poll for events
+    const data = await fetchJSON(`/events?since=${lastEventTs}&timeout=${t}`);
+    let events = data.events || [];
+    if (filterTools?.length) {
+        events = events.filter((e) => filterTools.includes(e.tool));
+    }
+    if (filterActors?.length) {
+        events = events.filter((e) => filterActors.includes(e.actorId));
+    }
+    if (events.length > 0) {
+        lastEventTs = Math.max(...events.map((e) => e.ts));
+    }
+    let predicateMatched = false;
+    if (predicate) {
+        try {
+            const fn = new Function("state", "actorId", `return ${predicate}`);
+            predicateMatched = !!fn(data.sharedState, currentActorId);
+        }
+        catch {
+            // ignore
+        }
+    }
+    const parts = [];
+    if (events.length > 0) {
+        parts.push(`${events.length} event(s):`);
+        for (const e of events) {
+            parts.push(`  [${e.actorId}] ${e.tool}(${JSON.stringify(e.input)}) → ${e.error ? `ERROR: ${e.error}` : JSON.stringify(e.output)}`);
+        }
+    }
+    else {
+        parts.push("No new events (timeout).");
+    }
+    parts.push(`State: ${JSON.stringify(data.sharedState, null, 2)}`);
+    parts.push(`Participants: ${data.participants?.join(", ")}`);
+    if (predicate) {
+        parts.push(`Predicate "${predicate}": ${predicateMatched}`);
+    }
+    return { content: [{ type: "text", text: parts.join("\n") }] };
+});
+// ── Tool: act ──────────────────────────────────────────────
+server.tool("act", `Execute a tool to mutate shared state. All state changes go through tools.
+
+Example: act(toolName="counter.increment", input={amount: 2})
+
+Auto-connects if not already connected.`, {
+    toolName: z.string().describe("Tool to call, e.g. 'counter.increment'"),
+    input: z.record(z.any()).optional().describe("Tool input parameters"),
+}, async ({ toolName, input }) => {
+    try {
+        await ensureConnected();
+    }
+    catch (err) {
+        return { content: [{ type: "text", text: `Not connected: ${err.message}` }] };
+    }
+    const result = await fetchJSON(`/tools/${toolName}`, {
+        method: "POST",
+        body: JSON.stringify({
+            actorId: currentActorId || "mcp-client",
+            input: input || {},
+        }),
+    });
+    if (result.error) {
+        return { content: [{ type: "text", text: `Tool error: ${result.error}` }] };
+    }
+    const state = await fetchJSON("/state");
+    const output = [
+        `${toolName} → ${JSON.stringify(result.output)}`,
+        `State: ${JSON.stringify(state.sharedState, null, 2)}`,
+    ].join("\n");
+    return { content: [{ type: "text", text: output }] };
+});
+// ── Tool: memory ───────────────────────────────────────────
+server.tool("memory", `Persistent agent memory (per-session). Survives across tool calls.
+
+Actions:
+  get — Retrieve current memory
+  set — Merge updates into memory`, {
+    action: z.enum(["get", "set"]).describe("What to do"),
+    updates: z.record(z.any()).optional().describe("Key-value pairs to merge (for set)"),
+}, async ({ action, updates }) => {
+    const key = currentActorId
+        ? `local:${currentActorId}`
+        : "default";
+    if (action === "get") {
+        const data = await fetchJSON(`/memory?key=${encodeURIComponent(key)}`);
+        return {
+            content: [{
+                    type: "text",
+                    text: `Memory: ${JSON.stringify(data, null, 2)}`,
+                }],
+        };
+    }
+    if (action === "set") {
+        if (!updates || Object.keys(updates).length === 0) {
+            return { content: [{ type: "text", text: "No updates provided." }] };
+        }
+        await fetchJSON("/memory", {
+            method: "POST",
+            body: JSON.stringify({ key, updates }),
+        });
+        return { content: [{ type: "text", text: `Memory updated: ${JSON.stringify(updates)}` }] };
+    }
+    return { content: [{ type: "text", text: `Unknown action: ${action}` }] };
+});
+// ── Tool: screenshot ──────────────────────────────────────
+server.tool("screenshot", `Capture a screenshot of the experience as seen in the browser.
+
+Returns the current visual state as a PNG image.
+Requires the browser viewer to be open.
+
+Use this to see what the user sees — inspect paintings, check layouts, read rendered text, etc.`, {
+    timeout: z.number().optional().describe("Max wait ms (default 10000)"),
+}, async ({ timeout }) => {
+    try {
+        const t = Math.min(timeout || 10000, 30000);
+        const screenshotHeaders = {};
+        if (ROOM_TOKEN) {
+            screenshotHeaders["Authorization"] = `Bearer ${ROOM_TOKEN}`;
+        }
+        const res = await fetch(`${SERVER_URL}/screenshot?timeout=${t}`, {
+            headers: screenshotHeaders,
+        });
+        if (!res.ok) {
+            const err = await res.json().catch(() => ({ error: res.statusText }));
+            return {
+                content: [{
+                        type: "text",
+                        text: `Screenshot failed: ${err.error || "Unknown error"}`,
+                    }],
+            };
+        }
+        const arrayBuffer = await res.arrayBuffer();
+        const base64 = Buffer.from(arrayBuffer).toString("base64");
+        return {
+            content: [{
+                    type: "image",
+                    data: base64,
+                    mimeType: "image/png",
+                }],
+        };
+    }
+    catch (err) {
+        return {
+            content: [{
+                    type: "text",
+                    text: `Screenshot failed: ${err.message}. Is the dev server running? Is the browser open?`,
+                }],
+        };
+    }
+});
+// ── Start ──────────────────────────────────────────────────
+async function main() {
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+}
+main().catch((err) => {
+    console.error("MCP server failed:", err);
+    process.exit(1);
+});

package/package.json

@@ -0,0 +1,33 @@
+{
+  "name": "@vibevibes/mcp",
+  "version": "0.1.0",
+  "description": "MCP server for joining vibevibes experiences — local or remote",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "bin": {
+    "vibevibes-mcp": "./bin/cli.js"
+  },
+  "scripts": {
+    "build": "tsc",
+    "prepublishOnly": "npm run build",
+    "dev": "tsx src/index.ts"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.9.0",
+    "zod": "^3.22.4"
+  },
+  "devDependencies": {
+    "tsx": "^4.7.0",
+    "typescript": "^5.3.3",
+    "@types/node": "^20.11.5"
+  },
+  "files": [
+    "dist",
+    "bin"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "license": "MIT"
+}