Merge remote-tracking branch 'origin/main' into ochafik/openai-compatibility

Author: ochafik

examples/basic-host/src/implementation.ts

@@ -1,5 +1,6 @@
 import { RESOURCE_MIME_TYPE, getToolUiResourceUri, type McpUiSandboxProxyReadyNotification, AppBridge, PostMessageTransport, type McpUiResourceCsp, type McpUiResourcePermissions, buildAllowAttribute, type McpUiUpdateModelContextRequest, type McpUiMessageRequest } from "@modelcontextprotocol/ext-apps/app-bridge";
 import { Client } from "@modelcontextprotocol/sdk/client/index.js";
+import { SSEClientTransport } from "@modelcontextprotocol/sdk/client/sse.js";
 import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";
 import type { CallToolResult, Tool } from "@modelcontextprotocol/sdk/types.js";
 
@@ -24,11 +25,8 @@ export interface ServerInfo {
 
 
 export async function connectToServer(serverUrl: URL): Promise<ServerInfo> {
-  const client = new Client(IMPLEMENTATION);
-
   log.info("Connecting to server:", serverUrl.href);
-  await client.connect(new StreamableHTTPClientTransport(serverUrl));
-  log.info("Connection successful");
+  const client = await connectWithFallback(serverUrl);
 
   const name = client.getServerVersion()?.name ?? serverUrl.href;
 
@@ -39,6 +37,28 @@ export async function connectToServer(serverUrl: URL): Promise<ServerInfo> {
   return { name, client, tools, appHtmlCache: new Map() };
 }
 
+async function connectWithFallback(serverUrl: URL): Promise<Client> {
+  // Try Streamable HTTP first (modern transport)
+  try {
+    const client = new Client(IMPLEMENTATION);
+    await client.connect(new StreamableHTTPClientTransport(serverUrl));
+    log.info("Connected via Streamable HTTP transport");
+    return client;
+  } catch (streamableError) {
+    log.info("Streamable HTTP failed:", streamableError);
+  }
+
+  // Fall back to SSE (deprecated but needed for older servers)
+  try {
+    const client = new Client(IMPLEMENTATION);
+    await client.connect(new SSEClientTransport(serverUrl));
+    log.info("Connected via SSE transport");
+    return client;
+  } catch (sseError) {
+    throw new Error(`Could not connect with any transport. SSE error: ${sseError}`);
+  }
+}
+
 
 interface UiResourceData {
   html: string;

examples/qr-server/grid-cell.png

@@ -2,7 +2,7 @@
 # /// script
 # requires-python = ">=3.10"
 # dependencies = [
-#     "mcp>=1.9.0",
+#     "mcp @ git+https://github.com/modelcontextprotocol/python-sdk@main",
 #     "qrcode[pil]>=8.0",
 #     "uvicorn>=0.34.0",
 #     "starlette>=0.46.0",
@@ -30,7 +30,10 @@
 mcp = FastMCP("QR Code Server", port=PORT, stateless_http=True)
 
 
-@mcp.tool(meta={"ui/resourceUri": WIDGET_URI})
+@mcp.tool(meta={
+    "ui":{"resourceUri": WIDGET_URI},
+    "ui/resourceUri": WIDGET_URI, # legacy support
+})
 def generate_qr(
     text: str = "https://modelcontextprotocol.io",
     box_size: int = 10,
@@ -72,53 +75,17 @@ def generate_qr(
     return [types.ImageContent(type="image", data=b64, mimeType="image/png")]
 
 
-# Register widget resource using FastMCP decorator (returns HTML string)
-@mcp.resource(WIDGET_URI, mime_type="text/html;profile=mcp-app")
+# IMPORTANT: all the external domains used by app must be listed
+# in the meta.ui.csp.resourceDomains - otherwise they will be blocked by CSP policy
+@mcp.resource(
+    WIDGET_URI,
+    mime_type="text/html;profile=mcp-app",
+    meta={"ui": {"csp": {"resourceDomains": ["https://unpkg.com"]}}},
+)
 def widget() -> str:
+    """Widget HTML resource with CSP metadata for external dependencies."""
     return Path(__file__).parent.joinpath("widget.html").read_text()
 
-
-# Override the read_resource handler to inject _meta into the response
-# This is needed because FastMCP doesn't support custom _meta on resources
-_low_level_server = mcp._mcp_server
-
-
-async def _read_resource_with_meta(req: types.ReadResourceRequest):
-    """Custom handler that injects CSP metadata for the widget resource."""
-    uri = str(req.params.uri)
-    html = Path(__file__).parent.joinpath("widget.html").read_text()
-
-    if uri == WIDGET_URI:
-        # NOTE: Must use model_validate with '_meta' key (not 'meta') due to Pydantic alias behavior
-        content = types.TextResourceContents.model_validate({
-            "uri": WIDGET_URI,
-            "mimeType": "text/html;profile=mcp-app",
-            "text": html,
-            # IMPORTANT: all the external domains used by app must be listed
-            # in the _meta.ui.csp.resourceDomains - otherwise they will be blocked by CSP policy
-            "_meta": {"ui": {"csp": {"resourceDomains": ["https://unpkg.com"]}}}
-        })
-        return types.ServerResult(
-            types.ReadResourceResult(contents=[content])
-        )
-
-    # Fallback for other resources (shouldn't happen for this server)
-    return types.ServerResult(
-        types.ReadResourceResult(
-            contents=[
-                types.TextResourceContents(
-                    uri=uri,
-                    mimeType="text/plain",
-                    text="Resource not found"
-                )
-            ]
-        )
-    )
-
-
-# Replace the handler after FastMCP has registered its own
-_low_level_server.request_handlers[types.ReadResourceRequest] = _read_resource_with_meta
-
 if __name__ == "__main__":
     if "--stdio" in sys.argv:
         # Claude Desktop mode

examples/qr-server/server.py

@@ -6,6 +6,9 @@
  *   bun examples/run-all.ts start  - Build and start all examples
  *   bun examples/run-all.ts dev    - Run all examples in dev/watch mode
  *   bun examples/run-all.ts build  - Build all examples
+ *
+ * Environment:
+ *   EXAMPLE=<folder>  - Run only a single example (e.g., EXAMPLE=say-server)
  */
 
 import { readdirSync, statSync, existsSync } from "fs";
@@ -14,21 +17,36 @@ import concurrently from "concurrently";
 const BASE_PORT = 3101;
 const BASIC_HOST = "basic-host";
 
+// Optional: filter to a single example via EXAMPLE env var (folder name)
+const EXAMPLE_FILTER = process.env.EXAMPLE;
+
 // Find all example directories except basic-host that have a package.json,
 // assign ports, and build URL list
-const servers = readdirSync("examples")
+const allServers = readdirSync("examples")
   .filter(
     (d) =>
       d !== BASIC_HOST &&
       statSync(`examples/${d}`).isDirectory() &&
       existsSync(`examples/${d}/package.json`),
   )
-  .sort() // Sort for consistent port assignment
-  .map((dir, i) => ({
-    dir,
-    port: BASE_PORT + i,
-    url: `http://localhost:${BASE_PORT + i}/mcp`,
-  }));
+  .sort(); // Sort for consistent port assignment
+
+// Filter servers if EXAMPLE is specified
+const filteredDirs = EXAMPLE_FILTER
+  ? allServers.filter((d) => d === EXAMPLE_FILTER)
+  : allServers;
+
+if (EXAMPLE_FILTER && filteredDirs.length === 0) {
+  console.error(`Error: No example found matching EXAMPLE=${EXAMPLE_FILTER}`);
+  console.error(`Available examples: ${allServers.join(", ")}`);
+  process.exit(1);
+}
+
+const servers = filteredDirs.map((dir, i) => ({
+  dir,
+  port: BASE_PORT + i,
+  url: `http://localhost:${BASE_PORT + i}/mcp`,
+}));
 
 const COMMANDS = ["start", "dev", "build"];
 
@@ -43,6 +61,9 @@ if (!command || !COMMANDS.includes(command)) {
 const serversEnv = JSON.stringify(servers.map((s) => s.url));
 
 console.log(`Running command: ${command}`);
+if (EXAMPLE_FILTER) {
+  console.log(`Filtering to single example: ${EXAMPLE_FILTER}`);
+}
 console.log(
   `Server examples: ${servers.map((s) => `${s.dir}:${s.port}`).join(", ")}`,
 );

examples/run-all.ts

@@ -15,6 +15,7 @@ A demo MCP App that renders [ShaderToy](https://www.shadertoy.com/)-compatible G
 - **Real-time Rendering**: Renders GLSL shaders using WebGL 2.0
 - **ShaderToy Compatibility**: Uses the standard `mainImage(out vec4 fragColor, in vec2 fragCoord)` entry point
 - **Multi-pass Rendering**: Supports buffers A-D for feedback effects, blur chains, and simulations
+- **Mouse & Touch Interaction**: Full iMouse support with click detection (works on mobile)
 - **Standard Uniforms**: iResolution, iTime, iTimeDelta, iFrame, iMouse, iDate, iChannel0-3
 
 ## Running
@@ -101,13 +102,20 @@ _Tool input:_
 }
 ```
 
-**Interactive Julia Set** (mouse controls the fractal's c parameter):
+**Interactive Julia Set** (click and drag to control the fractal's c parameter):
 
 ```glsl
 void mainImage(out vec4 fragColor, in vec2 fragCoord) {
     vec2 uv = (fragCoord - 0.5 * iResolution.xy) / iResolution.y * 2.5;
-    vec2 mouse = (iMouse.xy / iResolution.xy - 0.5) * 2.0;
-    vec2 c = mouse;
+    // Use mouse position if clicked, otherwise use animated default
+    vec2 c;
+    if (iMouse.z > 0.0) {
+        // Mouse is pressed - use mouse position
+        c = (iMouse.xy / iResolution.xy - 0.5) * 2.0;
+    } else {
+        // Not pressed - animate around an interesting region
+        c = vec2(-0.8 + 0.2 * sin(iTime * 0.5), 0.156 + 0.1 * cos(iTime * 0.7));
+    }
     vec2 z = uv;
     float iter = 0.0;
     for (int i = 0; i < 100; i++) {
@@ -126,25 +134,33 @@ _Tool input:_
 
 ```json
 {
-  "fragmentShader": "void mainImage(out vec4 fragColor, in vec2 fragCoord) {
-    vec2 uv = (fragCoord - 0.5 * iResolution.xy) / iResolution.y * 2.5;
-    vec2 mouse = (iMouse.xy / iResolution.xy - 0.5) * 2.0;
-    vec2 c = mouse;
-    vec2 z = uv;
-    float iter = 0.0;
-    for (int i = 0; i < 100; i++) {
-        z = vec2(z.x * z.x - z.y * z.y, 2.0 * z.x * z.y) + c;
-        if (dot(z, z) > 4.0) break;
-        iter++;
-    }
-    float t = iter / 100.0;
-    vec3 col = 0.5 + 0.5 * cos(3.0 + t * 6.28 * 2.0 + vec3(0.0, 0.6, 1.0));
-    if (iter == 100.0) col = vec3(0.0);
-    fragColor = vec4(col, 1.0);
-}"
+  "fragmentShader": "void mainImage(out vec4 fragColor, in vec2 fragCoord) {\n    vec2 uv = (fragCoord - 0.5 * iResolution.xy) / iResolution.y * 2.5;\n    vec2 c;\n    if (iMouse.z > 0.0) {\n        c = (iMouse.xy / iResolution.xy - 0.5) * 2.0;\n    } else {\n        c = vec2(-0.8 + 0.2 * sin(iTime * 0.5), 0.156 + 0.1 * cos(iTime * 0.7));\n    }\n    vec2 z = uv;\n    float iter = 0.0;\n    for (int i = 0; i < 100; i++) {\n        z = vec2(z.x * z.x - z.y * z.y, 2.0 * z.x * z.y) + c;\n        if (dot(z, z) > 4.0) break;\n        iter++;\n    }\n    float t = iter / 100.0;\n    vec3 col = 0.5 + 0.5 * cos(3.0 + t * 6.28 * 2.0 + vec3(0.0, 0.6, 1.0));\n    if (iter == 100.0) col = vec3(0.0);\n    fragColor = vec4(col, 1.0);\n}"
+}
+```
+
+## Mouse & Touch Interaction
+
+The `iMouse` uniform provides interactive input, compatible with the official Shadertoy specification:
+
+| Component   | When Button Down       | After Release    | Never Clicked |
+| ----------- | ---------------------- | ---------------- | ------------- |
+| `iMouse.xy` | Current position       | Last position    | `(0, 0)`      |
+| `iMouse.zw` | Click start (positive) | Negated (-x, -y) | `(0, 0)`      |
+
+**Detecting button state:**
+
+```glsl
+if (iMouse.z > 0.0) {
+    // Button/touch is currently held down
+} else if (iMouse.z < 0.0) {
+    // Button was released (can use abs(iMouse.zw) for last click position)
+} else {
+    // Never clicked - show default state or animate
 }
 ```
 
+Touch events are automatically supported for mobile devices.
+
 ## Architecture
 
 ### Server (`server.ts`)

examples/shadertoy-server/README.md

@@ -33,10 +33,24 @@ AVAILABLE UNIFORMS:
 - iTime (float): elapsed time in seconds
 - iTimeDelta (float): time since last frame
 - iFrame (int): frame counter
-- iMouse (vec4): mouse position (xy=current, zw=click)
+- iMouse (vec4): mouse/touch position in pixels (see MOUSE INTERACTION below)
 - iDate (vec4): year, month, day, seconds
 - iChannel0-3 (sampler2D): buffer inputs for multi-pass shaders
 
+MOUSE INTERACTION:
+The iMouse uniform provides interactive mouse/touch input (works on mobile):
+- iMouse.xy: Current position while button/touch is held down (frozen on release)
+- iMouse.zw: Click start position (positive when down, negative when released)
+- iMouse.z > 0: Button is currently pressed
+- iMouse.z < 0: Button was released
+- iMouse.z == 0: Never clicked
+
+Example - camera control:
+  vec2 uv = iMouse.xy / iResolution.xy;  // normalized 0-1
+
+Example - detect click:
+  if (iMouse.z > 0.0) { /* button is down */ }
+
 MULTI-PASS RENDERING:
 - Use bufferA-D parameters for feedback effects, blur chains, simulations
 - BufferA output -> iChannel0, BufferB -> iChannel1, etc.

examples/shadertoy-server/server.ts

@@ -90,7 +90,10 @@ function ShaderToyLite(canvasId) {
 
     // uniforms
     var iFrame = 0;
+    // iMouse state: xy = current position (only updates when button down)
+    // zw = click start position (positive when down, negative when released)
     var iMouse = {x: 0, y: 0, clickX: 0, clickY: 0};
+    var isMouseDown = false;
 
     // shader common source
     var common = "";
@@ -145,19 +148,75 @@ function ShaderToyLite(canvasId) {
             gl.viewport(0, 0, gl.canvas.width, gl.canvas.height);
         });
 
+        // Mouse event handlers - match official Shadertoy iMouse behavior:
+        // iMouse.xy: current position (only updates when button is down)
+        // iMouse.zw: click position (positive when down, negated when released)
         canvas.addEventListener("mousemove", (event) => {
-            iMouse.x = event.offsetX;
-            iMouse.y = canvas.height - event.offsetY;
+            if (isMouseDown) {
+                iMouse.x = event.offsetX;
+                iMouse.y = canvas.height - event.offsetY;
+            }
         });
 
         canvas.addEventListener("mousedown", (event) => {
-            iMouse.clickX = event.offsetX;
-            iMouse.clickY = canvas.height - event.offsetY;
+            isMouseDown = true;
+            var x = event.offsetX;
+            var y = canvas.height - event.offsetY;
+            iMouse.x = x;
+            iMouse.y = y;
+            iMouse.clickX = x;
+            iMouse.clickY = y;
         });
 
         canvas.addEventListener("mouseup", () => {
-            iMouse.clickX = 0;
-            iMouse.clickY = 0;
+            isMouseDown = false;
+            // Negate click position to indicate button released (Shadertoy convention)
+            iMouse.clickX = -Math.abs(iMouse.clickX);
+            iMouse.clickY = -Math.abs(iMouse.clickY);
+        });
+
+        // Prevent context menu on right-click to avoid interrupting interaction
+        canvas.addEventListener("contextmenu", (event) => {
+            event.preventDefault();
+        });
+
+        // Touch support for mobile devices
+        canvas.addEventListener("touchstart", (event) => {
+            event.preventDefault();
+            if (event.touches.length > 0) {
+                var touch = event.touches[0];
+                var rect = canvas.getBoundingClientRect();
+                var x = touch.clientX - rect.left;
+                var y = canvas.height - (touch.clientY - rect.top);
+                isMouseDown = true;
+                iMouse.x = x;
+                iMouse.y = y;
+                iMouse.clickX = x;
+                iMouse.clickY = y;
+            }
+        }, { passive: false });
+
+        canvas.addEventListener("touchmove", (event) => {
+            event.preventDefault();
+            if (isMouseDown && event.touches.length > 0) {
+                var touch = event.touches[0];
+                var rect = canvas.getBoundingClientRect();
+                iMouse.x = touch.clientX - rect.left;
+                iMouse.y = canvas.height - (touch.clientY - rect.top);
+            }
+        }, { passive: false });
+
+        canvas.addEventListener("touchend", (event) => {
+            event.preventDefault();
+            isMouseDown = false;
+            iMouse.clickX = -Math.abs(iMouse.clickX);
+            iMouse.clickY = -Math.abs(iMouse.clickY);
+        }, { passive: false });
+
+        canvas.addEventListener("touchcancel", () => {
+            isMouseDown = false;
+            iMouse.clickX = -Math.abs(iMouse.clickX);
+            iMouse.clickY = -Math.abs(iMouse.clickY);
         });
     }