@nuxtjs/mcp-toolkit 0.3.0 → 0.4.0

package/dist/module.json

@@ -1,6 +1,6 @@
 {
   "name": "@nuxtjs/mcp-toolkit",
-  "version": "0.3.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.3.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/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/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

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,33 +3,10 @@ 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';
-/**
- * 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>);
-/**
- * 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>;
+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>;
 /**
  * Handler callback type for MCP tools
  */

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

@@ -1,16 +1,5 @@
-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;
-}
+import { createCacheOptions, wrapWithCache } from "./cache.js";
 export function registerToolFromDefinition(server, tool) {
   const { name, title } = enrichNameTitle({
     name: tool.name,
@@ -24,19 +13,8 @@ export function registerToolFromDefinition(server, tool) {
       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(
+    const cacheOptions = createCacheOptions(tool.cache, `mcp-tool:${name}`, defaultGetKey);
+    handler = wrapWithCache(
       tool.handler,
       cacheOptions
     );

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nuxtjs/mcp-toolkit",
-  "version": "0.3.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",