@nuxtjs/mcp-toolkit 0.1.1 → 0.3.0

package/README.md

@@ -39,20 +39,18 @@ Or install manually:
 
 ```bash
 # npm
-npm install -D @nuxtjs/mcp-toolkit zod@^3
+npm install -D @nuxtjs/mcp-toolkit zod
 
 # yarn
-yarn add -D @nuxtjs/mcp-toolkit zod@^3
+yarn add -D @nuxtjs/mcp-toolkit zod
 
 # pnpm
-pnpm add -D @nuxtjs/mcp-toolkit zod@^3
+pnpm add -D @nuxtjs/mcp-toolkit zod
 
 # bun
-bun add -D @nuxtjs/mcp-toolkit zod@^3
+bun add -D @nuxtjs/mcp-toolkit zod
 ```
 
-> **Note:** Zod v3 is required. Zod v4 is not yet compatible with the MCP SDK.
-
 <!-- /automd -->
 
 ## 📖 Quick Start

package/dist/module.json

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

package/dist/module.mjs

@@ -6,7 +6,7 @@ import { ROUTES } from '../dist/runtime/server/mcp/constants.js';
 import { addDevToolsCustomTabs } from '../dist/runtime/server/mcp/devtools/index.js';
 
 const name = "@nuxtjs/mcp-toolkit";
-const version = "0.1.1";
+const version = "0.3.0";
 
 const log = logger.withTag("@nuxtjs/mcp-toolkit");
 const { resolve } = createResolver(import.meta.url);

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

@@ -1,6 +1,10 @@
 import type { McpToolDefinition } from './tools.js';
 import type { McpResourceDefinition } from './resources.js';
 import type { McpPromptDefinition } from './prompts.js';
+/**
+ * Options for defining a custom MCP handler
+ * @see https://mcp-toolkit.nuxt.dev/core-concepts/handlers
+ */
 export interface McpHandlerOptions {
     name: string;
     version?: string;
@@ -15,4 +19,18 @@ export interface McpHandlerDefinition extends Required<Omit<McpHandlerOptions, '
     resources: McpResourceDefinition[];
     prompts: McpPromptDefinition[];
 }
+/**
+ * Define a custom MCP handler with specific tools, resources, and prompts.
+ *
+ * @see https://mcp-toolkit.nuxt.dev/core-concepts/handlers
+ *
+ * @example
+ * ```ts
+ * export default defineMcpHandler({
+ *   name: 'my-handler',
+ *   tools: [myTool],
+ *   resources: [myResource]
+ * })
+ * ```
+ */
 export declare function defineMcpHandler(options: McpHandlerOptions): McpHandlerOptions;

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

@@ -1,11 +1,12 @@
-import type { z, ZodTypeAny, ZodRawShape } from 'zod';
+import type { ZodRawShape } from 'zod';
 import type { GetPromptResult, 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';
 /**
  * Callback type for MCP prompts, matching the SDK's PromptCallback type
  */
-export type McpPromptCallback<Args extends ZodRawShape | undefined = undefined> = Args extends ZodRawShape ? (args: z.objectOutputType<Args, ZodTypeAny>, extra: RequestHandlerExtra<ServerRequest, ServerNotification>) => GetPromptResult | Promise<GetPromptResult> : (extra: RequestHandlerExtra<ServerRequest, ServerNotification>) => GetPromptResult | Promise<GetPromptResult>;
+export type McpPromptCallback<Args extends ZodRawShape | undefined = undefined> = Args extends ZodRawShape ? (args: ShapeOutput<Args>, extra: RequestHandlerExtra<ServerRequest, ServerNotification>) => GetPromptResult | Promise<GetPromptResult> : (extra: RequestHandlerExtra<ServerRequest, ServerNotification>) => GetPromptResult | Promise<GetPromptResult>;
 /**
  * Definition of an MCP prompt
  * Uses `inputSchema` for consistency with tools, which is mapped to `argsSchema` when registering with the SDK
@@ -19,60 +20,24 @@ export interface McpPromptDefinition<Args extends ZodRawShape | undefined = unde
     handler: McpPromptCallback<Args>;
 }
 /**
- * Helper function to register a prompt from a McpPromptDefinition
+ * Register a prompt from a McpPromptDefinition
+ * @internal
  */
 export declare function registerPromptFromDefinition<Args extends ZodRawShape | undefined = undefined>(server: McpServer, prompt: McpPromptDefinition<Args>): import("@modelcontextprotocol/sdk/server/mcp.js").RegisteredPrompt;
 /**
- * Define an MCP prompt that will be automatically registered
+ * Define an MCP prompt that will be automatically registered.
  *
- * 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'`).
+ * `name` and `title` are auto-generated from filename if not provided.
  *
- * @example
- * ```ts
- * // server/mcp/prompts/my-prompt.ts
- * import { z } from 'zod'
- *
- * export default defineMcpPrompt({
- *   name: 'summarize',
- *   title: 'Text Summarizer',
- *   description: 'Summarize any text using an LLM',
- *   inputSchema: {
- *     text: z.string().describe('The text to summarize'),
- *     maxLength: z.string().optional().describe('Maximum length of summary')
- *   },
- *   handler: async ({ text, maxLength }) => {
- *     const summary = await summarizeText(text, maxLength ? parseInt(maxLength) : undefined)
- *     return {
- *       messages: [{
- *         role: 'user',
- *         content: {
- *           type: 'text',
- *           text: summary
- *         }
- *       }]
- *     }
- *   }
- * })
- * ```
+ * @see https://mcp-toolkit.nuxt.dev/core-concepts/prompts
  *
  * @example
  * ```ts
- * // Simple prompt without arguments
  * export default defineMcpPrompt({
- *   name: 'greeting',
  *   description: 'Generate a greeting message',
- *   handler: async () => {
- *     return {
- *       messages: [{
- *         role: 'user',
- *         content: {
- *           type: 'text',
- *           text: 'Hello! How can I help you today?'
- *         }
- *       }]
- *     }
- *   }
+ *   handler: async () => ({
+ *     messages: [{ role: 'user', content: { type: 'text', text: 'Hello!' } }]
+ *   })
  * })
  * ```
  */

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

@@ -15,6 +15,7 @@ export interface McpResourceAnnotations {
 export interface StandardMcpResourceDefinition {
     name?: string;
     title?: string;
+    description?: string;
     uri: string | ResourceTemplate;
     metadata?: ResourceMetadata & {
         annotations?: McpResourceAnnotations;
@@ -29,6 +30,7 @@ export interface StandardMcpResourceDefinition {
 export interface FileMcpResourceDefinition {
     name?: string;
     title?: string;
+    description?: string;
     uri?: string;
     metadata?: ResourceMetadata & {
         annotations?: McpResourceAnnotations;
@@ -48,82 +50,23 @@ export interface FileMcpResourceDefinition {
  */
 export type McpResourceDefinition = StandardMcpResourceDefinition | FileMcpResourceDefinition;
 /**
- * Helper function to register a resource from a McpResourceDefinition
+ * Register a resource from a McpResourceDefinition
+ * @internal
  */
 export declare function registerResourceFromDefinition(server: McpServer, resource: McpResourceDefinition): import("@modelcontextprotocol/sdk/server/mcp.js").RegisteredResource | import("@modelcontextprotocol/sdk/server/mcp.js").RegisteredResourceTemplate;
 /**
- * Define an MCP resource that will be automatically registered
+ * Define an MCP resource that will be automatically registered.
  *
- * This function matches the structure of server.registerResource() from the MCP SDK.
+ * `name` and `title` are auto-generated from filename if not provided.
  *
- * 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'`).
+ * @see https://mcp-toolkit.nuxt.dev/core-concepts/resources
  *
  * @example
  * ```ts
- * // server/mcp/resources/my-resource.ts
+ * // File-based resource
  * export default defineMcpResource({
- *   name: 'readme',
- *   title: 'README',
- *   uri: 'file:///project/README.md',
- *   metadata: {
- *     description: 'Project README file',
- *     mimeType: 'text/markdown'
- *   },
- *   handler: async (uri) => {
- *     const content = await readFile(uri.pathname, 'utf-8')
- *     return {
- *       contents: [{
- *         uri: uri.toString(),
- *         mimeType: 'text/markdown',
- *         text: content
- *       }]
- *     }
- *   }
- * })
- * ```
- *
- * @example
- * ```ts
- * // Simpler file-based resource
- * export default defineMcpResource({
- *   name: 'readme',
- *   file: 'README.md', // Automatically handles reading file and setting URI
- *   metadata: {
- *     description: 'Project README file'
- *   }
- * })
- * ```
- *
- * @example
- * ```ts
- * // Dynamic resource with template
- * import { ResourceTemplate } from '@modelcontextprotocol/sdk/server/mcp.js'
- *
- * export default defineMcpResource({
- *   name: 'file',
- *   title: 'File Resource',
- *   uri: new ResourceTemplate('file:///project/{+path}', {
- *     list: async () => {
- *       return {
- *         resources: [
- *           { uri: 'file:///project/README.md', name: 'README.md' },
- *           { uri: 'file:///project/src/index.ts', name: 'index.ts' }
- *         ]
- *       }
- *     }
- *   }),
- *   handler: async (uri, variables) => {
- *     const path = variables.path
- *     const content = await readFile(path, 'utf-8')
- *     return {
- *       contents: [{
- *         uri: uri.toString(),
- *         mimeType: 'text/plain',
- *         text: content
- *       }]
- *     }
- *   }
+ *   description: 'Project README file',
+ *   file: 'README.md'
  * })
  * ```
  */

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

@@ -43,7 +43,8 @@ export function registerResourceFromDefinition(server, resource) {
   let handler = resource.handler;
   const metadata = {
     ...resource.metadata,
-    title: resource.title || resource.metadata?.title || title
+    title: resource.title || resource.metadata?.title || title,
+    description: resource.description || resource.metadata?.description
   };
   if ("file" in resource && resource.file) {
     const filePath = resolve(process.cwd(), resource.file);

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

@@ -1,14 +1,42 @@
-import type { z, ZodRawShape, ZodTypeAny } from 'zod';
+import type { ZodRawShape } 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';
+import type { ShapeOutput } from '@modelcontextprotocol/sdk/server/zod-compat.js';
 /**
- * Callback type for MCP tools, matching the SDK's ToolCallback type
+ * Cache duration strings supported by the `ms` package
  */
-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>;
+export type MsCacheDuration = '1s' | '5s' | '10s' | '15s' | '30s' | '45s' | '1m' | '2m' | '5m' | '10m' | '15m' | '30m' | '45m' | '1h' | '2h' | '3h' | '4h' | '6h' | '8h' | '12h' | '24h' | '1d' | '2d' | '3d' | '7d' | '14d' | '30d' | '1w' | '2w' | '4w' | '1 second' | '1 minute' | '1 hour' | '1 day' | '1 week' | '2 seconds' | '5 seconds' | '10 seconds' | '30 seconds' | '2 minutes' | '5 minutes' | '10 minutes' | '15 minutes' | '30 minutes' | '2 hours' | '3 hours' | '6 hours' | '12 hours' | '24 hours' | '2 days' | '3 days' | '7 days' | '14 days' | '30 days' | '2 weeks' | '4 weeks' | (string & Record<never, never>);
 /**
- * Definition of an MCP tool matching the SDK's registerTool signature
- * This structure is identical to what you'd pass to server.registerTool()
+ * Cache options for MCP tools using Nitro's caching system
+ * @see https://nitro.build/guide/cache#options
+ */
+export interface McpToolCacheOptions<Args = unknown> {
+    /** Cache duration as string (e.g. '1h') or milliseconds (required) */
+    maxAge: MsCacheDuration | number;
+    /** Duration for stale-while-revalidate */
+    staleMaxAge?: number;
+    /** Cache name (auto-generated from tool name by default) */
+    name?: string;
+    /** Function to generate cache key from arguments */
+    getKey?: (args: Args) => string;
+    /** Cache group (default: 'mcp') */
+    group?: string;
+    /** Enable stale-while-revalidate behavior */
+    swr?: boolean;
+}
+/**
+ * Cache configuration: string duration, milliseconds, or full options
+ * @see https://nitro.build/guide/cache#options
+ */
+export type McpToolCache<Args = unknown> = MsCacheDuration | number | McpToolCacheOptions<Args>;
+/**
+ * Handler callback type for MCP tools
+ */
+export type McpToolCallback<Args extends ZodRawShape | undefined = ZodRawShape> = Args extends ZodRawShape ? (args: ShapeOutput<Args>, extra: RequestHandlerExtra<ServerRequest, ServerNotification>) => CallToolResult | Promise<CallToolResult> : (extra: RequestHandlerExtra<ServerRequest, ServerNotification>) => CallToolResult | Promise<CallToolResult>;
+/**
+ * MCP tool definition structure
+ * @see https://mcp-toolkit.nuxt.dev/core-concepts/tools
  */
 export interface McpToolDefinition<InputSchema extends ZodRawShape | undefined = ZodRawShape, OutputSchema extends ZodRawShape = ZodRawShape> {
     name?: string;
@@ -19,45 +47,36 @@ export interface McpToolDefinition<InputSchema extends ZodRawShape | undefined =
     annotations?: ToolAnnotations;
     _meta?: Record<string, unknown>;
     handler: McpToolCallback<InputSchema>;
+    /**
+     * Cache configuration for the tool response
+     * - string: Duration parsed by `ms` (e.g., '1h', '2 days', '30m')
+     * - number: Duration in milliseconds
+     * - object: Full cache options with getKey, group, swr, etc.
+     * @see https://nitro.build/guide/cache#options
+     */
+    cache?: McpToolCache<InputSchema extends ZodRawShape ? ShapeOutput<InputSchema> : undefined>;
 }
 /**
- * Helper function to register a tool from a McpToolDefinition
- * This provides better type inference when registering tools
+ * Register a tool from a McpToolDefinition
+ * @internal
  */
 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
+ * 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.
+ * `name` and `title` are auto-generated from filename if not provided.
  *
- * 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'`).
+ * @see https://mcp-toolkit.nuxt.dev/core-concepts/tools
  *
  * @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
- *     }
- *   }
+ *   description: 'Echo back a message',
+ *   inputSchema: { message: z.string() },
+ *   cache: '1h', // optional caching
+ *   handler: async ({ message }) => ({
+ *     content: [{ type: 'text', text: message }]
+ *   })
  * })
  * ```
  */

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

@@ -1,4 +1,16 @@
+import { defineCachedFunction } from "nitropack/runtime";
 import { enrichNameTitle } from "./utils.js";
+import ms from "ms";
+function parseCacheDuration(duration) {
+  if (typeof duration === "number") {
+    return duration;
+  }
+  const parsed = ms(duration);
+  if (parsed === void 0) {
+    throw new Error(`Invalid cache duration: ${duration}`);
+  }
+  return parsed;
+}
 export function registerToolFromDefinition(server, tool) {
   const { name, title } = enrichNameTitle({
     name: tool.name,
@@ -6,6 +18,29 @@ export function registerToolFromDefinition(server, tool) {
     _meta: tool._meta,
     type: "tool"
   });
+  let handler = tool.handler;
+  if (tool.cache !== void 0) {
+    const defaultGetKey = tool.inputSchema ? (args) => {
+      const values = Object.values(args);
+      return values.map((v) => String(v).replace(/\//g, "-").replace(/^-/, "")).join(":");
+    } : void 0;
+    const cacheOptions = typeof tool.cache === "object" ? {
+      getKey: defaultGetKey,
+      ...tool.cache,
+      maxAge: parseCacheDuration(tool.cache.maxAge),
+      name: tool.cache.name ?? `mcp-tool:${name}`,
+      group: tool.cache.group ?? "mcp"
+    } : {
+      maxAge: parseCacheDuration(tool.cache),
+      name: `mcp-tool:${name}`,
+      group: "mcp",
+      getKey: defaultGetKey
+    };
+    handler = defineCachedFunction(
+      tool.handler,
+      cacheOptions
+    );
+  }
   if (tool.inputSchema) {
     return server.registerTool(
       name,
@@ -17,7 +52,7 @@ export function registerToolFromDefinition(server, tool) {
         annotations: tool.annotations,
         _meta: tool._meta
       },
-      tool.handler
+      handler
     );
   } else {
     return server.registerTool(
@@ -29,7 +64,7 @@ export function registerToolFromDefinition(server, tool) {
         annotations: tool.annotations,
         _meta: tool._meta
       },
-      tool.handler
+      handler
     );
   }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nuxtjs/mcp-toolkit",
-  "version": "0.1.1",
+  "version": "0.3.0",
   "description": "Create MCP servers directly in your Nuxt application. Define tools, resources, and prompts with a simple and intuitive API.",
   "repository": {
     "type": "git",
@@ -33,17 +33,18 @@
   ],
   "dependencies": {
     "@clack/prompts": "^0.11.0",
-    "@modelcontextprotocol/sdk": "^1.22.0",
+    "@modelcontextprotocol/sdk": "^1.23.0",
     "@nuxt/kit": "^4.2.1",
     "automd": "^0.4.2",
     "chokidar": "^4.0.3",
     "defu": "^6.1.4",
+    "ms": "^2.1.3",
     "pathe": "^2.0.3",
     "scule": "^1.3.0",
     "tinyglobby": "^0.2.15"
   },
   "peerDependencies": {
-    "zod": "^3.25.76"
+    "zod": "^4.1.13"
   },
   "peerDependenciesMeta": {
     "zod": {