construct-shader-graph-mcp 0.1.0

package/README.md

@@ -0,0 +1,183 @@
+<p align="center">
+  <img src="./caw-icon-512.png" alt="Construct Shader Graph MCP icon" width="128" height="128">
+</p>
+
+# Construct Shader Graph MCP
+
+Standalone MCP server for controlling Construct Shader Graph through its browser bridge.
+
+It exposes project discovery, manifest inspection, and exact method execution for the live app, while also bundling the guidance the model needs to work well with the tool.
+
+Construct Shader Graph is a visual editor for building Construct effect shaders as node graphs. You can find the app here:
+
+- `https://skymen.github.io/construct-shader-graph/`
+
+## Features
+
+- MCP tools for project discovery and method execution
+- local WebSocket bridge on `ws://127.0.0.1:6359` by default
+- built-in skill guidance available directly from the MCP
+- works with hosts like Claude Desktop and OpenCode
+
+## MCP tools
+
+- `get_skill_guidance`
+- `list_projects`
+- `select_project`
+- `get_project_manifest`
+- `call_project_method`
+
+## Install as a package
+
+Global install:
+
+```bash
+npm install -g construct-shader-graph-mcp
+```
+
+Run after installing globally:
+
+```bash
+construct-shader-graph-mcp
+```
+
+Or run without installing globally:
+
+```bash
+npx -y construct-shader-graph-mcp
+```
+
+## Local development
+
+Clone the repo and install dependencies:
+
+```bash
+git clone https://github.com/skymen/construct-shader-graph-mcp.git
+cd construct-shader-graph-mcp
+npm install
+```
+
+Run locally:
+
+```bash
+npm start
+```
+
+## Configuration
+
+Optional environment variable:
+
+- `MCP_BRIDGE_PORT` to change the browser bridge port from `6359`
+
+Example:
+
+```bash
+MCP_BRIDGE_PORT=6360 construct-shader-graph-mcp
+```
+
+## How it works
+
+There are two sides to the integration:
+
+1. The MCP host launches this package over stdio.
+2. The Construct Shader Graph page connects to the local WebSocket bridge.
+
+The page should:
+
+- connect to `ws://127.0.0.1:6359` by default
+- register itself with project metadata from `shader.getInfo()`
+- answer `invoke` messages with exact API return values
+
+## Claude Desktop setup
+
+If installed globally:
+
+```json
+{
+  "mcpServers": {
+    "construct-shader-graph": {
+      "command": "construct-shader-graph-mcp"
+    }
+  }
+}
+```
+
+If using `npx`:
+
+```json
+{
+  "mcpServers": {
+    "construct-shader-graph": {
+      "command": "npx",
+      "args": ["-y", "construct-shader-graph-mcp"]
+    }
+  }
+}
+```
+
+## OpenCode setup
+
+Use the same command shape in your MCP configuration.
+
+Global install example:
+
+```json
+{
+  "mcpServers": {
+    "construct-shader-graph": {
+      "command": "construct-shader-graph-mcp"
+    }
+  }
+}
+```
+
+`npx` example:
+
+```json
+{
+  "mcpServers": {
+    "construct-shader-graph": {
+      "command": "npx",
+      "args": ["-y", "construct-shader-graph-mcp"]
+    }
+  }
+}
+```
+
+## Typical usage flow
+
+1. Start the MCP server from your host.
+2. Open Construct Shader Graph.
+3. In the app, connect to the MCP bridge from the Help menu.
+4. The host can now:
+   - call `list_projects`
+   - select the right project with `select_project`
+   - inspect available methods with `get_project_manifest`
+   - execute API calls with `call_project_method`
+
+## Publish notes
+
+This package is configured for npm publishing with:
+
+- package name: `construct-shader-graph-mcp`
+- CLI binary: `construct-shader-graph-mcp`
+- limited published files through the `files` field
+
+Check package contents before publishing:
+
+```bash
+npm run pack:check
+```
+
+Publish publicly:
+
+```bash
+npm publish
+```
+
+## Repo layout
+
+- `src/server.mjs` - MCP server and bridge
+- `src/guidance/skill.md` - bundled AI guidance and best practices
+- `bin/construct-shader-graph-mcp.js` - CLI entrypoint
+- `caw-icon.png` - package/readme icon

package/bin/construct-shader-graph-mcp.js

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+
+import "../src/server.mjs";

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "construct-shader-graph-mcp",
+  "version": "0.1.0",
+  "description": "Standalone MCP server for Construct Shader Graph",
+  "type": "module",
+  "files": [
+    "bin",
+    "src",
+    "README.md",
+    "caw-icon.png"
+  ],
+  "bin": {
+    "construct-shader-graph-mcp": "./bin/construct-shader-graph-mcp.js"
+  },
+  "scripts": {
+    "start": "node ./bin/construct-shader-graph-mcp.js",
+    "dev": "node ./src/server.mjs",
+    "pack:check": "npm pack --dry-run"
+  },
+  "keywords": [
+    "mcp",
+    "construct",
+    "shader-graph",
+    "claude",
+    "opencode"
+  ],
+  "author": "skymen",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/skymen/construct-shader-graph-mcp.git"
+  },
+  "homepage": "https://github.com/skymen/construct-shader-graph-mcp#readme",
+  "bugs": {
+    "url": "https://github.com/skymen/construct-shader-graph-mcp/issues"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.27.1",
+    "ws": "^8.19.0",
+    "zod": "^4.3.6"
+  }
+}

package/src/guidance/skill.md

@@ -0,0 +1,97 @@
+# Construct Shader Graph MCP Skill
+
+Use this guidance when working with Construct Shader Graph through the MCP bridge.
+
+## Purpose
+
+- Use the MCP tools as the only execution surface.
+- Inspect the current graph, make targeted graph edits, validate the result, and report progress clearly.
+- Treat the graph as the source of truth for shader logic. Use preview controls only to inspect or demonstrate the result.
+
+## MCP tool contract
+
+Use these tools for all work:
+
+- `list_projects`
+- `select_project`
+- `get_project_manifest`
+- `call_project_method`
+
+Execution rules:
+
+- Always use MCP tools instead of browser console access.
+- Always identify the active project from shader metadata returned by `shader.getInfo()`.
+- Always use exact return values from MCP calls; do not guess state.
+- Always read the manifest when capabilities or argument shapes are unclear.
+
+## Operating contract
+
+- Preserve existing user work unless the task clearly requires replacing it.
+- Identify the correct connected project before mutating anything.
+- Inspect first, mutate second.
+- Make the smallest valid change that satisfies the request.
+- Verify after every structural edit such as creating nodes, deleting nodes, or wiring ports.
+- Use stable ids from API results; do not rely on labels, visual position, or selection alone.
+- Do not open arbitrary local files or save project files autonomously.
+- Built-in examples are safe to open.
+- Export is allowed because it triggers a download rather than silently overwriting a project.
+
+## Preferred workflow
+
+1. Call `list_projects`.
+2. Select the correct project with `select_project`.
+3. Read `get_project_manifest` once per task or when capabilities are unclear.
+4. Start the session.
+5. Inspect current graph state.
+6. Identify exact node ids, port refs, uniform ids, or settings keys.
+7. Apply one atomic edit or one tightly related batch.
+8. Re-read the affected nodes, ports, wires, or settings.
+9. Check preview or generated code if relevant.
+10. Repeat only if needed.
+11. End the session with a recap.
+
+## Core rules
+
+- Always call `session.initAIWork()` when starting a task.
+- Always call `session.endAIWork()` when finishing a task.
+- Use `session.updateAIWork()` only for short phase updates.
+- Always inspect preview errors after meaningful shader edits.
+- Always use preview and screenshots for non-trivial visual validation.
+- Prefer setting editable input port values directly before adding constant/vector nodes.
+- Never assume a node id, port index, or wire id without reading it first.
+- Never connect ports without checking the actual node ports.
+- Never replace an output connection blindly; inspect the affected ports first.
+- Never use startup scripts as a substitute for graph logic.
+- Never create or edit custom node definitions unless explicitly asked.
+
+## Graph editing guidance
+
+- Always inspect ports before creating wires.
+- Use explicit port refs: `{ nodeId, kind, index }`.
+- Prefer `index` over `name` for automation stability.
+- Use `declaredType` and `resolvedType` to understand generic or dynamic nodes.
+- If an input port is editable and unconnected, prefer setting its value directly instead of creating a separate constant node.
+- If one output would feed many distant nodes, prefer variables instead of many long wires.
+
+## Preview and verification guidance
+
+- Default preview compiles from `Output`.
+- Use node preview for masks, UVs, gradients, lighting terms, and intermediate values.
+- Use the preview console as part of the normal debug loop.
+- Use screenshots to confirm that the visual result matches the intent.
+- Prefer `ai.runDebugCheck()` for combined validation.
+
+## Construct-specific guidance
+
+- Important shader settings include `blendsBackground`, `usesDepth`, `crossSampling`, `animated`, `mustPredraw`, `supports3DDirectRendering`, `extendBoxH`, and `extendBoxV`.
+- Background sampling only makes sense when `blendsBackground` is enabled.
+- Depth sampling only makes sense when `usesDepth` is enabled.
+- Construct uses premultiplied alpha, so many color workflows should use `unpremultiply` before edits and `premultiply` before output.
+- Prefer existing Construct helper nodes instead of rebuilding common math manually.
+
+## Troubleshooting
+
+- If no projects are listed, make sure the page is connected to the MCP bridge.
+- If the wrong project is selected, compare `shader.getInfo()` metadata and reselect.
+- If wire creation fails, inspect both nodes with `nodes.getPorts` and check `resolvedType`.
+- If preview looks wrong, inspect preview settings, preview errors, node preview, and screenshots.

package/src/server.mjs

@@ -0,0 +1,394 @@
+import fs from "node:fs";
+import path from "node:path";
+import { fileURLToPath } from "node:url";
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { WebSocketServer } from "ws";
+import { z } from "zod";
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+
+const BRIDGE_PORT = Number(process.env.MCP_BRIDGE_PORT || 6359);
+const SKILL_PATH = path.resolve(__dirname, "guidance/skill.md");
+
+const sessions = new Map();
+let selectedSessionId = null;
+
+function log(message, ...args) {
+  console.error(`[construct-shader-graph-mcp] ${message}`, ...args);
+}
+
+function nowIso() {
+  return new Date().toISOString();
+}
+
+function loadSkillText() {
+  return fs.readFileSync(SKILL_PATH, "utf8");
+}
+
+function getSessionSummary(session) {
+  return {
+    sessionId: session.sessionId,
+    project: session.project,
+    connectedAt: session.connectedAt,
+    updatedAt: session.updatedAt,
+    manifestVersion: session.manifest?.version || null,
+    methodCount: Array.isArray(session.manifest?.methods)
+      ? session.manifest.methods.length
+      : 0,
+    selected: selectedSessionId === session.sessionId,
+  };
+}
+
+function ensureSession(sessionId) {
+  const session = sessions.get(sessionId);
+  if (!session) {
+    throw new Error(`Unknown session '${sessionId}'`);
+  }
+  return session;
+}
+
+function ensureSelectedSession() {
+  if (!selectedSessionId) {
+    throw new Error("No project selected. Call select_project first.");
+  }
+
+  return ensureSession(selectedSessionId);
+}
+
+function sendJson(socket, payload) {
+  socket.send(JSON.stringify(payload));
+}
+
+function invokeSession(session, method, args = []) {
+  return new Promise((resolve, reject) => {
+    if (session.socket.readyState !== session.socket.OPEN) {
+      reject(new Error(`Session '${session.sessionId}' is not connected`));
+      return;
+    }
+
+    const requestId = `req_${Date.now()}_${Math.random().toString(16).slice(2)}`;
+    const timeoutId = setTimeout(() => {
+      session.pending.delete(requestId);
+      reject(
+        new Error(
+          `Timed out waiting for '${method}' result from session '${session.sessionId}'`,
+        ),
+      );
+    }, 15000);
+
+    session.pending.set(requestId, {
+      resolve,
+      reject,
+      timeoutId,
+      method,
+    });
+
+    sendJson(session.socket, {
+      type: "invoke",
+      requestId,
+      method,
+      args,
+    });
+  });
+}
+
+const bridge = new WebSocketServer({ host: "127.0.0.1", port: BRIDGE_PORT });
+
+bridge.on("connection", (socket) => {
+  let activeSessionId = null;
+
+  socket.on("message", (raw) => {
+    let message;
+    try {
+      message = JSON.parse(String(raw));
+    } catch {
+      return;
+    }
+
+    if (!message || typeof message !== "object") {
+      return;
+    }
+
+    if (message.type === "register") {
+      const sessionId = String(message.sessionId || "").trim();
+      if (!sessionId) {
+        sendJson(socket, { type: "error", message: "Missing sessionId" });
+        return;
+      }
+
+      const session = {
+        sessionId,
+        socket,
+        project: message.project || {
+          name: "Untitled Shader",
+          version: "0.0.0.0",
+        },
+        manifest: message.manifest || null,
+        connectedAt: nowIso(),
+        updatedAt: nowIso(),
+        pending: new Map(),
+      };
+
+      sessions.set(sessionId, session);
+      activeSessionId = sessionId;
+      if (!selectedSessionId) {
+        selectedSessionId = sessionId;
+      }
+
+      log(`registered ${sessionId} (${session.project?.name || "Untitled Shader"})`);
+      sendJson(socket, {
+        type: "registered",
+        sessionId,
+        selected: selectedSessionId === sessionId,
+      });
+      return;
+    }
+
+    if (!activeSessionId) {
+      return;
+    }
+
+    const session = sessions.get(activeSessionId);
+    if (!session) {
+      return;
+    }
+
+    session.updatedAt = nowIso();
+
+    if (message.type === "project-updated") {
+      session.project = message.project || session.project;
+      session.manifest = message.manifest || session.manifest;
+      return;
+    }
+
+    if (message.type === "result") {
+      const pending = session.pending.get(message.requestId);
+      if (!pending) {
+        return;
+      }
+
+      clearTimeout(pending.timeoutId);
+      session.pending.delete(message.requestId);
+
+      if (message.ok) {
+        pending.resolve(message);
+      } else {
+        const error = new Error(
+          message.error?.message || `Call '${pending.method}' failed`,
+        );
+        error.stack = message.error?.stack || error.stack;
+        pending.reject(error);
+      }
+    }
+  });
+
+  socket.on("close", () => {
+    if (!activeSessionId) {
+      return;
+    }
+
+    const session = sessions.get(activeSessionId);
+    if (!session) {
+      return;
+    }
+
+    for (const pending of session.pending.values()) {
+      clearTimeout(pending.timeoutId);
+      pending.reject(new Error(`Session '${activeSessionId}' disconnected`));
+    }
+
+    sessions.delete(activeSessionId);
+    if (selectedSessionId === activeSessionId) {
+      selectedSessionId = sessions.keys().next().value || null;
+    }
+
+    log(`disconnected ${activeSessionId}`);
+  });
+});
+
+log(`bridge listening on ws://127.0.0.1:${BRIDGE_PORT}`);
+
+const server = new McpServer({
+  name: "construct-shader-graph",
+  version: "0.1.0",
+});
+
+server.registerTool(
+  "get_skill_guidance",
+  {
+    description:
+      "Return the full Construct Shader Graph MCP guidance and best practices.",
+    inputSchema: {},
+    outputSchema: {
+      title: z.string(),
+      content: z.string(),
+    },
+  },
+  async () => {
+    const result = {
+      title: "Construct Shader Graph MCP Skill",
+      content: loadSkillText(),
+    };
+    return {
+      content: [{ type: "text", text: result.content }],
+      structuredContent: result,
+    };
+  },
+);
+
+server.registerTool(
+  "list_projects",
+  {
+    description:
+      "List connected Construct Shader Graph tabs registered with the local bridge.",
+    inputSchema: {},
+    outputSchema: {
+      projects: z.array(
+        z.object({
+          sessionId: z.string(),
+          project: z.object({
+            name: z.string(),
+            version: z.string().optional(),
+            author: z.string().optional(),
+            category: z.string().optional(),
+            description: z.string().optional(),
+            shaderInfo: z.any().optional(),
+          }),
+          connectedAt: z.string(),
+          updatedAt: z.string(),
+          manifestVersion: z.string().nullable(),
+          methodCount: z.number(),
+          selected: z.boolean(),
+        }),
+      ),
+      selectedSessionId: z.string().nullable(),
+    },
+  },
+  async () => {
+    const projects = [...sessions.values()].map(getSessionSummary);
+    return {
+      content: [
+        {
+          type: "text",
+          text: JSON.stringify({ projects, selectedSessionId }, null, 2),
+        },
+      ],
+      structuredContent: {
+        projects,
+        selectedSessionId,
+      },
+    };
+  },
+);
+
+server.registerTool(
+  "select_project",
+  {
+    description:
+      "Choose which connected shader graph tab future MCP calls should target.",
+    inputSchema: {
+      sessionId: z.string().describe("Session id returned by list_projects."),
+    },
+    outputSchema: {
+      sessionId: z.string(),
+      project: z.any(),
+    },
+  },
+  async ({ sessionId }) => {
+    const session = ensureSession(sessionId);
+    selectedSessionId = sessionId;
+    const result = {
+      sessionId,
+      project: session.project,
+    };
+    return {
+      content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
+      structuredContent: result,
+    };
+  },
+);
+
+server.registerTool(
+  "get_project_manifest",
+  {
+    description:
+      "Get the machine-readable API manifest for the selected project.",
+    inputSchema: {
+      sessionId: z
+        .string()
+        .optional()
+        .describe("Optional session id; defaults to the selected project."),
+    },
+    outputSchema: {
+      sessionId: z.string(),
+      project: z.any(),
+      manifest: z.any(),
+    },
+  },
+  async ({ sessionId }) => {
+    const session = sessionId
+      ? ensureSession(sessionId)
+      : ensureSelectedSession();
+    const result = {
+      sessionId: session.sessionId,
+      project: session.project,
+      manifest: session.manifest,
+    };
+    return {
+      content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
+      structuredContent: result,
+    };
+  },
+);
+
+server.registerTool(
+  "call_project_method",
+  {
+    description:
+      "Call one method from the selected project's shaderGraphAPI and return its exact result.",
+    inputSchema: {
+      sessionId: z
+        .string()
+        .optional()
+        .describe("Optional session id; defaults to the selected project."),
+      method: z
+        .string()
+        .describe("Manifest method path, for example nodes.create or shader.getInfo."),
+      args: z
+        .array(z.any())
+        .optional()
+        .describe("Positional arguments to pass to the API method."),
+    },
+    outputSchema: {
+      sessionId: z.string(),
+      project: z.any(),
+      method: z.string(),
+      args: z.array(z.any()),
+      durationMs: z.number(),
+      result: z.any(),
+    },
+  },
+  async ({ sessionId, method, args = [] }) => {
+    const session = sessionId
+      ? ensureSession(sessionId)
+      : ensureSelectedSession();
+    const response = await invokeSession(session, method, args);
+    const result = {
+      sessionId: session.sessionId,
+      project: session.project,
+      method,
+      args,
+      durationMs: response.durationMs ?? 0,
+      result: response.result,
+    };
+    return {
+      content: [{ type: "text", text: JSON.stringify(result, null, 2) }],
+      structuredContent: result,
+    };
+  },
+);
+
+const transport = new StdioServerTransport();
+await server.connect(transport);