TypeGPU Runtime Inspector MCP

Local stdio MCP server for validating TypeGPU code in Chromium with WebGPU.

It loads TypeGPU inspection modules through Vite, creates a browser GPUDevice, and reports generated WGSL, shader compilation messages, WebGPU validation errors, bind group layout stats, console/page errors, and recorded GPU calls.

Quick Setup

Use npx from the client you want to configure:

npx typegpu-runtime-inspector-mcp@latest setup codex
npx typegpu-runtime-inspector-mcp@latest setup claude
npx typegpu-runtime-inspector-mcp@latest setup opencode

Configure every supported client found on PATH:

npx typegpu-runtime-inspector-mcp@latest setup all

The setup command registers a local MCP server named typegpu_inspector and pins it to the package version that performed setup, for example:

npx [email protected]

Existing typegpu_inspector entries are left unchanged unless --upgrade or --force is provided.

Upgrade From v0.1

If you installed the first release with setup, your MCP client is pinned to that exact package version. Re-run setup with --upgrade to update an existing typegpu_inspector entry that already points at this npm package:

npx typegpu-runtime-inspector-mcp@latest setup codex --upgrade
npx typegpu-runtime-inspector-mcp@latest setup claude --upgrade
npx typegpu-runtime-inspector-mcp@latest setup opencode --upgrade

Or update every supported client found on PATH:

npx typegpu-runtime-inspector-mcp@latest setup all --upgrade

Then restart the MCP client so it launches the new server process. You can check the local environment with:

npx typegpu-runtime-inspector-mcp@latest doctor

--upgrade only replaces entries that already reference this npm package. If a client has a custom typegpu_inspector command, use --force to replace it intentionally.

Run a local environment check:

npx typegpu-runtime-inspector-mcp@latest doctor

Requirements:

• Node.js 20 or newer
• Local filesystem access to the inspected project
• Playwright Chromium with WebGPU support

playwright-chromium is a runtime dependency of this package. If lifecycle scripts were skipped during install, enable them and reinstall, then run doctor again.

Manual Client Config

Codex (~/.codex/config.toml):

[mcp_servers.typegpu_inspector]
command = "npx"
args = ["typegpu-runtime-inspector-mcp@<version>"]

Codex CLI:

codex mcp add typegpu_inspector -- npx typegpu-runtime-inspector-mcp@<version>

Claude Code:

claude mcp add --transport stdio --scope user typegpu_inspector -- npx typegpu-runtime-inspector-mcp@<version>

OpenCode:

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "typegpu_inspector": {
      "type": "local",
      "command": ["npx", "typegpu-runtime-inspector-mcp@<version>"],
      "enabled": true
    }
  }
}

MCP Tools

inspect_typegpu_module

Stable v0.1 compatibility API. Loads an inspection module and validates one or more returned targets.

Accepted source variants:

• modulePath: path to an inspection module on disk.
• inlineCode: full TypeScript inspection module source.
• inspectBody: function body for quick probes.

cwd controls relative paths and package resolution. When set, the inspector resolves typegpu, typegpu/data, typegpu/std, typegpu/common, and unplugin-typegpu from that project before falling back to its own dependencies.

Inspection modules export inspect by default:

export async function inspect({ root, device, tgpu, d, std, common }) {
  const main = tgpu.computeFn({ workgroupSize: [1] })(() => {
    'use gpu';
  });

  return {
    label: 'main',
    kind: 'compute-pipeline',
    value: main,
  };
}

The context contains:

• root: TypeGPU root backed by the inspector browser device.
• device: recorded GPUDevice proxy.
• tgpu, d, std, common: TypeGPU imports resolved for the inspected project.

Return a target or an array of targets:

{
  label?: string;
  kind?: 'compute-pipeline' | 'render-pipeline' | 'resolvable';
  value?: unknown;
  create?: () => unknown;
  unwrap?: boolean;
}

Plain returned values are treated as { value }. Compute pipeline targets may return a TypeGPU compute entrypoint; the inspector creates the pipeline. Use create when construction should happen during target attribution, especially for render pipelines and descriptor-heavy probes.

return {
  label: 'render',
  kind: 'render-pipeline',
  create: () =>
    root.createRenderPipeline({
      vertex: common.fullScreenTriangle,
      fragment,
      targets: { format: 'bgra8unorm' },
    }),
};

If kind is omitted on a create target, the inspector infers it from the created TypeGPU pipeline when possible.

unstable_inspect_typegpu_symbols

Convenience API for selecting exported symbols from an existing module. It is unstable in v0.1 and imports the target module directly, so module-level side effects can run. It is fine to try this path first; if it fails even though the selectors and descriptors are correct, fall back to inspect_typegpu_module with a small wrapper.

Resolve an exported helper:

{
  "cwd": "/path/to/project",
  "modulePath": "src/shaders.ts",
  "targets": [
    {
      "label": "helper WGSL",
      "selector": "exportedHelper",
      "kind": "resolvable"
    }
  ]
}

Create a compute pipeline from an exported compute entrypoint:

{
  "cwd": "/path/to/project",
  "modulePath": "src/shaders.ts",
  "targets": [
    {
      "label": "main compute",
      "kind": "compute-pipeline",
      "compute": "computeMain"
    }
  ]
}

Create a render pipeline from exported entrypoints:

{
  "cwd": "/path/to/project",
  "modulePath": "src/shaders.ts",
  "targets": [
    {
      "label": "main render",
      "kind": "render-pipeline",
      "vertex": "mainVertex",
      "fragment": "mainFragment",
      "descriptor": {
        "targets": { "format": "bgra8unorm" }
      }
    }
  ]
}

Vertex attributes can be a selector for a full attribs object or a map from shader input names to attrib selectors:

{
  "modulePath": "src/shaders.ts",
  "targets": [
    {
      "kind": "render-pipeline",
      "vertex": "mainVertex",
      "fragment": "mainFragment",
      "attribs": {
        "color": "vertexLayout.attrib"
      },
      "descriptor": {
        "targets": { "format": "bgra8unorm" }
      }
    }
  ]
}

Selectors are dot paths from the imported module by default. setupBody can return extra selector roots:

{
  "modulePath": "src/shaders.ts",
  "setupBody": "return { common };",
  "targets": [
    {
      "kind": "render-pipeline",
      "vertex": "common.fullScreenTriangle",
      "fragment": "mainFragment",
      "descriptor": {
        "targets": { "format": "bgra8unorm" }
      }
    }
  ]
}

Bind TypeGPU slots or accessors before pipeline creation with with:

{
  "modulePath": "src/shaders.ts",
  "setupBody": "return { time: root.createUniform(module.Time) };",
  "targets": [
    {
      "kind": "compute-pipeline",
      "compute": "computeGravityShader",
      "with": [{ "slot": "timeAccess", "value": "setup.time" }]
    }
  ]
}

Private top-level declarations are not extracted. Export them, return them from setupBody, or use inspect_typegpu_module with a small wrapper.

Inline Module Examples

Quick probe with inspectBody:

{
  "source": {
    "kind": "inspectBody",
    "inspectBody": "const fragment = tgpu.fragmentFn({ in: { uv: d.vec2f }, out: d.vec4f })(({ uv }) => { 'use gpu'; return d.vec4f(uv, 0, 1); }); return { label: 'render', kind: 'render-pipeline', create: () => root.createRenderPipeline({ vertex: common.fullScreenTriangle, fragment, targets: { format: 'bgra8unorm' } }) };"
  }
}

Inspection file:

{
  "cwd": "/path/to/project",
  "source": {
    "kind": "modulePath",
    "modulePath": "src/inspect-particle-step.ts"
  }
}

Inline module with top-level imports:

{
  "source": {
    "kind": "inlineCode",
    "inlineSourcePath": "/path/to/snippet.ts",
    "inlineCode": "import { helper } from './helper'; export async function inspect() { return helper; }"
  }
}

Browser Setup And Assets

Use these fields when the inspected module expects DOM nodes, globals, static assets, or non-standard import paths:

{
  "source": {
    "kind": "modulePath",
    "modulePath": "src/examples/image-processing/blur/index.ts"
  },
  "documentHtml": "<canvas width=\"512\" height=\"512\"></canvas>",
  "browserSetup": "window.__TEST_MODE__ = true;",
  "staticAssetRoutes": [
    { "urlPrefix": "/TypeGPU", "directory": "public" },
    { "urlPrefix": "/", "directory": "public" }
  ],
  "dependencyAliases": {
    "#inspector-helpers": "examples/deps/shader-library.ts"
  },
  "fsAllow": ["examples/deps"]
}

Fields:

• documentHtml: assigned to document.body.innerHTML before import.
• browserSetup: browser JavaScript executed before import with root, device, tgpu, d, std, and common parameters.
• staticAssetRoutes: serves files from local directories through the inspector Vite server.
• dependencyAliases: Vite aliases for helper modules.
• fsAllow: additional directories Vite may serve.
• features: WebGPU features to request from the adapter.
• strictNames: deterministic TypeGPU generated names. Defaults to true.
• viteConfigPath: optional project Vite config.

Output

Default output is a compact summary. Controls:

• verbosity: "summary" (default), "normal", or "full".
• includeWgsl: include WGSL in targets and shader-module descriptors. Defaults to true only for "full".
• includeCalls: include recorded GPU calls. Defaults to true only for "full".
• maxWgslBytes: truncate each included WGSL string to this many UTF-8 bytes.
• diagnosticsOnly: return diagnostics, target status, console messages, and page errors. With source.kind: "modulePath", diagnostic-only mode can import a normal app module that has no inspect export and report import/runtime diagnostics without requiring targets.

inspectBody, inlineCode, setupBody, and browserSetup are JavaScript or TypeScript source snippets. Pass actual newline characters in these fields when you need multiple lines; double-escaped text such as \\nconst x = 1 is parsed as literal source and will fail.

{
  "source": {
    "kind": "inspectBody",
    "inspectBody": "return { label: 'main', kind: 'resolvable', value: helper };"
  },
  "verbosity": "normal",
  "includeWgsl": true,
  "maxWgslBytes": 4000
}

Common diagnostic codes:

• plain-object-not-inspectable
• wrapper-required
• slot-binding-required
• pipeline-resource-shape
• pipeline-validated-without-recorded-creation
• raw-webgpu-pipeline-unsupported
• typegpu-fragment-function-not-resolvable
• module-import-failed
• canvas-dom-setup-required
• unstable-symbol-inspection
• typegpu-random-resolution-failed

Local Development

pnpm install
pnpm start

Checks:

pnpm typecheck
pnpm test
pnpm test:browser

Browser tests require Playwright Chromium with WebGPU support. If Chromium is missing, run:

pnpm exec playwright install chromium