@nuxtjs/mcp-toolkit 0.0.0 → 0.1.0

package/dist/runtime/server/mcp/definitions/resources.js

@@ -0,0 +1,94 @@
+import { readFile } from "node:fs/promises";
+import { resolve, extname } from "node:path";
+import { pathToFileURL } from "node:url";
+import { enrichNameTitle } from "./utils.js";
+function getMimeType(filePath) {
+  const ext = extname(filePath).toLowerCase();
+  switch (ext) {
+    case ".md":
+      return "text/markdown";
+    case ".ts":
+    case ".mts":
+    case ".cts":
+      return "text/typescript";
+    case ".js":
+    case ".mjs":
+    case ".cjs":
+      return "text/javascript";
+    case ".json":
+      return "application/json";
+    case ".html":
+      return "text/html";
+    case ".css":
+      return "text/css";
+    case ".xml":
+      return "text/xml";
+    case ".csv":
+      return "text/csv";
+    case ".yaml":
+    case ".yml":
+      return "text/yaml";
+    default:
+      return "text/plain";
+  }
+}
+export function registerResourceFromDefinition(server, resource) {
+  const { name, title } = enrichNameTitle({
+    name: resource.name,
+    title: resource.title,
+    _meta: resource._meta,
+    type: "resource"
+  });
+  let uri = resource.uri;
+  let handler = resource.handler;
+  const metadata = {
+    ...resource.metadata,
+    title: resource.title || resource.metadata?.title || title
+  };
+  if ("file" in resource && resource.file) {
+    const filePath = resolve(process.cwd(), resource.file);
+    if (!uri) {
+      uri = pathToFileURL(filePath).toString();
+    }
+    if (!handler) {
+      handler = async (requestUri) => {
+        try {
+          const content = await readFile(filePath, "utf-8");
+          return {
+            contents: [{
+              uri: requestUri.toString(),
+              mimeType: resource.metadata?.mimeType || getMimeType(filePath),
+              text: content
+            }]
+          };
+        } catch (error) {
+          throw new Error(`Failed to read file ${filePath}: ${error instanceof Error ? error.message : String(error)}`);
+        }
+      };
+    }
+  }
+  if (!uri) {
+    throw new Error(`Resource ${name} is missing a URI`);
+  }
+  if (!handler) {
+    throw new Error(`Resource ${name} is missing a handler`);
+  }
+  if (typeof uri === "string") {
+    return server.registerResource(
+      name,
+      uri,
+      metadata,
+      handler
+    );
+  } else {
+    return server.registerResource(
+      name,
+      uri,
+      metadata,
+      handler
+    );
+  }
+}
+export function defineMcpResource(definition) {
+  return definition;
+}

package/dist/runtime/server/mcp/definitions/tools.d.ts

@@ -0,0 +1,64 @@
+import type { z, ZodRawShape, ZodTypeAny } from 'zod';
+import type { CallToolResult, ServerRequest, ServerNotification, ToolAnnotations } from '@modelcontextprotocol/sdk/types.js';
+import type { RequestHandlerExtra } from '@modelcontextprotocol/sdk/shared/protocol.js';
+import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+/**
+ * Callback type for MCP tools, matching the SDK's ToolCallback type
+ */
+export type McpToolCallback<Args extends ZodRawShape | undefined = ZodRawShape> = Args extends ZodRawShape ? (args: z.objectOutputType<Args, ZodTypeAny>, extra: RequestHandlerExtra<ServerRequest, ServerNotification>) => CallToolResult | Promise<CallToolResult> : (extra: RequestHandlerExtra<ServerRequest, ServerNotification>) => CallToolResult | Promise<CallToolResult>;
+/**
+ * Definition of an MCP tool matching the SDK's registerTool signature
+ * This structure is identical to what you'd pass to server.registerTool()
+ */
+export interface McpToolDefinition<InputSchema extends ZodRawShape | undefined = ZodRawShape, OutputSchema extends ZodRawShape = ZodRawShape> {
+    name?: string;
+    title?: string;
+    description?: string;
+    inputSchema?: InputSchema;
+    outputSchema?: OutputSchema;
+    annotations?: ToolAnnotations;
+    _meta?: Record<string, unknown>;
+    handler: McpToolCallback<InputSchema>;
+}
+/**
+ * Helper function to register a tool from a McpToolDefinition
+ * This provides better type inference when registering tools
+ */
+export declare function registerToolFromDefinition<InputSchema extends ZodRawShape | undefined = ZodRawShape, OutputSchema extends ZodRawShape = ZodRawShape>(server: McpServer, tool: McpToolDefinition<InputSchema, OutputSchema>): import("@modelcontextprotocol/sdk/server/mcp.js").RegisteredTool;
+/**
+ * Define an MCP tool that will be automatically registered
+ *
+ * This function matches the exact structure of server.registerTool() from the MCP SDK,
+ * making it easy to migrate code from the SDK to this module.
+ *
+ * If `name` or `title` are not provided, they will be automatically generated from the filename
+ * (e.g., `list_documentation.ts` → `name: 'list-documentation'`, `title: 'List Documentation'`).
+ *
+ * @example
+ * ```ts
+ * // server/mcp/tools/my-tool.ts
+ * import { z } from 'zod'
+ *
+ * export default defineMcpTool({
+ *   name: 'calculate-bmi',
+ *   title: 'BMI Calculator',
+ *   description: 'Calculate Body Mass Index',
+ *   inputSchema: {
+ *     weightKg: z.number(),
+ *     heightM: z.number()
+ *   },
+ *   outputSchema: { bmi: z.number() },
+ *   handler: async ({ weightKg, heightM }) => {
+ *     const output = { bmi: weightKg / (heightM * heightM) }
+ *     return {
+ *       content: [{
+ *         type: 'text',
+ *         text: JSON.stringify(output)
+ *       }],
+ *       structuredContent: output
+ *     }
+ *   }
+ * })
+ * ```
+ */
+export declare function defineMcpTool<const InputSchema extends ZodRawShape | undefined = ZodRawShape, const OutputSchema extends ZodRawShape = ZodRawShape>(definition: McpToolDefinition<InputSchema, OutputSchema>): McpToolDefinition<InputSchema, OutputSchema>;

package/dist/runtime/server/mcp/definitions/tools.js

@@ -0,0 +1,38 @@
+import { enrichNameTitle } from "./utils.js";
+export function registerToolFromDefinition(server, tool) {
+  const { name, title } = enrichNameTitle({
+    name: tool.name,
+    title: tool.title,
+    _meta: tool._meta,
+    type: "tool"
+  });
+  if (tool.inputSchema) {
+    return server.registerTool(
+      name,
+      {
+        title,
+        description: tool.description,
+        inputSchema: tool.inputSchema,
+        outputSchema: tool.outputSchema,
+        annotations: tool.annotations,
+        _meta: tool._meta
+      },
+      tool.handler
+    );
+  } else {
+    return server.registerTool(
+      name,
+      {
+        title,
+        description: tool.description,
+        outputSchema: tool.outputSchema,
+        annotations: tool.annotations,
+        _meta: tool._meta
+      },
+      tool.handler
+    );
+  }
+}
+export function defineMcpTool(definition) {
+  return definition;
+}

package/dist/runtime/server/mcp/definitions/utils.d.ts

@@ -0,0 +1,14 @@
+export interface EnrichNameTitleOptions {
+    name?: string;
+    title?: string;
+    _meta?: Record<string, unknown>;
+    type: 'tool' | 'resource' | 'prompt';
+}
+export interface EnrichNameTitleResult {
+    name: string;
+    title?: string;
+}
+/**
+ * Enrich name and title from filename if missing
+ */
+export declare function enrichNameTitle(options: EnrichNameTitleOptions): EnrichNameTitleResult;

package/dist/runtime/server/mcp/definitions/utils.js

@@ -0,0 +1,23 @@
+import { kebabCase, titleCase } from "scule";
+export function enrichNameTitle(options) {
+  const { name, title, _meta, type } = options;
+  const filename = _meta?.filename;
+  let enrichedName = name;
+  let enrichedTitle = title;
+  if (filename) {
+    const nameWithoutExt = filename.replace(/\.(ts|js|mts|mjs)$/, "");
+    if (!enrichedName) {
+      enrichedName = kebabCase(nameWithoutExt);
+    }
+    if (!enrichedTitle) {
+      enrichedTitle = titleCase(nameWithoutExt);
+    }
+  }
+  if (!enrichedName) {
+    throw new Error(`Failed to auto-generate ${type} name from filename. Please provide a name explicitly.`);
+  }
+  return {
+    name: enrichedName,
+    title: enrichedTitle
+  };
+}

package/dist/runtime/server/mcp/devtools/index.d.ts

@@ -0,0 +1,3 @@
+import type { Nuxt } from 'nuxt/schema';
+import type { ModuleOptions } from '../../../../module.js';
+export declare function addDevToolsCustomTabs(nuxt: Nuxt, options: ModuleOptions): void;

package/dist/runtime/server/mcp/devtools/index.js

@@ -0,0 +1,342 @@
+import { logger } from "@nuxt/kit";
+import { spawn } from "node:child_process";
+const log = logger.withTag("@nuxtjs/mcp-toolkit");
+const INSPECTOR_TIMEOUT = 15e3;
+const HEALTH_CHECK_TIMEOUT = 3e3;
+const INSPECTOR_DEFAULT_CLIENT_PORT = 6274;
+const INSPECTOR_DEFAULT_SERVER_PORT = 6277;
+const HEALTH_CHECK_RETRIES = 5;
+const MAX_BUFFER_SIZE = 10240;
+const ERROR_PATTERNS = [
+  /PORT IS IN USE/i,
+  /EADDRINUSE/i,
+  /address already in use/i,
+  /port \d+ is already in use/i
+];
+let inspectorProcess = null;
+let inspectorUrl = null;
+let isReady = false;
+let promise = null;
+let proxyAuthToken = null;
+function resetState() {
+  inspectorProcess = null;
+  inspectorUrl = null;
+  isReady = false;
+  proxyAuthToken = null;
+}
+function buildInspectorUrl(baseUrl, mcpServerUrl) {
+  const urlObj = new URL(baseUrl);
+  urlObj.searchParams.set("transport", "streamable-http");
+  urlObj.searchParams.set("serverUrl", mcpServerUrl);
+  if (proxyAuthToken) {
+    urlObj.searchParams.set("MCP_PROXY_AUTH_TOKEN", proxyAuthToken);
+  }
+  return urlObj.toString();
+}
+function extractProxyToken(text) {
+  const match = text.match(/Session token:\s+([a-f0-9]+)/i);
+  return match?.[1] ?? null;
+}
+function limitBuffer(buffer, maxSize) {
+  if (buffer.length <= maxSize) {
+    return buffer;
+  }
+  return buffer.slice(-maxSize);
+}
+function getInspectorClientPort() {
+  if (process.env.CLIENT_PORT) {
+    const port = Number.parseInt(process.env.CLIENT_PORT, 10);
+    if (!Number.isNaN(port) && port > 0 && port < 65536) {
+      return port;
+    }
+  }
+  if (process.env.MCP_INSPECTOR_PORT) {
+    const port = Number.parseInt(process.env.MCP_INSPECTOR_PORT, 10);
+    if (!Number.isNaN(port) && port > 0 && port < 65536) {
+      return port;
+    }
+  }
+  return INSPECTOR_DEFAULT_CLIENT_PORT;
+}
+function getInspectorServerPort() {
+  if (process.env.SERVER_PORT) {
+    const port = Number.parseInt(process.env.SERVER_PORT, 10);
+    if (!Number.isNaN(port) && port > 0 && port < 65536) {
+      return port;
+    }
+  }
+  return INSPECTOR_DEFAULT_SERVER_PORT;
+}
+function buildInspectorBaseUrl(port) {
+  return `http://localhost:${port}`;
+}
+function containsError(text) {
+  return ERROR_PATTERNS.some((pattern) => pattern.test(text));
+}
+async function waitForInspectorReady(url) {
+  for (let attempt = 0; attempt < HEALTH_CHECK_RETRIES; attempt++) {
+    try {
+      const controller = new AbortController();
+      const timeoutId = setTimeout(() => controller.abort(), HEALTH_CHECK_TIMEOUT);
+      const response = await fetch(url, {
+        method: "GET",
+        signal: controller.signal
+      });
+      clearTimeout(timeoutId);
+      if (response.status >= 200 && response.status < 400) {
+        if (!proxyAuthToken) {
+          const text = await response.text().catch(() => "");
+          const token = extractProxyToken(text);
+          if (token) {
+            proxyAuthToken = token;
+          }
+        }
+        return true;
+      }
+    } catch {
+      if (attempt < HEALTH_CHECK_RETRIES - 1) {
+        continue;
+      }
+    }
+  }
+  return false;
+}
+function cleanupListeners(process2, handlers) {
+  if (handlers.stdout && process2.stdout) {
+    process2.stdout.removeListener("data", handlers.stdout);
+  }
+  if (handlers.stderr && process2.stderr) {
+    process2.stderr.removeListener("data", handlers.stderr);
+  }
+  if (handlers.error) {
+    process2.removeListener("error", handlers.error);
+  }
+  if (handlers.exit) {
+    process2.removeListener("exit", handlers.exit);
+  }
+}
+async function launchMcpInspector(nuxt, options) {
+  if (inspectorProcess) {
+    return;
+  }
+  const mcpServerUrl = `http://localhost:${nuxt.options.devServer?.port || 3e3}${options.route || "/mcp"}`;
+  const inspectorClientPort = getInspectorClientPort();
+  const inspectorServerPort = getInspectorServerPort();
+  const inspectorBaseUrl = buildInspectorBaseUrl(inspectorClientPort);
+  log.info("\u{1F680} Launching MCP Inspector...");
+  try {
+    const env = {
+      ...globalThis.process.env,
+      MCP_AUTO_OPEN_ENABLED: "false",
+      CLIENT_PORT: String(inspectorClientPort),
+      SERVER_PORT: String(inspectorServerPort)
+    };
+    inspectorProcess = spawn("npx", [
+      "-y",
+      "@modelcontextprotocol/inspector",
+      "streamable-http",
+      mcpServerUrl
+    ], {
+      stdio: ["ignore", "pipe", "pipe"],
+      env
+    });
+    const childProcess = inspectorProcess;
+    let stdoutBuffer = "";
+    let stderrBuffer = "";
+    let isResolved = false;
+    let timeoutId = null;
+    await new Promise((res, rej) => {
+      const resolve = () => {
+        if (timeoutId) {
+          clearTimeout(timeoutId);
+        }
+        cleanupListeners(childProcess, handlers);
+        res();
+      };
+      const reject = (error) => {
+        if (timeoutId) {
+          clearTimeout(timeoutId);
+        }
+        cleanupListeners(childProcess, handlers);
+        resetState();
+        rej(error);
+      };
+      const handlers = {
+        stdout: (data) => {
+          const text = data.toString();
+          stdoutBuffer += text;
+          stdoutBuffer = limitBuffer(stdoutBuffer, MAX_BUFFER_SIZE);
+          if (!proxyAuthToken) {
+            const token = extractProxyToken(text);
+            if (token) {
+              proxyAuthToken = token;
+            }
+          }
+        },
+        stderr: (data) => {
+          const text = data.toString();
+          stderrBuffer += text;
+          stderrBuffer = limitBuffer(stderrBuffer, MAX_BUFFER_SIZE);
+          if (!proxyAuthToken) {
+            const token = extractProxyToken(text);
+            if (token) {
+              proxyAuthToken = token;
+            }
+          }
+          if (containsError(stderrBuffer) && !isResolved) {
+            isResolved = true;
+            log.error("\u274C MCP Inspector port is already in use");
+            handleError(
+              new Error("MCP Inspector port is already in use. Please stop any running Inspector instances."),
+              timeoutId,
+              reject
+            );
+          }
+        },
+        error: (error) => {
+          if (!isResolved) {
+            isResolved = true;
+            log.error(`\u274C Failed to start inspector process: ${error.message}`);
+            handleError(error, timeoutId, reject);
+          }
+        },
+        exit: (code) => {
+          if (!isResolved) {
+            isResolved = true;
+            const errorOutput = stderrBuffer || stdoutBuffer || "No output";
+            const lastLines = errorOutput.split("\n").slice(-10).join("\n");
+            const errorMessage = code !== 0 && code !== null ? `MCP Inspector exited with code ${code}. Last output:
+${lastLines}` : `MCP Inspector exited unexpectedly. Last output:
+${lastLines}`;
+            log.error(`\u274C Inspector process exited with code ${code ?? "null"}`);
+            handleError(new Error(errorMessage), timeoutId, reject);
+          }
+        }
+      };
+      childProcess.stdout?.on("data", handlers.stdout);
+      childProcess.stderr?.on("data", handlers.stderr);
+      childProcess.on("error", handlers.error);
+      childProcess.on("exit", handlers.exit);
+      const startHealthCheck = async () => {
+        for (let delay = 500; delay <= 3e3; delay += 500) {
+          await new Promise((res2) => setTimeout(res2, delay));
+          if (isResolved) {
+            return;
+          }
+          if (childProcess.killed || childProcess.exitCode !== null) {
+            if (!isResolved) {
+              isResolved = true;
+              const errorOutput = stderrBuffer || stdoutBuffer || "Process exited unexpectedly";
+              log.error(`\u274C Inspector process exited before health check (code: ${childProcess.exitCode})`);
+              handleError(
+                new Error(`MCP Inspector process exited before health check. Output:
+${errorOutput.slice(0, 500)}`),
+                timeoutId,
+                reject
+              );
+            }
+            return;
+          }
+          const isReady2 = await waitForInspectorReady(inspectorBaseUrl);
+          if (isReady2 && !isResolved) {
+            isResolved = true;
+            log.success(`\u2705 MCP Inspector is ready at ${inspectorBaseUrl}`);
+            handleUrlDetected(inspectorBaseUrl, mcpServerUrl, timeoutId, resolve);
+            return;
+          }
+        }
+        if (!isResolved) {
+          log.warn("\u26A0\uFE0F Inspector health check failed");
+        }
+      };
+      startHealthCheck().catch((error) => {
+        if (!isResolved) {
+          isResolved = true;
+          handleError(error, timeoutId, reject);
+        }
+      });
+      timeoutId = setTimeout(() => {
+        if (!isResolved) {
+          isResolved = true;
+          const errorOutput = stderrBuffer || stdoutBuffer || "Unknown error";
+          const lastLines = errorOutput.split("\n").slice(-10).join("\n");
+          log.error(`\u274C Inspector startup timeout after ${INSPECTOR_TIMEOUT}ms`);
+          handleError(
+            new Error(`MCP Inspector failed to start - timeout after ${INSPECTOR_TIMEOUT}ms.
+Last output:
+${lastLines}`),
+            null,
+            reject
+          );
+        }
+      }, INSPECTOR_TIMEOUT);
+    });
+  } catch (error) {
+    log.error("\u274C Failed to launch MCP Inspector:", error);
+    resetState();
+    throw error;
+  }
+}
+function handleUrlDetected(baseUrl, mcpServerUrl, timeoutId, resolve) {
+  if (timeoutId) {
+    clearTimeout(timeoutId);
+  }
+  const builtUrl = buildInspectorUrl(baseUrl, mcpServerUrl);
+  inspectorUrl = builtUrl;
+  isReady = true;
+  resolve();
+}
+function handleError(error, timeoutId, reject) {
+  if (timeoutId) {
+    clearTimeout(timeoutId);
+  }
+  reject(error);
+}
+function stopMcpInspector() {
+  if (inspectorProcess) {
+    inspectorProcess.kill();
+    resetState();
+  }
+}
+export function addDevToolsCustomTabs(nuxt, options) {
+  nuxt.hook("devtools:customTabs", (tabs) => {
+    if (!options.enabled) {
+      return;
+    }
+    tabs.push({
+      category: "server",
+      name: "mcp-inspector",
+      title: "MCP Inspector",
+      icon: "i-lucide-circuit-board",
+      view: isReady && inspectorUrl ? {
+        type: "iframe",
+        src: inspectorUrl
+      } : {
+        type: "launch",
+        description: "Launch MCP Inspector to test/debug your MCP server",
+        actions: [
+          {
+            label: promise ? "Starting..." : "Launch Inspector",
+            pending: !!promise,
+            handle() {
+              promise = promise || launchMcpInspector(nuxt, options).finally(() => {
+                promise = null;
+              });
+              return promise;
+            }
+          },
+          ...inspectorProcess ? [{
+            label: "Stop Inspector",
+            handle() {
+              stopMcpInspector();
+              promise = null;
+            }
+          }] : []
+        ]
+      }
+    });
+  });
+  nuxt.hook("close", () => {
+    stopMcpInspector();
+  });
+}

package/dist/runtime/server/mcp/handler.d.ts

@@ -0,0 +1,2 @@
+declare const _default: import("h3").EventHandler<import("h3").EventHandlerRequest, Promise<void>>;
+export default _default;

package/dist/runtime/server/mcp/handler.js

@@ -0,0 +1,37 @@
+import { getRouterParam } from "h3";
+import { useRuntimeConfig } from "#imports";
+import { tools } from "#nuxt-mcp/tools.mjs";
+import { resources } from "#nuxt-mcp/resources.mjs";
+import { prompts } from "#nuxt-mcp/prompts.mjs";
+import { handlers } from "#nuxt-mcp/handlers.mjs";
+import { createMcpHandler } from "./utils.js";
+import { getMcpConfig } from "./config.js";
+export default createMcpHandler((event) => {
+  const runtimeConfig = useRuntimeConfig(event).mcp;
+  const config = getMcpConfig(runtimeConfig);
+  const handlerName = getRouterParam(event, "handler");
+  if (handlerName) {
+    const handlerDef = handlers.find(
+      (h) => h.name === handlerName
+    );
+    if (!handlerDef) {
+      throw new Error(`Handler "${handlerName}" not found`);
+    }
+    return {
+      name: handlerDef.name,
+      version: handlerDef.version ?? config.version,
+      browserRedirect: handlerDef.browserRedirect ?? config.browserRedirect,
+      tools: handlerDef.tools,
+      resources: handlerDef.resources,
+      prompts: handlerDef.prompts
+    };
+  }
+  return {
+    name: config.name || "MCP Server",
+    version: config.version,
+    browserRedirect: config.browserRedirect,
+    tools,
+    resources,
+    prompts
+  };
+});

package/dist/runtime/server/mcp/loaders/index.d.ts

@@ -0,0 +1,28 @@
+import { type LoadResult } from './utils.js';
+export interface LoaderPaths {
+    tools: string[];
+    resources: string[];
+    prompts: string[];
+    handlers?: string[];
+}
+export interface HandlerRouteInfo {
+    name: string;
+    route?: string;
+}
+declare function loadHandlers(paths?: string[]): Promise<LoadResult>;
+export declare function loadTools(paths: string[]): Promise<LoadResult>;
+export declare function loadResources(paths: string[]): Promise<LoadResult>;
+export declare function loadPrompts(paths: string[]): Promise<LoadResult>;
+export { loadHandlers };
+export declare function loadAllDefinitions(paths: LoaderPaths): Promise<{
+    total: number;
+    tools: LoadResult;
+    resources: LoadResult;
+    prompts: LoadResult;
+    handlers: LoadResult;
+}>;
+/**
+ * Get handler route information from loaded handlers
+ * This is used at runtime to identify handlers by their routes
+ */
+export declare function getHandlerRoutes(): Promise<HandlerRouteInfo[]>;