feat(inspector): add @mcp-apps-kit/inspector package for MCP server testing and debugging (#129)

Author: gabe4coding

eslint.config.js

@@ -18,6 +18,7 @@ export default [
       "packages/testing/**/*.ts",
       "packages/ui-react-builder/**/*.ts",
       "packages/codegen/**/*.ts",
+      "packages/inspector/**/*.ts",
     ],
     languageOptions: {
       parser: tsparser,
@@ -28,6 +29,7 @@ export default [
           "./packages/testing/tsconfig.json",
           "./packages/ui-react-builder/tsconfig.json",
           "./packages/codegen/tsconfig.json",
+          "./packages/inspector/tsconfig.json",
         ],
         tsconfigRootDir: import.meta.dirname,
       },

examples/weather-app/mcp.config.ts

@@ -31,7 +31,6 @@ export default defineConfig({
       origin: true,
     },
     debug: {
-      logTool: true,
       level: "debug",
     },
   },

examples/weather-app/tests/integration/server.test.ts

@@ -47,8 +47,8 @@ describe("Weather App MCP Server", () => {
     it("should list all weather tools", async () => {
       const tools = await env.client.listTools();
 
-      // 4 weather tools + 1 log_debug tool (from debug.logTool config)
-      expect(tools.length).toBe(5);
+      // 4 weather tools: getCurrentWeather, getForecast, getWeatherAlerts, dailyBriefing
+      expect(tools.length).toBe(4);
       // File-based naming: get-current-weather.ts -> getCurrentWeather (camelCase)
       expect(tools.some((t) => t.name === "getCurrentWeather")).toBe(true);
       expect(tools.some((t) => t.name === "getForecast")).toBe(true);

examples/weather-app/ui/styles.css

@@ -9,6 +9,7 @@
  * to avoid Tailwind layer specificity issues.
  */
 
+/* Light theme (default) */
 :root {
   --weather-bg-primary: #f5f7fa;
   --weather-bg-card: #ffffff;
@@ -21,8 +22,21 @@
   --weather-shadow: 0 4px 6px -1px rgba(0, 0, 0, 0.1), 0 2px 4px -1px rgba(0, 0, 0, 0.06);
 }
 
+/* Dark theme - applied via class from useDocumentTheme hook */
+body.dark {
+  --weather-bg-primary: #111827;
+  --weather-bg-card: #1f2937;
+  --weather-bg-inset: #374151;
+  --weather-text-primary: #f9fafb;
+  --weather-text-secondary: #d1d5db;
+  --weather-text-muted: #9ca3af;
+  --weather-border: #374151;
+  --weather-shadow: 0 4px 6px -1px rgba(0, 0, 0, 0.3), 0 2px 4px -1px rgba(0, 0, 0, 0.2);
+}
+
+/* Fallback: also support OS preference when no class is set */
 @media (prefers-color-scheme: dark) {
-  :root {
+  body:not(.light):not(.dark) {
     --weather-bg-primary: #111827;
     --weather-bg-card: #1f2937;
     --weather-bg-inset: #374151;

package.json

@@ -52,6 +52,7 @@
     "lint-staged": "^16.2.7",
     "nx": "^22.4.2",
     "prettier": "^3.8.1",
+    "playwright": "^1.58.0",
     "tsup": "^8.5.1",
     "typedoc": "^0.28.16",
     "typedoc-plugin-markdown": "^4.9.0",

packages/core/src/constants.ts

@@ -0,0 +1,19 @@
+/**
+ * Constants for MCP Apps Kit
+ */
+
+/**
+ * MIME type for MCP Apps (Claude Desktop) widgets
+ *
+ * Used to identify UI resources that should be rendered using the
+ * MCP Apps protocol (JSON-RPC over postMessage via ext-apps).
+ */
+export const MCP_WIDGET_MIME_TYPE = "text/html;profile=mcp-app";
+
+/**
+ * MIME type for OpenAI Apps (ChatGPT) widgets
+ *
+ * Used to identify UI resources that should be rendered using the
+ * OpenAI Apps SDK protocol (window.openai + DOM events).
+ */
+export const OPENAI_WIDGET_MIME_TYPE = "text/html+skybridge";

packages/core/src/createApp.ts

@@ -473,6 +473,21 @@ function createSingleVersionApp<T extends ToolDefs>(config: AppConfig<T>): App<T
     configureDebugLogger(normalizedConfig.config.debug);
   }
 
+  // Handle autoInspector config - inject dev-inspector plugin
+  if (normalizedConfig.config?.autoInspector) {
+    // Dynamic import to avoid bundling inspector in production builds
+    // eslint-disable-next-line @typescript-eslint/no-require-imports
+    const { createDevInspectorPlugin } = require("./plugins/builtin/dev-inspector") as {
+      createDevInspectorPlugin: typeof import("./plugins/builtin/dev-inspector").createDevInspectorPlugin;
+    };
+    const serverRoute = normalizedConfig.config.serverRoute ?? "/mcp";
+    const inspectorPlugin = createDevInspectorPlugin(
+      normalizedConfig.config.autoInspector,
+      serverRoute
+    );
+    normalizedConfig.plugins = [...(normalizedConfig.plugins ?? []), inspectorPlugin];
+  }
+
   // Initialize plugin manager (but defer init() call to app.start())
   const pluginManager = new PluginManager(normalizedConfig.plugins ?? []);
   let pluginInitialized = false;
@@ -768,6 +783,26 @@ function createMultiVersionApp<T extends ToolDefs>(config: VersionsConfig<T>): A
     // because it's a global singleton. If version-specific debug configs are needed, they would
     // require per-version logger instances, which is a larger architectural change.
 
+    // Handle autoInspector config - inject dev-inspector plugin
+    // Only inject for the first version to avoid multiple inspectors
+    if (normalizedVersionConfig.config?.autoInspector && versionApps.size === 0) {
+      // Dynamic import to avoid bundling inspector in production builds
+      // eslint-disable-next-line @typescript-eslint/no-require-imports
+      const { createDevInspectorPlugin } = require("./plugins/builtin/dev-inspector") as {
+        createDevInspectorPlugin: typeof import("./plugins/builtin/dev-inspector").createDevInspectorPlugin;
+      };
+      // For multi-version, use the version-specific route
+      const serverRoute = `/${versionKey}/mcp`;
+      const inspectorPlugin = createDevInspectorPlugin(
+        normalizedVersionConfig.config.autoInspector,
+        serverRoute
+      );
+      normalizedVersionConfig.plugins = [
+        ...(normalizedVersionConfig.plugins ?? []),
+        inspectorPlugin,
+      ];
+    }
+
     // Initialize version-specific plugin manager
     const versionPluginManager = new PluginManager(normalizedVersionConfig.plugins ?? []);
     let versionPluginInitialized = false;

packages/core/src/index.ts

@@ -323,6 +323,9 @@ export type {
   ToolBuilderConfigurable,
 } from "./builder/tool-builder";
 
+// Constants
+export { MCP_WIDGET_MIME_TYPE, OPENAI_WIDGET_MIME_TYPE } from "./constants";
+
 // =============================================================================
 // WORKFLOW ENGINE
 // =============================================================================

packages/core/src/plugins/builtin/dev-inspector.ts

@@ -0,0 +1,110 @@
+/**
+ * Dev Inspector Plugin
+ *
+ * Automatically spawns the MCP Inspector and connects it to this server.
+ * Used internally by createApp when autoInspector config is enabled.
+ *
+ * @internal - Not exported publicly, used by createApp when autoInspector is enabled
+ */
+
+import { spawn, type ChildProcess } from "child_process";
+import type { Plugin } from "../types";
+import type { AutoInspectorConfig } from "../../types/config";
+
+/**
+ * Resolve auto-inspector config to full config object with defaults
+ */
+function resolveConfig(config: AutoInspectorConfig | true): Required<AutoInspectorConfig> {
+  if (config === true) {
+    return {
+      port: 6274,
+      debug: false,
+      devOnly: true,
+    };
+  }
+  return {
+    port: config.port ?? 6274,
+    debug: config.debug ?? false,
+    devOnly: config.devOnly ?? true,
+  };
+}
+
+/**
+ * Create dev inspector plugin with given config
+ *
+ * @param config - Auto-inspector configuration
+ * @param serverRoute - The MCP server route path (e.g., "/mcp")
+ * @returns Plugin that spawns inspector on start
+ *
+ * @internal - Not exported publicly, used by createApp when autoInspector is enabled
+ */
+export function createDevInspectorPlugin(
+  config: AutoInspectorConfig | true,
+  serverRoute: string
+): Plugin {
+  const resolvedConfig = resolveConfig(config);
+
+  // Keep inspector process state scoped to this plugin instance
+  let inspectorProcess: ChildProcess | null = null;
+
+  return {
+    name: "dev-inspector",
+    version: "1.0.0",
+
+    onStart: async (context) => {
+      // Skip in production if devOnly is true
+      if (resolvedConfig.devOnly && process.env.NODE_ENV === "production") {
+        return;
+      }
+
+      // Only works with HTTP transport
+      if (context.transport !== "http" || !context.port) {
+        // eslint-disable-next-line no-console
+        console.warn("[autoInspector] Skipped: only works with HTTP transport");
+        return;
+      }
+
+      const serverUrl = `http://localhost:${context.port}${serverRoute}`;
+      const args = ["--url", serverUrl, "--port", String(resolvedConfig.port)];
+
+      if (resolvedConfig.debug) {
+        args.push("--debug");
+      }
+
+      // eslint-disable-next-line no-console
+      console.log(`[autoInspector] Starting inspector on port ${resolvedConfig.port}`);
+      // eslint-disable-next-line no-console
+      console.log(`[autoInspector] Connecting to: ${serverUrl}`);
+
+      // Spawn mcp-inspector using npx to find the CLI
+      // We use npx to ensure we find the installed mcp-inspector binary
+      inspectorProcess = spawn("npx", ["mcp-inspector", ...args], {
+        stdio: "inherit",
+        detached: false,
+        shell: true,
+      });
+
+      inspectorProcess.on("error", (err) => {
+        // eslint-disable-next-line no-console
+        console.error(`[autoInspector] Failed to spawn inspector: ${err.message}`);
+      });
+
+      inspectorProcess.on("exit", (code) => {
+        if (code !== null && code !== 0) {
+          // eslint-disable-next-line no-console
+          console.warn(`[autoInspector] Inspector exited with code ${code}`);
+        }
+        inspectorProcess = null;
+      });
+    },
+
+    onShutdown: async () => {
+      if (inspectorProcess) {
+        // eslint-disable-next-line no-console
+        console.log("[autoInspector] Stopping inspector...");
+        inspectorProcess.kill();
+        inspectorProcess = null;
+      }
+    },
+  };
+}

packages/core/src/server/index.ts

@@ -6,6 +6,7 @@
 
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
+import { WebStandardStreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/webStandardStreamableHttp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import {
   mcpAuthMetadataRouter,
@@ -498,7 +499,7 @@ export function createServerInstance<T extends ToolDefs>(
       req: globalThis.Request,
       _env?: unknown
     ): Promise<globalThis.Response> => {
-      // Serverless handler using Streamable HTTP transport
+      // Serverless handler using Web Standard Streamable HTTP transport
       try {
         const url = new URL(req.url);
 
@@ -543,60 +544,22 @@ export function createServerInstance<T extends ToolDefs>(
           );
         }
 
-        // For serverless, create a one-shot transport
-        const transport = new StreamableHTTPServerTransport({
+        // Use Web Standard transport for serverless - accepts Request, returns Response
+        const transport = new WebStandardStreamableHTTPServerTransport({
           sessionIdGenerator: undefined,
           enableJsonResponse: true,
         });
 
         // Connect to current MCP server (supports hot reload)
         await currentMcpServer.connect(transport);
 
-        // Convert Web Request to Express-like request
-        const body: unknown = req.method === "POST" ? await req.json() : undefined;
-
-        // Create a mock response object to capture the output
-        let responseBody = "";
-        let responseStatus = 200;
-        const responseHeaders: Record<string, string> = {};
-
-        const mockRes = {
-          status: (code: number) => {
-            responseStatus = code;
-            return mockRes;
-          },
-          setHeader: (name: string, value: string) => {
-            responseHeaders[name] = value;
-          },
-          json: (data: unknown) => {
-            responseBody = JSON.stringify(data);
-            responseHeaders["Content-Type"] = "application/json";
-          },
-          send: (data: string) => {
-            responseBody = data;
-          },
-          end: (): void => {
-            // No-op for serverless mock
-          },
-          on: () => mockRes,
-          write: (chunk: string) => {
-            responseBody += chunk;
-          },
-        };
-
-        const mockReq = { body, headers: Object.fromEntries(req.headers) };
-        await transport.handleRequest(
-          mockReq as unknown as Request,
-          mockRes as unknown as Response,
-          body
-        );
+        // Handle the request directly - returns a Response
+        const response = await transport.handleRequest(req);
 
+        // Close transport after handling
         await transport.close();
 
-        return new globalThis.Response(responseBody, {
-          status: responseStatus,
-          headers: responseHeaders,
-        });
+        return response;
       } catch (error) {
         const appError = wrapError(error);
         return new globalThis.Response(JSON.stringify({ error: appError.message }), {