@nuxtjs/mcp-toolkit 0.2.0 → 0.4.0

package/dist/module.json

@@ -1,6 +1,6 @@
 {
   "name": "@nuxtjs/mcp-toolkit",
-  "version": "0.2.0",
+  "version": "0.4.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.2.0";
+const version = "0.4.0";
 
 const log = logger.withTag("@nuxtjs/mcp-toolkit");
 const { resolve } = createResolver(import.meta.url);
@@ -87,24 +87,17 @@ const module$1 = defineNuxtModule({
     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"));
+    const mcpDefinitionsPath = resolver.resolve("runtime/server/mcp/definitions");
     addServerImports([
-      {
-        name: "defineMcpTool",
-        from: resolver.resolve("runtime/server/mcp/definitions")
-      },
-      {
-        name: "defineMcpResource",
-        from: resolver.resolve("runtime/server/mcp/definitions")
-      },
-      {
-        name: "defineMcpPrompt",
-        from: resolver.resolve("runtime/server/mcp/definitions")
-      },
-      {
-        name: "defineMcpHandler",
-        from: resolver.resolve("runtime/server/mcp/definitions")
-      }
-    ]);
+      "defineMcpTool",
+      "defineMcpResource",
+      "defineMcpPrompt",
+      "defineMcpHandler",
+      "textResult",
+      "jsonResult",
+      "errorResult",
+      "imageResult"
+    ].map((name2) => ({ name: name2, from: mcpDefinitionsPath })));
     addServerHandler({
       route: options.route,
       handler: resolver.resolve("runtime/server/mcp/handler")

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

@@ -0,0 +1,39 @@
+/**
+ * Cache duration strings supported by the `ms` package
+ */
+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>);
+/**
+ * Base cache options using Nitro's caching system
+ * @see https://nitro.build/guide/cache#options
+ */
+export interface McpCacheOptions<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 by default) */
+    name?: string;
+    /** Function to generate cache key */
+    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 McpCache<Args = unknown> = MsCacheDuration | number | McpCacheOptions<Args>;
+/**
+ * Parse cache duration to milliseconds
+ */
+export declare function parseCacheDuration(duration: MsCacheDuration | number): number;
+/**
+ * Create cache options from McpCache config
+ */
+export declare function createCacheOptions<Args>(cache: McpCache<Args>, name: string, defaultGetKey?: (args: Args) => string): Record<string, unknown>;
+/**
+ * Wrap a function with caching
+ */
+export declare function wrapWithCache<T extends (...args: unknown[]) => unknown>(fn: T, cacheOptions: Record<string, unknown>): T;

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

@@ -0,0 +1,35 @@
+import { defineCachedFunction } from "nitropack/runtime";
+import ms from "ms";
+export 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 createCacheOptions(cache, name, defaultGetKey) {
+  if (typeof cache === "object") {
+    return {
+      getKey: defaultGetKey,
+      ...cache,
+      maxAge: parseCacheDuration(cache.maxAge),
+      name: cache.name ?? name,
+      group: cache.group ?? "mcp"
+    };
+  }
+  return {
+    maxAge: parseCacheDuration(cache),
+    name,
+    group: "mcp",
+    getKey: defaultGetKey
+  };
+}
+export function wrapWithCache(fn, cacheOptions) {
+  return defineCachedFunction(
+    fn,
+    cacheOptions
+  );
+}

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/index.d.ts

@@ -1,4 +1,6 @@
+export * from './cache.js';
 export * from './tools.js';
 export * from './resources.js';
 export * from './prompts.js';
 export * from './handlers.js';
+export * from './results.js';

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

@@ -1,4 +1,6 @@
+export * from "./cache.js";
 export * from "./tools.js";
 export * from "./resources.js";
 export * from "./prompts.js";
 export * from "./handlers.js";
+export * from "./results.js";

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

@@ -20,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

@@ -1,4 +1,7 @@
 import type { McpServer, ResourceTemplate, ReadResourceCallback, ReadResourceTemplateCallback, ResourceMetadata } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { type McpCacheOptions, type McpCache } from './cache.js';
+export type McpResourceCacheOptions = McpCacheOptions<URL>;
+export type McpResourceCache = McpCache<URL>;
 /**
  * Annotations for a resource
  * @see https://modelcontextprotocol.io/specification/2025-06-18/server/resources#annotations
@@ -23,6 +26,14 @@ export interface StandardMcpResourceDefinition {
     _meta?: Record<string, unknown>;
     handler: ReadResourceCallback | ReadResourceTemplateCallback;
     file?: never;
+    /**
+     * Cache configuration for the resource 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?: McpResourceCache;
 }
 /**
  * Definition of a file-based MCP resource
@@ -42,6 +53,14 @@ export interface FileMcpResourceDefinition {
      * Relative to the project root
      */
     file: string;
+    /**
+     * Cache configuration for the resource 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?: McpResourceCache;
 }
 /**
  * Definition of an MCP resource matching the SDK's registerResource signature
@@ -50,80 +69,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
- *
- * This function matches the structure of server.registerResource() from the MCP SDK.
+ * Define an MCP resource 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/resources/my-resource.ts
- * export default defineMcpResource({
- *   name: 'readme',
- *   title: 'README',
- *   description: 'Project README file',
- *   uri: 'file:///project/README.md',
- *   metadata: {
- *     mimeType: 'text/markdown'
- *   },
- *   handler: async (uri) => {
- *     const content = await readFile(uri.pathname, 'utf-8')
- *     return {
- *       contents: [{
- *         uri: uri.toString(),
- *         mimeType: 'text/markdown',
- *         text: content
- *       }]
- *     }
- *   }
- * })
- * ```
+ * @see https://mcp-toolkit.nuxt.dev/core-concepts/resources
  *
  * @example
  * ```ts
- * // Simpler file-based resource
+ * // File-based resource
  * export default defineMcpResource({
- *   name: 'readme',
  *   description: 'Project README file',
- *   file: 'README.md', // Automatically handles reading file and setting URI
- * })
- * ```
- *
- * @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
- *       }]
- *     }
- *   }
+ *   file: 'README.md'
  * })
  * ```
  */

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

@@ -2,6 +2,7 @@ import { readFile } from "node:fs/promises";
 import { resolve, extname } from "node:path";
 import { pathToFileURL } from "node:url";
 import { enrichNameTitle } from "./utils.js";
+import { createCacheOptions, wrapWithCache } from "./cache.js";
 function getMimeType(filePath) {
   const ext = extname(filePath).toLowerCase();
   switch (ext) {
@@ -74,6 +75,14 @@ export function registerResourceFromDefinition(server, resource) {
   if (!handler) {
     throw new Error(`Resource ${name} is missing a handler`);
   }
+  if (resource.cache !== void 0) {
+    const defaultGetKey = (requestUri) => requestUri.pathname.replace(/\//g, "-").replace(/^-/, "");
+    const cacheOptions = createCacheOptions(resource.cache, `mcp-resource:${name}`, defaultGetKey);
+    handler = wrapWithCache(
+      handler,
+      cacheOptions
+    );
+  }
   if (typeof uri === "string") {
     return server.registerResource(
       name,

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

@@ -0,0 +1,55 @@
+import type { CallToolResult } from '@modelcontextprotocol/sdk/types.js';
+/**
+ * Create a text result for an MCP tool response.
+ *
+ * @example
+ * ```ts
+ * export default defineMcpTool({
+ *   handler: async () => textResult('Hello world')
+ * })
+ * ```
+ */
+export declare function textResult(text: string): CallToolResult;
+/**
+ * Create a JSON result for an MCP tool response.
+ * Automatically stringifies the data.
+ *
+ * @param data - The data to serialize as JSON
+ * @param pretty - Whether to pretty-print the JSON (default: true)
+ *
+ * @example
+ * ```ts
+ * export default defineMcpTool({
+ *   handler: async () => jsonResult({ foo: 'bar', count: 42 })
+ * })
+ * ```
+ */
+export declare function jsonResult(data: unknown, pretty?: boolean): CallToolResult;
+/**
+ * Create an error result for an MCP tool response.
+ *
+ * @example
+ * ```ts
+ * export default defineMcpTool({
+ *   handler: async () => {
+ *     if (!found) return errorResult('Resource not found')
+ *     return textResult('Success')
+ *   }
+ * })
+ * ```
+ */
+export declare function errorResult(message: string): CallToolResult;
+/**
+ * Create an image result for an MCP tool response.
+ *
+ * @param data - Base64-encoded image data
+ * @param mimeType - The MIME type of the image (e.g., 'image/png', 'image/jpeg')
+ *
+ * @example
+ * ```ts
+ * export default defineMcpTool({
+ *   handler: async () => imageResult(base64Data, 'image/png')
+ * })
+ * ```
+ */
+export declare function imageResult(data: string, mimeType: string): CallToolResult;

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

@@ -0,0 +1,13 @@
+export function textResult(text) {
+  return { content: [{ type: "text", text }] };
+}
+export function jsonResult(data, pretty = true) {
+  const text = pretty ? JSON.stringify(data, null, 2) : JSON.stringify(data);
+  return { content: [{ type: "text", text }] };
+}
+export function errorResult(message) {
+  return { content: [{ type: "text", text: message }], isError: true };
+}
+export function imageResult(data, mimeType) {
+  return { content: [{ type: "image", data, mimeType }] };
+}

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

@@ -3,13 +3,17 @@ import type { CallToolResult, ServerRequest, ServerNotification, ToolAnnotations
 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';
+export type { MsCacheDuration };
+export type McpToolCacheOptions<Args = unknown> = McpCacheOptions<Args>;
+export type McpToolCache<Args = unknown> = McpCache<Args>;
 /**
- * Callback type for MCP tools, matching the SDK's ToolCallback type
+ * 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>;
 /**
- * Definition of an MCP tool matching the SDK's registerTool signature
- * This structure is identical to what you'd pass to server.registerTool()
+ * 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;
@@ -20,45 +24,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,5 @@
 import { enrichNameTitle } from "./utils.js";
+import { createCacheOptions, wrapWithCache } from "./cache.js";
 export function registerToolFromDefinition(server, tool) {
   const { name, title } = enrichNameTitle({
     name: tool.name,
@@ -6,6 +7,18 @@ 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 = createCacheOptions(tool.cache, `mcp-tool:${name}`, defaultGetKey);
+    handler = wrapWithCache(
+      tool.handler,
+      cacheOptions
+    );
+  }
   if (tool.inputSchema) {
     return server.registerTool(
       name,
@@ -17,7 +30,7 @@ export function registerToolFromDefinition(server, tool) {
         annotations: tool.annotations,
         _meta: tool._meta
       },
-      tool.handler
+      handler
     );
   } else {
     return server.registerTool(
@@ -29,7 +42,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.2.0",
+  "version": "0.4.0",
   "description": "Create MCP servers directly in your Nuxt application. Define tools, resources, and prompts with a simple and intuitive API.",
   "repository": {
     "type": "git",
@@ -38,6 +38,7 @@
     "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"