@nuxtjs/mcp-toolkit 0.0.0 → 0.0.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 Vercel
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,133 @@
+![Nuxt MCP Toolkit](https://raw.githubusercontent.com/nuxt-modules/mcp-toolkit/main/assets/banner.jpg)
+
+# Nuxt MCP Toolkit
+
+<!-- automd:badges color="black" license name="@nuxtjs/mcp-toolkit" -->
+
+[![npm version](https://img.shields.io/npm/v/@nuxtjs/mcp-toolkit?color=black)](https://npmjs.com/package/@nuxtjs/mcp-toolkit)
+[![npm downloads](https://img.shields.io/npm/dm/@nuxtjs/mcp-toolkit?color=black)](https://npm.chart.dev/@nuxtjs/mcp-toolkit)
+[![license](https://img.shields.io/github/license/nuxt-modules/mcp-toolkit?color=black)](https://github.com/nuxt-modules/mcp-toolkit/blob/main/LICENSE)
+
+<!-- /automd -->
+
+A Nuxt module to easily create a [Model Context Protocol (MCP)](https://modelcontextprotocol.io) server directly in your Nuxt application. Define MCP tools, resources, and prompts with zero configuration - just create files and they're automatically discovered and registered.
+
+## ✨ Features
+
+<!-- automd:file src="../../.github/snippets/features.md" -->
+
+- 🎯 **Zero Configuration** - Automatic discovery of tools, resources, and prompts
+- 📦 **File-based** - Organize definitions in intuitive directory structures
+- 🚀 **Multiple Handlers** - Create multiple MCP endpoints in a single app
+- 🔍 **Built-in Inspector** - Visual debugging tool in Nuxt DevTools
+- 📝 **TypeScript First** - Full type safety with auto-imports
+- 🔒 **Zod Validation** - Built-in input/output validation
+
+<!-- /automd -->
+
+## 🚀 Installation
+
+<!-- automd:file src="../../.github/snippets/installation.md" -->
+
+Use `nuxt` to install the module automatically:
+
+```bash
+npx nuxt module add mcp-toolkit
+```
+
+Or install manually:
+
+```bash
+# npm
+npm install -D @nuxtjs/mcp-toolkit zod@^3
+
+# yarn
+yarn add -D @nuxtjs/mcp-toolkit zod@^3
+
+# pnpm
+pnpm add -D @nuxtjs/mcp-toolkit zod@^3
+
+# bun
+bun add -D @nuxtjs/mcp-toolkit zod@^3
+```
+
+> **Note:** Zod v3 is required. Zod v4 is not yet compatible with the MCP SDK.
+
+<!-- /automd -->
+
+## 📖 Quick Start
+
+Add the module to your `nuxt.config.ts`:
+
+```typescript
+export default defineNuxtConfig({
+  modules: ['@nuxtjs/mcp-toolkit'],
+  mcp: {
+    name: 'My MCP Server',
+    version: '1.0.0',
+  },
+})
+```
+
+Create your first tool in `server/mcp/tools/echo.ts`:
+
+```typescript
+import { z } from 'zod'
+
+export default defineMcpTool({
+  description: 'Echo back a message',
+  inputSchema: {
+    message: z.string().describe('The message to echo back'),
+  },
+  handler: async ({ message }) => {
+    return {
+      content: [{
+        type: 'text',
+        text: `Echo: ${message}`,
+      }],
+    }
+  },
+})
+```
+
+The tool will be automatically discovered and registered. No imports needed - all helpers are auto-imported!
+
+## 📚 Documentation
+
+📖 **[Full Documentation →](https://mcp-toolkit.nuxt.dev)**
+
+## 🤝 Contributing
+
+<!-- automd:file src="../../.github/snippets/contributing.md" -->
+
+Contributions are welcome! Feel free to open an issue or submit a pull request.
+
+```bash
+# Install dependencies
+pnpm install
+
+# Generate type stubs
+pnpm run dev:prepare
+
+# Start the playground
+pnpm run dev
+
+# Run tests
+pnpm run test
+```
+
+<!-- /automd -->
+
+## 📄 License
+
+<!-- automd:file src="../../.github/snippets/license.md" -->
+
+Published under the [MIT](https://github.com/nuxt-modules/mcp-toolkit/blob/main/LICENSE) license.
+
+Made by [@HugoRCD](https://github.com/HugoRCD) and [community](https://github.com/nuxt-modules/mcp-toolkit/graphs/contributors) 💛
+
+<a href="https://github.com/nuxt-modules/mcp-toolkit/graphs/contributors">
+  <img src="https://contrib.rocks/image?repo=nuxt-modules/mcp-toolkit" />
+</a>
+
+<!-- /automd -->

package/dist/module.d.mts

@@ -0,0 +1,42 @@
+import * as _nuxt_schema from '@nuxt/schema';
+export * from '../dist/runtime/server/types/index.js';
+
+declare const resolve: (...path: string[]) => string;
+
+interface ModuleOptions {
+    /**
+     * Enable or disable the MCP server
+     * @default true
+     */
+    enabled?: boolean;
+    /**
+     * The route path for the MCP server endpoint
+     * @default '/mcp'
+     */
+    route?: string;
+    /**
+     * URL to redirect to when a browser accesses the MCP endpoint
+     * @default '/'
+     */
+    browserRedirect?: string;
+    /**
+     * The name of the MCP server
+     * @default Site name from site config or 'Docus Documentation'
+     */
+    name?: string;
+    /**
+     * The version of the MCP server
+     * @default '1.0.0'
+     */
+    version?: string;
+    /**
+     * Base directory for MCP definitions relative to server directory
+     * The module will look for tools, resources, and prompts in subdirectories
+     * @default 'mcp'
+     */
+    dir?: string;
+}
+declare const _default: _nuxt_schema.NuxtModule<ModuleOptions, ModuleOptions, false>;
+
+export { _default as default, resolve };
+export type { ModuleOptions };

package/dist/module.json

@@ -0,0 +1,11 @@
+{
+  "name": "@nuxtjs/mcp-toolkit",
+  "version": "0.0.1",
+  "configKey": "mcp",
+  "docs": "https://mcp-toolkit.nuxt.dev/getting-started/installation",
+  "mcp": "https://mcp-toolkit.nuxt.dev/mcp",
+  "builder": {
+    "@nuxt/module-builder": "1.0.2",
+    "unbuild": "3.6.1"
+  }
+}

package/dist/module.mjs

@@ -0,0 +1,116 @@
+import { logger, createResolver, defineNuxtModule, addServerHandler, addServerImports } from '@nuxt/kit';
+import { defu } from 'defu';
+import { loadAllDefinitions } from '../dist/runtime/server/mcp/loaders/index.js';
+import { defaultMcpConfig } from '../dist/runtime/server/mcp/config.js';
+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.0.1";
+
+const log = logger.withTag("@nuxtjs/mcp-toolkit");
+const { resolve } = createResolver(import.meta.url);
+const module$1 = defineNuxtModule({
+  meta: {
+    name,
+    version,
+    configKey: "mcp",
+    docs: "https://mcp-toolkit.nuxt.dev/getting-started/installation",
+    mcp: "https://mcp-toolkit.nuxt.dev/mcp"
+  },
+  defaults: defaultMcpConfig,
+  async setup(options, nuxt) {
+    const resolver = createResolver(import.meta.url);
+    nuxt.options.runtimeConfig.mcp = defu(
+      nuxt.options.runtimeConfig.mcp,
+      {
+        enabled: options.enabled,
+        route: options.route,
+        browserRedirect: options.browserRedirect,
+        name: options.name,
+        version: options.version,
+        dir: options.dir
+      }
+    );
+    if (!options.enabled) {
+      return;
+    }
+    const mcpDir = options.dir ?? defaultMcpConfig.dir;
+    const paths = {
+      tools: [`${mcpDir}/tools`],
+      resources: [`${mcpDir}/resources`],
+      prompts: [`${mcpDir}/prompts`],
+      handlers: [mcpDir]
+    };
+    nuxt.hook("modules:done", async () => {
+      try {
+        await nuxt.callHook("mcp:definitions:paths", paths);
+        const result = await loadAllDefinitions(paths);
+        if (result.handlers && result.handlers.count > 0) {
+          addServerHandler({
+            route: ROUTES.CUSTOM_HANDLER,
+            handler: resolver.resolve("runtime/server/mcp/handler")
+          });
+        }
+        if (result.total === 0) {
+          log.warn("No MCP definitions found. Create tools, resources, or prompts in server/mcp/");
+        } else {
+          const summary = [];
+          if (result.tools.count > 0) summary.push(`${result.tools.count} tool${result.tools.count > 1 ? "s" : ""}`);
+          if (result.resources.count > 0) summary.push(`${result.resources.count} resource${result.resources.count > 1 ? "s" : ""}`);
+          if (result.prompts.count > 0) summary.push(`${result.prompts.count} prompt${result.prompts.count > 1 ? "s" : ""}`);
+          if (result.handlers.count > 0) summary.push(`${result.handlers.count} handler${result.handlers.count > 1 ? "s" : ""}`);
+          const boxContent = [];
+          if (options.name) {
+            boxContent.push(`${options.name}`);
+          }
+          boxContent.push(`Route: ${options.route}`);
+          boxContent.push(`Definitions: ${summary.join(", ")}`);
+          log.box({
+            title: "MCP Server",
+            message: boxContent.join("\n")
+          });
+        }
+      } catch (error) {
+        const errorMessage = error instanceof Error ? error.message : String(error);
+        log.error("Failed to initialize MCP server");
+        log.error(`Error: ${errorMessage}`);
+        throw error;
+      }
+    });
+    nuxt.hook("prepare:types", ({ references }) => {
+      references.push({
+        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"));
+    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")
+      }
+    ]);
+    addServerHandler({
+      route: options.route,
+      handler: resolver.resolve("runtime/server/mcp/handler")
+    });
+    addDevToolsCustomTabs(nuxt, options);
+  }
+});
+
+export { module$1 as default, resolve };

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

@@ -0,0 +1,10 @@
+export interface McpConfig {
+    enabled: boolean;
+    route: string;
+    browserRedirect: string;
+    name: string;
+    version: string;
+    dir: string;
+}
+export declare const defaultMcpConfig: McpConfig;
+export declare function getMcpConfig(partial?: Partial<McpConfig>): McpConfig;

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

@@ -0,0 +1,12 @@
+import { defu } from "defu";
+export const defaultMcpConfig = {
+  enabled: true,
+  route: "/mcp",
+  browserRedirect: "/",
+  name: "",
+  version: "1.0.0",
+  dir: "mcp"
+};
+export function getMcpConfig(partial) {
+  return defu(partial, defaultMcpConfig);
+}

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

@@ -0,0 +1,22 @@
+/**
+ * Constants used throughout the MCP module
+ */
+/**
+ * Default route paths for MCP endpoints
+ */
+export declare const ROUTES: {
+    readonly DEFAULT: "/mcp";
+    readonly CUSTOM_HANDLER: "/mcp/:handler";
+};
+/**
+ * Subdirectory names for MCP definitions
+ */
+export declare const SUBDIRECTORIES: {
+    readonly TOOLS: "tools";
+    readonly RESOURCES: "resources";
+    readonly PROMPTS: "prompts";
+};
+/**
+ * Supported file extensions for MCP definition files
+ */
+export declare const FILE_EXTENSIONS: readonly ["ts", "js", "mts", "mjs"];

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

@@ -0,0 +1,10 @@
+export const ROUTES = {
+  DEFAULT: "/mcp",
+  CUSTOM_HANDLER: "/mcp/:handler"
+};
+export const SUBDIRECTORIES = {
+  TOOLS: "tools",
+  RESOURCES: "resources",
+  PROMPTS: "prompts"
+};
+export const FILE_EXTENSIONS = ["ts", "js", "mts", "mjs"];

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

@@ -0,0 +1,18 @@
+import type { McpToolDefinition } from './tools.js';
+import type { McpResourceDefinition } from './resources.js';
+import type { McpPromptDefinition } from './prompts.js';
+export interface McpHandlerOptions {
+    name: string;
+    version?: string;
+    route?: string;
+    browserRedirect?: string;
+    tools?: Array<McpToolDefinition<any, any>>;
+    resources?: McpResourceDefinition[];
+    prompts?: McpPromptDefinition[];
+}
+export interface McpHandlerDefinition extends Required<Omit<McpHandlerOptions, 'tools' | 'resources' | 'prompts'>> {
+    tools: Array<McpToolDefinition<any, any>>;
+    resources: McpResourceDefinition[];
+    prompts: McpPromptDefinition[];
+}
+export declare function defineMcpHandler(options: McpHandlerOptions): McpHandlerOptions;

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

@@ -0,0 +1,3 @@
+export function defineMcpHandler(options) {
+  return options;
+}

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

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

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

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

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

@@ -0,0 +1,79 @@
+import type { z, ZodTypeAny, 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';
+/**
+ * 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>;
+/**
+ * Definition of an MCP prompt
+ * Uses `inputSchema` for consistency with tools, which is mapped to `argsSchema` when registering with the SDK
+ */
+export interface McpPromptDefinition<Args extends ZodRawShape | undefined = undefined> {
+    name?: string;
+    title?: string;
+    description?: string;
+    inputSchema?: Args;
+    _meta?: Record<string, unknown>;
+    handler: McpPromptCallback<Args>;
+}
+/**
+ * Helper function to register a prompt from a McpPromptDefinition
+ */
+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
+ *
+ * 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/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
+ *         }
+ *       }]
+ *     }
+ *   }
+ * })
+ * ```
+ *
+ * @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?'
+ *         }
+ *       }]
+ *     }
+ *   }
+ * })
+ * ```
+ */
+export declare function defineMcpPrompt<const Args extends ZodRawShape | undefined = undefined>(definition: McpPromptDefinition<Args>): McpPromptDefinition<Args>;

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

@@ -0,0 +1,32 @@
+import { enrichNameTitle } from "./utils.js";
+export function registerPromptFromDefinition(server, prompt) {
+  const { name, title } = enrichNameTitle({
+    name: prompt.name,
+    title: prompt.title,
+    _meta: prompt._meta,
+    type: "prompt"
+  });
+  if (prompt.inputSchema) {
+    return server.registerPrompt(
+      name,
+      {
+        title,
+        description: prompt.description,
+        argsSchema: prompt.inputSchema
+      },
+      prompt.handler
+    );
+  } else {
+    return server.registerPrompt(
+      name,
+      {
+        title,
+        description: prompt.description
+      },
+      prompt.handler
+    );
+  }
+}
+export function defineMcpPrompt(definition) {
+  return definition;
+}

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

@@ -0,0 +1,130 @@
+import type { McpServer, ResourceTemplate, ReadResourceCallback, ReadResourceTemplateCallback, ResourceMetadata } from '@modelcontextprotocol/sdk/server/mcp.js';
+/**
+ * Annotations for a resource
+ * @see https://modelcontextprotocol.io/specification/2025-06-18/server/resources#annotations
+ */
+export interface McpResourceAnnotations {
+    audience?: ('user' | 'assistant')[];
+    priority?: number;
+    lastModified?: string;
+    [key: string]: unknown;
+}
+/**
+ * Definition of a standard MCP resource (with URI and handler)
+ */
+export interface StandardMcpResourceDefinition {
+    name?: string;
+    title?: string;
+    uri: string | ResourceTemplate;
+    metadata?: ResourceMetadata & {
+        annotations?: McpResourceAnnotations;
+    };
+    _meta?: Record<string, unknown>;
+    handler: ReadResourceCallback | ReadResourceTemplateCallback;
+    file?: never;
+}
+/**
+ * Definition of a file-based MCP resource
+ */
+export interface FileMcpResourceDefinition {
+    name?: string;
+    title?: string;
+    uri?: string;
+    metadata?: ResourceMetadata & {
+        annotations?: McpResourceAnnotations;
+    };
+    _meta?: Record<string, unknown>;
+    handler?: ReadResourceCallback;
+    /**
+     * Path to the local file to serve as a resource
+     * Relative to the project root
+     */
+    file: string;
+}
+/**
+ * Definition of an MCP resource matching the SDK's registerResource signature
+ * Supports both static resources (URI string), dynamic resources (ResourceTemplate),
+ * and local file resources.
+ */
+export type McpResourceDefinition = StandardMcpResourceDefinition | FileMcpResourceDefinition;
+/**
+ * Helper function to register a resource from a McpResourceDefinition
+ */
+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.
+ *
+ * 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/resources/my-resource.ts
+ * 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
+ *       }]
+ *     }
+ *   }
+ * })
+ * ```
+ */
+export declare function defineMcpResource(definition: McpResourceDefinition): McpResourceDefinition;