nuxt-graphql-middleware 5.2.3 → 5.3.1

package/dist/module.mjs

@@ -1,9 +1,9 @@
 import { fileURLToPath } from 'url';
-import { useLogger, addTemplate, addServerTemplate, addTypeTemplate, createResolver, resolveAlias, resolveFiles, addPlugin, addServerHandler, addImports, addServerImports, useNitro, defineNuxtModule } from '@nuxt/kit';
-import { existsSync, promises } from 'node:fs';
-import { basename } from 'node:path';
+import { useLogger, addTemplate, addServerTemplate, createResolver, resolveAlias, resolveFiles, addPlugin, addServerHandler, addImports, addServerImports, useNitro, defineNuxtModule, addDevServerHandler } from '@nuxt/kit';
+import { existsSync, promises, readFileSync } from 'node:fs';
+import { basename, join as join$1, dirname, isAbsolute, relative as relative$1 } from 'node:path';
 import { relative, join } from 'pathe';
-import { printSourceLocation, parse, Source, OperationTypeNode } from 'graphql';
+import { printSourceLocation, parse, Source, OperationTypeNode, isObjectType, isInputObjectType, isEnumType, isUnionType, isInterfaceType, isScalarType, isNonNullType, isListType, printType, TypeInfo, visit, visitWithTypeInfo } from 'graphql';
 import { Generator, FieldNotFoundError, TypeNotFoundError, FragmentNotFoundError } from 'graphql-typescript-deluxe';
 import color from 'picocolors';
 import { validateGraphQlDocuments } from '@graphql-tools/utils';
@@ -18,9 +18,10 @@ import isUnicodeSupported from 'is-unicode-supported';
 import { hash } from 'ohash';
 import { existsSync as existsSync$1 } from 'fs';
 import { onDevToolsInitialized, extendServerRpc } from '@nuxt/devtools-kit';
+import { defineEventHandler, readBody, createError } from 'h3';
 
 const name = "nuxt-graphql-middleware";
-const version = "5.2.3";
+const version = "5.3.1";
 
 const logger = useLogger("nuxt-graphql-middleware");
 const defaultOptions = {
@@ -33,6 +34,7 @@ const defaultOptions = {
   documents: [],
   devtools: true,
   errorOverlay: true,
+  logOnlyErrors: true,
   graphqlConfigFilePath: "./graphql.config.ts",
   experimental: {
     improvedQueryParamEncoding: false
@@ -40,6 +42,9 @@ const defaultOptions = {
   clientCache: {
     enabled: false,
     maxSize: 100
+  },
+  mcp: {
+    enabled: false
   }
 };
 function validateOptions(options) {
@@ -161,6 +166,8 @@ class Collector {
       mappedOptions.output.buildTypeDocFilePath = (filePath) => {
         if (filePath.startsWith("/")) {
           return this.filePathToBuildRelative(filePath);
+        } else if (filePath.startsWith("hook:")) {
+          return "./../nuxt-graphql-middleware/hook-documents.graphql";
         }
         return filePath;
       };
@@ -199,6 +206,14 @@ class Collector {
    * The generated template contents.
    */
   templateResult = /* @__PURE__ */ new Map();
+  /**
+   * Operations with full metadata for MCP tools.
+   */
+  operations = [];
+  /**
+   * Fragments with full metadata for MCP tools.
+   */
+  fragments = [];
   isInitialised = false;
   async reset() {
     this.files.clear();
@@ -218,6 +233,9 @@ class Collector {
   filePathToSourceRelative(filePath) {
     if (filePath.startsWith("/")) {
       return "./" + relative(process.cwd(), filePath);
+    } else if (filePath.startsWith("hook:")) {
+      const hookPathAbsolute = this.helper.paths.moduleBuildDir + "/hook-documents.graphql";
+      return "./" + relative(process.cwd(), hookPathAbsolute);
     }
     return filePath;
   }
@@ -292,7 +310,7 @@ class Collector {
       } else {
         this.operationTimestamps.set(operation.graphqlName, operation.timestamp);
       }
-      const shouldLog = errors.length || !this.helper.options.logOnlyErrors;
+      const shouldLog = errors.length || !this.helper.isPrepare && !this.helper.options.logOnlyErrors;
       if (shouldLog) {
         logEntries.push(this.operationToLogEntry(operation, errors));
       }
@@ -306,6 +324,40 @@ class Collector {
       throw new Error("GraphQL errors");
     }
     await this.helper.nuxt.callHook("nuxt-graphql-middleware:build", { output });
+    if (this.helper.isDev) {
+      this.operations = operations.map((op) => {
+        const fragmentDeps = op.getGraphQLFragmentDependencies().map((name) => fragmentMap.get(name) || "").join("\n");
+        const source = operationSourceMap.get(op.graphqlName) || "";
+        const sourceFull = [source, fragmentDeps].join("\n");
+        return {
+          name: op.graphqlName,
+          type: op.operationType,
+          filePath: op.filePath,
+          relativeFilePath: this.filePathToSourceRelative(op.filePath),
+          hasVariables: op.hasVariables,
+          needsVariables: op.needsVariables,
+          variablesTypeName: op.variablesTypeName,
+          responseTypeName: op.typeName,
+          source,
+          sourceFull
+        };
+      });
+      const outputFragments = output.getFragments();
+      this.fragments = outputFragments.map((frag) => {
+        const source = fragmentMap.get(frag.node.name.value) || "";
+        const fragmentDeps = frag.getGraphQLFragmentDependencies().map((name) => fragmentMap.get(name) || "").join("\n");
+        const sourceFull = [source, fragmentDeps].join("\n");
+        return {
+          name: frag.node.name.value,
+          typeName: frag.node.typeCondition.name.value,
+          filePath: frag.filePath,
+          relativeFilePath: this.filePathToSourceRelative(frag.filePath),
+          source,
+          sourceFull,
+          dependencies: frag.getGraphQLFragmentDependencies()
+        };
+      });
+    }
     if (this.helper.isDev) {
       for (const code of generatedCode) {
         const id = `${code.identifier}_${code.graphqlName}`;
@@ -313,7 +365,7 @@ class Collector {
           if (this.rpcItems.get(id)?.timestamp === code.timestamp) {
             continue;
           }
-          const fragmentDepdendencies = code.getGraphQLFragmentDependencies().map((name) => fragmentMap.get(name) || "").join("\n\n");
+          const fragmentDepdendencies = code.getGraphQLFragmentDependencies().map((name) => fragmentMap.get(name) || "").join("\n");
           this.rpcItems.set(id, {
             id,
             timestamp: code.timestamp,
@@ -426,7 +478,9 @@ class Collector {
         await this.addFile(filePath);
       }
       await this.buildState();
-      logger.success("All GraphQL documents are valid.");
+      if (!this.helper.isPrepare) {
+        logger.success("All GraphQL documents are valid.");
+      }
     } catch (e) {
       this.logError(e);
       throw new Error("GraphQL document validation failed.");
@@ -586,16 +640,10 @@ class Collector {
     if (template.buildTypes) {
       const path = template.options.path;
       const filename = template.options.path + ".d.ts";
-      addTypeTemplate(
-        {
-          filename,
-          write: true,
-          getContents: () => this.getTemplate(path, "types")
-        },
-        {
-          nuxt: true,
-          nitro: true
-        }
+      this.helper.registerTypeTemplate(
+        filename,
+        () => this.getTemplate(path, "types"),
+        template.options.context
       );
     }
   }
@@ -616,6 +664,30 @@ class Collector {
   getHookFiles() {
     return [...this.hookFiles.values()];
   }
+  /**
+   * Get all operations with metadata (for MCP tools).
+   */
+  getOperations() {
+    return this.operations;
+  }
+  /**
+   * Get all fragments for a specific GraphQL type (for MCP tools).
+   */
+  getFragmentsForType(typeName) {
+    return this.fragments.filter((frag) => frag.typeName === typeName);
+  }
+  /**
+   * Get all fragments (for MCP tools).
+   */
+  getFragments() {
+    return this.fragments;
+  }
+  /**
+   * Get a fragment by name (for MCP tools).
+   */
+  getFragment(name) {
+    return this.fragments.find((frag) => frag.name === name);
+  }
 }
 
 class SchemaProvider {
@@ -667,7 +739,11 @@ class SchemaProvider {
       );
       throw new Error("Missing GraphQL schema.");
     }
-    logger.info(`Loading GraphQL schema from disk: ${this.helper.paths.schema}`);
+    if (!this.helper.isPrepare) {
+      logger.info(
+        `Loading GraphQL schema from disk: ${this.helper.paths.schema}`
+      );
+    }
     return await fs.readFile(this.helper.paths.schema).then((v) => v.toString());
   }
   /**
@@ -720,7 +796,7 @@ class SchemaProvider {
    * @param forceDownload - Forces downloading the schema.
    */
   async loadSchema(opts) {
-    if (opts?.forceDisk) {
+    if (opts?.forceDisk || this.helper.isPrepare) {
       this.schemaContent = await this.loadSchemaFromDisk();
     } else if (this.helper.options.downloadSchema || opts?.forceDownload) {
       this.schemaContent = await this.downloadSchema();
@@ -817,9 +893,72 @@ ${color.cyan(S_BAR_END)}
   }
 }
 
+function defineImport(name, description, context) {
+  const docsPath = context === "nuxt" ? "composables" : "server-utils";
+  return {
+    name,
+    description,
+    context,
+    docsUrl: `https://nuxt-graphql-middleware.dulnan.net/${docsPath}/${name}.html`
+  };
+}
+const useGraphqlQuery = defineImport(
+  "useGraphqlQuery",
+  "Perform a GraphQL query via the middleware. Returns a promise. Can be used anywhere - in components, plugins, other composables, event handlers, or inside useAsyncData.",
+  "nuxt"
+);
+const useAsyncGraphqlQuery = defineImport(
+  "useAsyncGraphqlQuery",
+  "SSR-compatible, reactive data fetching. Must be called at the root of a component setup or inside another composable. Same limitations as useAsyncData.",
+  "nuxt"
+);
+const useGraphqlMutation = defineImport(
+  "useGraphqlMutation",
+  "Perform a GraphQL mutation via the middleware. Returns a promise. Can be used anywhere - in components, plugins, other composables, or event handlers.",
+  "nuxt"
+);
+const useGraphqlUploadMutation = defineImport(
+  "useGraphqlUploadMutation",
+  "Perform a GraphQL mutation via the middleware with support for file uploads. Returns a promise. Can be used anywhere - in components, plugins, other composables, or event handlers.",
+  "nuxt"
+);
+const useGraphqlState = defineImport(
+  "useGraphqlState",
+  "allows you to set fetch options for the useGraphqlQuery, useAsyncGraphqlQuery and useGraphqlMutation composables. One common use case is to pass custom request headers to the GraphQL middleware request.",
+  "nuxt"
+);
+const COMPOSABLES = {
+  useGraphqlQuery,
+  useGraphqlMutation,
+  useAsyncGraphqlQuery,
+  useGraphqlUploadMutation,
+  useGraphqlState
+};
+const serverUseGraphqlQuery = defineImport(
+  "useGraphqlQuery",
+  "Perform a GraphQL query via the middleware in a Nitro server context. Auto-imported and available in event handlers, server plugins, and other server-side code.",
+  "nitro"
+);
+const serverUseGraphqlMutation = defineImport(
+  "useGraphqlMutation",
+  "Perform a GraphQL mutation via the middleware in a Nitro server context. Auto-imported and available in event handlers, server plugins, and other server-side code.",
+  "nitro"
+);
+const doGraphqlRequest = defineImport(
+  "doGraphqlRequest",
+  "Perform a raw GraphQL request in a Nitro server context. Provides low-level access to execute arbitrary GraphQL queries and mutations.",
+  "nitro"
+);
+const SERVER_UTILS = {
+  useGraphqlQuery: serverUseGraphqlQuery,
+  useGraphqlMutation: serverUseGraphqlMutation,
+  doGraphqlRequest
+};
+
 class ModuleHelper {
   constructor(nuxt, moduleUrl, options) {
     this.nuxt = nuxt;
+    this.isPrepare = nuxt.options._prepare;
     const mergedOptions = defu(
       {},
       options,
@@ -897,6 +1036,7 @@ class ModuleHelper {
   resolvers;
   paths;
   isDev;
+  isPrepare;
   options;
   prompt = new ConsolePrompt();
   nitroExternals = [];
@@ -926,7 +1066,9 @@ class ModuleHelper {
         );
       }
     }
-    logger.info("No graphqlMiddleware.serverOptions file found.");
+    if (!this.isPrepare) {
+      logger.info("No graphqlMiddleware.serverOptions file found.");
+    }
     return null;
   }
   findClientOptions() {
@@ -1029,10 +1171,38 @@ ${content.trim()}`;
         template.buildTypes(this)
       );
       const filename = template.options.path + ".d.ts";
-      addTypeTemplate({
+      this.registerTypeTemplate(
         filename,
-        write: true,
-        getContents: () => content
+        () => content,
+        template.options.context
+      );
+    }
+  }
+  /**
+   * Register a type template without adding to globalTypeFiles.
+   *
+   * Uses addTemplate instead of addTypeTemplate to avoid Vue compiler-sfc
+   * issue where exported types from globalTypeFiles cannot be resolved.
+   * @see https://github.com/nuxt/nuxt/issues/33694
+   */
+  registerTypeTemplate(filename, getContents, context) {
+    const resolvedTemplate = addTemplate({
+      filename,
+      write: true,
+      getContents
+    });
+    const forNuxt = context === "nuxt" || context === "both";
+    const forNitro = context === "nitro" || context === "both";
+    if (forNuxt) {
+      this.nuxt.hook("prepare:types", (payload) => {
+        payload.references ||= [];
+        payload.references.push({ path: resolvedTemplate.dst });
+      });
+    }
+    if (forNitro) {
+      this.nuxt.hook("nitro:prepare:types", (payload) => {
+        payload.references ||= [];
+        payload.references.push({ path: resolvedTemplate.dst });
       });
     }
   }
@@ -1049,16 +1219,26 @@ ${content.trim()}`;
     });
   }
   addComposable(name) {
+    const composable = COMPOSABLES[name];
     addImports({
       from: this.resolvers.module.resolve("./runtime/composables/" + name),
-      name
+      name,
+      meta: {
+        description: composable.description,
+        docsUrl: composable.docsUrl
+      }
     });
   }
   addServerUtil(name) {
+    const serverUtil = SERVER_UTILS[name];
     addServerImports([
       {
         from: this.resolvers.module.resolve("./runtime/server/utils/" + name),
-        name
+        name,
+        meta: {
+          description: serverUtil.description,
+          docsUrl: serverUtil.docsUrl
+        }
       }
     ]);
   }
@@ -1082,7 +1262,7 @@ function defineStaticTemplate(options, build, buildTypes) {
 }
 
 const ClientOptions = defineStaticTemplate(
-  { path: "nuxt-graphql-middleware/client-options" },
+  { path: "nuxt-graphql-middleware/client-options", context: "both" },
   (helper) => {
     if (helper.paths.clientOptions) {
       const pathRelative = helper.toModuleBuildRelative(
@@ -1102,21 +1282,21 @@ export { clientOptions }
       return `import type { GraphqlClientOptions } from '${helper.paths.runtimeTypes}'
 import clientOptionsImport from '${pathRelative}'
 
-declare export const clientOptions: GraphqlClientOptions|undefined
+export declare const clientOptions: GraphqlClientOptions|undefined
 export type GraphqlClientContext = typeof clientOptionsImport extends GraphqlClientOptions<infer R> ? R : {}
 `;
     }
     return `
 import type { GraphqlClientOptions } from '${helper.paths.runtimeTypes}'
 
-declare export const clientOptions: GraphqlClientOptions|undefined
+export declare const clientOptions: GraphqlClientOptions|undefined
 export type GraphqlClientContext = {}
 `;
   }
 );
 
 const Config = defineStaticTemplate(
-  { path: "nuxt-graphql-middleware/config" },
+  { path: "nuxt-graphql-middleware/config", context: "both" },
   (helper) => {
     const experimentalQueryParamEncoding = !!helper.options.experimental.improvedQueryParamEncoding;
     const clientCacheEnabledAtBuild = !!helper.options.clientCache.enabled;
@@ -1129,16 +1309,20 @@ export const importMetaClient = import.meta.client
   },
   () => {
     return `
-declare export const experimentalQueryParamEncoding: boolean
-declare export const clientCacheEnabledAtBuild: boolean
-declare export const importMetaServer: boolean
-declare export const importMetaClient: boolean
+export declare const experimentalQueryParamEncoding: boolean
+export declare const clientCacheEnabledAtBuild: boolean
+export declare const importMetaServer: boolean
+export declare const importMetaClient: boolean
 `;
   }
 );
 
 const Documents = defineGeneratorTemplate(
-  { path: "nuxt-graphql-middleware/documents", virtual: true },
+  {
+    path: "nuxt-graphql-middleware/documents",
+    virtual: true,
+    context: "nitro"
+  },
   (output, helper) => {
     return output.getOperationsFile({
       exportName: "documents",
@@ -1160,7 +1344,7 @@ declare module '#nuxt-graphql-middleware/documents' {
 );
 
 const GraphqlConfig = defineStaticTemplate(
-  { path: "nuxt-graphql-middleware/graphql.config" },
+  { path: "nuxt-graphql-middleware/graphql.config", context: "nuxt" },
   (helper) => {
     const patterns = helper.options.autoImportPatterns || [];
     const configPath = helper.resolvers.root.resolve(
@@ -1203,15 +1387,15 @@ import type { IGraphQLProject } from 'graphql-config'
 
 type WithRequired<T, K extends keyof T> = T & { [P in K]-?: T[P] };
 
-const config: WithRequired<IGraphQLProject, 'schema' | 'documents'>;
+declare const config: WithRequired<IGraphQLProject, 'schema' | 'documents'>
 
-export default config;
+export default config
 `;
   }
 );
 
 const Helpers = defineStaticTemplate(
-  { path: "nuxt-graphql-middleware/helpers" },
+  { path: "nuxt-graphql-middleware/helpers", context: "both" },
   (helper) => {
     return `export const serverApiPrefix = '${helper.options.serverApiPrefix}'
 export function getEndpoint(operation, operationName) {
@@ -1220,8 +1404,8 @@ export function getEndpoint(operation, operationName) {
 `;
   },
   () => {
-    return `export const serverApiPrefix: string;
-export function getEndpoint(operation: string, operationName: string): string`;
+    return `export declare const serverApiPrefix: string
+export declare function getEndpoint(operation: string, operationName: string): string`;
   }
 );
 
@@ -1229,7 +1413,8 @@ const HookDocuments = defineGeneratorTemplate(
   {
     path: "nuxt-graphql-middleware/hook-documents.graphql",
     virtual: false,
-    isFullPath: true
+    isFullPath: true,
+    context: "nuxt"
   },
   (_output, _helper, collector) => {
     return collector.getHookDocuments().map((v) => {
@@ -1245,7 +1430,8 @@ ${v.source}
 const HookFiles = defineGeneratorTemplate(
   {
     path: "nuxt-graphql-middleware/hook-files",
-    virtual: false
+    virtual: false,
+    context: "nuxt"
   },
   (_output, helper, collector) => {
     const configPath = helper.resolvers.root.resolve(
@@ -1259,11 +1445,13 @@ const HookFiles = defineGeneratorTemplate(
     });
     return `export const hookFiles = ${JSON.stringify(files, null, 2)}`;
   },
-  null
+  () => {
+    return `export declare const hookFiles: string[]`;
+  }
 );
 
 const NitroTypes = defineGeneratorTemplate(
-  { path: "nuxt-graphql-middleware/nitro" },
+  { path: "nuxt-graphql-middleware/nitro", context: "nitro" },
   null,
   (output, helper) => {
     const operations = output.getCollectedOperations();
@@ -1293,7 +1481,11 @@ ${endpoints.sort().join("\n")}
 );
 
 const OperationHashes = defineGeneratorTemplate(
-  { path: "nuxt-graphql-middleware/operation-hashes", virtual: true },
+  {
+    path: "nuxt-graphql-middleware/operation-hashes",
+    virtual: true,
+    context: "nuxt"
+  },
   (output, helper) => {
     if (helper.isDev) {
       return `export const operationHashes = {}`;
@@ -1333,7 +1525,7 @@ declare module '#nuxt-graphql-middleware/operation-hashes' {
 );
 
 const OperationTypesAll = defineGeneratorTemplate(
-  { path: "nuxt-graphql-middleware/operation-types" },
+  { path: "nuxt-graphql-middleware/operation-types", context: "both" },
   () => `export {}`,
   (output) => {
     return output.getOperationTypesFile({
@@ -1343,7 +1535,7 @@ const OperationTypesAll = defineGeneratorTemplate(
 );
 
 const Operations = defineGeneratorTemplate(
-  { path: "graphql-operations/index" },
+  { path: "graphql-operations/index", context: "both" },
   (output) => {
     const typesFile = output.getOperations("js");
     return typesFile.getSource();
@@ -1355,7 +1547,7 @@ const Operations = defineGeneratorTemplate(
 );
 
 const OperationVariables = defineGeneratorTemplate(
-  { path: "nuxt-graphql-middleware/operation-variables" },
+  { path: "nuxt-graphql-middleware/operation-variables", context: "nitro" },
   (output) => {
     const operations = output.getCollectedOperations().reduce((acc, collectedOperation) => {
       const node = collectedOperation.node;
@@ -1368,13 +1560,13 @@ const OperationVariables = defineGeneratorTemplate(
   },
   () => {
     return `
-declare export const operationVariables: Record<string, string[]>
+export declare const operationVariables: Record<string, string[]>
 `;
   }
 );
 
 const Response = defineGeneratorTemplate(
-  { path: "nuxt-graphql-middleware/response" },
+  { path: "nuxt-graphql-middleware/response", context: "both" },
   null,
   (output, helper) => {
     const operations = output.getCollectedOperations();
@@ -1396,7 +1588,7 @@ declare module '#nuxt-graphql-middleware/response' {
 );
 
 const ServerOptions = defineStaticTemplate(
-  { path: "nuxt-graphql-middleware/server-options" },
+  { path: "nuxt-graphql-middleware/server-options", context: "both" },
   (helper) => {
     const resolvedPathRelative = helper.paths.serverOptions ? helper.toModuleBuildRelative(helper.paths.serverOptions) : null;
     const serverOptionsLine = resolvedPathRelative ? `import serverOptions from '${resolvedPathRelative}'` : `const serverOptions = {}`;
@@ -1418,13 +1610,13 @@ type AdditionsFromServerOptions = typeof serverOptionsImport extends GraphqlMidd
 
 export type GraphqlResponseAdditions = Omit<AdditionsFromServerOptions, 'data' | 'errors'>
 
-declare export const serverOptions: GraphqlMiddlewareServerOptions
+export declare const serverOptions: GraphqlMiddlewareServerOptions
 `;
     }
     return `
 import type { GraphqlMiddlewareServerOptions } from '${helper.paths.runtimeTypes}'
 
-declare export const serverOptions: GraphqlMiddlewareServerOptions
+export declare const serverOptions: GraphqlMiddlewareServerOptions
 
 export type GraphqlResponseAdditions = object
 `;
@@ -1432,7 +1624,7 @@ export type GraphqlResponseAdditions = object
 );
 
 const Sources = defineGeneratorTemplate(
-  { path: "nuxt-graphql-middleware/sources" },
+  { path: "nuxt-graphql-middleware/sources", context: "nuxt" },
   (output, helper) => {
     const operations = output.getCollectedOperations();
     const srcDir = helper.paths.root;
@@ -1450,7 +1642,125 @@ export const operationSources = {
 `;
   },
   () => {
-    return `export const operationSources: Record<string, string>`;
+    return `export declare const operationSources: Record<string, string>`;
+  }
+);
+
+const DOCS = [
+  // Composables
+  {
+    path: "composables/useGraphqlQuery",
+    file: "composables/useGraphqlQuery.md",
+    name: "useGraphqlQuery",
+    description: "Execute a GraphQL query using $fetch"
+  },
+  {
+    path: "composables/useGraphqlMutation",
+    file: "composables/useGraphqlMutation.md",
+    name: "useGraphqlMutation",
+    description: "Execute a GraphQL mutation using $fetch"
+  },
+  {
+    path: "composables/useAsyncGraphqlQuery",
+    file: "composables/useAsyncGraphqlQuery.md",
+    name: "useAsyncGraphqlQuery",
+    description: "SSR-compatible GraphQL query with useAsyncData"
+  },
+  {
+    path: "composables/useGraphqlState",
+    file: "composables/useGraphqlState.md",
+    name: "useGraphqlState",
+    description: "Access cached GraphQL query state"
+  },
+  {
+    path: "composables/useGraphqlUploadMutation",
+    file: "composables/useGraphqlUploadMutation.md",
+    name: "useGraphqlUploadMutation",
+    description: "GraphQL mutation with file upload support"
+  },
+  // Configuration
+  {
+    path: "configuration/module",
+    file: "configuration/module.md",
+    name: "Module Configuration",
+    description: "Configure the nuxt-graphql-middleware module options"
+  },
+  {
+    path: "configuration/client-options",
+    file: "configuration/client-options.md",
+    name: "Client Options",
+    description: "Configure client-side GraphQL request behavior"
+  },
+  {
+    path: "configuration/server-options",
+    file: "configuration/server-options.md",
+    name: "Server Options",
+    description: "Configure server-side GraphQL request handling"
+  },
+  {
+    path: "configuration/module-hooks",
+    file: "configuration/module-hooks.md",
+    name: "Module Hooks",
+    description: "Use Nuxt hooks to customize module behavior"
+  },
+  {
+    path: "configuration/module-utils",
+    file: "configuration/module-utils.md",
+    name: "Module Utils",
+    description: "Utility functions for working with the module"
+  },
+  {
+    path: "configuration/runtime-config",
+    file: "configuration/runtime-config.md",
+    name: "Runtime Config",
+    description: "Configure runtime settings via Nuxt runtime config"
+  }
+];
+const MCP = defineStaticTemplate(
+  { path: "nuxt-graphql-middleware/mcp", context: "nitro" },
+  (helper) => {
+    const mcpServerRoute = helper.options.mcp.route ?? "/mcp/nuxt-graphql-middleware";
+    const devServerUrl = helper.isDev ? `http://${helper.nuxt.options.devServer.host || "localhost"}:${helper.nuxt.options.devServer.port || 3e3}` : "";
+    const docsDir = helper.resolvers.module.resolve("../docs");
+    const entries = [];
+    if (helper.isDev || helper.isPrepare) {
+      for (const doc of DOCS) {
+        const filePath = join$1(docsDir, doc.file);
+        try {
+          const content = readFileSync(filePath, "utf-8");
+          entries.push({
+            uri: `docs://${doc.path}`,
+            name: doc.name,
+            description: doc.description,
+            content
+          });
+        } catch {
+        }
+      }
+    }
+    const includeComposables = !!helper.options.includeComposables;
+    return `
+export const mcpServerRoute = ${JSON.stringify(mcpServerRoute)}
+export const devServerUrl = ${JSON.stringify(devServerUrl)}
+export const includeComposables = ${JSON.stringify(includeComposables)}
+export const docs = ${JSON.stringify(entries, null, 2)}
+`;
+  },
+  () => {
+    return `
+export declare const mcpServerRoute: string
+export declare const devServerUrl: string
+export declare const includeComposables: boolean
+
+export type Doc = {
+  uri: string
+  name: string
+  description: string
+  content: string
+}
+
+export declare const docs: Doc[]
+`;
   }
 );
 
@@ -1469,7 +1779,8 @@ const TEMPLATES = [
   OperationVariables,
   Response,
   ServerOptions,
-  Sources
+  Sources,
+  MCP
 ];
 
 const DEVTOOLS_UI_ROUTE = "/__nuxt-graphql-middleware";
@@ -1533,6 +1844,8 @@ class DevModeHandler {
       this.onViteServerCreated.bind(this)
     );
     this.nuxt.hook("builder:watch", this.onBuilderWatch.bind(this));
+    const additionalFoldersToWatch = this.getAdditionalWatchFolders();
+    this.helper.nuxt.options.watch.push(...additionalFoldersToWatch);
     if (this.helper.options.devtools) {
       const clientPath = this.helper.resolvers.module.resolve("./client");
       setupDevToolsUI(this.nuxt, clientPath);
@@ -1642,6 +1955,34 @@ class DevModeHandler {
       data: { operations }
     });
   }
+  /**
+   * Get additional folders that need to be watched.
+   */
+  getAdditionalWatchFolders() {
+    const folders = /* @__PURE__ */ new Set();
+    const srcDir = this.helper.nuxt.options.srcDir;
+    const rootDir = this.helper.nuxt.options.rootDir;
+    for (const pattern of this.helper.options.autoImportPatterns) {
+      if (pattern.startsWith("!")) {
+        continue;
+      }
+      const match = pattern.match(/[*?{[]/);
+      if (!match || match.index === void 0) {
+        folders.add(dirname(pattern));
+      } else {
+        const pathBeforeGlob = pattern.slice(0, match.index);
+        const folder = pathBeforeGlob.endsWith("/") ? pathBeforeGlob.slice(0, -1) : dirname(pathBeforeGlob);
+        if (folder && folder !== ".") {
+          folders.add(folder);
+        }
+      }
+    }
+    return [...folders].filter((folder) => {
+      return !folder.startsWith(srcDir) && folder !== rootDir;
+    }).map((folder) => {
+      return relative(srcDir, folder);
+    });
+  }
 }
 
 class ModuleContext {
@@ -1722,7 +2063,1108 @@ class ModuleContext {
   }
 }
 
-const module = defineNuxtModule({
+function createNameFilter(pattern) {
+  try {
+    const regex = new RegExp(pattern);
+    return (name) => regex.test(name);
+  } catch {
+    return (name) => name.includes(pattern);
+  }
+}
+
+function handleListOperations(collector, nameFilter, typeFilter) {
+  let operations = collector.getOperations();
+  if (nameFilter) {
+    const filterFn = createNameFilter(nameFilter);
+    operations = operations.filter((op) => filterFn(op.name));
+  }
+  if (typeFilter) {
+    operations = operations.filter((op) => op.type === typeFilter);
+  }
+  return { operations };
+}
+
+function handleGetOperation(collector, name) {
+  const operations = collector.getOperations();
+  const operation = operations.find((op) => op.name === name);
+  if (!operation) {
+    return { operation: null, error: `Operation "${name}" not found` };
+  }
+  return { operation };
+}
+
+function handleGetOperationSource(collector, name, includeDependencies = false) {
+  const operations = collector.getOperations();
+  const operation = operations.find((op) => op.name === name);
+  if (!operation) {
+    return { source: null, error: `Operation "${name}" not found` };
+  }
+  const source = includeDependencies ? operation.sourceFull : operation.source;
+  return { source };
+}
+
+function handleListFragments(collector, nameFilter) {
+  let fragments = collector.getFragments();
+  if (nameFilter) {
+    const filterFn = createNameFilter(nameFilter);
+    fragments = fragments.filter((frag) => filterFn(frag.name));
+  }
+  return { fragments };
+}
+
+function handleGetFragment(collector, name) {
+  const fragment = collector.getFragment(name);
+  if (!fragment) {
+    return { fragment: null, error: `Fragment "${name}" not found` };
+  }
+  return { fragment };
+}
+
+function handleGetFragmentSource(collector, name, includeDependencies = false) {
+  const fragment = collector.getFragment(name);
+  if (!fragment) {
+    return { source: null, error: `Fragment "${name}" not found` };
+  }
+  const source = includeDependencies ? fragment.sourceFull : fragment.source;
+  return { source };
+}
+
+function handleGetFragmentsForType(collector, name) {
+  return { fragments: collector.getFragmentsForType(name) };
+}
+
+function formatType$2(type) {
+  return type.toString();
+}
+function isNonNull(type) {
+  return isNonNullType(type);
+}
+function isList(type) {
+  if (isNonNullType(type)) {
+    return isListType(type.ofType);
+  }
+  return isListType(type);
+}
+function mapField(field) {
+  return {
+    name: field.name,
+    description: field.description || null,
+    type: formatType$2(field.type),
+    isNonNull: isNonNull(field.type),
+    isList: isList(field.type),
+    deprecationReason: "deprecationReason" in field ? field.deprecationReason || null : null
+  };
+}
+function mapEnumValue(value) {
+  return {
+    name: value.name,
+    description: value.description || null
+  };
+}
+function handleGetSchemaType(schema, name) {
+  const type = schema.getType(name);
+  if (!type) {
+    return { type: null, error: `Type "${name}" not found in schema` };
+  }
+  const info = {
+    name: type.name,
+    kind: "UNKNOWN",
+    description: type.description || null,
+    fields: null,
+    enumValues: null,
+    possibleTypes: null,
+    interfaces: null
+  };
+  if (isObjectType(type)) {
+    info.kind = "OBJECT";
+    info.fields = Object.values(type.getFields()).map(mapField);
+    info.interfaces = type.getInterfaces().map((i) => i.name);
+  } else if (isInputObjectType(type)) {
+    info.kind = "INPUT_OBJECT";
+    info.fields = Object.values(type.getFields()).map(mapField);
+  } else if (isEnumType(type)) {
+    info.kind = "ENUM";
+    info.enumValues = type.getValues().map(mapEnumValue);
+  } else if (isUnionType(type)) {
+    info.kind = "UNION";
+    info.possibleTypes = type.getTypes().map((t) => t.name);
+  } else if (isInterfaceType(type)) {
+    info.kind = "INTERFACE";
+    info.fields = Object.values(type.getFields()).map(mapField);
+  } else if (isScalarType(type)) {
+    info.kind = "SCALAR";
+  }
+  return { type: info };
+}
+
+function handleGetSchemaTypeDefinition(schema, name) {
+  const type = schema.getType(name);
+  if (!type) {
+    return { definition: null, error: `Type "${name}" not found in schema` };
+  }
+  return { definition: printType(type) };
+}
+
+function getTypeKind(type) {
+  if (isObjectType(type)) return "OBJECT";
+  if (isInputObjectType(type)) return "INPUT_OBJECT";
+  if (isEnumType(type)) return "ENUM";
+  if (isUnionType(type)) return "UNION";
+  if (isInterfaceType(type)) return "INTERFACE";
+  if (isScalarType(type)) return "SCALAR";
+  return null;
+}
+function handleListSchemaTypes(schema, kind) {
+  const typeMap = schema.getTypeMap();
+  const types = [];
+  for (const [name, type] of Object.entries(typeMap)) {
+    if (name.startsWith("__")) {
+      continue;
+    }
+    const typeKind = getTypeKind(type);
+    if (!typeKind) {
+      continue;
+    }
+    if (kind && typeKind !== kind) {
+      continue;
+    }
+    types.push({
+      name: type.name,
+      kind: typeKind,
+      description: type.description || null
+    });
+  }
+  types.sort((a, b) => a.name.localeCompare(b.name));
+  return { types };
+}
+
+function handleGetTypesImplementingInterface(schema, interfaceName) {
+  const interfaceType = schema.getType(interfaceName);
+  if (!interfaceType) {
+    return {
+      interfaceName,
+      types: [],
+      error: `Type "${interfaceName}" not found in schema`
+    };
+  }
+  if (!isInterfaceType(interfaceType)) {
+    return {
+      interfaceName,
+      types: [],
+      error: `Type "${interfaceName}" is not an interface`
+    };
+  }
+  const implementingTypes = schema.getPossibleTypes(interfaceType);
+  const types = implementingTypes.map((type) => ({
+    name: type.name,
+    description: type.description || null
+  }));
+  types.sort((a, b) => a.name.localeCompare(b.name));
+  return { interfaceName, types };
+}
+
+function handleGetUnionMembers(schema, unionName) {
+  const unionType = schema.getType(unionName);
+  if (!unionType) {
+    return {
+      unionName,
+      members: [],
+      error: `Type "${unionName}" not found in schema`
+    };
+  }
+  if (!isUnionType(unionType)) {
+    return {
+      unionName,
+      members: [],
+      error: `Type "${unionName}" is not a union`
+    };
+  }
+  const memberTypes = unionType.getTypes();
+  const members = memberTypes.map((type) => ({
+    name: type.name,
+    description: type.description || null
+  }));
+  members.sort((a, b) => a.name.localeCompare(b.name));
+  return { unionName, members };
+}
+
+function getNamedType(type) {
+  if (isNonNullType(type) || isListType(type)) {
+    return getNamedType(type.ofType);
+  }
+  return "name" in type ? type.name : "";
+}
+function handleGetTypeUsage(schema, typeName) {
+  const targetType = schema.getType(typeName);
+  if (!targetType) {
+    return {
+      typeName,
+      usages: [],
+      error: `Type "${typeName}" not found in schema`
+    };
+  }
+  const usages = [];
+  const typeMap = schema.getTypeMap();
+  for (const [name, type] of Object.entries(typeMap)) {
+    if (name.startsWith("__")) {
+      continue;
+    }
+    if (isObjectType(type) || isInterfaceType(type)) {
+      const fields = type.getFields();
+      for (const [fieldName, field] of Object.entries(fields)) {
+        const returnTypeName = getNamedType(field.type);
+        if (returnTypeName === typeName) {
+          usages.push({
+            typeName: name,
+            fieldName,
+            usageType: "return_type"
+          });
+        }
+        for (const arg of field.args) {
+          const argTypeName = getNamedType(arg.type);
+          if (argTypeName === typeName) {
+            usages.push({
+              typeName: name,
+              fieldName: `${fieldName}(${arg.name})`,
+              usageType: "argument"
+            });
+          }
+        }
+      }
+    }
+    if (isInputObjectType(type)) {
+      const fields = type.getFields();
+      for (const [fieldName, field] of Object.entries(fields)) {
+        const fieldTypeName = getNamedType(field.type);
+        if (fieldTypeName === typeName) {
+          usages.push({
+            typeName: name,
+            fieldName,
+            usageType: "input_field"
+          });
+        }
+      }
+    }
+  }
+  usages.sort((a, b) => {
+    const typeCompare = a.typeName.localeCompare(b.typeName);
+    if (typeCompare !== 0) return typeCompare;
+    return a.fieldName.localeCompare(b.fieldName);
+  });
+  return { typeName, usages };
+}
+
+function handleGetFieldUsage(collector, schema, typeName, fieldName) {
+  const type = schema.getType(typeName);
+  if (!type) {
+    return {
+      typeName,
+      fieldName,
+      usages: [],
+      error: `Type "${typeName}" not found in schema`
+    };
+  }
+  if (!isObjectType(type) && !isInterfaceType(type)) {
+    return {
+      typeName,
+      fieldName,
+      usages: [],
+      error: `Type "${typeName}" is not an object or interface type`
+    };
+  }
+  const fields = type.getFields();
+  if (!fields[fieldName]) {
+    return {
+      typeName,
+      fieldName,
+      usages: [],
+      error: `Field "${fieldName}" not found on type "${typeName}"`
+    };
+  }
+  const usages = [];
+  const operations = collector.getOperations();
+  const fragments = collector.getFragments();
+  for (const operation of operations) {
+    if (hasFieldUsage(schema, operation.source, typeName, fieldName)) {
+      usages.push({
+        kind: "operation",
+        name: operation.name,
+        filePath: operation.relativeFilePath
+      });
+    }
+  }
+  for (const fragment of fragments) {
+    if (hasFieldUsage(schema, fragment.source, typeName, fieldName)) {
+      usages.push({
+        kind: "fragment",
+        name: fragment.name,
+        filePath: fragment.relativeFilePath
+      });
+    }
+  }
+  return {
+    typeName,
+    fieldName,
+    usages
+  };
+}
+function hasFieldUsage(schema, source, targetTypeName, targetFieldName) {
+  try {
+    const document = parse(source);
+    const typeInfo = new TypeInfo(schema);
+    let found = false;
+    visit(
+      document,
+      visitWithTypeInfo(typeInfo, {
+        Field: {
+          enter(node) {
+            if (found) return;
+            const parentType = typeInfo.getParentType();
+            if (!parentType) return;
+            const parentTypeName = parentType.name;
+            const fieldName = node.name.value;
+            if (parentTypeName === targetTypeName && fieldName === targetFieldName) {
+              found = true;
+              return;
+            }
+            if (isObjectType(parentType)) {
+              const interfaces = parentType.getInterfaces();
+              for (const iface of interfaces) {
+                if (iface.name === targetTypeName && fieldName === targetFieldName) {
+                  const ifaceFields = iface.getFields();
+                  if (ifaceFields[targetFieldName]) {
+                    found = true;
+                    return;
+                  }
+                }
+              }
+            }
+            const targetType = schema.getType(targetTypeName);
+            if (targetType && isObjectType(targetType)) {
+              const targetInterfaces = targetType.getInterfaces();
+              for (const iface of targetInterfaces) {
+                if (parentTypeName === iface.name && fieldName === targetFieldName) {
+                  found = true;
+                  return;
+                }
+              }
+            }
+          }
+        }
+      })
+    );
+    return found;
+  } catch {
+    return false;
+  }
+}
+
+function collectFragmentInfo(documentSource) {
+  const usedFragments = /* @__PURE__ */ new Set();
+  const definedFragments = /* @__PURE__ */ new Set();
+  try {
+    const document = parse(documentSource);
+    visit(document, {
+      FragmentSpread(node) {
+        usedFragments.add(node.name.value);
+      },
+      FragmentDefinition(node) {
+        definedFragments.add(node.name.value);
+      }
+    });
+  } catch {
+  }
+  return { usedFragments, definedFragments };
+}
+function collectRequiredFragments(fragmentNames, collector, collected = /* @__PURE__ */ new Map()) {
+  for (const name of fragmentNames) {
+    if (collected.has(name)) {
+      continue;
+    }
+    const fragment = collector.getFragment(name);
+    if (!fragment) {
+      continue;
+    }
+    collected.set(name, fragment.source);
+    if (fragment.dependencies.length > 0) {
+      collectRequiredFragments(
+        new Set(fragment.dependencies),
+        collector,
+        collected
+      );
+    }
+  }
+  return collected;
+}
+function handleValidateDocument(schema, collector, documentSource) {
+  try {
+    const { usedFragments, definedFragments } = collectFragmentInfo(documentSource);
+    const missingFragments = /* @__PURE__ */ new Set();
+    for (const name of usedFragments) {
+      if (!definedFragments.has(name)) {
+        missingFragments.add(name);
+      }
+    }
+    const requiredFragments = collectRequiredFragments(
+      missingFragments,
+      collector
+    );
+    let fullDocument = documentSource;
+    if (requiredFragments.size > 0) {
+      const fragmentSources = [...requiredFragments.values()].join("\n\n");
+      fullDocument = `${documentSource}
+
+${fragmentSources}`;
+    }
+    const source = new Source(fullDocument, "input");
+    const document = parse(source);
+    const errors = validateGraphQlDocuments(schema, [document]);
+    if (errors.length === 0) {
+      return {
+        valid: true,
+        errors: []
+      };
+    }
+    return {
+      valid: false,
+      errors: errors.map((error) => ({
+        message: error.message,
+        locations: error.locations?.map((loc) => ({
+          line: loc.line,
+          column: loc.column
+        }))
+      }))
+    };
+  } catch (error) {
+    const message = error instanceof Error ? error.message : "Unknown parsing error";
+    const locations = error && typeof error === "object" && "locations" in error && Array.isArray(error.locations) ? error.locations.map((loc) => ({
+      line: loc.line,
+      column: loc.column
+    })) : void 0;
+    return {
+      valid: false,
+      errors: [{ message, locations }]
+    };
+  }
+}
+
+function getMockValueForType$1(typeNode, varName) {
+  if (typeNode.kind === "NonNullType") {
+    return getMockValueForType$1(typeNode.type, varName);
+  }
+  if (typeNode.kind === "ListType") {
+    const innerValue = getMockValueForType$1(typeNode.type, varName);
+    return `[${innerValue}]`;
+  }
+  if (typeNode.kind === "NamedType") {
+    const typeName = typeNode.name.value;
+    switch (typeName) {
+      case "String":
+        return `'${varName}_value'`;
+      case "Int":
+        return "1";
+      case "Float":
+        return "1.0";
+      case "Boolean":
+        return "true";
+      case "ID":
+        return `'${varName}_id'`;
+      default:
+        return `{ /* placeholder for: ${typeName} */ }`;
+    }
+  }
+  return `'${varName}'`;
+}
+function formatType$1(typeNode) {
+  if (typeNode.kind === "NonNullType") {
+    return `${formatType$1(typeNode.type)}!`;
+  }
+  if (typeNode.kind === "ListType") {
+    return `[${formatType$1(typeNode.type)}]`;
+  }
+  if (typeNode.kind === "NamedType") {
+    return typeNode.name.value;
+  }
+  return "unknown";
+}
+function getBaseTypeName$1(typeNode) {
+  if (typeNode.kind === "NonNullType") {
+    return getBaseTypeName$1(typeNode.type);
+  }
+  if (typeNode.kind === "ListType") {
+    return getBaseTypeName$1(typeNode.type);
+  }
+  if (typeNode.kind === "NamedType") {
+    return typeNode.name.value;
+  }
+  return null;
+}
+function extractVariables$1(source) {
+  try {
+    const doc = parse(source);
+    const operation = doc.definitions.find(
+      (def) => def.kind === "OperationDefinition"
+    );
+    if (!operation || operation.kind !== "OperationDefinition") {
+      return [];
+    }
+    const variables = operation.variableDefinitions || [];
+    return variables.map((varDef) => ({
+      name: varDef.variable.name.value,
+      type: formatType$1(varDef.type),
+      mockValue: getMockValueForType$1(varDef.type, varDef.variable.name.value)
+    }));
+  } catch {
+    return [];
+  }
+}
+function extractVariableTypeNames$1(source) {
+  try {
+    const doc = parse(source);
+    const operation = doc.definitions.find(
+      (def) => def.kind === "OperationDefinition"
+    );
+    if (!operation || operation.kind !== "OperationDefinition") {
+      return [];
+    }
+    const typeNames = /* @__PURE__ */ new Set();
+    const variables = operation.variableDefinitions || [];
+    for (const varDef of variables) {
+      const typeName = getBaseTypeName$1(varDef.type);
+      if (typeName) {
+        typeNames.add(typeName);
+      }
+    }
+    return Array.from(typeNames);
+  } catch {
+    return [];
+  }
+}
+function buildImports$1(schema, variablesTypeName, responseTypeName, variableTypeNames, hasVariables) {
+  const imports = [];
+  imports.push({
+    typeName: responseTypeName,
+    description: "Response type for the operation"
+  });
+  if (hasVariables) {
+    imports.push({
+      typeName: variablesTypeName,
+      description: "Variables type for the operation"
+    });
+  }
+  for (const typeName of variableTypeNames) {
+    const schemaType = schema.getType(typeName);
+    if (!schemaType) continue;
+    if (isScalarType(schemaType)) continue;
+    if (isEnumType(schemaType)) {
+      imports.push({
+        typeName,
+        description: `Enum type used in variables`
+      });
+    } else if (isInputObjectType(schemaType)) {
+      imports.push({
+        typeName,
+        description: `Input object type used in variables`
+      });
+    }
+  }
+  return imports;
+}
+function generateExamples$1(operationName, operationType, variables, variablesTypeName, responseTypeName) {
+  const examples = [];
+  const hasVariables = variables.length > 0;
+  const variablesObject = hasVariables ? `{ ${variables.map((v) => `${v.name}: ${v.mockValue}`).join(", ")} }` : "";
+  const variablesObjectIndented = hasVariables ? `{
+    ${variables.map((v) => `${v.name}: ${v.mockValue}`).join(",\n    ")},
+  }` : "";
+  if (operationType === "query") {
+    const transformDescription = `// The type of "graphqlResponse.data" is ${responseTypeName}. Prepare the data here before returning it.`;
+    if (hasVariables) {
+      examples.push({
+        description: COMPOSABLES.useAsyncGraphqlQuery.description,
+        documentationUrl: COMPOSABLES.useAsyncGraphqlQuery.docsUrl,
+        code: `import type { ${variablesTypeName} } from '#graphql-operations'
+
+const variables = computed<${variablesTypeName}>(() => {
+  return ${variablesObjectIndented}
+})
+
+const { data } = await useAsyncGraphqlQuery(
+  '${operationName}',
+  variables,
+  // Same options as useAsyncData.
+  {
+    transform: function (graphqlResponse) {
+      // ${transformDescription}
+      return graphqlResponse.data
+    },
+  },
+)
+
+// data is reactive, data.value is ${responseTypeName} | undefined
+console.log(data.value)`
+      });
+    } else {
+      examples.push({
+        description: COMPOSABLES.useAsyncGraphqlQuery.description,
+        documentationUrl: COMPOSABLES.useAsyncGraphqlQuery.docsUrl,
+        code: `const { data } = await useAsyncGraphqlQuery(
+  '${operationName}',
+  null,
+  // Same options as useAsyncData.
+  {
+    transform: function (graphqlResponse) {
+      // ${transformDescription}
+      return graphqlResponse.data
+    },
+  },
+)
+
+// data is reactive, data.value is ${responseTypeName} | undefined
+console.log(data.value)`
+      });
+    }
+    if (hasVariables) {
+      examples.push({
+        description: COMPOSABLES.useGraphqlQuery.description,
+        documentationUrl: COMPOSABLES.useGraphqlQuery.docsUrl,
+        code: `const response = await useGraphqlQuery('${operationName}', ${variablesObject})
+
+// response.data is ${responseTypeName} | undefined
+console.log(response.data)`
+      });
+    } else {
+      examples.push({
+        description: COMPOSABLES.useGraphqlQuery.description,
+        documentationUrl: COMPOSABLES.useGraphqlQuery.docsUrl,
+        code: `const response = await useGraphqlQuery('${operationName}')
+
+// response.data is ${responseTypeName} | undefined
+console.log(response.data)`
+      });
+    }
+  } else {
+    if (hasVariables) {
+      examples.push({
+        description: COMPOSABLES.useGraphqlMutation.description,
+        documentationUrl: COMPOSABLES.useGraphqlMutation.docsUrl,
+        code: `const response = await useGraphqlMutation('${operationName}', ${variablesObject})
+
+// response.data is ${responseTypeName} | undefined
+console.log(response.data)`
+      });
+    } else {
+      examples.push({
+        description: COMPOSABLES.useGraphqlMutation.description,
+        documentationUrl: COMPOSABLES.useGraphqlMutation.docsUrl,
+        code: `const response = await useGraphqlMutation('${operationName}')
+
+// response.data is ${responseTypeName} | undefined
+console.log(response.data)`
+      });
+    }
+  }
+  return examples;
+}
+function handleGetComposableExamples(collector, schema, operationName) {
+  const operations = collector.getOperations();
+  const operation = operations.find((op) => op.name === operationName);
+  if (!operation) {
+    return { error: `Operation "${operationName}" not found` };
+  }
+  const variables = extractVariables$1(operation.source);
+  const variableTypeNames = extractVariableTypeNames$1(operation.source);
+  const examples = generateExamples$1(
+    operationName,
+    operation.type,
+    variables,
+    operation.variablesTypeName,
+    operation.responseTypeName
+  );
+  const imports = buildImports$1(
+    schema,
+    operation.variablesTypeName,
+    operation.responseTypeName,
+    variableTypeNames,
+    variables.length > 0
+  );
+  return { examples, imports };
+}
+
+function getMockValueForType(typeNode, varName) {
+  if (typeNode.kind === "NonNullType") {
+    return getMockValueForType(typeNode.type, varName);
+  }
+  if (typeNode.kind === "ListType") {
+    const innerValue = getMockValueForType(typeNode.type, varName);
+    return `[${innerValue}]`;
+  }
+  if (typeNode.kind === "NamedType") {
+    const typeName = typeNode.name.value;
+    switch (typeName) {
+      case "String":
+        return `'${varName}_value'`;
+      case "Int":
+        return "1";
+      case "Float":
+        return "1.0";
+      case "Boolean":
+        return "true";
+      case "ID":
+        return `'${varName}_id'`;
+      default:
+        return `{ /* placeholder for: ${typeName} */ }`;
+    }
+  }
+  return `'${varName}'`;
+}
+function formatType(typeNode) {
+  if (typeNode.kind === "NonNullType") {
+    return `${formatType(typeNode.type)}!`;
+  }
+  if (typeNode.kind === "ListType") {
+    return `[${formatType(typeNode.type)}]`;
+  }
+  if (typeNode.kind === "NamedType") {
+    return typeNode.name.value;
+  }
+  return "unknown";
+}
+function getBaseTypeName(typeNode) {
+  if (typeNode.kind === "NonNullType") {
+    return getBaseTypeName(typeNode.type);
+  }
+  if (typeNode.kind === "ListType") {
+    return getBaseTypeName(typeNode.type);
+  }
+  if (typeNode.kind === "NamedType") {
+    return typeNode.name.value;
+  }
+  return null;
+}
+function extractVariables(source) {
+  try {
+    const doc = parse(source);
+    const operation = doc.definitions.find(
+      (def) => def.kind === "OperationDefinition"
+    );
+    if (!operation || operation.kind !== "OperationDefinition") {
+      return [];
+    }
+    const variables = operation.variableDefinitions || [];
+    return variables.map((varDef) => ({
+      name: varDef.variable.name.value,
+      type: formatType(varDef.type),
+      mockValue: getMockValueForType(varDef.type, varDef.variable.name.value)
+    }));
+  } catch {
+    return [];
+  }
+}
+function extractVariableTypeNames(source) {
+  try {
+    const doc = parse(source);
+    const operation = doc.definitions.find(
+      (def) => def.kind === "OperationDefinition"
+    );
+    if (!operation || operation.kind !== "OperationDefinition") {
+      return [];
+    }
+    const typeNames = /* @__PURE__ */ new Set();
+    const variables = operation.variableDefinitions || [];
+    for (const varDef of variables) {
+      const typeName = getBaseTypeName(varDef.type);
+      if (typeName) {
+        typeNames.add(typeName);
+      }
+    }
+    return Array.from(typeNames);
+  } catch {
+    return [];
+  }
+}
+function buildImports(schema, variablesTypeName, responseTypeName, variableTypeNames, hasVariables) {
+  const imports = [];
+  imports.push({
+    typeName: responseTypeName,
+    description: "Response type for the operation"
+  });
+  if (hasVariables) {
+    imports.push({
+      typeName: variablesTypeName,
+      description: "Variables type for the operation"
+    });
+  }
+  for (const typeName of variableTypeNames) {
+    const schemaType = schema.getType(typeName);
+    if (!schemaType) continue;
+    if (isScalarType(schemaType)) continue;
+    if (isEnumType(schemaType)) {
+      imports.push({
+        typeName,
+        description: `Enum type used in variables`
+      });
+    } else if (isInputObjectType(schemaType)) {
+      imports.push({
+        typeName,
+        description: `Input object type used in variables`
+      });
+    }
+  }
+  return imports;
+}
+function generateExamples(operationName, operationType, variables, responseTypeName) {
+  const examples = [];
+  const hasVariables = variables.length > 0;
+  const variablesObject = hasVariables ? `{ ${variables.map((v) => `${v.name}: ${v.mockValue}`).join(", ")} }` : "";
+  if (operationType === "query") {
+    if (hasVariables) {
+      examples.push({
+        description: SERVER_UTILS.useGraphqlQuery.description,
+        documentationUrl: SERVER_UTILS.useGraphqlQuery.docsUrl,
+        code: `export default defineEventHandler(async (event) => {
+  const response = await useGraphqlQuery('${operationName}', ${variablesObject})
+
+  // response.data is ${responseTypeName} | undefined
+  return response.data
+})`
+      });
+    } else {
+      examples.push({
+        description: SERVER_UTILS.useGraphqlQuery.description,
+        documentationUrl: SERVER_UTILS.useGraphqlQuery.docsUrl,
+        code: `export default defineEventHandler(async (event) => {
+  const response = await useGraphqlQuery('${operationName}')
+
+  // response.data is ${responseTypeName} | undefined
+  return response.data
+})`
+      });
+    }
+  } else {
+    if (hasVariables) {
+      examples.push({
+        description: SERVER_UTILS.useGraphqlMutation.description,
+        documentationUrl: SERVER_UTILS.useGraphqlMutation.docsUrl,
+        code: `export default defineEventHandler(async (event) => {
+  const response = await useGraphqlMutation('${operationName}', ${variablesObject})
+
+  // response.data is ${responseTypeName} | undefined
+  return response.data
+})`
+      });
+    } else {
+      examples.push({
+        description: SERVER_UTILS.useGraphqlMutation.description,
+        documentationUrl: SERVER_UTILS.useGraphqlMutation.docsUrl,
+        code: `export default defineEventHandler(async (event) => {
+  const response = await useGraphqlMutation('${operationName}')
+
+  // response.data is ${responseTypeName} | undefined
+  return response.data
+})`
+      });
+    }
+  }
+  examples.push({
+    description: SERVER_UTILS.doGraphqlRequest.description,
+    documentationUrl: SERVER_UTILS.doGraphqlRequest.docsUrl,
+    code: `export default defineEventHandler(async (event) => {
+  // Use doGraphqlRequest for raw GraphQL requests with custom query strings
+  const response = await doGraphqlRequest({
+    query: \`
+      ${operationType} ${operationName}${hasVariables ? `(${variables.map((v) => `$${v.name}: ${v.type}`).join(", ")})` : ""} {
+        # Your query fields here
+      }
+    \`,${hasVariables ? `
+    variables: ${variablesObject},` : ""}
+    operationName: '${operationName}',
+  })
+
+  return response.data
+})`
+  });
+  return examples;
+}
+function handleGetServerUtilsExamples(collector, schema, operationName) {
+  const operations = collector.getOperations();
+  const operation = operations.find((op) => op.name === operationName);
+  if (!operation) {
+    return { error: `Operation "${operationName}" not found` };
+  }
+  const variables = extractVariables(operation.source);
+  const variableTypeNames = extractVariableTypeNames(operation.source);
+  const examples = generateExamples(
+    operationName,
+    operation.type,
+    variables,
+    operation.responseTypeName
+  );
+  const imports = buildImports(
+    schema,
+    operation.variablesTypeName,
+    operation.responseTypeName,
+    variableTypeNames,
+    variables.length > 0
+  );
+  return { examples, imports };
+}
+
+function makeRelative(rootDir, path) {
+  if (!path) {
+    return null;
+  }
+  if (isAbsolute(path)) {
+    const rel = relative$1(rootDir, path);
+    if (!rel.startsWith(".")) {
+      return "./" + rel;
+    }
+    return rel;
+  }
+  if (!path.startsWith(".")) {
+    return "./" + path;
+  }
+  return path;
+}
+function handleGetModuleConfig(helper) {
+  const rootDir = helper.nuxt.options.rootDir;
+  return {
+    autoImportPatterns: (helper.options.autoImportPatterns || []).map(
+      (pattern) => makeRelative(rootDir, pattern)
+    ),
+    paths: {
+      runtimeTypes: makeRelative(rootDir, helper.paths.runtimeTypes),
+      schema: makeRelative(rootDir, helper.paths.schema),
+      serverOptions: makeRelative(rootDir, helper.paths.serverOptions),
+      clientOptions: makeRelative(rootDir, helper.paths.clientOptions),
+      documentTypes: makeRelative(
+        rootDir,
+        helper.paths.moduleTypesDir + "/index.d.ts"
+      )
+    }
+  };
+}
+
+function requireName(body) {
+  const name = body.name;
+  if (!name) {
+    throw createError({
+      statusCode: 400,
+      message: 'Missing "name" parameter in request body'
+    });
+  }
+  return name;
+}
+function createMcpDevHandler(collector, schemaProvider, helper) {
+  return defineEventHandler(async (event) => {
+    const body = await readBody(event);
+    const tool = body?.tool;
+    if (!tool) {
+      throw createError({
+        statusCode: 400,
+        message: 'Missing "tool" parameter in request body'
+      });
+    }
+    switch (tool) {
+      // Operation tools
+      case "operations-list":
+        return handleListOperations(
+          collector,
+          body.nameFilter,
+          body.type
+        );
+      case "operations-get":
+        return handleGetOperation(collector, requireName(body));
+      case "operations-get-source":
+        return handleGetOperationSource(
+          collector,
+          requireName(body),
+          body.includeDependencies
+        );
+      // Fragment tools
+      case "fragments-list":
+        return handleListFragments(
+          collector,
+          body.nameFilter
+        );
+      case "fragments-get":
+        return handleGetFragment(collector, requireName(body));
+      case "fragments-get-source":
+        return handleGetFragmentSource(
+          collector,
+          requireName(body),
+          body.includeDependencies
+        );
+      case "fragments-list-for-type":
+        return handleGetFragmentsForType(collector, requireName(body));
+      // Schema tools
+      case "schema-get-type":
+        return handleGetSchemaType(
+          schemaProvider.getSchema(),
+          requireName(body)
+        );
+      case "schema-get-type-definition":
+        return handleGetSchemaTypeDefinition(
+          schemaProvider.getSchema(),
+          requireName(body)
+        );
+      case "schema-list-types":
+        return handleListSchemaTypes(
+          schemaProvider.getSchema(),
+          body.kind
+        );
+      case "schema-get-interface-implementors":
+        return handleGetTypesImplementingInterface(
+          schemaProvider.getSchema(),
+          requireName(body)
+        );
+      case "schema-get-union-members":
+        return handleGetUnionMembers(
+          schemaProvider.getSchema(),
+          requireName(body)
+        );
+      case "schema-get-type-usage":
+        return handleGetTypeUsage(schemaProvider.getSchema(), requireName(body));
+      case "operations-get-field-usage":
+        return handleGetFieldUsage(
+          collector,
+          schemaProvider.getSchema(),
+          body.typeName,
+          body.fieldName
+        );
+      case "schema-validate-document":
+        return handleValidateDocument(
+          schemaProvider.getSchema(),
+          collector,
+          body.document
+        );
+      // Composable examples tool
+      case "vue-graphql-composable-example":
+        return handleGetComposableExamples(
+          collector,
+          schemaProvider.getSchema(),
+          requireName(body)
+        );
+      // Server utils examples tool
+      case "nitro-graphql-server-utils-example":
+        return handleGetServerUtilsExamples(
+          collector,
+          schemaProvider.getSchema(),
+          requireName(body)
+        );
+      // Module config tool
+      case "module-get-config":
+        return handleGetModuleConfig(helper);
+      default:
+        throw createError({
+          statusCode: 400,
+          message: `Unknown tool: ${tool}`
+        });
+    }
+  });
+}
+
+const module$1 = defineNuxtModule({
   meta: {
     name,
     configKey: "graphqlMiddleware",
@@ -1783,22 +3225,36 @@ const module = defineNuxtModule({
         collector.addTemplate(template);
       }
     });
-    helper.applyBuildConfig();
+    if (helper.isDev) {
+      const devModeHandler = new DevModeHandler(
+        nuxt,
+        schemaProvider,
+        collector,
+        helper
+      );
+      devModeHandler.init();
+    }
+    const mcpToolkitInstalled = nuxt.options.modules.some(
+      (v) => v === "@nuxtjs/mcp-toolkit"
+    );
+    if (helper.isDev && mcpToolkitInstalled && helper.options.mcp.enabled) {
+      nuxt.hook("mcp:definitions:paths", (paths) => {
+        const mcpPath = helper.resolvers.module.resolve("./runtime/server/mcp");
+        paths.handlers ||= [];
+        paths.handlers.push(mcpPath);
+      });
+      addDevServerHandler({
+        route: "/__nuxt_graphql_middleware/mcp",
+        handler: createMcpDevHandler(collector, schemaProvider, helper)
+      });
+      helper.addServerHandler("doRequest", "/do-request", "post");
+    }
     nuxt.hooks.hookOnce("modules:done", async () => {
       await nuxt.hooks.callHook("nuxt-graphql-middleware:init", moduleContext);
       await collector.init();
     });
-    if (!helper.isDev) {
-      return;
-    }
-    const devModeHandler = new DevModeHandler(
-      nuxt,
-      schemaProvider,
-      collector,
-      helper
-    );
-    devModeHandler.init();
+    helper.applyBuildConfig();
   }
 });
 
-export { module as default };
+export { module$1 as default };