vendure-mcp-graphql 1.3.0 → 1.4.0

package/dist/index.js

@@ -22,7 +22,7 @@ if (existsSync(apiKeyPath)) {
         process.env.VENDURE_API_KEY = envConfig.parsed.VENDURE_API_KEY;
     }
 }
-import { adminQuery, adminMutation, adminBatchMutation, getAdminSchema, getAdminOperations, shopQuery, shopMutation, shopBatchMutation, getShopSchema, getShopOperations, } from "./src/tools/index.js";
+import { adminQuery, adminMutation, adminBatchMutation, getAdminSchema, getAdminOperations, shopQuery, shopMutation, shopBatchMutation, getShopSchema, getShopOperations, describeOperation, } from "./src/tools/index.js";
 // Singleton pattern for shared resources
 class SharedResources {
     static instance = null;
@@ -198,6 +198,25 @@ server.setRequestHandler(ListToolsRequestSchema, async () => ({
             description: "List all available queries and mutations for the Shop API with descriptions.",
             inputSchema: { type: "object", properties: {}, required: [] },
         },
+        {
+            name: "describe_operation",
+            description: "Describe a GraphQL query or mutation in detail: shows which API(s) it's available on, arguments with input types, and the return type with all its fields. Checks both Admin and Shop APIs by default.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    operation: {
+                        type: "string",
+                        description: "The name of the query or mutation to describe (e.g. productGroups, createProduct)",
+                    },
+                    api: {
+                        type: "string",
+                        enum: ["admin", "shop"],
+                        description: "Optional: restrict lookup to a specific API. If omitted, checks both Admin and Shop APIs.",
+                    },
+                },
+                required: ["operation"],
+            },
+        },
     ],
 }));
 // Handle tool calls
@@ -295,6 +314,15 @@ server.setRequestHandler(CallToolRequestSchema, async (request) => {
                         },
                     ],
                 };
+            case "describe_operation":
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: JSON.stringify(await describeOperation(args?.operation, args?.api), null, 2),
+                        },
+                    ],
+                };
             default:
                 throw new McpError(ErrorCode.MethodNotFound, `Unknown tool: ${name}`);
         }

package/dist/src/tools/graphql-operations.d.ts

@@ -22,6 +22,14 @@ export declare function getAdminSchema(): Promise<any>;
  * Fetch the Shop GraphQL schema introspection
  */
 export declare function getShopSchema(): Promise<any>;
+/**
+ * Fetch details for a single type from the Admin API schema
+ */
+export declare function getAdminTypeDetails(name: string): Promise<any>;
+/**
+ * Fetch details for a single type from the Shop API schema
+ */
+export declare function getShopTypeDetails(name: string): Promise<any>;
 /**
  * Fetch a summary of available queries and mutations for the Admin API
  */
@@ -30,6 +38,16 @@ export declare function getAdminOperations(): Promise<any>;
  * Fetch a summary of available queries and mutations for the Shop API
  */
 export declare function getShopOperations(): Promise<any>;
+/**
+ * Describe a GraphQL operation (query or mutation) with full details.
+ *
+ * Checks both Admin and Shop APIs (or just one if `api` is specified).
+ * Returns the operation's arguments with input types, and its return type with fields.
+ *
+ * @param operationName - The name of the query or mutation
+ * @param api - Optional: restrict to "admin" or "shop" only
+ */
+export declare function describeOperation(operationName: string, api?: "admin" | "shop"): Promise<any>;
 export interface BatchResult {
     total: number;
     succeeded: number;

package/dist/src/tools/graphql-operations.js

@@ -138,6 +138,102 @@ const operationsSummaryQuery = `
     }
   }
 `;
+/**
+ * Query that fetches all operations with their return type chain and args.
+ * Used by describeOperation to find a specific operation's details.
+ */
+const allOperationsWithTypesQuery = `
+  query AllOperationsWithTypes {
+    __schema {
+      queryType {
+        fields {
+          name
+          description
+          args {
+            name
+            description
+            defaultValue
+            type {
+              name
+              kind
+              ofType {
+                name
+                kind
+                ofType {
+                  name
+                  kind
+                  ofType {
+                    name
+                    kind
+                  }
+                }
+              }
+            }
+          }
+          type {
+            name
+            kind
+            ofType {
+              name
+              kind
+              ofType {
+                name
+                kind
+                ofType {
+                  name
+                  kind
+                }
+              }
+            }
+          }
+        }
+      }
+      mutationType {
+        fields {
+          name
+          description
+          args {
+            name
+            description
+            defaultValue
+            type {
+              name
+              kind
+              ofType {
+                name
+                kind
+                ofType {
+                  name
+                  kind
+                  ofType {
+                    name
+                    kind
+                  }
+                }
+              }
+            }
+          }
+          type {
+            name
+            kind
+            ofType {
+              name
+              kind
+              ofType {
+                name
+                kind
+                ofType {
+                  name
+                  kind
+                }
+              }
+            }
+          }
+        }
+      }
+    }
+  }
+`;
 /**
  * Fetch the Admin GraphQL schema introspection
  */
@@ -152,6 +248,93 @@ export async function getShopSchema() {
     const client = getClient();
     return client.request(getShopUrl(), introspectionQuery);
 }
+/**
+ * Fetch a summary of available queries and mutations for the Admin API
+ */
+const typeDetailsQuery = `
+  query GetTypeDetails($name: String!) {
+    __type(name: $name) {
+      kind
+      name
+      description
+      fields(includeDeprecated: false) {
+        name
+        description
+        args {
+          name
+          description
+          type {
+            name
+            kind
+            ofType {
+              name
+              kind
+              ofType {
+                name
+                kind
+              }
+            }
+          }
+          defaultValue
+        }
+        type {
+          name
+          kind
+          ofType {
+            name
+            kind
+            ofType {
+              name
+              kind
+              ofType {
+                name
+                kind
+              }
+            }
+          }
+        }
+      }
+      inputFields {
+        name
+        description
+        type {
+          name
+          kind
+          ofType {
+            name
+            kind
+            ofType {
+              name
+              kind
+            }
+          }
+        }
+        defaultValue
+      }
+      enumValues(includeDeprecated: false) {
+        name
+        description
+      }
+      interfaces {
+        name
+      }
+    }
+  }
+`;
+/**
+ * Fetch details for a single type from the Admin API schema
+ */
+export async function getAdminTypeDetails(name) {
+    const client = getClient();
+    return client.request(getAdminUrl(), typeDetailsQuery, { name });
+}
+/**
+ * Fetch details for a single type from the Shop API schema
+ */
+export async function getShopTypeDetails(name) {
+    const client = getClient();
+    return client.request(getShopUrl(), typeDetailsQuery, { name });
+}
 /**
  * Fetch a summary of available queries and mutations for the Admin API
  */
@@ -166,6 +349,150 @@ export async function getShopOperations() {
     const client = getClient();
     return client.request(getShopUrl(), operationsSummaryQuery);
 }
+// ─── Helpers for describeOperation ───────────────────────────────
+/**
+ * Extract the named type name from a type chain (through NonNull/List wrappers).
+ * e.g., `[ProductGroup!]!` → `ProductGroup`
+ */
+function extractNamedTypeName(type) {
+    if (!type)
+        return null;
+    if (type.kind !== "NON_NULL" && type.kind !== "LIST") {
+        return type.name || null;
+    }
+    return extractNamedTypeName(type.ofType);
+}
+/**
+ * Format a GraphQL type chain into a readable string like `[ProductGroup!]!`
+ */
+function formatTypeString(type) {
+    if (!type)
+        return "unknown";
+    switch (type.kind) {
+        case "NON_NULL":
+            return `${formatTypeString(type.ofType)}!`;
+        case "LIST":
+            return `[${formatTypeString(type.ofType)}]`;
+        default:
+            return type.name || "unknown";
+    }
+}
+/**
+ * Describe a GraphQL operation (query or mutation) with full details.
+ *
+ * Checks both Admin and Shop APIs (or just one if `api` is specified).
+ * Returns the operation's arguments with input types, and its return type with fields.
+ *
+ * @param operationName - The name of the query or mutation
+ * @param api - Optional: restrict to "admin" or "shop" only
+ */
+export async function describeOperation(operationName, api) {
+    const apisToCheck = api ? [api] : ["admin", "shop"];
+    const client = getClient();
+    const details = [];
+    for (const targetApi of apisToCheck) {
+        const url = targetApi === "admin" ? getAdminUrl() : getShopUrl();
+        try {
+            // Step 1: Fetch all operations with type chains to find the one we need
+            const schemaData = await client.request(url, allOperationsWithTypesQuery);
+            const queryFields = schemaData.__schema.queryType.fields;
+            const mutationFields = schemaData.__schema.mutationType.fields;
+            const queryField = queryFields.find((f) => f.name === operationName);
+            const mutationField = mutationFields.find((f) => f.name === operationName);
+            if (!queryField && !mutationField)
+                continue;
+            const field = queryField || mutationField;
+            const kind = queryField ? "query" : "mutation";
+            // Step 2: Resolve the return type's fields
+            const returnTypeName = extractNamedTypeName(field.type);
+            let returnType = {
+                name: formatTypeString(field.type),
+                namedType: returnTypeName,
+            };
+            if (returnTypeName) {
+                try {
+                    const result = await client.request(url, typeDetailsQuery, {
+                        name: returnTypeName,
+                    });
+                    if (result.__type) {
+                        returnType = {
+                            name: returnTypeName,
+                            kind: result.__type.kind,
+                            description: result.__type.description,
+                            fields: (result.__type.fields || []).map((f) => ({
+                                name: f.name,
+                                type: formatTypeString(f.type),
+                                description: f.description,
+                                args: f.args?.length
+                                    ? f.args.map((a) => ({
+                                        name: a.name,
+                                        type: formatTypeString(a.type),
+                                        description: a.description,
+                                        defaultValue: a.defaultValue,
+                                    }))
+                                    : undefined,
+                            })),
+                            enumValues: result.__type.enumValues,
+                            inputFields: result.__type.inputFields,
+                        };
+                    }
+                }
+                catch {
+                    // Type might be a built-in scalar - skip
+                }
+            }
+            // Step 3: Resolve argument input types
+            const argDetails = await Promise.all((field.args || []).map(async (arg) => {
+                const argTypeName = extractNamedTypeName(arg.type);
+                const detail = {
+                    name: arg.name,
+                    type: formatTypeString(arg.type),
+                    description: arg.description,
+                    defaultValue: arg.defaultValue,
+                };
+                if (argTypeName) {
+                    try {
+                        const result = await client.request(url, typeDetailsQuery, {
+                            name: argTypeName,
+                        });
+                        if (result.__type) {
+                            detail.inputFields = (result.__type.inputFields || []).map((f) => ({
+                                name: f.name,
+                                type: formatTypeString(f.type),
+                                description: f.description,
+                                defaultValue: f.defaultValue,
+                            }));
+                            detail.inputKind = result.__type.kind;
+                            detail.inputDescription = result.__type.description;
+                        }
+                    }
+                    catch {
+                        // ignore
+                    }
+                }
+                return detail;
+            }));
+            details.push({
+                api: targetApi,
+                kind,
+                description: field.description,
+                arguments: argDetails,
+                returnType,
+            });
+        }
+        catch (error) {
+            details.push({
+                api: targetApi,
+                error: error instanceof Error ? error.message : String(error),
+            });
+        }
+    }
+    return {
+        operation: operationName,
+        availableOn: details.filter((d) => !d.error).map((d) => d.api),
+        details,
+    };
+}
 /**
  * Execute a GraphQL mutation in batch for multiple IDs on the Admin API.
  * Runs mutations concurrently with configurable concurrency.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "vendure-mcp-graphql",
-  "version": "1.3.0",
-  "description": "MCP server for Vendure Admin and Shop GraphQL APIs",
+  "version": "1.4.0",
+    "description": "MCP server for Vendure Admin and Shop GraphQL APIs",
   "type": "module",
   "bin": {
     "vendure-mcp-graphql": "./dist/index.js"

package/dist/src/types.d.ts

@@ -1,45 +0,0 @@
-/**
- * Type definitions for GraphQL entities
- */
-export interface Archetype {
-    id: string;
-    code: string;
-    name: string;
-    coreDrive: string;
-    primaryFear: string;
-    languageSignature: string;
-    psychologicalTriggers: string[];
-}
-export type PulseScriptType = 'OPENING' | 'RESPONSE' | 'RESOLUTION' | 'CUSTOM';
-export interface PulseScript {
-    id: string;
-    code: string;
-    name: string;
-    type: PulseScriptType;
-    description?: string;
-    archetypeId: string;
-    archetype?: Archetype;
-}
-export interface CreatePulseScriptInput {
-    code: string;
-    name: string;
-    type: PulseScriptType;
-    description?: string;
-    archetypeId: string;
-}
-export interface UpdatePulseScriptInput {
-    id: string;
-    code?: string;
-    name?: string;
-    type?: PulseScriptType;
-    description?: string;
-    archetypeId?: string;
-}
-export interface Pulse {
-    id: string;
-    code: string;
-    status: string;
-    currentState: string;
-    initiatorArchetype?: Archetype;
-    targetArchetype?: Archetype;
-}

package/dist/src/types.js

@@ -1,4 +0,0 @@
-/**
- * Type definitions for GraphQL entities
- */
-export {};