vibevibes-mcp-server 0.1.0

package/README.md

@@ -0,0 +1,96 @@
+# @vibevibes/mcp-server
+
+MCP server for [vibe vibes](https://github.com/o-one-run/vibe-vibes) — create and manage collaborative multiplayer AI experiences from Claude Code.
+
+## Install
+
+```bash
+npm install -g @vibevibes/mcp-server
+```
+
+Or use directly with `npx`:
+
+```bash
+npx @vibevibes/mcp-server
+```
+
+## Configure in Claude Code
+
+Add to your `.mcp.json`:
+
+```json
+{
+  "mcpServers": {
+    "vibevibes": {
+      "type": "stdio",
+      "command": "npx",
+      "args": ["-y", "@vibevibes/mcp-server"]
+    }
+  }
+}
+```
+
+### Environment variables
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `VIBEVIBES_REALTIME_URL` | Railway production | URL of the realtime server |
+| `VIBEVIBES_WEB_URL` | Railway production | URL of the web app |
+| `GITHUB_TOKEN` | — | GitHub PAT for experience storage |
+| `GITHUB_OWNER` | derived from token | GitHub org/user for repos |
+
+For local development:
+
+```json
+{
+  "mcpServers": {
+    "vibevibes": {
+      "type": "stdio",
+      "command": "npx",
+      "args": ["-y", "@vibevibes/mcp-server"],
+      "env": {
+        "VIBEVIBES_REALTIME_URL": "http://localhost:4000",
+        "VIBEVIBES_WEB_URL": "http://localhost:3000"
+      }
+    }
+  }
+}
+```
+
+## Tools
+
+| Tool | Description |
+|------|-------------|
+| `vibevibes_health` | Check realtime server health |
+| `vibevibes_diagnostics` | Detailed server diagnostics and event log |
+| `vibevibes_list_experiences` | List all saved experiences |
+| `vibevibes_get_experience_source` | Get full source code of an experience |
+| `vibevibes_get_experience_tools` | List tools exported by an experience |
+| `vibevibes_save_experience` | Create/update a single-file experience |
+| `vibevibes_save_experience_files` | Create/update a multi-file experience |
+| `vibevibes_get_experience_files` | Get all files for a multi-file experience |
+| `vibevibes_edit_experience_file` | Update/delete specific files in an experience |
+| `vibevibes_create_room` | Create a new room for an experience |
+| `vibevibes_join_room` | Join a room as a participant |
+| `vibevibes_watch_room` | Long-poll for activity in a joined room |
+| `vibevibes_leave_room` | Leave a room |
+| `vibevibes_get_room_state` | Inspect shared state and participants |
+| `vibevibes_room_screenshot` | Capture a PNG screenshot of a room |
+| `vibevibes_execute_tool` | Execute a tool in a room |
+| `vibevibes_edit_experience` | Edit an experience and hot-reload in a room |
+| `vibevibes_sync_from_github` | Re-sync an experience from GitHub |
+
+## How it works
+
+The MCP server is a bridge between Claude Code and a running vibe vibes instance. It communicates with the realtime server over HTTP and exposes every operation as an MCP tool. This means Claude Code can:
+
+- Create and edit experiences (collaborative multiplayer apps)
+- Create rooms and execute tools inside them
+- Join rooms alongside humans and react to their actions
+- Take screenshots to see the current visual state
+
+All state mutations go through the same tool gate that humans use, so the audit log and event system stay consistent.
+
+## License
+
+MIT

package/dist/http-client.d.ts

@@ -0,0 +1,21 @@
+declare const REALTIME_URL: string;
+declare const WEB_URL: string;
+export type HttpResult<T = any> = {
+    ok: boolean;
+    status: number;
+    data?: T;
+    error?: string;
+};
+export declare function realtimeGet<T = any>(path: string, timeoutMs?: number): Promise<HttpResult<T>>;
+export declare function realtimePost<T = any>(path: string, body: any, extraHeaders?: Record<string, string>): Promise<HttpResult<T>>;
+export declare function realtimePatch<T = any>(path: string, body: any, extraHeaders?: Record<string, string>): Promise<HttpResult<T>>;
+export declare function webGet<T = any>(path: string): Promise<HttpResult<T>>;
+export declare function webPost<T = any>(path: string, body: any): Promise<HttpResult<T>>;
+export declare function realtimeGetBinary(path: string): Promise<{
+    ok: boolean;
+    data?: Buffer;
+    contentType?: string;
+    error?: string;
+}>;
+export { REALTIME_URL, WEB_URL };
+//# sourceMappingURL=http-client.d.ts.map

package/dist/http-client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"http-client.d.ts","sourceRoot":"","sources":["../src/http-client.ts"],"names":[],"mappings":"AAKA,QAAA,MAAM,YAAY,QAA8F,CAAC;AACjH,QAAA,MAAM,OAAO,QAAyF,CAAC;AAEvG,MAAM,MAAM,UAAU,CAAC,CAAC,GAAG,GAAG,IAAI;IAChC,EAAE,EAAE,OAAO,CAAC;IACZ,MAAM,EAAE,MAAM,CAAC;IACf,IAAI,CAAC,EAAE,CAAC,CAAC;IACT,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB,CAAC;AAsDF,wBAAgB,WAAW,CAAC,CAAC,GAAG,GAAG,EAAE,IAAI,EAAE,MAAM,EAAE,SAAS,CAAC,EAAE,MAAM,0BAEpE;AAED,wBAAgB,YAAY,CAAC,CAAC,GAAG,GAAG,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,GAAG,EAAE,YAAY,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,0BAEnG;AAED,wBAAgB,aAAa,CAAC,CAAC,GAAG,GAAG,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,GAAG,EAAE,YAAY,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,0BAEpG;AAID,wBAAgB,MAAM,CAAC,CAAC,GAAG,GAAG,EAAE,IAAI,EAAE,MAAM,0BAE3C;AAED,wBAAgB,OAAO,CAAC,CAAC,GAAG,GAAG,EAAE,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,GAAG,0BAEvD;AAID,wBAAsB,iBAAiB,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC;IAAE,EAAE,EAAE,OAAO,CAAC;IAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAAC,KAAK,CAAC,EAAE,MAAM,CAAA;CAAE,CAAC,CAiBnI;AAED,OAAO,EAAE,YAAY,EAAE,OAAO,EAAE,CAAC"}

package/dist/http-client.js

@@ -0,0 +1,79 @@
+const REALTIME_URL = process.env.VIBEVIBES_REALTIME_URL || "https://vibevibesrealtime-production.up.railway.app";
+const WEB_URL = process.env.VIBEVIBES_WEB_URL || "https://vibevibesweb-production-e644.up.railway.app";
+async function request(baseUrl, path, method, body, extraHeaders, timeoutMs) {
+    const url = `${baseUrl}${path}`;
+    try {
+        const headers = {
+            ...(body ? { "Content-Type": "application/json" } : {}),
+            ...(extraHeaders || {}),
+        };
+        const fetchOptions = {
+            method,
+            headers: Object.keys(headers).length > 0 ? headers : undefined,
+            body: body ? JSON.stringify(body) : undefined,
+        };
+        if (timeoutMs) {
+            fetchOptions.signal = AbortSignal.timeout(timeoutMs);
+        }
+        const res = await fetch(url, fetchOptions);
+        const text = await res.text();
+        let data;
+        try {
+            data = JSON.parse(text);
+        }
+        catch {
+            data = text;
+        }
+        if (!res.ok) {
+            return {
+                ok: false,
+                status: res.status,
+                error: data?.error || data?.message || `HTTP ${res.status}: ${text.slice(0, 200)}`,
+            };
+        }
+        return { ok: true, status: res.status, data };
+    }
+    catch (err) {
+        return {
+            ok: false,
+            status: 0,
+            error: `Connection failed: ${err.message}. Is the server running at ${baseUrl}?`,
+        };
+    }
+}
+export function realtimeGet(path, timeoutMs) {
+    return request(REALTIME_URL, path, "GET", undefined, undefined, timeoutMs);
+}
+export function realtimePost(path, body, extraHeaders) {
+    return request(REALTIME_URL, path, "POST", body, extraHeaders);
+}
+export function realtimePatch(path, body, extraHeaders) {
+    return request(REALTIME_URL, path, "PATCH", body, extraHeaders);
+}
+export function webGet(path) {
+    return request(WEB_URL, path, "GET");
+}
+export function webPost(path, body) {
+    return request(WEB_URL, path, "POST", body);
+}
+export async function realtimeGetBinary(path) {
+    const url = `${REALTIME_URL}${path}`;
+    try {
+        const res = await fetch(url);
+        if (!res.ok) {
+            const text = await res.text();
+            return { ok: false, error: `HTTP ${res.status}: ${text.slice(0, 200)}` };
+        }
+        const arrayBuffer = await res.arrayBuffer();
+        return {
+            ok: true,
+            data: Buffer.from(arrayBuffer),
+            contentType: res.headers.get('content-type') || 'application/octet-stream',
+        };
+    }
+    catch (err) {
+        return { ok: false, error: `Connection failed: ${err.message}` };
+    }
+}
+export { REALTIME_URL, WEB_URL };
+//# sourceMappingURL=http-client.js.map

package/dist/http-client.js.map

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

package/dist/index.d.ts

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+export {};
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

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