@wix/mcp 1.0.81 → 1.0.83

package/build/dts/bin.d.ts

@@ -1,6 +1,6 @@
 import './infra/sentry.js';
 declare const PUBLIC_TOOLS: readonly ["WDS", "REST", "SDK", "BUILD_APPS", "WIX_HEADLESS", "VELO", "BUSINESS_SOLUTIONS", "CLI", "OVERVIEW"];
-declare const EXPERIMENTAL_TOOLS: readonly ["WIX_API", "CLI_COMMAND", "GET_TO_KNOW_WIX", "CREATE_WIX_BUSINESS_GUIDE", "VELO_README", "WIX_API_THROUGH_FS"];
+declare const EXPERIMENTAL_TOOLS: readonly ["WIX_API", "CLI_COMMAND", "GET_TO_KNOW_WIX", "CREATE_WIX_BUSINESS_GUIDE", "VELO_README", "WIX_API_THROUGH_FS", "GRAPHQL"];
 type Tool = (typeof PUBLIC_TOOLS)[number] | (typeof EXPERIMENTAL_TOOLS)[number];
 export declare const DEFAULT_TOOLS: Tool[];
 export {};

package/build/dts/bin.js

@@ -15,6 +15,7 @@ import { addVeloReadmeTools } from './docs/velo-readme.js';
 import { getCliAuthToken } from './cli-tools/utils.js';
 import { TokenStore } from './cli-tools/account-token-store.js';
 import { createAccountFileAuthStrategy } from './cli-tools/account-auth-strategy.js';
+import { addGraphqlTools } from './graphql/index.js';
 const PUBLIC_TOOLS = [...VALID_DOCS_TOOLS];
 const EXPERIMENTAL_TOOLS = [
     'WIX_API',
@@ -22,7 +23,8 @@ const EXPERIMENTAL_TOOLS = [
     'GET_TO_KNOW_WIX',
     'CREATE_WIX_BUSINESS_GUIDE',
     'VELO_README',
-    'WIX_API_THROUGH_FS'
+    'WIX_API_THROUGH_FS',
+    'GRAPHQL'
 ];
 export const DEFAULT_TOOLS = [...VALID_DOCS_TOOLS];
 const parsedArgs = minimist(process.argv.slice(2));
@@ -139,6 +141,7 @@ if (cliTools.length > 0) {
         }
     }
 }
+let cliAccountAuthStrategy;
 // When `--wixCliAuth` is passed, register the auth-requiring tools using the
 // OAuth token written by `npx @wix/cli login` at ~/.wix/auth/account.json.
 // Refreshes the access token transparently when it nears expiry.
@@ -152,6 +155,15 @@ if (isWixCliAuth) {
     const tokens = new TokenStore({ accountFile });
     const accountAuthStrategy = createAccountFileAuthStrategy({ tokens });
     addApiCallTool(server, accountAuthStrategy);
+    cliAccountAuthStrategy = accountAuthStrategy;
+}
+// Experimental: Wix GraphQL tools. Schema search/inspection need no auth;
+// ExecuteWixGraphQL registers only when --wixCliAuth supplies credentials.
+if (activeTools.includes('GRAPHQL')) {
+    logger.log('Adding GraphQL tools', {
+        execute: Boolean(cliAccountAuthStrategy)
+    });
+    addGraphqlTools(server, { authStrategy: cliAccountAuthStrategy });
 }
 try {
     const portals = parsedArgs['portals']?.split(',') || [];

package/build/dts/config/default-config.d.ts

@@ -19,6 +19,7 @@ export interface ModeDefaultConfig {
     partnerContextEnabled?: boolean;
     usePlatformizedSearch?: boolean;
     skillsPrOverrideEnabled?: boolean;
+    graphqlEnabled?: boolean;
 }
 export declare const SYSTEM_REMINDER_GUIDELINES: string;
 export declare function buildSystemReminder(includeReadme: boolean, includeImageUploadGuidance?: boolean): string;

package/build/dts/config/default-config.js

@@ -80,6 +80,8 @@ export const SITE_CREATION_COPY = {
 const SITE_GUIDANCE = dedent `
   A new-site request has two things to settle: what the site is for, and how to build it. The how is AI generation vs. starting from a template, so naming templates, a template id or Wix Studio (Wix Studio is also the template side) already settles it.
 
+  One case skips all of this: the user ALREADY HAS the finished site as files — hand-written HTML/CSS/JS, a zip, or the export of an AI builder. There is nothing to build, so don't offer AI or templates and don't call any site-creation tool. Send them to https://www.wix.com/headless/drop?utm_campaign=mcp — they drag the files in and get a live Wix-hosted site. Give that URL exactly as written, keeping the utm_campaign=mcp parameter.
+
   Settle what the site is for first: its purpose, topic, business type, audience, or main visitor action. Naming a method is not a description of the site, and neither is the business or industry on its own.
   If you can't tell yet, ask the preferred question below and nothing else — one question, no creation-method question in the same reply, and no internal tool names.
   Once the purpose is clear, unless the user already named a method, ${SITE_CREATION_COPY.unstatedMethod.nonWidget}. A method they named is settled — never re-open it. Never default to AI or to templates, and never ask the user to choose between Harmony and Wix Studio; infer that from their words.
@@ -412,7 +414,8 @@ export function buildToolDescriptions(includeReadme, includeImageUploadGuidance
     After calling, you MUST speak the message provided in the tool result to the user as your reply — do not stay silent and do not replace it with a one-line pointer to the widget. Write out ALL of it, word for word: its opening line (the "Ready to set up your … site?" question INCLUDING "Choose your path in the widget above:"), BOTH of its option bullets, and its "Next up:" line, each on its own line and in that order. Do not summarize, shorten, drop any line, invent your own opener, rename the options, or add an intro or outro.
   `,
         'import-claude-design-from-url': dedent `
-    Import a design into Wix from a publicly fetchable URL. The file is a self-contained HTML bundle with all images, fonts, and styles inlined. Creates a live Wix-hosted site and returns its URL.
+    Import a design created in Claude's design tool into Wix. Takes the signed claudeusercontent.com URL Claude Design produces for its self-contained HTML bundle (all images, fonts, and styles inlined); any other host is rejected. Creates a live Wix-hosted site and returns its URL.
+    NOT for site files the user provides themselves (their own HTML/CSS/JS, a zip, another builder's export) — for those, don't call this tool: send the user to https://www.wix.com/headless/drop?utm_campaign=mcp, where they upload the files and get a live hosted site. Give that URL exactly as written, keeping the utm_campaign=mcp parameter.
   `,
         RunWixCliCommand: dedent `
     Executes Wix CLI commands for Wix app development and management.
@@ -809,10 +812,37 @@ export function buildToolDescriptions(includeReadme, includeImageUploadGuidance
 
     Call this when the user provides a specific template by \`metaSiteId\` or \`templateId\`. Use this only when the user gives a valid \`metaSiteId\` or \`templateId\` directly. To browse or choose a template first, call \`SearchSiteTemplates\`.
 
+  `,
+        SearchWixGraphQLOperations: dedent `
+    Discover Wix GraphQL operations by intent (ranked keyword search over the root fields). Wix exposes ONE GraphQL schema over all Wix public APIs (Developer Preview) at POST https://www.wixapis.com/graphql/alpha: about 100 query roots and 580 mutation roots named <app><Service><Version><Verb/Entity>, e.g. \`storesProductsV3V3Products\`, \`crmContactsV4Contacts\`, \`crmContactsV4CreateContact\`, \`ecomOrdersV1SearchOrders\`.
+
+    GraphQL flow (3 steps, keep to it): SearchWixGraphQLOperations (find the operation) -> InspectWixGraphQLSchema (read its exact input and return types) -> ExecuteWixGraphQL (run it). Never write an operation or field name you did not see in one of these results.
+
+    When to prefer GraphQL over the REST tools:
+    - Reading several related entities in ONE round-trip: related entities are resolved fields (product -> inventoryItems / collections, order -> fulfillments, booking -> contact), and independent root fields (products + contacts + orders) can share one request.
+    - Picking exactly the fields you need, so responses stay small.
+    - Answering "how many / list / show" questions: a query root plus \`pageInfo\` (\`hasNext\`, and \`total\` where the API provides it).
+    Prefer the REST tools when a recipe or code example already gives you the exact REST call, for uploads/media, or when the GraphQL schema has no matching operation.
+
+    Conventions: query roots take \`queryInput\`; list roots (plural names) take \`queryInput: { query: { paging | cursorPaging, filter, sort } }\` and return \`{ items, pageInfo }\`; singular roots take the entity id. \`filter\`/\`sort\` are a JSON scalar in REST filter syntax (e.g. {"info.name.first": {"$eq": "Ada"}}) — pass them as variables. Mutations take \`input\`; a few read operations (search/list) are exposed as mutations, so search kind "all" unless you are sure.
+    Results list \`kind name(arg: InputType): ReturnType\` plus a one-line description; pass the chosen name to InspectWixGraphQLSchema next.
+  `,
+        InspectWixGraphQLSchema: dedent `
+    Read the exact Wix GraphQL schema for an operation and its types, as compact SDL with field descriptions. Pass \`operation\` (a root query/mutation name from SearchWixGraphQLOperations) to get its arguments, input type and return type expanded \`depth\` levels (default 2). Types that were referenced but not expanded are listed at the end — pass the ones you need in \`typeNames\` (optionally together with \`operation\`) instead of raising depth for everything.
+    Use it before every ExecuteWixGraphQL call that introduces a new operation or new fields: read the INPUT type before writing a mutation or filter, and the RETURN type before writing the selection set. GraphQL rejects unknown fields and arguments, and every object-typed field needs its own selection set. \`JSON\` scalar fields (filter, sort, free-form data) accept any JSON — pass them as variables. Never guess a type or field name; if a validation error names a field, come back here.
+  `,
+        ExecuteWixGraphQL: dedent `
+    Execute a GraphQL query or mutation against the Wix GraphQL API (POST https://www.wixapis.com/graphql/alpha) with the user's credentials. Authentication is injected — never add Authorization or site/account headers.
+    Site targeting: site-level operations (anything that reads or writes inside a site: products, inventory, orders, contacts, bookings, CMS data, blog, members ...) require \`siteId\`; resolve it with GetSiteContext or ListWixSites first. Use \`scope: "account"\` only for account-level operations.
+    Grounding: every root field, argument and selected field must come from SearchWixGraphQLOperations / InspectWixGraphQLSchema results in this conversation — never from memory. If the response says "Cannot query field" or "Unknown argument", re-inspect the schema and fix the name; do not retry with another guess.
+    Compose: put independent reads in one document as several root fields, and use related-entity fields (e.g. \`inventoryItems\`, \`collections\`, \`fulfillments\`) instead of extra round-trips. Select only the fields you need; every object field needs a selection set. Variables: use them for \`JSON\` scalars (filter, sort) and plain scalars (String, Int, ID), declared in the document (e.g. \`query Q($f: JSON) { ... filter: $f ... }\`). Write mutation inputs and any object that contains an enum INLINE as GraphQL literals with enum values unquoted (e.g. \`input: { product: { name: "Mug", productType: PHYSICAL } }\`) — this endpoint fails with 503 when an enum value arrives inside an object-typed variable. For lists page with \`cursorPaging\` or \`paging\` exactly as the input type declares (never the other one), and request \`pageInfo { hasNext total }\`; \`total\` is only populated with offset \`paging\`, so for a cursor-paged list count by walking pages or use a count operation.
+    Results: each root field fails independently — \`errors[].path\` names the failing field and \`errors[].extensions.message\` the cause (e.g. PERMISSION_DENIED); \`data\` still holds the fields that succeeded. Mutations return the created/updated entity — read the IDs from it and do not re-query to verify. Large results are truncated: narrow the selection or page size instead of re-running.
+    Set \`hasMutations: true\` for any document containing a mutation root field.
   `,
         CreateWixBusinessGuide: dedent `
     Provides comprehensive documentation for creating a new Wix business (site, app, etc.).
     Call this ONLY when the user explicitly asks for a headless site, a Wix Classic Editor site, or manual/advanced account/API-based site creation — these don't need the site's purpose first. For normal site-creation ${SITE_CREATION_COPY.normalCreationRoute.nonWidget}; for a specific template id, call \`CreateSiteFromTemplate\`.
+    Exception, even when the user says "headless": if they ALREADY HAVE the finished site as files (their own HTML/CSS/JS, a zip, an AI-builder export) and want those files hosted, don't call this tool — send them to https://www.wix.com/headless/drop?utm_campaign=mcp to upload the files and get a live hosted site (give that URL exactly, keeping the utm_campaign=mcp parameter). This guide's CLI flow is for BUILDING a headless frontend, not for hosting ready-made files.
 
     ## What This Tool Contains
 
@@ -945,7 +975,8 @@ export function mergeConfig(base, overrides) {
         dynamicContextEnabled: overrides.dynamicContextEnabled ?? base.dynamicContextEnabled,
         partnerContextEnabled: overrides.partnerContextEnabled ?? base.partnerContextEnabled,
         usePlatformizedSearch: overrides.usePlatformizedSearch ?? base.usePlatformizedSearch,
-        skillsPrOverrideEnabled: overrides.skillsPrOverrideEnabled ?? base.skillsPrOverrideEnabled
+        skillsPrOverrideEnabled: overrides.skillsPrOverrideEnabled ?? base.skillsPrOverrideEnabled,
+        graphqlEnabled: overrides.graphqlEnabled ?? base.graphqlEnabled
     };
 }
 /**

package/build/dts/config/param-descriptions.d.ts

@@ -90,6 +90,27 @@ export declare const paramDescriptions: {
         mimeType: string;
         displayName: string;
     };
+    SearchWixGraphQLOperations: {
+        query: string;
+        kind: string;
+        maxResults: string;
+        reason: string;
+    };
+    InspectWixGraphQLSchema: {
+        operation: string;
+        typeNames: string;
+        depth: string;
+        reason: string;
+    };
+    ExecuteWixGraphQL: {
+        query: string;
+        variables: string;
+        operationName: string;
+        siteId: string;
+        scope: string;
+        hasMutations: string;
+        reason: string;
+    };
     RunWixCliCommand: {
         appPath: string;
         extensionType: string;

package/build/dts/config/param-descriptions.js

@@ -127,6 +127,27 @@ export const paramDescriptions = {
         mimeType: 'MIME type of the image (e.g. "image/jpeg", "image/png", "image/webp"). Required when imageBase64 does not include a data URL prefix.',
         displayName: 'Optional display name for the file in Media Manager. If not provided, uses the original filename.'
     },
+    SearchWixGraphQLOperations: {
+        query: 'Free-text intent or entity, e.g. "products with inventory", "create contact", "orders", "blog posts", "booking services". Operation names encode app + service + version + verb/entity (e.g. storesProductsV3V3Products, crmContactsV4CreateContact), so a noun plus a verb (query/get/create/update/delete) ranks best. You may also pass an exact operation name.',
+        kind: 'Restrict to "query" (reads), "mutation" (writes — note a few reads such as search/list calls are exposed as mutations), or "all" (default).',
+        maxResults: 'Maximum number of operations to return (default 10, max 50).',
+        reason: 'One sentence describing the original user request and why you are looking for a GraphQL operation.'
+    },
+    InspectWixGraphQLSchema: {
+        operation: 'Exact root query or mutation name from SearchWixGraphQLOperations (e.g. "crmContactsV4Contacts"). Returns its arguments, input type and return type as compact SDL, expanded `depth` levels.',
+        typeNames: 'Type names to expand, e.g. ones listed as "Not expanded" in a previous result, or a nested input/object/enum type you need before writing the request. Can be combined with `operation`.',
+        depth: 'How many levels of referenced types to expand (1-4, default 2). Level 1 is the given types, level 2 the types their fields reference, and so on. Keep it small and expand specific types with typeNames instead of dumping everything.',
+        reason: 'One sentence describing the original user request and why you need this part of the GraphQL schema.'
+    },
+    ExecuteWixGraphQL: {
+        query: 'The GraphQL document (a query or a mutation). Every root field, argument and selected field MUST come from SearchWixGraphQLOperations / InspectWixGraphQLSchema results in this conversation, never from memory. Declare variables for filters, sort and large inputs, e.g. `query Q($f: JSON) { crmContactsV4Contacts(queryInput: { query: { filter: $f, paging: { limit: 50 } } }) { items { id } pageInfo { hasNext } } }`. Object-typed fields need a selection set. You can put several independent root fields in one document.',
+        variables: 'Variables object for the document, as a JSON object (not a string). Use it for JSON-scalar filters/sort (REST filter syntax, e.g. {"info.name.first": {"$eq": "Ada"}}) and plain scalars. Do NOT pass object inputs that contain enum values (product types, statuses, registration types ...) through variables — write those inline in the document with the enum unquoted; the endpoint returns 503 otherwise.',
+        operationName: 'Operation to run when the document defines more than one named operation.',
+        siteId: 'The Wix site to run against. Required for site-level operations (anything reading or writing inside a site — products, orders, contacts, bookings, CMS, blog, members ...). Resolve it with GetSiteContext or ListWixSites; never pass a guessed value.',
+        scope: '"site" (default when siteId is given) runs with a site-scoped credential; "account" runs account-level operations (sites, account settings) and ignores siteId.',
+        hasMutations: 'Whether this document creates, updates, deletes or otherwise mutates Wix data. True for any mutation root field (in any operation of the document) even when the intent is inspection; false only for pure queries. This flag alone decides whether a transient server error may be retried, so never mark a document that writes as false.',
+        reason: 'One sentence explaining the original user request and why you are running this GraphQL operation to complete it.'
+    },
     RunWixCliCommand: {
         appPath: 'The full path to the Wix CLI app to run the command on.',
         extensionType: 'The type of extension to generate. You MUST provide this for commands that generate extensions.',

package/build/dts/graphql/constants.d.ts

@@ -0,0 +1,8 @@
+/** Wix "Auto GraphQL": one schema generated over all Wix public APIs. */
+export declare const WIX_GRAPHQL_ENDPOINT = "https://www.wixapis.com/graphql/alpha";
+export declare const SEARCH_GRAPHQL_TOOL_NAME = "SearchWixGraphQLOperations";
+export declare const INSPECT_GRAPHQL_TOOL_NAME = "InspectWixGraphQLSchema";
+export declare const EXECUTE_GRAPHQL_TOOL_NAME = "ExecuteWixGraphQL";
+export declare const GRAPHQL_TOOL_NAMES: readonly ["SearchWixGraphQLOperations", "InspectWixGraphQLSchema", "ExecuteWixGraphQL"];
+export type GraphqlToolName = (typeof GRAPHQL_TOOL_NAMES)[number];
+//# sourceMappingURL=constants.d.ts.map

package/build/dts/graphql/constants.js

@@ -0,0 +1,11 @@
+/** Wix "Auto GraphQL": one schema generated over all Wix public APIs. */
+export const WIX_GRAPHQL_ENDPOINT = 'https://www.wixapis.com/graphql/alpha';
+export const SEARCH_GRAPHQL_TOOL_NAME = 'SearchWixGraphQLOperations';
+export const INSPECT_GRAPHQL_TOOL_NAME = 'InspectWixGraphQLSchema';
+export const EXECUTE_GRAPHQL_TOOL_NAME = 'ExecuteWixGraphQL';
+export const GRAPHQL_TOOL_NAMES = [
+    SEARCH_GRAPHQL_TOOL_NAME,
+    INSPECT_GRAPHQL_TOOL_NAME,
+    EXECUTE_GRAPHQL_TOOL_NAME
+];
+//# sourceMappingURL=constants.js.map

package/build/dts/graphql/index.d.ts

@@ -0,0 +1,30 @@
+import type { WixMcpServer } from '../wix-mcp-server.js';
+import { type McpAuthenticationStrategy } from '../auth/index.js';
+import { type FetchLike } from './introspection.js';
+export { EXECUTE_GRAPHQL_TOOL_NAME, GRAPHQL_TOOL_NAMES, INSPECT_GRAPHQL_TOOL_NAME, SEARCH_GRAPHQL_TOOL_NAME, WIX_GRAPHQL_ENDPOINT, type GraphqlToolName } from './constants.js';
+export { resetGraphqlSchemaCache } from './introspection.js';
+export interface GraphqlToolsOptions {
+    /**
+     * Auth for ExecuteWixGraphQL. Without it only the two schema tools
+     * (introspection needs no auth) are registered.
+     */
+    authStrategy?: McpAuthenticationStrategy;
+    disableTools?: string[];
+    toolDescriptions?: Record<string, string>;
+    /** Max response size in chars before truncation (default: 24,000). */
+    maxResponseSize?: number;
+    /** Override the GraphQL endpoint (tests / other environments). */
+    endpoint?: string;
+    /** Override fetch (tests). */
+    fetchImpl?: FetchLike;
+    /** Backoff schedule for transient 5xx from the endpoint (tests pass []). */
+    retryDelaysMs?: number[];
+}
+/**
+ * Register the Wix GraphQL tools. Progressive disclosure over one ~4MB schema:
+ *   SearchWixGraphQLOperations (rank root operations for an intent)
+ *   → InspectWixGraphQLSchema (exact input/return types, expanded on demand)
+ *   → ExecuteWixGraphQL (run the query/mutation with the caller's auth).
+ */
+export declare function addGraphqlTools(server: WixMcpServer, options?: GraphqlToolsOptions): void;
+//# sourceMappingURL=index.d.ts.map

package/build/dts/graphql/index.js

@@ -0,0 +1,259 @@
+import { z } from 'zod';
+import { logger } from '../infra/logger.js';
+import { defaultToolDescriptions } from '../config/default-config.js';
+import { desc } from '../config/param-descriptions.js';
+import { truncateResponse } from '../code-mode/truncate-response.js';
+import { rethrowIfUnauthorized } from '../auth/index.js';
+import { EXECUTE_GRAPHQL_TOOL_NAME, INSPECT_GRAPHQL_TOOL_NAME, SEARCH_GRAPHQL_TOOL_NAME, WIX_GRAPHQL_ENDPOINT } from './constants.js';
+import { expandTypes, fetchWithRetry, getRootOperations, namedType, renderOperationSignature } from './introspection.js';
+import { searchOperations } from './search.js';
+export { EXECUTE_GRAPHQL_TOOL_NAME, GRAPHQL_TOOL_NAMES, INSPECT_GRAPHQL_TOOL_NAME, SEARCH_GRAPHQL_TOOL_NAME, WIX_GRAPHQL_ENDPOINT } from './constants.js';
+export { resetGraphqlSchemaCache } from './introspection.js';
+const textResult = (text) => ({
+    content: [{ type: 'text', text }]
+});
+const errorResult = (text) => ({
+    isError: true,
+    content: [{ type: 'text', text }]
+});
+const SCHEMA_MAX_RESPONSE_CHARS = 48_000;
+/**
+ * Register the Wix GraphQL tools. Progressive disclosure over one ~4MB schema:
+ *   SearchWixGraphQLOperations (rank root operations for an intent)
+ *   → InspectWixGraphQLSchema (exact input/return types, expanded on demand)
+ *   → ExecuteWixGraphQL (run the query/mutation with the caller's auth).
+ */
+export function addGraphqlTools(server, options = {}) {
+    const { authStrategy, disableTools = [], toolDescriptions } = options;
+    const getDescription = (name) => toolDescriptions?.[name] ?? defaultToolDescriptions[name];
+    if (!disableTools.includes(SEARCH_GRAPHQL_TOOL_NAME)) {
+        addSearchGraphqlTool(server, getDescription(SEARCH_GRAPHQL_TOOL_NAME), options);
+    }
+    if (!disableTools.includes(INSPECT_GRAPHQL_TOOL_NAME)) {
+        addInspectGraphqlTool(server, getDescription(INSPECT_GRAPHQL_TOOL_NAME), options);
+    }
+    if (authStrategy && !disableTools.includes(EXECUTE_GRAPHQL_TOOL_NAME)) {
+        addExecuteGraphqlTool(server, getDescription(EXECUTE_GRAPHQL_TOOL_NAME), authStrategy, options);
+    }
+}
+function introspectionOptions(options) {
+    return {
+        endpoint: options.endpoint,
+        fetchImpl: options.fetchImpl,
+        retryDelaysMs: options.retryDelaysMs
+    };
+}
+function addSearchGraphqlTool(server, description, options) {
+    const d = desc('SearchWixGraphQLOperations');
+    server.tool(SEARCH_GRAPHQL_TOOL_NAME, description, {
+        query: z.string().describe(d.query),
+        kind: z.enum(['query', 'mutation', 'all']).optional().describe(d.kind),
+        maxResults: z
+            .number()
+            .int()
+            .min(1)
+            .max(50)
+            .optional()
+            .describe(d.maxResults),
+        reason: z.string().describe(d.reason)
+    }, { readOnlyHint: true, destructiveHint: false, openWorldHint: false }, async ({ query, kind, maxResults, reason }) => {
+        logger.log(`[${SEARCH_GRAPHQL_TOOL_NAME}] query="${query}" kind=${kind ?? 'all'} reason="${reason}"`);
+        try {
+            const ops = await getRootOperations(introspectionOptions(options));
+            const matches = searchOperations(ops, query, {
+                kind: kind ?? 'all',
+                maxResults: maxResults ?? 10
+            });
+            if (matches.length === 0) {
+                return textResult(`No GraphQL operations matched "${query}". Try other words for the entity (e.g. "contact" instead of "customer", "product" instead of "item") or the verb (query/get/create/update/delete), or search a single noun.`);
+            }
+            const lines = matches.map((m, i) => `${i + 1}. ${m.kind} ${m.signature}\n   ${m.description || '(no description)'}`);
+            const text = [
+                `Top ${matches.length} of ${ops.length} Wix GraphQL root operations for "${query}":`,
+                '',
+                ...lines,
+                '',
+                `Next: call ${INSPECT_GRAPHQL_TOOL_NAME} with \`operation\` set to the chosen name to read its exact input type and return type before writing the request.`
+            ].join('\n');
+            return textResult(text);
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            logger.log(`[${SEARCH_GRAPHQL_TOOL_NAME}] Error: ${message}`);
+            return errorResult(`GraphQL schema search error: ${message}`);
+        }
+    });
+}
+function addInspectGraphqlTool(server, description, options) {
+    const d = desc('InspectWixGraphQLSchema');
+    const maxChars = options.maxResponseSize ?? SCHEMA_MAX_RESPONSE_CHARS;
+    server.tool(INSPECT_GRAPHQL_TOOL_NAME, description, {
+        operation: z.string().optional().describe(d.operation),
+        typeNames: z.array(z.string()).optional().describe(d.typeNames),
+        depth: z.number().int().min(1).max(4).optional().describe(d.depth),
+        reason: z.string().describe(d.reason)
+    }, { readOnlyHint: true, destructiveHint: false, openWorldHint: false }, async ({ operation, typeNames, depth, reason }) => {
+        logger.log(`[${INSPECT_GRAPHQL_TOOL_NAME}] operation=${operation ?? '-'} typeNames=${JSON.stringify(typeNames ?? [])} depth=${depth ?? 2} reason="${reason}"`);
+        if (!operation && !(typeNames && typeNames.length > 0)) {
+            return errorResult('Pass `operation` (a root query/mutation name from SearchWixGraphQLOperations) and/or `typeNames` (type names to expand).');
+        }
+        try {
+            const io = introspectionOptions(options);
+            const sections = [];
+            const roots = [];
+            if (operation) {
+                const ops = await getRootOperations(io);
+                const op = ops.find((o) => o.name === operation);
+                if (!op) {
+                    const suggestions = searchOperations(ops, operation, {
+                        maxResults: 5
+                    });
+                    return errorResult(`No root operation named "${operation}". ${suggestions.length
+                        ? `Did you mean: ${suggestions.map((s) => `${s.kind} ${s.operation}`).join(', ')}? Use SearchWixGraphQLOperations to discover the exact name.`
+                        : 'Use SearchWixGraphQLOperations to discover the exact name.'}`);
+                }
+                sections.push(`# ${renderOperationSignature(op)}`, op.description
+                    ? op.description
+                        .trim()
+                        .split('\n')
+                        .map((l) => `# ${l}`)
+                        .join('\n')
+                    : '# (no description)');
+                op.args.forEach((a) => {
+                    const n = namedType(a.type);
+                    if (n)
+                        roots.push(n);
+                });
+                const ret = namedType(op.type);
+                if (ret)
+                    roots.push(ret);
+            }
+            if (typeNames?.length)
+                roots.push(...typeNames);
+            const { rendered, unexpanded, unknown } = await expandTypes(roots, {
+                ...io,
+                depth: depth ?? 2
+            });
+            sections.push(...rendered);
+            if (unknown.length) {
+                sections.push(`# Unknown type names (not in the schema): ${unknown.join(', ')}`);
+            }
+            if (unexpanded.length) {
+                sections.push(`# Not expanded (pass any of these in \`typeNames\` to read them): ${unexpanded.join(', ')}`);
+            }
+            sections.push('# Notes: `JSON` scalar fields (filter, sort, free-form data) take any JSON — pass them as variables. Every object-typed field in a selection needs its own { ... } selection set. Only fields listed above exist. Paging: use exactly the paging style the input type declares — `paging` (offset) or `cursorPaging` (cursor) — never the other one. `pageInfo.total` is only populated with offset paging; with cursor paging, count by walking pages (`pageInfo.hasNext` + cursor) or use a dedicated count operation if one exists.');
+            return textResult(truncateResponse(sections.join('\n\n'), maxChars));
+        }
+        catch (err) {
+            const message = err instanceof Error ? err.message : String(err);
+            logger.log(`[${INSPECT_GRAPHQL_TOOL_NAME}] Error: ${message}`);
+            return errorResult(`GraphQL schema inspection error: ${message}`);
+        }
+    });
+}
+function addExecuteGraphqlTool(server, description, authStrategy, options) {
+    const d = desc('ExecuteWixGraphQL');
+    const endpoint = options.endpoint ?? WIX_GRAPHQL_ENDPOINT;
+    const fetchImpl = options.fetchImpl ?? fetch;
+    server.tool(EXECUTE_GRAPHQL_TOOL_NAME, description, {
+        query: z.string().describe(d.query),
+        variables: z.record(z.unknown()).optional().describe(d.variables),
+        operationName: z.string().optional().describe(d.operationName),
+        siteId: z.string().optional().describe(d.siteId),
+        scope: z.enum(['site', 'account']).optional().describe(d.scope),
+        hasMutations: z.boolean().describe(d.hasMutations),
+        reason: z.string().describe(d.reason)
+    }, { readOnlyHint: false, destructiveHint: true, openWorldHint: false }, async ({ query, variables, operationName, siteId, scope, hasMutations, reason }, extra) => {
+        const effectiveScope = scope ?? (siteId ? 'site' : 'account');
+        logger.log(`[${EXECUTE_GRAPHQL_TOOL_NAME}] scope=${effectiveScope} siteId=${siteId ?? 'none'} hasMutations=${hasMutations} operationName=${operationName ?? '-'} reason="${reason}"`);
+        if (effectiveScope === 'site' && !siteId) {
+            return errorResult('A `siteId` is required for site-level GraphQL operations (anything that reads or writes inside a site). Resolve it with GetSiteContext or ListWixSites, or set scope: "account" for account-level operations.');
+        }
+        if (!query.trim()) {
+            return errorResult('`query` must be a non-empty GraphQL document.');
+        }
+        // Resolve auth before the try so an UnauthorizedError propagates to
+        // wrapToolCallback (which attaches the re-auth metadata).
+        const authHeaders = effectiveScope === 'site'
+            ? await authStrategy.getSiteAuthHeaders(siteId)
+            : await authStrategy.getAccountAuthHeaders();
+        try {
+            const init = {
+                method: 'POST',
+                headers: {
+                    'Content-Type': 'application/json',
+                    Accept: 'application/json',
+                    ...authHeaders
+                },
+                body: JSON.stringify({
+                    query,
+                    ...(variables ? { variables } : {}),
+                    ...(operationName ? { operationName } : {})
+                })
+            };
+            // Transient 503s are retried only when the agent declared the document
+            // read-only (hasMutations: false) — the same contract as ExecuteWixAPI,
+            // with no inference from the document text. A mutation might have been
+            // applied before the edge failed the response, so it is never resent.
+            const resp = hasMutations
+                ? await fetchImpl(endpoint, init)
+                : await fetchWithRetry(fetchImpl, endpoint, init, options.retryDelaysMs);
+            const requestId = resp.headers?.get('x-wix-request-id') ?? undefined;
+            extra?.setToolBiParams?.({ siteId, requestId });
+            const text = await resp.text();
+            if (!resp.ok) {
+                await authStrategy.enforceValidWixToken?.({
+                    status: resp.status,
+                    response: { status: resp.status }
+                });
+                // The edge serves a branded HTML page on 5xx; keep the result short.
+                const body = /^\s*<(!doctype|html)/i.test(text)
+                    ? '(HTML error page)'
+                    : text.slice(0, 2000);
+                const hasObjectVariables = !!variables &&
+                    Object.values(variables).some((v) => v !== null && typeof v === 'object');
+                const hint = resp.status >= 500
+                    ? hasObjectVariables
+                        ? ` The Wix GraphQL endpoint (Developer Preview) returns 503 when an object-typed variable carries an enum value. Rewrite the document with the input INLINE as a GraphQL literal (enum values unquoted, e.g. productType: PHYSICAL), keep variables only for JSON scalars and plain scalars, and retry once. If it still fails and REST tools (ExecuteWixAPI / CallWixSiteAPI) are available, use the equivalent REST method.`
+                        : ` The Wix GraphQL endpoint (Developer Preview) failed for this operation. Do not retry the same document more than once. If REST tools (ExecuteWixAPI / CallWixSiteAPI) are available, complete the task through the equivalent REST method instead; otherwise report the failure with the request id.`
+                    : '';
+                return errorResult(`Wix GraphQL request failed: ${resp.status} ${resp.statusText}.${requestId ? ` request id: ${requestId}.` : ''}${hint}\n${body}`);
+            }
+            let json;
+            try {
+                json = JSON.parse(text);
+            }
+            catch {
+                return errorResult(`Wix GraphQL returned a non-JSON body:\n${text.slice(0, 2000)}`);
+            }
+            const hasData = json.data != null &&
+                Object.values(json.data).some((v) => v !== null && v !== undefined);
+            const errors = json.errors ?? [];
+            if (!hasData && errors.length > 0) {
+                const permissionDenied = errors.some((e) => e.extensions?.message === 'PERMISSION_DENIED');
+                return errorResult([
+                    `Wix GraphQL returned errors and no data${requestId ? ` (request id: ${requestId})` : ''}:`,
+                    JSON.stringify(errors, null, 2).slice(0, 4000),
+                    permissionDenied
+                        ? 'PERMISSION_DENIED usually means the operation is site-level and was called without the right `siteId`, the app behind it is not installed on the site, or the credential lacks that permission scope.'
+                        : 'Validation errors ("Cannot query field ...", "Unknown argument ...") mean a name was guessed — re-read the exact fields with InspectWixGraphQLSchema and retry.'
+                ].join('\n'));
+            }
+            const body = { data: json.data };
+            if (errors.length > 0) {
+                body.errors = errors;
+                body.note =
+                    'Partial result: some root fields failed (see errors[].path). Fields present in data succeeded.';
+            }
+            return textResult(truncateResponse(body, options.maxResponseSize));
+        }
+        catch (err) {
+            rethrowIfUnauthorized(err);
+            await authStrategy.enforceValidWixToken?.(err);
+            const message = err instanceof Error ? err.message : String(err);
+            logger.log(`[${EXECUTE_GRAPHQL_TOOL_NAME}] Error: ${message}`);
+            return errorResult(`Wix GraphQL execution error: ${message}`);
+        }
+    });
+}
+//# sourceMappingURL=index.js.map

package/build/dts/graphql/introspection.d.ts

@@ -0,0 +1,106 @@
+export interface TypeRef {
+    kind: string;
+    name: string | null;
+    ofType?: TypeRef | null;
+}
+export interface RootOperation {
+    /** 'query' | 'mutation' */
+    kind: 'query' | 'mutation';
+    name: string;
+    description: string;
+    args: Array<{
+        name: string;
+        type: TypeRef;
+    }>;
+    type: TypeRef;
+}
+export interface TypeField {
+    name: string;
+    description: string | null;
+    type: TypeRef;
+    args?: Array<{
+        name: string;
+        type: TypeRef;
+    }> | null;
+    defaultValue?: string | null;
+}
+export interface TypeInfo {
+    kind: string;
+    name: string;
+    description: string | null;
+    fields: TypeField[] | null;
+    inputFields: TypeField[] | null;
+    enumValues: Array<{
+        name: string;
+        description: string | null;
+    }> | null;
+    possibleTypes: Array<{
+        name: string;
+    }> | null;
+}
+export type FetchLike = (input: string, init?: {
+    method?: string;
+    headers?: Record<string, string>;
+    body?: string;
+}) => Promise<{
+    ok: boolean;
+    status: number;
+    statusText: string;
+    headers?: {
+        get(name: string): string | null;
+    };
+    text(): Promise<string>;
+}>;
+/** Test hook: forget every cached introspection result. */
+export declare function resetGraphqlSchemaCache(): void;
+export interface IntrospectionOptions {
+    endpoint?: string;
+    fetchImpl?: FetchLike;
+    /** Backoff schedule for transient 5xx (tests pass [] to disable). */
+    retryDelaysMs?: number[];
+}
+/**
+ * The endpoint answers bursts with transient 503s (an HTML page). Retry a few
+ * times with backoff; introspection is idempotent so this is always safe.
+ */
+export declare const RETRY_DELAYS_MS: number[];
+export declare function fetchWithRetry(fetchImpl: FetchLike, url: string, init: Parameters<FetchLike>[1], delays?: number[]): Promise<Awaited<ReturnType<FetchLike>>>;
+/** All root query + mutation fields, cached in-process. */
+export declare function getRootOperations(options?: IntrospectionOptions): Promise<RootOperation[]>;
+/**
+ * Fetch several named types in one round-trip (aliased `__type` lookups).
+ * Unknown names resolve to null. Results are cached per name.
+ */
+export declare function getTypes(names: string[], options?: IntrospectionOptions): Promise<Map<string, TypeInfo | null>>;
+/** `[Foo!]!` style rendering of a (possibly wrapped) type ref. */
+export declare function renderTypeRef(ref: TypeRef | null | undefined): string;
+/** The named type at the bottom of LIST/NON_NULL wrappers. */
+export declare function namedType(ref: TypeRef | null | undefined): string | null;
+export declare function isBuiltinScalar(name: string | null): boolean;
+/**
+ * Compact SDL for one type. Returns the text and the named types it references
+ * (so callers can expand the next level).
+ */
+export declare function renderType(type: TypeInfo): {
+    text: string;
+    references: string[];
+};
+/** One-line signature of a root operation. */
+export declare function renderOperationSignature(op: RootOperation): string;
+export interface ExpandOptions extends IntrospectionOptions {
+    /** How many levels of referenced types to expand (1 = only the given types). */
+    depth?: number;
+    /** Safety cap on the number of types rendered in one call. */
+    maxTypes?: number;
+}
+/**
+ * Breadth-first expansion of `rootTypeNames`. Level 1 is the given names,
+ * level 2 the types they reference, and so on up to `depth`. Anything
+ * referenced but not expanded is returned as `unexpanded` for a follow-up.
+ */
+export declare function expandTypes(rootTypeNames: string[], options?: ExpandOptions): Promise<{
+    rendered: string[];
+    unexpanded: string[];
+    unknown: string[];
+}>;
+//# sourceMappingURL=introspection.d.ts.map