@nuxtjs/mcp-toolkit 0.0.0 → 0.0.1

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

@@ -0,0 +1,119 @@
+import { addServerTemplate, logger } from "@nuxt/kit";
+import {
+  createExcludePatterns,
+  createTemplateContent,
+  loadDefinitionFiles,
+  toIdentifier
+} from "./utils.js";
+const log = logger.withTag("@nuxtjs/mcp-toolkit");
+async function loadMcpDefinitions(type, templateFilename, paths) {
+  try {
+    const result = await loadDefinitionFiles(paths);
+    addServerTemplate({
+      filename: templateFilename,
+      getContents: () => {
+        if (result.count === 0) {
+          return `export const ${type} = []
+`;
+        }
+        const entries = result.files.map((file) => {
+          const filename = file.split("/").pop();
+          const identifier = toIdentifier(filename);
+          return [identifier, file];
+        });
+        return createTemplateContent(type, entries);
+      }
+    });
+    return result;
+  } catch (error) {
+    const errorMessage = error instanceof Error ? error.message : String(error);
+    log.error(`Failed to load ${type} definitions from paths: ${paths.join(", ")}`);
+    log.error(`Error: ${errorMessage}`);
+    throw new Error(`Failed to load MCP ${type} definitions. Check that the paths exist and contain valid definition files.`);
+  }
+}
+async function loadHandlers(paths = []) {
+  try {
+    if (paths.length === 0) {
+      addServerTemplate({
+        filename: "#nuxt-mcp/handlers.mjs",
+        getContents: () => `export const handlers = []
+`
+      });
+      return { count: 0, files: [], overriddenCount: 0 };
+    }
+    const excludePatterns = createExcludePatterns(paths, ["tools", "resources", "prompts"]);
+    const result = await loadDefinitionFiles(paths, {
+      excludePatterns,
+      filter: (filePath) => {
+        const relativePath = filePath.replace(/.*\/server\//, "");
+        return !relativePath.includes("/tools/") && !relativePath.includes("/resources/") && !relativePath.includes("/prompts/");
+      }
+    });
+    addServerTemplate({
+      filename: "#nuxt-mcp/handlers.mjs",
+      getContents: () => {
+        if (result.count === 0) {
+          return `export const handlers = []
+`;
+        }
+        const entries = result.files.map((file) => {
+          const filename = file.split("/").pop();
+          const identifier = toIdentifier(filename);
+          return [identifier, file];
+        });
+        return createTemplateContent("handlers", entries);
+      }
+    });
+    return result;
+  } catch (error) {
+    const errorMessage = error instanceof Error ? error.message : String(error);
+    log.error(`Failed to load handler definitions from paths: ${paths.join(", ")}`);
+    log.error(`Error: ${errorMessage}`);
+    throw new Error(`Failed to load MCP handler definitions. Check that the paths exist and contain valid handler files.`);
+  }
+}
+export async function loadTools(paths) {
+  return loadMcpDefinitions("tools", "#nuxt-mcp/tools.mjs", paths);
+}
+export async function loadResources(paths) {
+  return loadMcpDefinitions("resources", "#nuxt-mcp/resources.mjs", paths);
+}
+export async function loadPrompts(paths) {
+  return loadMcpDefinitions("prompts", "#nuxt-mcp/prompts.mjs", paths);
+}
+export { loadHandlers };
+export async function loadAllDefinitions(paths) {
+  try {
+    const [tools, resources, prompts, handlers] = await Promise.all([
+      loadTools(paths.tools),
+      loadResources(paths.resources),
+      loadPrompts(paths.prompts),
+      loadHandlers(paths.handlers ?? [])
+    ]);
+    const results = {
+      tools,
+      resources,
+      prompts,
+      handlers
+    };
+    return {
+      ...results,
+      total: tools.count + resources.count + prompts.count + handlers.count
+    };
+  } catch (error) {
+    const errorMessage = error instanceof Error ? error.message : String(error);
+    log.error("Failed to load MCP definitions");
+    log.error(`Error: ${errorMessage}`);
+    throw new Error("Failed to load MCP definitions. Please check your configuration and ensure definition files are valid.");
+  }
+}
+export async function getHandlerRoutes() {
+  try {
+    const handlersModule = await import("#nuxt-mcp/handlers.mjs");
+    const handlers = handlersModule.handlers;
+    return handlers.map((h) => ({ name: h.name, route: h.route }));
+  } catch {
+    return [];
+  }
+}

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

@@ -0,0 +1,13 @@
+export interface LoadResult {
+    count: number;
+    files: string[];
+    overriddenCount: number;
+}
+export declare function createFilePatterns(paths: string[], extensions?: string[]): string[];
+export declare function createExcludePatterns(paths: string[], subdirs: string[]): string[];
+export declare function toIdentifier(filename: string): string;
+export declare function createTemplateContent(type: string, entries: Array<[string, string]>): string;
+export declare function loadDefinitionFiles(paths: string[], options?: {
+    excludePatterns?: string[];
+    filter?: (filePath: string) => boolean;
+}): Promise<LoadResult>;

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

@@ -0,0 +1,139 @@
+import { getLayerDirectories } from "@nuxt/kit";
+import { resolve as resolvePath } from "pathe";
+import { glob } from "tinyglobby";
+const RESERVED_KEYWORDS = /* @__PURE__ */ new Set([
+  "break",
+  "case",
+  "catch",
+  "class",
+  "const",
+  "continue",
+  "debugger",
+  "default",
+  "delete",
+  "do",
+  "else",
+  "export",
+  "extends",
+  "finally",
+  "for",
+  "function",
+  "if",
+  "import",
+  "in",
+  "instanceof",
+  "new",
+  "return",
+  "super",
+  "switch",
+  "this",
+  "throw",
+  "try",
+  "typeof",
+  "var",
+  "void",
+  "while",
+  "with",
+  "yield",
+  "enum",
+  "implements",
+  "interface",
+  "let",
+  "package",
+  "private",
+  "protected",
+  "public",
+  "static",
+  "await",
+  "abstract",
+  "boolean",
+  "byte",
+  "char",
+  "double",
+  "final",
+  "float",
+  "goto",
+  "int",
+  "long",
+  "native",
+  "short",
+  "synchronized",
+  "transient",
+  "volatile"
+]);
+export function createFilePatterns(paths, extensions = ["ts", "js", "mts", "mjs"]) {
+  const layerDirectories = getLayerDirectories();
+  return layerDirectories.flatMap(
+    (layer) => paths.flatMap(
+      (pathPattern) => extensions.map((ext) => resolvePath(layer.server, `${pathPattern}/*.${ext}`))
+    )
+  );
+}
+export function createExcludePatterns(paths, subdirs) {
+  const layerDirectories = getLayerDirectories();
+  return layerDirectories.flatMap(
+    (layer) => paths.flatMap(
+      (pathPattern) => subdirs.map((subdir) => resolvePath(layer.server, `${pathPattern}/${subdir}/**`))
+    )
+  );
+}
+export function toIdentifier(filename) {
+  const id = filename.replace(/\.(ts|js|mts|mjs)$/, "").replace(/\W/g, "_");
+  if (RESERVED_KEYWORDS.has(id)) {
+    return `_${id}`;
+  }
+  return id;
+}
+export function createTemplateContent(type, entries) {
+  const imports = entries.map(
+    ([name, path]) => `import ${name.replace(/-/g, "_")} from '${path}'`
+  ).join("\n");
+  const enrichedExports = entries.map(([name, path]) => {
+    const identifier = name.replace(/-/g, "_");
+    const filename = path.split("/").pop();
+    return `(function() {
+  const def = ${identifier}
+  return {
+    ...def,
+    _meta: {
+      ...def._meta,
+      filename: ${JSON.stringify(filename)}
+    }
+  }
+})()`;
+  }).join(",\n  ");
+  return `${imports}
+
+export const ${type} = [
+  ${enrichedExports}
+]
+`;
+}
+export async function loadDefinitionFiles(paths, options = {}) {
+  if (paths.length === 0) {
+    return { count: 0, files: [], overriddenCount: 0 };
+  }
+  const patterns = createFilePatterns(paths);
+  const files = await glob(patterns, {
+    absolute: true,
+    onlyFiles: true,
+    ignore: options.excludePatterns
+  });
+  const definitionsMap = /* @__PURE__ */ new Map();
+  const filteredFiles = options.filter ? files.filter(options.filter) : files;
+  let overriddenCount = 0;
+  for (const filePath of filteredFiles) {
+    const filename = filePath.split("/").pop();
+    const identifier = toIdentifier(filename);
+    if (definitionsMap.has(identifier)) {
+      overriddenCount++;
+    }
+    definitionsMap.set(identifier, filePath);
+  }
+  const total = definitionsMap.size;
+  return {
+    count: total,
+    files: Array.from(definitionsMap.values()),
+    overriddenCount
+  };
+}

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

@@ -0,0 +1,18 @@
+import type { McpToolDefinition, McpResourceDefinition, McpPromptDefinition } from './definitions/index.js';
+import type { H3Event } from 'h3';
+export type CreateMcpHandlerConfig = {
+    name: string;
+    version: string;
+    browserRedirect: string;
+    tools?: McpToolDefinition[];
+    resources?: McpResourceDefinition[];
+    prompts?: McpPromptDefinition[];
+} | ((event: H3Event) => {
+    name: string;
+    version: string;
+    browserRedirect: string;
+    tools?: McpToolDefinition[];
+    resources?: McpResourceDefinition[];
+    prompts?: McpPromptDefinition[];
+});
+export declare function createMcpHandler(config: CreateMcpHandlerConfig): import("h3").EventHandler<import("h3").EventHandlerRequest, Promise<void>>;

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

@@ -0,0 +1,42 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
+import { registerToolFromDefinition, registerResourceFromDefinition, registerPromptFromDefinition } from "./definitions/index.js";
+import { sendRedirect, getHeader, readBody, defineEventHandler } from "h3";
+function resolveConfig(config, event) {
+  return typeof config === "function" ? config(event) : config;
+}
+function createMcpServer(config) {
+  const server = new McpServer({
+    name: config.name,
+    version: config.version
+  });
+  for (const tool of config.tools || []) {
+    registerToolFromDefinition(server, tool);
+  }
+  for (const resource of config.resources || []) {
+    registerResourceFromDefinition(server, resource);
+  }
+  for (const prompt of config.prompts || []) {
+    registerPromptFromDefinition(server, prompt);
+  }
+  return server;
+}
+export function createMcpHandler(config) {
+  return defineEventHandler(async (event) => {
+    const resolvedConfig = resolveConfig(config, event);
+    if (getHeader(event, "accept")?.includes("text/html")) {
+      return sendRedirect(event, resolvedConfig.browserRedirect);
+    }
+    const server = createMcpServer(resolvedConfig);
+    const transport = new StreamableHTTPServerTransport({
+      sessionIdGenerator: void 0
+    });
+    event.node.res.on("close", () => {
+      transport.close();
+      server.close();
+    });
+    await server.connect(transport);
+    const body = await readBody(event);
+    await transport.handleRequest(event.node.req, event.node.res, body);
+  });
+}

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

@@ -0,0 +1,4 @@
+export * from './tools.js';
+export * from './resources.js';
+export * from './prompts.js';
+export type { ValidationError } from './tools.js';

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

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

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

@@ -0,0 +1,14 @@
+import type { McpPromptDefinition } from '../definitions/prompts.js';
+export interface ValidationError {
+    file?: string;
+    message: string;
+    suggestion?: string;
+}
+/**
+ * Validate an MCP prompt definition
+ */
+export declare function validatePromptDefinition(prompt: McpPromptDefinition, filePath?: string): ValidationError[];
+/**
+ * Validate multiple prompt definitions
+ */
+export declare function validatePromptDefinitions(prompts: McpPromptDefinition[], filePaths?: string[]): ValidationError[];

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

@@ -0,0 +1,36 @@
+export function validatePromptDefinition(prompt, filePath) {
+  const errors = [];
+  if (!prompt.handler) {
+    errors.push({
+      file: filePath,
+      message: "Prompt definition is missing a handler function",
+      suggestion: "Add a handler function: handler: async (args) => { ... } or handler: async () => { ... }"
+    });
+  }
+  if (prompt.handler && typeof prompt.handler !== "function") {
+    errors.push({
+      file: filePath,
+      message: "Prompt handler must be a function",
+      suggestion: "Ensure handler is defined as: handler: async (args) => { ... }"
+    });
+  }
+  if (prompt.inputSchema && typeof prompt.inputSchema !== "object") {
+    errors.push({
+      file: filePath,
+      message: "Prompt inputSchema must be an object with Zod string schemas",
+      suggestion: "Use an object with Zod string schemas: inputSchema: { param: z.string() }"
+    });
+  }
+  return errors;
+}
+export function validatePromptDefinitions(prompts, filePaths) {
+  const errors = [];
+  for (let i = 0; i < prompts.length; i++) {
+    const prompt = prompts[i];
+    if (!prompt) continue;
+    const filePath = filePaths?.[i];
+    const promptErrors = validatePromptDefinition(prompt, filePath);
+    errors.push(...promptErrors);
+  }
+  return errors;
+}

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

@@ -0,0 +1,14 @@
+import type { McpResourceDefinition } from '../definitions/resources.js';
+export interface ValidationError {
+    file?: string;
+    message: string;
+    suggestion?: string;
+}
+/**
+ * Validate an MCP resource definition
+ */
+export declare function validateResourceDefinition(resource: McpResourceDefinition, filePath?: string): ValidationError[];
+/**
+ * Validate multiple resource definitions
+ */
+export declare function validateResourceDefinitions(resources: McpResourceDefinition[], filePaths?: string[]): ValidationError[];

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

@@ -0,0 +1,43 @@
+export function validateResourceDefinition(resource, filePath) {
+  const errors = [];
+  const isFileResource = "file" in resource && !!resource.file;
+  if (!resource.handler && !isFileResource) {
+    errors.push({
+      file: filePath,
+      message: "Resource definition is missing a handler function",
+      suggestion: "Add a handler function: handler: async (uri) => { ... }"
+    });
+  }
+  if (!resource.uri && !isFileResource) {
+    errors.push({
+      file: filePath,
+      message: "Resource definition is missing a URI",
+      suggestion: 'Add a URI string or ResourceTemplate: uri: "file:///path/to/resource"'
+    });
+  } else if (resource.uri && typeof resource.uri !== "string" && typeof resource.uri !== "object") {
+    errors.push({
+      file: filePath,
+      message: "Resource URI must be a string or ResourceTemplate",
+      suggestion: "Use a string URI or ResourceTemplate instance"
+    });
+  }
+  if (resource.handler && typeof resource.handler !== "function") {
+    errors.push({
+      file: filePath,
+      message: "Resource handler must be a function",
+      suggestion: "Ensure handler is defined as: handler: async (uri) => { ... }"
+    });
+  }
+  return errors;
+}
+export function validateResourceDefinitions(resources, filePaths) {
+  const errors = [];
+  for (let i = 0; i < resources.length; i++) {
+    const resource = resources[i];
+    if (!resource) continue;
+    const filePath = filePaths?.[i];
+    const resourceErrors = validateResourceDefinition(resource, filePath);
+    errors.push(...resourceErrors);
+  }
+  return errors;
+}

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

@@ -0,0 +1,14 @@
+import type { McpToolDefinition } from '../definitions/tools.js';
+export interface ValidationError {
+    file?: string;
+    message: string;
+    suggestion?: string;
+}
+/**
+ * Validate an MCP tool definition
+ */
+export declare function validateToolDefinition(tool: McpToolDefinition, filePath?: string): ValidationError[];
+/**
+ * Validate multiple tool definitions
+ */
+export declare function validateToolDefinitions(tools: McpToolDefinition[], filePaths?: string[]): ValidationError[];

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

@@ -0,0 +1,47 @@
+export function validateToolDefinition(tool, filePath) {
+  const errors = [];
+  if (!tool.handler) {
+    errors.push({
+      file: filePath,
+      message: "Tool definition is missing a handler function",
+      suggestion: "Add a handler function: handler: async (args) => { ... }"
+    });
+  }
+  if (tool.inputSchema && typeof tool.inputSchema !== "object") {
+    errors.push({
+      file: filePath,
+      message: "Tool inputSchema must be an object with Zod schemas",
+      suggestion: "Use an object with Zod schemas: inputSchema: { param: z.string() }"
+    });
+  } else if (tool.inputSchema) {
+    const schema = tool.inputSchema;
+    for (const [key, value] of Object.entries(schema)) {
+      if (!value || typeof value !== "object") {
+        errors.push({
+          file: filePath,
+          message: `inputSchema property "${key}" is not a valid Zod schema`,
+          suggestion: `Use a Zod schema: ${key}: z.string() or z.number(), etc.`
+        });
+      }
+    }
+  }
+  if (tool.handler && typeof tool.handler !== "function") {
+    errors.push({
+      file: filePath,
+      message: "Tool handler must be a function",
+      suggestion: "Ensure handler is defined as: handler: async (args) => { ... }"
+    });
+  }
+  return errors;
+}
+export function validateToolDefinitions(tools, filePaths) {
+  const errors = [];
+  for (let i = 0; i < tools.length; i++) {
+    const tool = tools[i];
+    if (!tool) continue;
+    const filePath = filePaths?.[i];
+    const toolErrors = validateToolDefinition(tool, filePath);
+    errors.push(...toolErrors);
+  }
+  return errors;
+}

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

@@ -0,0 +1,16 @@
+declare module '@nuxt/schema' {
+    interface NuxtHooks {
+        /**
+         * 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.
+         * @returns void | Promise<void>
+         */
+        'mcp:definitions:paths': (paths: {
+            tools?: string[];
+            resources?: string[];
+            prompts?: string[];
+            handlers?: string[];
+        }) => void | Promise<void>;
+    }
+}
+export {};

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

@@ -0,0 +1 @@
+export * from '../mcp/definitions/index.js';

package/dist/runtime/server/types/index.js

@@ -0,0 +1 @@
+export * from "../mcp/definitions/index.js";

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

@@ -0,0 +1,14 @@
+import type { McpToolDefinition, McpResourceDefinition, McpPromptDefinition } from './mcp/definitions'
+import './types/hooks'
+
+declare module '#nuxt-mcp/tools.mjs' {
+  export const tools: McpToolDefinition[]
+}
+
+declare module '#nuxt-mcp/resources.mjs' {
+  export const resources: McpResourceDefinition[]
+}
+
+declare module '#nuxt-mcp/prompts.mjs' {
+  export const prompts: McpPromptDefinition[]
+}

package/dist/types.d.mts

@@ -0,0 +1,5 @@
+export { default, type resolve } from './module.mjs'
+
+export { type ModuleOptions } from './module.mjs'
+
+export * from '../dist/runtime/server/types/index.js'

package/package.json

@@ -1,8 +1,80 @@
 {
   "name": "@nuxtjs/mcp-toolkit",
-  "version": "0.0.0",
+  "version": "0.0.1",
+  "description": "Create MCP servers directly in your Nuxt application. Define tools, resources, and prompts with a simple and intuitive API.",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/nuxt-modules/mcp-toolkit.git"
+  },
+  "homepage": "https://mcp-toolkit.nuxt.dev",
+  "bugs": {
+    "url": "https://github.com/nuxt-modules/mcp-toolkit/issues"
+  },
+  "author": "Hugo Richard <hugo.richard@vercel.com>",
+  "license": "MIT",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/types.d.mts",
+      "import": "./dist/module.mjs"
+    }
+  },
+  "main": "./dist/module.mjs",
+  "typesVersions": {
+    "*": {
+      ".": [
+        "./dist/types.d.mts"
+      ]
+    }
+  },
   "files": [
+    "README.md",
     "dist"
   ],
-  "author": "Daniel Roe <daniel@roe.dev>"
+  "dependencies": {
+    "@clack/prompts": "^0.11.0",
+    "@modelcontextprotocol/sdk": "^1.22.0",
+    "@nuxt/kit": "^4.2.1",
+    "automd": "^0.4.2",
+    "chokidar": "^4.0.3",
+    "defu": "^6.1.4",
+    "pathe": "^2.0.3",
+    "scule": "^1.3.0",
+    "tinyglobby": "^0.2.15"
+  },
+  "peerDependencies": {
+    "zod": "^3.25.76"
+  },
+  "peerDependenciesMeta": {
+    "zod": {
+      "optional": false
+    }
+  },
+  "devDependencies": {
+    "@nuxt/devtools": "^3.1.0",
+    "@nuxt/eslint-config": "^1.10.0",
+    "@nuxt/module-builder": "^1.0.2",
+    "@nuxt/schema": "^4.2.1",
+    "@nuxt/test-utils": "^3.20.1",
+    "@types/node": "latest",
+    "changelogen": "^0.6.2",
+    "eslint": "^9.39.1",
+    "nuxt": "^4.2.1",
+    "typescript": "~5.9.3",
+    "vitest": "^4.0.10",
+    "vue-tsc": "^3.1.4"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "build": "nuxt-module-build build",
+    "dev:prepare": "nuxt-module-build build --stub && nuxt-module-build prepare",
+    "lint": "eslint .",
+    "lint:fix": "eslint . --fix",
+    "test": "vitest run",
+    "test:watch": "vitest watch",
+    "typecheck": "vue-tsc --noEmit",
+    "release": "pnpm run typecheck && pnpm run test && pnpm run lint && pnpm run build && npm publish && git push --follow-tags"
+  }
 }