create-mcp-use-app 2.0.0-beta.0 → 2.0.0-beta.10

package/dist/templates/blank/tsconfig.json

@@ -1,24 +1,24 @@
 {
   "compilerOptions": {
-    "target": "ES2022",
+    "target": "ES2024",
     "jsx": "react-jsx",
-    "module": "ESNext",
-    "moduleResolution": "bundler",
-    "allowJs": true,
+    "module": "NodeNext",
+    "moduleResolution": "NodeNext",
+    "lib": ["ES2024", "DOM", "DOM.Iterable"],
     "strict": true,
-    "outDir": "./dist",
-    "sourceMap": true,
-    "allowSyntheticDefaultImports": true,
     "esModuleInterop": true,
     "forceConsistentCasingInFileNames": true,
     "skipLibCheck": true,
-    "incremental": true,
-    "tsBuildInfoFile": "./dist/.tsbuildinfo",
-    "baseUrl": ".",
-    "paths": {
-      "@/*": ["src/*"]
-    }
+    "noEmit": true,
+    "noUncheckedSideEffectImports": false
   },
-  "include": ["index.ts", "src/**/*", "resources/**/*", "server.ts", ".mcp-use/**/*.d.ts"],
+  "include": [
+    "index.ts",
+    "mcp-env.d.ts",
+    "src/**/*",
+    "views/**/*",
+    "server.ts",
+    ".mcp-use/**/*.d.ts"
+  ],
   "exclude": ["node_modules", "dist"]
 }

package/dist/templates/mcp-apps/README.md

@@ -11,10 +11,12 @@ npm install
 npm run dev
 ```
 
-Open [http://localhost:3000/inspector](http://localhost:3000/inspector) with your browser to test your server.
+Open [http://localhost:3000/mcp/inspector](http://localhost:3000/mcp/inspector) with your browser to test your server.
 
 You can start building by editing the entry file. Add tools, resources, and prompts — the server auto-reloads as you edit.
 
+Run `npm run typecheck` to refresh MCP view types and check the project with its local TypeScript compiler. Statically declared tools used by views must be assigned to exported constants.
+
 ## Learn More
 
 To learn more about mcp-use and MCP:

package/dist/templates/mcp-apps/index.ts

@@ -1,40 +1,114 @@
 import { MCPServer } from "mcp-use";
 import { z } from "zod";
 
-const fruits = ["apple", "banana", "mango", "orange", "strawberry"];
-
-const outputSchema = z.object({
-  query: z.string(),
-  items: z.array(z.object({ id: z.string(), name: z.string() })),
-});
-
 const server = new MCPServer({
   name: "{{PROJECT_NAME}}",
-  title: "{{PROJECT_NAME}}",
+  title: "{{PROJECT_NAME}}", // Human readable name of the server
   version: "1.0.0",
-  description: "An MCP Apps server built with mcp-use",
+  description: "an mcp-use app",
+  instructions: "use show-app to open the app view", // Model-facing guidance — surfaced to the LLM by compatible clients.
+  websiteUrl: "https://mcp-use.com",
+  // Icons for your MCP Server, from public/ (or absolute URLs).
+  icons: [
+    {
+      src: "icon.svg",
+      mimeType: "image/svg+xml",
+      sizes: ["512x512"],
+    },
+  ],
+
+  // The MCP server is by default served at /mcp, to customise
+  // basePath: "/mcp",
+
+  // mcp-use has 1 line adapter for OAuth, import from mcp-use/oauth/*
+  // oauth: oauthClerkProvider(), // zero-config via MCP_USE_OAUTH_CLERK_FRONTEND_API_URL, import from mcp-use/oauth/*
+
+  // When OAuth is on, the HTML landing page (/mcp) is protected by default, set to true to keep the landing page public while /mcp stays bearer-protected.
+  // publicLandingPage: true,
 });
 
-server.tool(
+// TOOLS
+
+// tool inputs are zod schemas. Important: set decriptions for the model to understand the input.
+const showAppInputSchema = z.object({
+  appName: z
+    .string()
+    .optional()
+    .describe(
+      "Optional title shown in the MCP App card instead of the default"
+    ),
+});
+
+// tool outputs are zod schemas. Important: set descriptions for the model to understand the output.
+const showAppOutputSchema = z.object({
+  message: z.string().describe("Message to display in the MCP App"),
+});
+
+export const showApp = server.tool(
   {
-    name: "search-fruits",
-    description: "Search the fruit catalog",
-    inputSchema: z.object({ query: z.string().optional() }),
-    outputSchema,
+    name: "show-app", // Unique tool id on the wire.
+    title: "Show MCP App", // Short label in inspector and client UIs (falls back to name).
+    description: "Display the MCP App starter view", // LLM-facing summary of what the tool does.
+    inputSchema: showAppInputSchema, // Validated before the handler runs; .describe() text becomes LLM hints.
+    outputSchema: showAppOutputSchema, // Required when binding a view — the view reads structuredContent typed by this.
     view: {
-      name: "product-search-result",
-      description: "Fruit search results",
-      prefersBorder: true,
+      name: "my-view", // directory under views/
+      description: "MCP App starter card with interactive demo hooks",
+      prefersBorder: false, // ask the host to skip a card border around the view
+      csp: {
+        resourceDomains: [
+          "https://fonts.googleapis.com",
+          "https://fonts.gstatic.com",
+        ],
+      },
+    },
+    // Behavioral hints for clients (readOnly / destructive / open-world).
+    annotations: {
+      readOnlyHint: true,
+      destructiveHint: false,
+      openWorldHint: false,
+    },
+  },
+  async ({ appName }, ctx) => {
+    // Brief delay so the pending skeleton is visible during dev/inspector demos.
+    await new Promise((resolve) => setTimeout(resolve, 1500));
+
+    console.log(`The app name was: ${appName}`);
+    const data = { message: `The MCP App starter for ${appName} is ready!` };
+
+    return {
+      content: [{ type: "text", text: data.message }],
+      structuredContent: data,
+    };
+  }
+);
+
+// say-hello — plain tool (no view); used by the Say Hello button in my-view
+const sayHelloInputSchema = z.object({
+  name: z.string().describe("Name to greet"),
+});
+
+const sayHelloOutputSchema = z.object({
+  greeting: z.string().describe("Greeting to display"),
+});
+
+export const sayHello = server.tool(
+  {
+    name: "say-hello",
+    title: "Say hello",
+    description: "Returns a greeting for the Say Hello button demo",
+    inputSchema: sayHelloInputSchema,
+    outputSchema: sayHelloOutputSchema,
+    annotations: {
+      readOnlyHint: true,
+      destructiveHint: false,
+      openWorldHint: false,
     },
-    annotations: { readOnlyHint: true, openWorldHint: false },
   },
-  async ({ query = "" }) => {
-    const items = fruits
-      .filter((fruit) => fruit.includes(query.toLowerCase()))
-      .map((fruit) => ({ id: fruit, name: fruit }));
-    const data = { query, items };
+  async ({ name }) => {
+    const data = { greeting: `Hello, ${name}!` };
     return {
-      content: [{ type: "text", text: `Found ${items.length} fruits.` }],
+      content: [{ type: "text", text: data.greeting }],
       structuredContent: data,
     };
   }

package/dist/templates/mcp-apps/mcp-env.d.ts

@@ -0,0 +1,10 @@
+// Generated by mcp-use. Do not edit.
+declare module "*.css";
+
+declare module "mcp-use/react" {
+  interface Register {
+    tools: typeof import("./index.js");
+  }
+}
+
+export {};

package/dist/templates/mcp-apps/package.json

@@ -1,20 +1,22 @@
 {
   "name": "mcp-use server",
   "type": "module",
+  "engines": {
+    "node": ">=22.22.2"
+  },
   "version": "1.0.0",
-  "description": "MCP server with a standard MCP Apps view",
-  "author": "",
+  "description": "an mcp-use server",
+  "author": "mcp-use",
   "license": "MIT",
+  "homepage": "https://github.com/mcp-use/mcp-use",
   "keywords": [
     "mcp",
-    "server",
-    "starter",
-    "tools",
-    "resources",
-    "prompts",
-    "ui",
-    "react",
-    "mcp-apps"
+    "mcp-server",
+    "chatgpt plugins",
+    "claude connector",
+    "mcp-app",
+    "mcp-use",
+    "manufact"
   ],
   "main": "dist/index.js",
   "scripts": {
@@ -22,18 +24,18 @@
     "dev": "mcp-use dev",
     "start": "mcp-use start",
     "deploy": "mcp-use deploy",
-    "typecheck": "tsc --noEmit"
+    "typecheck": "mcp-use typecheck"
   },
   "dependencies": {
     "mcp-use": "workspace:*",
-    "react": "^19.2.4",
-    "react-dom": "^19.2.4",
+    "react": "^19.2.7",
+    "react-dom": "^19.2.7",
     "zod": "^4.4.3"
   },
   "devDependencies": {
-    "@types/node": "^24.13.2",
+    "@types/node": "^22.20.0",
     "@types/react": "^19.2.17",
     "@types/react-dom": "^19.2.3",
-    "typescript": "7.0.1-rc"
+    "typescript": "^7.0.2"
   }
 }

package/dist/templates/mcp-apps/public/logo-mcp-use.svg

@@ -0,0 +1,8 @@
+<svg width="2476" height="480" viewBox="0 0 2476 480" fill="none" xmlns="http://www.w3.org/2000/svg">
+<path d="M793.5 245.5C793.5 218.167 790 198.5 783 186.5C776.333 174.167 763.667 168 745 168C738.333 168 731 168.5 723 169.5C715 170.5 709 171.333 705 172V383H644.5V130C656.167 126.667 671.333 123.5 690 120.5C709 117.5 729 116 750 116C768 116 782.667 118.333 794 123C805.667 127.667 815.333 133.833 823 141.5C826.667 138.833 831.333 136 837 133C842.667 130 849 127.333 856 125C863 122.333 870.333 120.167 878 118.5C886 116.833 894 116 902 116C922.333 116 939 119 952 125C965.333 130.667 975.667 138.833 983 149.5C990.667 159.833 995.833 172.5 998.5 187.5C1001.5 202.167 1003 218.333 1003 236V383H942.5V245.5C942.5 218.167 939.167 198.5 932.5 186.5C925.833 174.167 913 168 894 168C884.333 168 875.167 169.667 866.5 173C857.833 176 851.333 179 847 182C849.667 190.333 851.5 199.167 852.5 208.5C853.5 217.833 854 227.833 854 238.5V383H793.5V245.5ZM1052.62 252.5C1052.62 233.167 1055.62 215.167 1061.62 198.5C1067.62 181.5 1076.12 166.833 1087.12 154.5C1098.45 142.167 1112.12 132.5 1128.12 125.5C1144.12 118.5 1162.12 115 1182.12 115C1206.78 115 1230.12 119.5 1252.12 128.5L1239.12 178C1232.12 175 1224.12 172.5 1215.12 170.5C1206.45 168.5 1197.12 167.5 1187.12 167.5C1163.45 167.5 1145.45 175 1133.12 190C1120.78 204.667 1114.62 225.5 1114.62 252.5C1114.62 278.5 1120.45 299.167 1132.12 314.5C1143.78 329.5 1163.45 337 1191.12 337C1201.45 337 1211.62 336 1221.62 334C1231.62 332 1240.28 329.5 1247.62 326.5L1256.12 376.5C1249.45 379.833 1239.28 382.833 1225.62 385.5C1212.28 388.167 1198.45 389.5 1184.12 389.5C1161.78 389.5 1142.28 386.167 1125.62 379.5C1109.28 372.5 1095.62 363 1084.62 351C1073.95 338.667 1065.95 324.167 1060.62 307.5C1055.28 290.5 1052.62 272.167 1052.62 252.5ZM1466.46 253.5C1466.46 226.5 1460.29 205.5 1447.96 190.5C1435.96 175.5 1416.46 168 1389.46 168C1383.79 168 1377.79 168.333 1371.46 169C1365.46 169.333 1359.46 170.333 1353.46 172V321.5C1358.79 325.167 1365.79 328.667 1374.46 332C1383.46 335 1392.96 336.5 1402.96 336.5C1424.96 336.5 1440.96 329 1450.96 314C1461.29 299 1466.46 278.833 1466.46 253.5ZM1528.46 252.5C1528.46 272.5 1525.79 290.833 1520.46 307.5C1515.46 324.167 1508.12 338.5 1498.46 350.5C1488.79 362.5 1476.62 371.833 1461.96 378.5C1447.62 385.167 1431.29 388.5 1412.96 388.5C1400.62 388.5 1389.29 387 1378.96 384C1368.62 381 1360.12 377.667 1353.46 374V475.5H1292.96V130C1305.29 126.667 1320.46 123.5 1338.46 120.5C1356.46 117.5 1375.46 116 1395.46 116C1416.12 116 1434.62 119.167 1450.96 125.5C1467.29 131.833 1481.12 141 1492.46 153C1504.12 164.667 1512.96 179 1518.96 196C1525.29 212.667 1528.46 231.5 1528.46 252.5ZM1553.81 212.5H1688.31V268H1553.81V212.5ZM1943.02 375C1931.36 378 1916.19 381 1897.52 384C1878.86 387.333 1858.36 389 1836.02 389C1815.02 389 1797.36 386 1783.02 380C1769.02 374 1757.69 365.667 1749.02 355C1740.69 344.333 1734.69 331.667 1731.02 317C1727.36 302 1725.52 285.667 1725.52 268V121.5H1786.02V258.5C1786.02 286.5 1790.02 306.5 1798.02 318.5C1806.36 330.5 1820.69 336.5 1841.02 336.5C1848.36 336.5 1856.02 336.167 1864.02 335.5C1872.36 334.833 1878.52 334 1882.52 333V121.5H1943.02V375ZM2075.53 339.5C2091.53 339.5 2103.19 337.667 2110.53 334C2117.86 330 2121.53 323.333 2121.53 314C2121.53 305.333 2117.53 298.167 2109.53 292.5C2101.86 286.833 2089.03 280.667 2071.03 274C2060.03 270 2049.86 265.833 2040.53 261.5C2031.53 256.833 2023.69 251.5 2017.03 245.5C2010.36 239.5 2005.03 232.333 2001.03 224C1997.36 215.333 1995.53 204.833 1995.53 192.5C1995.53 168.5 2004.36 149.667 2022.03 136C2039.69 122 2063.69 115 2094.03 115C2109.36 115 2124.03 116.5 2138.03 119.5C2152.03 122.167 2162.53 124.833 2169.53 127.5L2158.53 176.5C2151.86 173.5 2143.36 170.833 2133.03 168.5C2122.69 165.833 2110.69 164.5 2097.03 164.5C2084.69 164.5 2074.69 166.667 2067.03 171C2059.36 175 2055.53 181.333 2055.53 190C2055.53 194.333 2056.19 198.167 2057.53 201.5C2059.19 204.833 2061.86 208 2065.53 211C2069.19 213.667 2074.03 216.5 2080.03 219.5C2086.03 222.167 2093.36 225 2102.03 228C2116.36 233.333 2128.53 238.667 2138.53 244C2148.53 249 2156.69 254.833 2163.03 261.5C2169.69 267.833 2174.53 275.167 2177.53 283.5C2180.53 291.833 2182.03 301.833 2182.03 313.5C2182.03 338.5 2172.69 357.5 2154.03 370.5C2135.69 383.167 2109.36 389.5 2075.03 389.5C2052.03 389.5 2033.53 387.5 2019.53 383.5C2005.53 379.833 1995.69 376.833 1990.03 374.5L2000.53 324C2009.53 327.667 2020.19 331.167 2032.53 334.5C2045.19 337.833 2059.53 339.5 2075.53 339.5ZM2214.04 253.5C2214.04 230.5 2217.38 210.333 2224.04 193C2231.04 175.667 2240.21 161.333 2251.54 150C2262.88 138.333 2275.88 129.667 2290.54 124C2305.21 118 2320.21 115 2335.54 115C2371.54 115 2399.54 126.167 2419.54 148.5C2439.88 170.833 2450.04 204.167 2450.04 248.5C2450.04 251.833 2449.88 255.667 2449.54 260C2449.54 264 2449.38 267.667 2449.04 271H2276.54C2278.21 292 2285.54 308.333 2298.54 320C2311.88 331.333 2331.04 337 2356.04 337C2370.71 337 2384.04 335.667 2396.04 333C2408.38 330.333 2418.04 327.5 2425.04 324.5L2433.04 374C2429.71 375.667 2425.04 377.5 2419.04 379.5C2413.38 381.167 2406.71 382.667 2399.04 384C2391.71 385.667 2383.71 387 2375.04 388C2366.38 389 2357.54 389.5 2348.54 389.5C2325.54 389.5 2305.54 386.167 2288.54 379.5C2271.54 372.5 2257.54 363 2246.54 351C2235.54 338.667 2227.38 324.333 2222.04 308C2216.71 291.333 2214.04 273.167 2214.04 253.5ZM2389.54 226.5C2389.54 218.167 2388.38 210.333 2386.04 203C2383.71 195.333 2380.21 188.833 2375.54 183.5C2371.21 177.833 2365.71 173.5 2359.04 170.5C2352.71 167.167 2345.04 165.5 2336.04 165.5C2326.71 165.5 2318.54 167.333 2311.54 171C2304.54 174.333 2298.54 178.833 2293.54 184.5C2288.88 190.167 2285.21 196.667 2282.54 204C2279.88 211.333 2278.04 218.833 2277.04 226.5H2389.54Z" fill="black"/>
+<g transform="scale(0.96)">
+<path d="M105.933 0C164.437 0.000116002 211.865 47.607 211.865 106.333C211.865 131.829 210.493 158.403 221.068 181.602L228.975 198.947C243.584 230.997 269.265 256.7 301.303 271.336L316.155 278.121C340.142 289.079 367.694 287.335 394.066 287.335C452.571 287.335 499.999 334.942 499.999 393.668C499.999 452.394 452.571 500.001 394.066 500.001C335.562 500.001 288.134 452.394 288.134 393.668C288.134 368.974 289.24 343.275 278.992 320.807L270.586 302.38C255.948 270.29 230.214 244.565 198.118 229.939L180.164 221.758C157.282 211.331 131.078 212.666 105.933 212.666C47.4278 212.666 4.86252e-05 165.059 0 106.333C0 47.607 47.4278 0 105.933 0Z" fill="black"/>
+<circle cx="100.426" cy="399.575" r="100.426" fill="black"/>
+<path d="M500 100.426C500 155.889 455.037 200.851 399.574 200.851C344.11 200.851 299.148 155.889 299.148 100.426C299.148 44.962 344.11 0 399.574 0C455.037 0 500 44.962 500 100.426Z" fill="black"/>
+</g>
+</svg>

package/dist/templates/mcp-apps/tsconfig.json

@@ -10,9 +10,15 @@
     "forceConsistentCasingInFileNames": true,
     "skipLibCheck": true,
     "noEmit": true,
-    "noUncheckedIndexedAccess": true,
-    "exactOptionalPropertyTypes": true
+    "noUncheckedSideEffectImports": false
   },
-  "include": ["index.ts", "src/**/*", "resources/**/*"],
+  "include": [
+    "index.ts",
+    "mcp-env.d.ts",
+    "src/**/*",
+    "views/**/*",
+    "server.ts",
+    ".mcp-use/**/*.d.ts"
+  ],
   "exclude": ["node_modules", "dist"]
 }

package/dist/templates/mcp-apps/views/my-view/MeshGradient.tsx

@@ -0,0 +1,299 @@
+import { useEffect, useRef } from "react";
+
+// Hero mesh palette (light landing surfaces)
+const MESH_COLORS = ["#e0eaff", "#f9ffbd", "#dedede", "#ffffff"];
+const HERO_MESH_SPEED = 1.15;
+const HERO_MESH_SWIRL = 0.95;
+const ORB_MAX_WIDTH_PX = 800;
+
+const VERT = `#version 300 es
+precision mediump float;
+in vec4 a_position;
+uniform vec2 u_resolution;
+out vec2 v_objectUV;
+void main(){
+  gl_Position=a_position;
+  vec2 uv=a_position.xy*0.5;
+  float box=min(u_resolution.x,u_resolution.y);
+  vec2 scale=box>0.0?u_resolution/box:vec2(1.);
+  v_objectUV=uv*scale;
+}`;
+
+const FRAG = `#version 300 es
+precision mediump float;
+uniform float u_time;
+uniform vec4 u_colors[4];
+uniform float u_colorsCount;
+uniform float u_distortion;
+uniform float u_swirl;
+uniform float u_grainMixer;
+uniform float u_grainOverlay;
+in vec2 v_objectUV;
+out vec4 fragColor;
+vec2 rotate(vec2 uv,float th){return mat2(cos(th),sin(th),-sin(th),cos(th))*uv;}
+float hash21(vec2 p){
+  p=fract(p*vec2(0.3183099,0.3678794))+0.1;
+  p+=dot(p,p+19.19);
+  return fract(p.x*p.y);
+}
+float valueNoise(vec2 st){
+  vec2 i=floor(st);vec2 f=fract(st);
+  float a=hash21(i),b=hash21(i+vec2(1.,0.)),c=hash21(i+vec2(0.,1.)),d=hash21(i+vec2(1.,1.));
+  vec2 u=f*f*(3.-2.*f);
+  return mix(mix(a,b,u.x),mix(c,d,u.x),u.y);
+}
+vec2 getPosition(int i,float t){
+  float a=float(i)*.37,b=.6+fract(float(i)/3.)*.9,c=.8+fract(float(i+1)/4.);
+  float x=sin(t*b+a),y=cos(t*c+a*1.5);
+  return .5+.5*vec2(x,y);
+}
+void main(){
+  vec2 uv=v_objectUV;uv+=.5;
+  vec2 grainUV=uv*1000.;
+  float grain=valueNoise(grainUV);
+  float mixerGrain=.4*u_grainMixer*(grain-.5);
+  float t=.5*(u_time+41.5);
+  float radius=smoothstep(0.,1.,length(uv-.5));
+  float center=1.-radius;
+  for(float i=1.;i<=2.;i++){
+    uv.x+=u_distortion*center/i*sin(t+i*.4*smoothstep(0.,1.,uv.y))*cos(.2*t+i*2.4*smoothstep(0.,1.,uv.y));
+    uv.y+=u_distortion*center/i*cos(t+i*2.*smoothstep(0.,1.,uv.x));
+  }
+  vec2 uvR=uv-vec2(.5);
+  float angle=3.*u_swirl*radius;
+  uvR=rotate(uvR,-angle);uvR+=vec2(.5);
+  vec3 color=vec3(0.);float opacity=0.,totalWeight=0.;
+  for(int i=0;i<4;i++){
+    if(i>=int(u_colorsCount))break;
+    vec2 pos=getPosition(i,t)+mixerGrain;
+    vec3 cf=u_colors[i].rgb*u_colors[i].a;
+    float opacityF=u_colors[i].a;
+    float dist=length(uvR-pos);
+    dist=pow(dist,3.5);
+    float w=1./(dist+1e-3);
+    color+=cf*w;opacity+=opacityF*w;totalWeight+=w;
+  }
+  color/=max(1e-4,totalWeight);
+  opacity/=max(1e-4,totalWeight);
+  float grainO=valueNoise(rotate(grainUV,1.)+vec2(3.));
+  grainO=mix(grainO,valueNoise(rotate(grainUV,2.)+vec2(-1.)),.5);
+  grainO=pow(grainO,1.3);
+  float grainOV=grainO*2.-1.;
+  vec3 grainOC=vec3(step(0.,grainOV));
+  float grainOS=u_grainOverlay*abs(grainOV);
+  grainOS=pow(grainOS,.8);
+  color=mix(color,grainOC,.35*grainOS);
+  opacity+=.5*grainOS;
+  fragColor=vec4(color,clamp(opacity,0.,1.));
+}`;
+
+function hexToRgba(hex: string): [number, number, number, number] {
+  return [
+    parseInt(hex.slice(1, 3), 16) / 255,
+    parseInt(hex.slice(3, 5), 16) / 255,
+    parseInt(hex.slice(5, 7), 16) / 255,
+    1,
+  ];
+}
+
+/** WebGL2 mesh gradient canvas (self-contained; no external deps). */
+function MeshGradientCanvas({
+  className,
+  colors = MESH_COLORS,
+  distortion = 0.8,
+  swirl = 0.1,
+  grainMixer = 0,
+  grainOverlay = 0.2,
+  speed = 1,
+}: {
+  className?: string;
+  colors?: string[];
+  distortion?: number;
+  swirl?: number;
+  grainMixer?: number;
+  grainOverlay?: number;
+  speed?: number;
+}) {
+  const canvasRef = useRef<HTMLCanvasElement>(null);
+  const wrapRef = useRef<HTMLDivElement>(null);
+  const propsRef = useRef({
+    colors,
+    distortion,
+    swirl,
+    grainMixer,
+    grainOverlay,
+    speed,
+  });
+  propsRef.current = {
+    colors,
+    distortion,
+    swirl,
+    grainMixer,
+    grainOverlay,
+    speed,
+  };
+
+  useEffect(() => {
+    const canvas = canvasRef.current;
+    const wrap = wrapRef.current;
+    if (!canvas || !wrap) return;
+
+    const gl = canvas.getContext("webgl2");
+    if (!gl) return;
+
+    const compileShader = (type: number, src: string) => {
+      const shader = gl.createShader(type);
+      if (!shader) return null;
+      gl.shaderSource(shader, src);
+      gl.compileShader(shader);
+      if (!gl.getShaderParameter(shader, gl.COMPILE_STATUS)) {
+        console.error(gl.getShaderInfoLog(shader));
+        return null;
+      }
+      return shader;
+    };
+
+    const vs = compileShader(gl.VERTEX_SHADER, VERT);
+    const fs = compileShader(gl.FRAGMENT_SHADER, FRAG);
+    if (!vs || !fs) return;
+
+    const prog = gl.createProgram();
+    if (!prog) return;
+    gl.attachShader(prog, vs);
+    gl.attachShader(prog, fs);
+    gl.linkProgram(prog);
+    if (!gl.getProgramParameter(prog, gl.LINK_STATUS)) {
+      console.error(gl.getProgramInfoLog(prog));
+      return;
+    }
+    gl.useProgram(prog);
+
+    const posLoc = gl.getAttribLocation(prog, "a_position");
+    const buf = gl.createBuffer();
+    gl.bindBuffer(gl.ARRAY_BUFFER, buf);
+    gl.bufferData(
+      gl.ARRAY_BUFFER,
+      new Float32Array([-1, -1, 1, -1, -1, 1, -1, 1, 1, -1, 1, 1]),
+      gl.STATIC_DRAW
+    );
+    gl.enableVertexAttribArray(posLoc);
+    gl.vertexAttribPointer(posLoc, 2, gl.FLOAT, false, 0, 0);
+
+    const uTime = gl.getUniformLocation(prog, "u_time");
+    const uResolution = gl.getUniformLocation(prog, "u_resolution");
+    const uColors = [0, 1, 2, 3].map((i) =>
+      gl.getUniformLocation(prog, `u_colors[${i}]`)
+    );
+    const uColorsCount = gl.getUniformLocation(prog, "u_colorsCount");
+    const uDistortion = gl.getUniformLocation(prog, "u_distortion");
+    const uSwirl = gl.getUniformLocation(prog, "u_swirl");
+    const uGrainMixer = gl.getUniformLocation(prog, "u_grainMixer");
+    const uGrainOverlay = gl.getUniformLocation(prog, "u_grainOverlay");
+
+    let frameMs = 0;
+    let lastNow = performance.now();
+    let raf = 0;
+
+    const resize = () => {
+      const dpr = Math.min(2, window.devicePixelRatio || 1);
+      canvas.width = Math.floor(wrap.clientWidth * dpr);
+      canvas.height = Math.floor(wrap.clientHeight * dpr);
+      gl.viewport(0, 0, canvas.width, canvas.height);
+    };
+
+    const draw = (now: number) => {
+      if (document.hidden) {
+        lastNow = now;
+        raf = requestAnimationFrame(draw);
+        return;
+      }
+      const {
+        colors: currentColors,
+        distortion: currentDistortion,
+        swirl: currentSwirl,
+        grainMixer: currentGrainMixer,
+        grainOverlay: currentGrainOverlay,
+        speed: currentSpeed,
+      } = propsRef.current;
+      const dt = now - lastNow;
+      lastNow = now;
+      frameMs += dt * currentSpeed;
+      const rgbaColors = currentColors.map(hexToRgba);
+      gl.uniform1f(uTime, frameMs * 1e-3);
+      gl.uniform2f(uResolution, canvas.width, canvas.height);
+      for (let i = 0; i < 4; i++) {
+        const loc = uColors[i];
+        if (loc) gl.uniform4fv(loc, rgbaColors[i] ?? [1, 1, 1, 1]);
+      }
+      gl.uniform1f(uColorsCount, rgbaColors.length);
+      gl.uniform1f(uDistortion, currentDistortion);
+      gl.uniform1f(uSwirl, currentSwirl);
+      gl.uniform1f(uGrainMixer, currentGrainMixer);
+      gl.uniform1f(uGrainOverlay, currentGrainOverlay);
+      gl.drawArrays(gl.TRIANGLES, 0, 6);
+      raf = requestAnimationFrame(draw);
+    };
+
+    resize();
+    const ro = new ResizeObserver(resize);
+    ro.observe(wrap);
+    raf = requestAnimationFrame(draw);
+
+    return () => {
+      cancelAnimationFrame(raf);
+      ro.disconnect();
+    };
+  }, []);
+
+  return (
+    <div ref={wrapRef} className={className}>
+      <canvas ref={canvasRef} className="h-full w-full" aria-hidden />
+    </div>
+  );
+}
+
+function MeshOrbContent() {
+  return (
+    <>
+      <div className="absolute inset-0 bg-[#edf2ff]" />
+      <MeshGradientCanvas
+        className="absolute inset-0 h-full w-full"
+        colors={MESH_COLORS}
+        distortion={0.8}
+        swirl={HERO_MESH_SWIRL}
+        grainMixer={0}
+        grainOverlay={0.3}
+        speed={HERO_MESH_SPEED}
+      />
+    </>
+  );
+}
+
+/** Mesh disc peeking from the bottom — 80% of card width, capped at 800px. */
+export function HeroMeshOrb({ flow = false }: { flow?: boolean }) {
+  if (flow) {
+    return (
+      <div
+        className="relative z-0 mt-2 w-full overflow-hidden pb-[22%]"
+        aria-hidden
+      >
+        <div
+          className="absolute bottom-0 left-1/2 aspect-square w-full -translate-x-1/2 translate-y-[78%] overflow-hidden rounded-full opacity-90"
+          style={{ maxWidth: ORB_MAX_WIDTH_PX }}
+        >
+          <MeshOrbContent />
+        </div>
+      </div>
+    );
+  }
+
+  return (
+    <div
+      className="pointer-events-none absolute bottom-0 left-1/2 z-0 aspect-square w-[80%] -translate-x-1/2 translate-y-[78%] overflow-hidden rounded-full opacity-90"
+      style={{ maxWidth: ORB_MAX_WIDTH_PX }}
+      aria-hidden
+    >
+      <MeshOrbContent />
+    </div>
+  );
+}

package/dist/templates/mcp-apps/views/my-view/Tooltip.tsx

@@ -0,0 +1,75 @@
+import { useRef, useState, type ReactNode } from "react";
+
+/** Hover/focus tooltip clamped to the nearest [data-card-shell] ancestor. */
+export function Tooltip({
+  label,
+  children,
+  multiline = false,
+}: {
+  label: string;
+  children: ReactNode;
+  multiline?: boolean;
+}) {
+  const wrapRef = useRef<HTMLSpanElement>(null);
+  const tipRef = useRef<HTMLSpanElement>(null);
+  const [open, setOpen] = useState(false);
+  const [pos, setPos] = useState({ left: 0, maxWidth: 320 });
+
+  const show = () => {
+    const wrap = wrapRef.current;
+    const tip = tipRef.current;
+    const card = wrap?.closest("[data-card-shell]");
+    if (!wrap || !tip || !card) {
+      setOpen(true);
+      return;
+    }
+    const pad = 12;
+    const cardR = card.getBoundingClientRect();
+    const wrapR = wrap.getBoundingClientRect();
+    const maxWidth = Math.min(320, Math.max(160, cardR.width - pad * 2));
+    Object.assign(tip.style, {
+      maxWidth: `${maxWidth}px`,
+      visibility: "hidden",
+      opacity: "1",
+    });
+    const w = tip.offsetWidth;
+    tip.style.visibility = "";
+    tip.style.opacity = "";
+    const left =
+      Math.max(
+        cardR.left + pad,
+        Math.min(wrapR.left + wrapR.width / 2 - w / 2, cardR.right - pad - w)
+      ) - wrapR.left;
+    setPos({ left, maxWidth });
+    setOpen(true);
+  };
+
+  return (
+    <span
+      ref={wrapRef}
+      className="relative inline-flex"
+      onMouseEnter={show}
+      onMouseLeave={() => setOpen(false)}
+      onFocus={show}
+      onBlur={() => setOpen(false)}
+    >
+      {children}
+      <span
+        ref={tipRef}
+        role="tooltip"
+        style={{
+          left: pos.left,
+          maxWidth: pos.maxWidth,
+          opacity: open ? 1 : 0,
+        }}
+        className={`pointer-events-none absolute top-full z-30 mt-1.5 w-max rounded-lg bg-zinc-900 px-3 py-2 text-[11px] font-medium text-white transition-opacity duration-200 dark:bg-zinc-800 dark:text-neutral-100 ${
+          multiline
+            ? "whitespace-normal text-left leading-snug"
+            : "whitespace-nowrap"
+        }`}
+      >
+        {label}
+      </span>
+    </span>
+  );
+}