@vibevibes/mcp 0.1.0 → 0.3.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 vibevibes
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,51 @@
+# @vibevibes/mcp
+
+MCP server + runtime engine for [vibevibes](https://github.com/vibevibes/sdk) experiences.
+
+Agents connect via MCP. Humans connect via browser. Same room, same state.
+
+## Install
+
+```bash
+npm install @vibevibes/mcp
+```
+
+## Quick Start
+
+```bash
+# Start the server for an experience
+npx vibevibes-serve ./my-experience
+
+# Or use as MCP server (for AI agents)
+npx vibevibes-mcp
+```
+
+## How It Works
+
+1. Define an experience using [@vibevibes/sdk](https://github.com/vibevibes/sdk)
+2. This server loads and runs it
+3. Agents connect via MCP tools (`connect`, `act`, `look`)
+4. Humans open the browser to see the canvas
+5. Everyone shares the same state — tools are the only mutation path
+
+## MCP Tools
+
+| Tool | Purpose |
+|------|---------|
+| `connect` | Join the server, get room info |
+| `act` | Execute a tool in the experience |
+| `look` | Observe current state |
+| `disconnect` | Leave room |
+
+## Ecosystem
+
+| Package | Description |
+|---------|-------------|
+| [@vibevibes/sdk](https://github.com/vibevibes/sdk) | Define experiences — tools, canvas, state |
+| **@vibevibes/mcp** (this) | Runtime server — MCP + WebSocket + browser viewer |
+| [create-vibevibes](https://github.com/vibevibes/create) | `npx create-vibevibes my-exp` — scaffold in seconds |
+| [experiences](https://github.com/vibevibes/experiences) | Example experiences — fork and remix |
+
+## License
+
+MIT

package/bin/cli.js

@@ -1,11 +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";
+#!/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/bin/postinstall.js

@@ -0,0 +1,39 @@
+#!/usr/bin/env node
+
+/**
+ * Postinstall: writes .mcp.json into the project root so Claude Code
+ * can discover the vibevibes MCP server automatically.
+ *
+ * Skipped during self-install (e.g. when building the monorepo).
+ */
+
+import { writeFileSync, existsSync } from "node:fs";
+import { resolve } from "node:path";
+
+// npm sets INIT_CWD to the directory where `npm install` was run
+const projectRoot = process.env.INIT_CWD;
+if (!projectRoot) process.exit(0);
+
+// Skip if we're installing inside the vibevibes monorepo itself
+const isMonorepo = existsSync(resolve(projectRoot, "sdk")) && existsSync(resolve(projectRoot, "mcp"));
+if (isMonorepo) process.exit(0);
+
+const mcpJsonPath = resolve(projectRoot, ".mcp.json");
+
+// Don't overwrite an existing .mcp.json
+if (existsSync(mcpJsonPath)) process.exit(0);
+
+const config = {
+  mcpServers: {
+    vibevibes: {
+      command: "npx",
+      args: ["vibevibes-mcp"],
+      env: {
+        VIBEVIBES_SERVER_URL: "http://localhost:4321",
+      },
+    },
+  },
+};
+
+writeFileSync(mcpJsonPath, JSON.stringify(config, null, 2) + "\n");
+console.log("vibevibes: wrote .mcp.json for Claude Code");

package/bin/serve.js

@@ -0,0 +1,41 @@
+#!/usr/bin/env node
+
+/**
+ * Start the vibevibes server for an experience.
+ *
+ * Usage:
+ *   npx vibevibes-serve              # serves from current directory
+ *   npx vibevibes-serve ./my-exp     # serves from a specific path
+ */
+
+import { resolve } from "node:path";
+import { writeFileSync, existsSync } from "node:fs";
+import { execSync } from "node:child_process";
+import { startServer } from "../dist/server.js";
+
+const projectRoot = resolve(process.argv[2] || ".");
+const port = parseInt(process.env.PORT || "4321", 10);
+
+// Find git root (where Claude Code reads .mcp.json from)
+let mcpJsonDir = projectRoot;
+try {
+  mcpJsonDir = execSync("git rev-parse --show-toplevel", { cwd: projectRoot, encoding: "utf-8" }).trim();
+} catch {}
+
+// Auto-generate .mcp.json so Claude Code can connect via /mcp
+const mcpJsonPath = resolve(mcpJsonDir, ".mcp.json");
+if (!existsSync(mcpJsonPath)) {
+  const config = {
+    mcpServers: {
+      vibevibes: {
+        command: "npx",
+        args: ["vibevibes-mcp"],
+        env: { VIBEVIBES_SERVER_URL: `http://localhost:${port}` },
+      },
+    },
+  };
+  writeFileSync(mcpJsonPath, JSON.stringify(config, null, 2) + "\n");
+  console.log(`  .mcp.json: wrote ${mcpJsonPath}`);
+}
+
+startServer({ projectRoot, port });

package/dist/bundler.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Experience bundler — produces server and client bundles from src/index.tsx.
+ *
+ * Server bundle: CJS, eval'd via new Function() to extract tools + manifest.
+ * Client bundle: ESM, loaded in browser via blob URL + dynamic import().
+ *
+ * Extracted from create-experience/runtime/bundler.ts into @vibevibes/runtime.
+ */
+/**
+ * Bundle for server-side tool execution (Node.js eval).
+ * Returns the raw ExperienceModule extracted via new Function().
+ */
+export declare function bundleForServer(entryPath: string): Promise<string>;
+/**
+ * Evaluate a server bundle and extract the ExperienceModule.
+ */
+export declare function evalServerBundle(serverCode: string): Promise<unknown>;
+/**
+ * Bundle for client-side Canvas rendering (browser).
+ * Returns pure ESM. External imports (react, zod, etc.) are left as-is —
+ * the viewer's import map resolves them in the browser.
+ */
+export declare function bundleForClient(entryPath: string): Promise<string>;
+/**
+ * Build both bundles from an entry file.
+ */
+export declare function buildExperience(entryPath: string): Promise<{
+    serverCode: string;
+    clientCode: string;
+}>;
+/**
+ * Validate a client bundle for common issues.
+ * Lightweight — esbuild already validates syntax. This just checks the output exists.
+ * Returns null if OK, or an error message string.
+ */
+export declare function validateClientBundle(code: string): string | null;

package/dist/bundler.js

@@ -0,0 +1,254 @@
+/**
+ * Experience bundler — produces server and client bundles from src/index.tsx.
+ *
+ * Server bundle: CJS, eval'd via new Function() to extract tools + manifest.
+ * Client bundle: ESM, loaded in browser via blob URL + dynamic import().
+ *
+ * Extracted from create-experience/runtime/bundler.ts into @vibevibes/runtime.
+ */
+import * as esbuild from "esbuild";
+const EXTERNALS = ["react", "react/jsx-runtime", "react-dom", "react-dom/client", "yjs", "zod", "@vibevibes/sdk", "@vibevibes/runtime"];
+// Additional externals for server-only bundles — heavy rendering libraries that
+// aren't needed for tool/test execution. Canvas components are never called server-side.
+const SERVER_ONLY_EXTERNALS = [
+    ...EXTERNALS,
+    "three", "three/*",
+    "@react-three/fiber", "@react-three/fiber/*",
+    "@react-three/drei", "@react-three/drei/*",
+];
+/**
+ * Strip esbuild's CJS annotation: `0 && (module.exports = {...})`.
+ * Uses brace-depth counting to handle nested objects/functions in the annotation,
+ * unlike a simple `[^}]*` regex which breaks on nested braces.
+ */
+function stripCjsAnnotation(code) {
+    const marker = /0\s*&&\s*\(module\.exports\s*=\s*\{/g;
+    let match;
+    let result = code;
+    while ((match = marker.exec(code)) !== null) {
+        const start = match.index;
+        let depth = 1; // we matched the opening `{`
+        let i = match.index + match[0].length;
+        while (i < code.length && depth > 0) {
+            if (code[i] === "{")
+                depth++;
+            else if (code[i] === "}")
+                depth--;
+            i++;
+        }
+        // Skip the closing `)` and optional `;`
+        if (i < code.length && code[i] === ")")
+            i++;
+        if (i < code.length && code[i] === ";")
+            i++;
+        result = result.slice(0, start) + "/* [vibevibes] stripped CJS annotation */" + result.slice(i);
+        break; // Only one annotation per bundle
+    }
+    return result;
+}
+/**
+ * Strip import/export statements for external packages.
+ * The runtime provides these via globalThis (browser) or function args (server).
+ */
+/**
+ * Strip external imports from a CJS server bundle so it can be eval'd with new Function().
+ * Only used for server bundles — client bundles keep imports (resolved by browser import map).
+ */
+function stripExternalImports(code, externals = EXTERNALS) {
+    let result = code;
+    for (const ext of externals) {
+        let escaped;
+        if (ext.endsWith("/*")) {
+            const base = ext.slice(0, -2).replace(/[.*+?^${}()|[\]\\\/]/g, "\\$&");
+            escaped = `${base}\\/[^"']+`;
+        }
+        else {
+            escaped = ext.replace(/[.*+?^${}()|[\]\\\/]/g, "\\$&");
+        }
+        // CJS: var import_X = __toESM(require("pkg"), N); or var import_X = require("pkg");
+        result = result.replace(new RegExp(`var\\s+\\w+\\s*=\\s*(?:__toESM\\()?require\\(["']${escaped}["']\\)[^;]{0,500};`, "g"), "");
+    }
+    return result;
+}
+/**
+ * CJS shim definitions for server-side eval (new Function()).
+ * Maps esbuild-generated variable names to runtime-provided globals.
+ */
+const SDK_CORE_SHIM = "{ defineExperience: defineExperience, defineTool: defineTool, defineTest: defineTest, defineStream: defineStream, createChatTools: createChatTools, default: { defineExperience: defineExperience, defineTool: defineTool, defineTest: defineTest, defineStream: defineStream, createChatTools: createChatTools } }";
+const CJS_BASE_SHIMS = {
+    import_react: "{ default: React, __esModule: true, createElement: React.createElement, Fragment: React.Fragment, useState: React.useState, useEffect: React.useEffect, useCallback: React.useCallback, useMemo: React.useMemo, useRef: React.useRef, useContext: React.useContext, useReducer: React.useReducer, createContext: React.createContext, forwardRef: React.forwardRef, memo: React.memo }",
+    import_zod: "{ z: z, default: z }",
+    import_yjs: "{ default: Y }",
+    import_sdk: SDK_CORE_SHIM,
+    import_vibevibes_sdk: SDK_CORE_SHIM,
+    import_runtime: SDK_CORE_SHIM,
+    import_vibevibes_runtime: SDK_CORE_SHIM,
+    import_react_dom: "{ default: {}, __esModule: true }",
+    import_client: "{ default: {}, __esModule: true }",
+    // Proxy stubs for rendering libraries (server-side only — Canvas is never called)
+    import_three: "(new Proxy({}, { get: (_, p) => typeof p === 'string' ? function(){} : undefined }))",
+    import_fiber: "(new Proxy({}, { get: (_, p) => typeof p === 'string' ? function(){} : undefined }))",
+    import_drei: "(new Proxy({}, { get: (_, p) => typeof p === 'string' ? function(){} : undefined }))",
+};
+/**
+ * Inject CJS shim variables for server-side eval.
+ */
+function injectCjsShims(code) {
+    const lines = [];
+    // Emit base shims
+    for (const [name, value] of Object.entries(CJS_BASE_SHIMS)) {
+        lines.push(`var ${name} = ${value};`);
+    }
+    // Scan for numbered variants (e.g. import_react2, import_zod3) and alias them
+    for (const baseName of Object.keys(CJS_BASE_SHIMS)) {
+        const pattern = new RegExp(`\\b(${baseName}(\\d+))\\b`, "g");
+        const seen = new Set();
+        let match;
+        while ((match = pattern.exec(code)) !== null) {
+            const numberedName = match[1];
+            if (!seen.has(numberedName)) {
+                seen.add(numberedName);
+                lines.push(`var ${numberedName} = ${baseName};`);
+            }
+        }
+    }
+    return lines.join("\n");
+}
+/**
+ * Format esbuild errors into actionable messages with file:line and suggestions.
+ */
+function formatEsbuildError(err, target) {
+    const buildErr = err;
+    if (buildErr.errors && Array.isArray(buildErr.errors)) {
+        const formatted = buildErr.errors.map((e) => {
+            const loc = e.location
+                ? `${e.location.file}:${e.location.line}:${e.location.column}`
+                : "unknown location";
+            return `  ${loc}: ${e.text}`;
+        }).join("\n");
+        return new Error(`Build failed (${target} bundle):\n${formatted}\n\n` +
+            `Common fixes:\n` +
+            `- Check for syntax errors at the indicated location\n` +
+            `- Ensure all imports resolve to existing files in src/\n` +
+            `- Verify @vibevibes/sdk imports match the available exports`);
+    }
+    return err instanceof Error ? err : new Error(String(err));
+}
+/**
+ * Bundle for server-side tool execution (Node.js eval).
+ * Returns the raw ExperienceModule extracted via new Function().
+ */
+export async function bundleForServer(entryPath) {
+    let result;
+    try {
+        result = await esbuild.build({
+            entryPoints: [entryPath],
+            bundle: true,
+            format: "cjs",
+            platform: "node",
+            target: "es2022",
+            write: false,
+            external: SERVER_ONLY_EXTERNALS,
+            jsx: "transform",
+            jsxFactory: "React.createElement",
+            jsxFragment: "React.Fragment",
+            logLevel: "silent",
+        });
+    }
+    catch (err) {
+        throw formatEsbuildError(err, "server");
+    }
+    const outputFile = result.outputFiles?.[0];
+    if (!outputFile)
+        throw new Error("esbuild produced no output files for server bundle");
+    let code = outputFile.text;
+    code = stripExternalImports(code, SERVER_ONLY_EXTERNALS);
+    // Strip user-code React hook destructuring (already provided by CJS shims)
+    code = code.replace(/(?:const|let|var)\s+\{[^}]*?\b(?:useState|useEffect|useCallback|useMemo|useRef|useContext|useReducer)\b[^}]*?\}\s*=\s*(?:React|import_react\w*)\s*;/g, "/* [vibevibes] stripped duplicate React destructuring */");
+    // Inject CJS shims for esbuild-generated variable references
+    // Pass code so we can detect numbered variants (import_react2, etc.)
+    code = injectCjsShims(code) + "\n" + code;
+    // Strip esbuild's CJS annotation `0 && (module.exports = {...})` — dead code that
+    // causes syntax errors when module.exports is replaced with var assignment.
+    // Uses brace-depth counting to handle nested objects/functions in the annotation.
+    code = stripCjsAnnotation(code);
+    // Replace module.exports/export default with variable assignment
+    code = code.replace(/module\.exports\s*=\s*/g, "var __experience_export__ = ");
+    code = code.replace(/exports\.default(?!\w)\s*=\s*/g, "var __experience_export__ = ");
+    return code;
+}
+/**
+ * Evaluate a server bundle and extract the ExperienceModule.
+ */
+export async function evalServerBundle(serverCode) {
+    const sdk = await import("@vibevibes/sdk");
+    const { defineExperience, defineTool, defineTest, defineStream, createChatTools } = sdk;
+    const noop = () => null;
+    const stubReact = {
+        createElement: noop, Fragment: "Fragment",
+        useState: (init) => [typeof init === "function" ? init() : init, noop],
+        useEffect: noop, useCallback: (fn) => fn,
+        useMemo: (fn) => fn(), useRef: (init) => ({ current: init ?? null }),
+        useContext: noop, useReducer: noop,
+        createContext: noop, forwardRef: noop, memo: (x) => x,
+    };
+    const zodModule = await import("zod");
+    const z = zodModule.z ?? zodModule.default ?? zodModule;
+    const fn = new Function("globalThis", "process", "global", "React", "Y", "z", "defineExperience", "defineTool", "defineTest", "defineStream", "createChatTools", "require", "exports", "module", "console", `"use strict";\n${serverCode}\nreturn typeof __experience_export__ !== 'undefined' ? __experience_export__ : (typeof module !== 'undefined' ? module.exports : undefined);`);
+    const fakeModule = { exports: {} };
+    const sandboxGlobal = Object.create(null);
+    const sandboxProcess = { env: { NODE_ENV: "production" } };
+    const result = fn(sandboxGlobal, sandboxProcess, sandboxGlobal, stubReact, {}, z, defineExperience, defineTool, defineTest, defineStream, createChatTools, (id) => { throw new Error(`require('${id}') is not supported in the vibevibes server sandbox. Add '${id}' to EXTERNALS in bundler.ts.`); }, fakeModule.exports, fakeModule, console);
+    const exports = fakeModule.exports;
+    return result?.default ?? result ?? exports?.default ?? exports;
+}
+/**
+ * Bundle for client-side Canvas rendering (browser).
+ * Returns pure ESM. External imports (react, zod, etc.) are left as-is —
+ * the viewer's import map resolves them in the browser.
+ */
+export async function bundleForClient(entryPath) {
+    let result;
+    try {
+        result = await esbuild.build({
+            entryPoints: [entryPath],
+            bundle: true,
+            format: "esm",
+            platform: "browser",
+            target: "es2020",
+            write: false,
+            external: EXTERNALS,
+            jsx: "transform",
+            jsxFactory: "React.createElement",
+            jsxFragment: "React.Fragment",
+            logLevel: "silent",
+        });
+    }
+    catch (err) {
+        throw formatEsbuildError(err, "client");
+    }
+    const clientOutputFile = result.outputFiles?.[0];
+    if (!clientOutputFile)
+        throw new Error("esbuild produced no output files for client bundle");
+    return clientOutputFile.text;
+}
+/**
+ * Build both bundles from an entry file.
+ */
+export async function buildExperience(entryPath) {
+    const [serverCode, clientCode] = await Promise.all([
+        bundleForServer(entryPath),
+        bundleForClient(entryPath),
+    ]);
+    return { serverCode, clientCode };
+}
+/**
+ * Validate a client bundle for common issues.
+ * Lightweight — esbuild already validates syntax. This just checks the output exists.
+ * Returns null if OK, or an error message string.
+ */
+export function validateClientBundle(code) {
+    if (!code || !code.trim())
+        return "Client bundle is empty";
+    return null;
+}

package/dist/index.d.ts

@@ -1,13 +1,9 @@
 /**
- * vibevibes-mcp — standalone MCP server for joining vibevibes experiences.
+ * vibevibes-mcp — MCP server for agent participation in vibevibes experiences.
  *
- * Works with both local dev servers and remote shared tunnels.
+ * The `connect` tool is the single entry point: it joins the server, writes
+ * the state file (for the stop hook to poll), and returns room info.
  *
- * 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
+ * 4 tools: connect, act, look, disconnect
  */
 export {};