@nuxtjs/mcp-toolkit 0.6.4 → 0.8.0

package/dist/module.d.mts

@@ -35,6 +35,23 @@ interface ModuleOptions {
      * @default 'mcp'
      */
     dir?: string;
+    /**
+     * Enable MCP session management (stateful transport).
+     * When enabled, the server assigns session IDs and maintains state across requests,
+     * enabling SSE streaming, server-to-client notifications, and resumability.
+     *
+     * Pass `true` for defaults or an object to configure session behavior.
+     * @default false
+     * @see https://modelcontextprotocol.io/specification/2025-11-25/basic/transports#session-management
+     */
+    sessions?: boolean | {
+        enabled?: boolean;
+        /**
+         * Maximum session duration in milliseconds. Sessions inactive longer than this are cleaned up.
+         * @default 1800000 (30 minutes)
+         */
+        maxDuration?: number;
+    };
 }
 declare const _default: _nuxt_schema.NuxtModule<ModuleOptions, ModuleOptions, false>;
 

package/dist/module.json

@@ -1,6 +1,6 @@
 {
   "name": "@nuxtjs/mcp-toolkit",
-  "version": "0.6.4",
+  "version": "0.8.0",
   "configKey": "mcp",
   "docs": "https://mcp-toolkit.nuxt.dev/getting-started/installation",
   "mcp": "https://mcp-toolkit.nuxt.dev/mcp",

package/dist/module.mjs

@@ -72,7 +72,7 @@ function generateDeeplinkUrl(baseUrl, route, ide, serverName) {
 }
 
 const name = "@nuxtjs/mcp-toolkit";
-const version = "0.6.4";
+const version = "0.8.0";
 
 const log = logger.withTag("@nuxtjs/mcp-toolkit");
 const { resolve } = createResolver(import.meta.url);
@@ -86,11 +86,15 @@ const module$1 = defineNuxtModule({
   },
   defaults: defaultMcpConfig,
   async setup(options, nuxt) {
-    if (nuxt.options.nitro.static || nuxt.options._generate) {
+    const nitroOptions = nuxt.options.nitro;
+    if (nitroOptions?.static || nuxt.options._generate) {
       log.warn("@nuxtjs/mcp-toolkit is not compatible with `nuxt generate` as it needs a server to run.");
       return;
     }
     const resolver = createResolver(import.meta.url);
+    if (typeof options.sessions === "boolean") {
+      options.sessions = { enabled: options.sessions };
+    }
     const mcpConfig = getMcpConfig(options);
     if (!options.enabled) {
       return;
@@ -113,7 +117,8 @@ const module$1 = defineNuxtModule({
     let mcpSummary = null;
     nuxt.hook("modules:done", async () => {
       try {
-        await nuxt.callHook("mcp:definitions:paths", paths);
+        const callCustomHook = nuxt.callHook;
+        await callCustomHook("mcp:definitions:paths", paths);
         const result = await loadAllDefinitions(paths);
         if (result.handlers && result.handlers.count > 0) {
           addServerHandler({
@@ -162,10 +167,12 @@ const module$1 = defineNuxtModule({
         path: resolver.resolve("runtime/server/types.server.d.ts")
       });
     });
-    nuxt.options.nitro.typescript ??= {};
-    nuxt.options.nitro.typescript.tsConfig ??= {};
-    nuxt.options.nitro.typescript.tsConfig.include ??= [];
-    nuxt.options.nitro.typescript.tsConfig.include.push(resolver.resolve("runtime/server/types.server.d.ts"));
+    if (nitroOptions) {
+      nitroOptions.typescript ??= {};
+      nitroOptions.typescript.tsConfig ??= {};
+      nitroOptions.typescript.tsConfig.include ??= [];
+      nitroOptions.typescript.tsConfig.include.push(resolver.resolve("runtime/server/types.server.d.ts"));
+    }
     let isCloudflare = false;
     if (!nuxt.options.dev) {
       nuxt.hook("nitro:config", (nitroConfig) => {

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

@@ -1,3 +1,7 @@
+export interface McpSessionsConfig {
+    enabled: boolean;
+    maxDuration: number;
+}
 export interface McpConfig {
     enabled: boolean;
     route: string;
@@ -5,6 +9,7 @@ export interface McpConfig {
     name: string;
     version: string;
     dir: string;
+    sessions: McpSessionsConfig;
 }
 export declare const defaultMcpConfig: McpConfig;
 export declare function getMcpConfig(partial?: Partial<McpConfig>): McpConfig;

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

@@ -5,7 +5,12 @@ export const defaultMcpConfig = {
   browserRedirect: "/",
   name: "",
   version: "1.0.0",
-  dir: "mcp"
+  dir: "mcp",
+  sessions: {
+    enabled: false,
+    maxDuration: 30 * 60 * 1e3
+    // 30 minutes
+  }
 };
 export function getMcpConfig(partial) {
   return defu(partial, defaultMcpConfig);

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

@@ -1,9 +1,27 @@
 import type { ZodRawShape } from 'zod';
-import type { CallToolResult, ServerRequest, ServerNotification, ToolAnnotations } from '@modelcontextprotocol/sdk/types.js';
+import type { CallToolResult, ServerRequest, ServerNotification } from '@modelcontextprotocol/sdk/types.js';
 import type { RequestHandlerExtra } from '@modelcontextprotocol/sdk/shared/protocol.js';
 import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import type { ShapeOutput } from '@modelcontextprotocol/sdk/server/zod-compat.js';
 import { type MsCacheDuration, type McpCacheOptions, type McpCache } from './cache.js';
+/**
+ * Hints that describe tool behavior to MCP clients.
+ *
+ * Clients may use these to decide whether to prompt the user for confirmation (human-in-the-loop).
+ * All properties are optional hints — they are not guaranteed to be respected by every client.
+ *
+ * @see https://modelcontextprotocol.io/docs/concepts/tools#tool-annotations
+ */
+export interface McpToolAnnotations {
+    /** If `true`, the tool does not modify any state (e.g. a read/search/lookup). Defaults to `false`. */
+    readOnlyHint?: boolean;
+    /** If `true`, the tool may perform destructive operations like deleting data. Only meaningful when `readOnlyHint` is `false`. Defaults to `true`. */
+    destructiveHint?: boolean;
+    /** If `true`, calling the tool multiple times with the same arguments has no additional effect beyond the first call. Only meaningful when `readOnlyHint` is `false`. Defaults to `false`. */
+    idempotentHint?: boolean;
+    /** If `true`, the tool may interact with the outside world (e.g. external APIs, the internet). If `false`, the tool only operates on local/internal data. Defaults to `true`. */
+    openWorldHint?: boolean;
+}
 export type { MsCacheDuration };
 export type McpToolCacheOptions<Args = unknown> = McpCacheOptions<Args>;
 export type McpToolCache<Args = unknown> = McpCache<Args>;
@@ -21,7 +39,8 @@ export interface McpToolDefinition<InputSchema extends ZodRawShape | undefined =
     description?: string;
     inputSchema?: InputSchema;
     outputSchema?: OutputSchema;
-    annotations?: ToolAnnotations;
+    annotations?: McpToolAnnotations;
+    inputExamples?: InputSchema extends ZodRawShape ? Partial<ShapeOutput<InputSchema>>[] : never;
     _meta?: Record<string, unknown>;
     handler: McpToolCallback<InputSchema>;
     /**

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

@@ -25,7 +25,10 @@ export function registerToolFromDefinition(server, tool) {
     inputSchema: tool.inputSchema,
     outputSchema: tool.outputSchema,
     annotations: tool.annotations,
-    _meta: tool._meta
+    _meta: {
+      ...tool._meta,
+      ...tool.inputExamples && { inputExamples: tool.inputExamples }
+    }
   };
   return server.registerTool(name, options, handler);
 }

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

@@ -120,7 +120,14 @@ async function launchMcpInspector(nuxt, options) {
   if (inspectorProcess) {
     return;
   }
-  const mcpServerUrl = `http://localhost:${nuxt.options.devServer?.port || 3e3}${options.route || "/mcp"}`;
+  const devServerUrl = nuxt.options.devServer?.url;
+  let mcpServerUrl;
+  if (devServerUrl) {
+    mcpServerUrl = `${devServerUrl.replace(/\/$/, "")}${options.route || "/mcp"}`;
+  } else {
+    const protocol = nuxt.options.devServer?.https ? "https" : "http";
+    mcpServerUrl = `${protocol}://localhost:${nuxt.options.devServer?.port || 3e3}${options.route || "/mcp"}`;
+  }
   const inspectorClientPort = getInspectorClientPort();
   const inspectorServerPort = getInspectorServerPort();
   const inspectorBaseUrl = buildInspectorBaseUrl(inspectorClientPort);
@@ -305,7 +312,9 @@ export function addDevToolsCustomTabs(nuxt, options) {
   if (!options.enabled) {
     return;
   }
-  nuxt.hook("devtools:customTabs", (tabs) => {
+  const registerCustomHook = nuxt.hook;
+  registerCustomHook("devtools:customTabs", (tabsArg) => {
+    const tabs = tabsArg;
     tabs.push({
       category: "server",
       name: "mcp-inspector",

package/dist/runtime/server/mcp/providers/cloudflare.js

@@ -6,7 +6,8 @@ const fallbackCtx = {
   passThroughOnException: () => {
   }
 };
-export default createMcpTransportHandler(async (server, event) => {
+export default createMcpTransportHandler(async (createServer, event) => {
+  const server = createServer();
   const { createMcpHandler } = await import("agents/mcp");
   const handler = createMcpHandler(server, {
     route: ""

package/dist/runtime/server/mcp/providers/node.js

@@ -1,13 +1,83 @@
 import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
-import { readBody } from "h3";
+import { randomUUID } from "uncrypto";
+import { readBody, getHeader, getMethod } from "h3";
+import config from "#nuxt-mcp-toolkit/config.mjs";
 import { createMcpTransportHandler } from "./types.js";
-export default createMcpTransportHandler(async (server, event) => {
-  const transport = new StreamableHTTPServerTransport({ sessionIdGenerator: void 0 });
-  event.node.res.on("close", () => {
-    transport.close();
-    server.close();
+const sessions = /* @__PURE__ */ new Map();
+let cleanupInterval = null;
+function ensureCleanup(maxDuration) {
+  if (cleanupInterval) return;
+  cleanupInterval = setInterval(() => {
+    const now = Date.now();
+    for (const [id, session] of sessions) {
+      if (now - session.lastAccessed > maxDuration) {
+        session.transport.close();
+        session.server.close();
+        sessions.delete(id);
+      }
+    }
+    if (sessions.size === 0 && cleanupInterval) {
+      clearInterval(cleanupInterval);
+      cleanupInterval = null;
+    }
+  }, 6e4);
+}
+export default createMcpTransportHandler(async (createServer, event) => {
+  const sessionsConfig = config.sessions;
+  const sessionsEnabled = sessionsConfig?.enabled ?? false;
+  if (!sessionsEnabled) {
+    const server2 = createServer();
+    const transport2 = new StreamableHTTPServerTransport({ sessionIdGenerator: void 0 });
+    event.node.res.on("close", () => {
+      transport2.close();
+      server2.close();
+    });
+    await server2.connect(transport2);
+    const body2 = await readBody(event);
+    await transport2.handleRequest(event.node.req, event.node.res, body2);
+    return;
+  }
+  const maxDuration = sessionsConfig?.maxDuration ?? 30 * 60 * 1e3;
+  const method = getMethod(event);
+  const sessionId = getHeader(event, "mcp-session-id");
+  if (sessionId) {
+    const session = sessions.get(sessionId);
+    if (!session) {
+      event.node.res.writeHead(404, { "Content-Type": "application/json" });
+      event.node.res.end(JSON.stringify({
+        jsonrpc: "2.0",
+        error: { code: -32001, message: "Session not found" },
+        id: null
+      }));
+      return;
+    }
+    session.lastAccessed = Date.now();
+    const body2 = method === "POST" ? await readBody(event) : void 0;
+    await session.transport.handleRequest(event.node.req, event.node.res, body2);
+    return;
+  }
+  const server = createServer();
+  let sessionStored = false;
+  const transport = new StreamableHTTPServerTransport({
+    sessionIdGenerator: () => randomUUID(),
+    onsessioninitialized: (id) => {
+      sessionStored = true;
+      sessions.set(id, { server, transport, lastAccessed: Date.now() });
+      ensureCleanup(maxDuration);
+    }
   });
+  transport.onclose = () => {
+    const sid = transport.sessionId;
+    if (sid && sessions.has(sid)) {
+      sessions.delete(sid);
+    }
+    server.close();
+  };
   await server.connect(transport);
   const body = await readBody(event);
   await transport.handleRequest(event.node.req, event.node.res, body);
+  if (!sessionStored) {
+    transport.close();
+    server.close();
+  }
 });

package/dist/runtime/server/mcp/providers/types.d.ts

@@ -1,4 +1,4 @@
 import type { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import type { H3Event } from 'h3';
-export type McpTransportHandler = (server: McpServer, event: H3Event) => Promise<Response | void> | Response | void;
+export type McpTransportHandler = (createServer: () => McpServer, event: H3Event) => Promise<Response | void> | Response | void;
 export declare const createMcpTransportHandler: (handler: McpTransportHandler) => McpTransportHandler;

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

@@ -1,6 +1,9 @@
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import type { H3Event } from 'h3';
-import type { McpToolDefinition, McpResourceDefinition, McpPromptDefinition, McpMiddleware } from './definitions/index.js';
+import type { McpMiddleware } from './definitions/handlers.js';
+import type { McpPromptDefinition } from './definitions/prompts.js';
+import type { McpResourceDefinition } from './definitions/resources.js';
+import type { McpToolDefinition } from './definitions/tools.js';
 export type { McpTransportHandler } from './providers/types.js';
 export { createMcpTransportHandler } from './providers/types.js';
 export interface ResolvedMcpConfig {

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

@@ -1,11 +1,24 @@
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { sendRedirect, getHeader, defineEventHandler } from "h3";
-import { registerToolFromDefinition, registerResourceFromDefinition, registerPromptFromDefinition } from "./definitions/index.js";
+import { registerPromptFromDefinition } from "./definitions/prompts.js";
+import { registerResourceFromDefinition } from "./definitions/resources.js";
+import { registerToolFromDefinition } from "./definitions/tools.js";
 import handleMcpRequest from "#nuxt-mcp-toolkit/transport.mjs";
 export { createMcpTransportHandler } from "./providers/types.js";
 function resolveConfig(config, event) {
   return typeof config === "function" ? config(event) : config;
 }
+function registerEmptyDefinitionFallbacks(server, config) {
+  if (!config.tools?.length) {
+    server.registerTool("__init__", {}, async () => ({ content: [] })).remove();
+  }
+  if (!config.resources?.length) {
+    server.registerResource("__init__", "noop://init", {}, async () => ({ contents: [] })).remove();
+  }
+  if (!config.prompts?.length) {
+    server.registerPrompt("__init__", {}, async () => ({ messages: [] })).remove();
+  }
+}
 export function createMcpServer(config) {
   const server = new McpServer({
     name: config.name,
@@ -20,6 +33,7 @@ export function createMcpServer(config) {
   for (const prompt of config.prompts || []) {
     registerPromptFromDefinition(server, prompt);
   }
+  registerEmptyDefinitionFallbacks(server, config);
   return server;
 }
 export function createMcpHandler(config) {
@@ -29,8 +43,7 @@ export function createMcpHandler(config) {
       return sendRedirect(event, resolvedConfig.browserRedirect);
     }
     const handler = async () => {
-      const server = createMcpServer(resolvedConfig);
-      return handleMcpRequest(server, event);
+      return handleMcpRequest(() => createMcpServer(resolvedConfig), event);
     };
     if (resolvedConfig.middleware) {
       let nextCalled = false;

package/dist/runtime/server/types/hooks.d.ts

@@ -3,6 +3,10 @@ declare module '@nuxt/schema' {
         /**
          * Add additional directories to scan for MCP definition files (tools, resources, prompts, handlers).
          * @param paths - Object containing arrays of directory paths for each definition type.
+         * @param paths.tools - Array of directory paths to scan for tool definitions.
+         * @param paths.resources - Array of directory paths to scan for resource definitions.
+         * @param paths.prompts - Array of directory paths to scan for prompt definitions.
+         * @param paths.handlers - Array of directory paths to scan for handler definitions.
          * @returns void | Promise<void>
          */
         'mcp:definitions:paths': (paths: {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nuxtjs/mcp-toolkit",
-  "version": "0.6.4",
+  "version": "0.8.0",
   "description": "Create MCP servers directly in your Nuxt application. Define tools, resources, and prompts with a simple and intuitive API.",
   "repository": {
     "type": "git",
@@ -39,20 +39,24 @@
     "dist"
   ],
   "dependencies": {
-    "@modelcontextprotocol/sdk": "^1.26.0",
-    "@nuxt/kit": "^4.3.1",
+    "@modelcontextprotocol/sdk": "^1.27.1",
+    "@nuxt/kit": "^4.4.2",
     "defu": "^6.1.4",
     "ms": "^2.1.3",
     "pathe": "^2.0.3",
-    "satori": "^0.19.1",
+    "satori": "^0.25.0",
     "scule": "^1.3.0",
     "tinyglobby": "^0.2.15"
   },
   "peerDependencies": {
+    "h3": "^1.15.6",
     "zod": "^4.1.13",
-    "agents": ">=0.4.0"
+    "agents": ">=0.7.6"
   },
   "peerDependenciesMeta": {
+    "h3": {
+      "optional": false
+    },
     "zod": {
       "optional": false
     },
@@ -61,18 +65,18 @@
     }
   },
   "devDependencies": {
-    "@nuxt/devtools": "^3.1.1",
-    "@nuxt/eslint-config": "^1.15.1",
+    "@nuxt/devtools": "^3.2.3",
+    "@nuxt/eslint-config": "^1.15.2",
     "@nuxt/module-builder": "^1.0.2",
-    "@nuxt/schema": "^4.3.1",
-    "@nuxt/test-utils": "^3.23.0",
+    "@nuxt/schema": "^4.4.2",
+    "@nuxt/test-utils": "^4.0.0",
     "@types/node": "latest",
     "changelogen": "^0.6.2",
-    "eslint": "^9.39.2",
-    "nuxt": "^4.3.1",
+    "eslint": "^9.39.4",
+    "nuxt": "^4.4.2",
     "typescript": "~5.9.3",
-    "vitest": "^4.0.18",
-    "vue-tsc": "^3.2.4"
+    "vitest": "^4.1.0",
+    "vue-tsc": "^3.2.5"
   },
   "publishConfig": {
     "access": "public"