vendure-mcp-graphql 1.0.0

package/CHANGELOG.md

@@ -0,0 +1,5 @@
+# Changelog
+
+## 1.0.0 (2025-01-24)
+- Initial public release of `vendure-mcp-graphql` (formerly `raptorr-graphql-mcp`).
+- Standardized package structure for npm publication.

package/README.md

@@ -0,0 +1,38 @@
+# vendure-mcp-graphql
+
+MCP (Model Context Protocol) server for interacting with Vendure GraphQL APIs (Admin & Shop).
+
+## Installation
+
+```bash
+npm install -g vendure-mcp-graphql
+```
+
+## Usage
+
+Configure as an MCP server in your IDE (like Claude Desktop):
+
+```json
+{
+  "mcpServers": {
+    "vendure-mcp-graphql": {
+      "command": "vendure-mcp-graphql",
+      "args": [],
+      "env": {
+        "VENDURE_URL": "http://localhost:3000/admin-api",
+        "VENDURE_AUTH_TOKEN": "your-token-here"
+      }
+    }
+  }
+}
+```
+
+## Features
+
+- Admin API access
+- Shop API access
+- GraphQL introspection and execution
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,6 @@
+#!/usr/bin/env node
+/**
+ * Raptorr GraphQL MCP Server
+ * Consolidated version for both Vendure Admin and Shop APIs
+ */
+export {};

package/dist/index.js

@@ -0,0 +1,214 @@
+#!/usr/bin/env node
+/**
+ * Raptorr GraphQL MCP Server
+ * Consolidated version for both Vendure Admin and Shop APIs
+ */
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { CallToolRequestSchema, ListToolsRequestSchema, ErrorCode, McpError, } from "@modelcontextprotocol/sdk/types.js";
+import { config } from "dotenv";
+import { resolve, dirname } from "path";
+import { fileURLToPath } from "url";
+import { existsSync } from "fs";
+// Load environment variables
+const __dirname = dirname(fileURLToPath(import.meta.url));
+// 1. Try to load from project root .env.local
+config({ path: resolve(__dirname, "../../.env.local") });
+// 2. Also try to load from specific vendure-api-key.env if it exists
+const apiKeyPath = resolve(__dirname, "../../vendure-api-key.env");
+if (existsSync(apiKeyPath)) {
+    const envConfig = config({ path: apiKeyPath });
+    if (envConfig.parsed?.VENDURE_API_KEY) {
+        process.env.VENDURE_API_KEY = envConfig.parsed.VENDURE_API_KEY;
+    }
+}
+import { adminQuery, adminMutation, getAdminSchema, getAdminOperations, shopQuery, shopMutation, getShopSchema, getShopOperations, } from "./src/tools/index.js";
+const server = new Server({
+    name: "raptorr-graphql-mcp",
+    version: "3.1.0",
+}, {
+    capabilities: {
+        tools: {},
+    },
+});
+// Define available tools
+server.setRequestHandler(ListToolsRequestSchema, async () => ({
+    tools: [
+        {
+            name: "admin_query",
+            description: "Execute a GraphQL query on the Vendure Admin API.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    query: { type: "string", description: "The GraphQL query string" },
+                    variables: { type: "object", description: "Optional variables" },
+                },
+                required: ["query"],
+            },
+        },
+        {
+            name: "admin_mutation",
+            description: "Execute a GraphQL mutation on the Vendure Admin API.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    mutation: {
+                        type: "string",
+                        description: "The GraphQL mutation string",
+                    },
+                    variables: { type: "object", description: "Optional variables" },
+                },
+                required: ["mutation"],
+            },
+        },
+        {
+            name: "get_admin_schema",
+            description: "Fetch the full Admin API GraphQL schema introspection. (Warning: Large output)",
+            inputSchema: { type: "object", properties: {}, required: [] },
+        },
+        {
+            name: "list_admin_operations",
+            description: "List all available queries and mutations for the Admin API with descriptions.",
+            inputSchema: { type: "object", properties: {}, required: [] },
+        },
+        {
+            name: "shop_query",
+            description: "Execute a GraphQL query on the Vendure Shop API.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    query: { type: "string", description: "The GraphQL query string" },
+                    variables: { type: "object", description: "Optional variables" },
+                },
+                required: ["query"],
+            },
+        },
+        {
+            name: "shop_mutation",
+            description: "Execute a GraphQL mutation on the Vendure Shop API.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    mutation: {
+                        type: "string",
+                        description: "The GraphQL mutation string",
+                    },
+                    variables: { type: "object", description: "Optional variables" },
+                },
+                required: ["mutation"],
+            },
+        },
+        {
+            name: "get_shop_schema",
+            description: "Fetch the full Shop API GraphQL schema introspection. (Warning: Large output)",
+            inputSchema: { type: "object", properties: {}, required: [] },
+        },
+        {
+            name: "list_shop_operations",
+            description: "List all available queries and mutations for the Shop API with descriptions.",
+            inputSchema: { type: "object", properties: {}, required: [] },
+        },
+    ],
+}));
+// Handle tool calls
+server.setRequestHandler(CallToolRequestSchema, async (request) => {
+    const { name, arguments: args } = request.params;
+    try {
+        switch (name) {
+            case "admin_query":
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: JSON.stringify(await adminQuery(args?.query, args?.variables), null, 2),
+                        },
+                    ],
+                };
+            case "admin_mutation":
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: JSON.stringify(await adminMutation(args?.mutation, args?.variables), null, 2),
+                        },
+                    ],
+                };
+            case "get_admin_schema":
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: JSON.stringify(await getAdminSchema(), null, 2),
+                        },
+                    ],
+                };
+            case "list_admin_operations":
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: JSON.stringify(await getAdminOperations(), null, 2),
+                        },
+                    ],
+                };
+            case "shop_query":
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: JSON.stringify(await shopQuery(args?.query, args?.variables), null, 2),
+                        },
+                    ],
+                };
+            case "shop_mutation":
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: JSON.stringify(await shopMutation(args?.mutation, args?.variables), null, 2),
+                        },
+                    ],
+                };
+            case "get_shop_schema":
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: JSON.stringify(await getShopSchema(), null, 2),
+                        },
+                    ],
+                };
+            case "list_shop_operations":
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: JSON.stringify(await getShopOperations(), null, 2),
+                        },
+                    ],
+                };
+            default:
+                throw new McpError(ErrorCode.MethodNotFound, `Unknown tool: ${name}`);
+        }
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        return {
+            content: [{ type: "text", text: `Error: ${message}` }],
+            isError: true,
+        };
+    }
+});
+// Start the server
+async function main() {
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    console.error("Raptorr GraphQL MCP server running on stdio");
+    console.error(`API Key: ${process.env.VENDURE_API_KEY ? "Present" : "Missing"}`);
+    console.error(`Admin URL: ${process.env.ADMIN_API_URL || "default"}`);
+    console.error(`Shop URL: ${process.env.SHOP_API_URL || "default"}`);
+}
+main().catch((error) => {
+    console.error("Server error:", error);
+    process.exit(1);
+});

package/dist/src/client.d.ts

@@ -0,0 +1,19 @@
+/**
+ * GraphQL Client for Vendure API
+ * Handles authentication via API Key for both Admin and Shop APIs
+ */
+export interface GraphQLResponse<T = any> {
+    data?: T;
+    errors?: Array<{
+        message: string;
+        path?: string[];
+    }>;
+}
+export declare class GraphQLClient {
+    private apiKey;
+    constructor(apiKey?: string | null);
+    request<T = any>(url: string, queryString: string, variables?: Record<string, any>): Promise<T>;
+}
+export declare function getClient(): GraphQLClient;
+export declare function getAdminUrl(): string;
+export declare function getShopUrl(): string;

package/dist/src/client.js

@@ -0,0 +1,51 @@
+/**
+ * GraphQL Client for Vendure API
+ * Handles authentication via API Key for both Admin and Shop APIs
+ */
+export class GraphQLClient {
+    apiKey;
+    constructor(apiKey = null) {
+        this.apiKey = apiKey;
+    }
+    async request(url, queryString, variables) {
+        const headers = {
+            "Content-Type": "application/json",
+        };
+        if (this.apiKey) {
+            headers["vendure-api-key"] = this.apiKey;
+        }
+        const response = await fetch(url, {
+            method: "POST",
+            headers,
+            body: JSON.stringify({
+                query: queryString,
+                variables,
+            }),
+        });
+        if (!response.ok) {
+            const text = await response.text();
+            throw new Error(`HTTP Error ${response.status}: ${text}`);
+        }
+        const result = (await response.json());
+        if (result.errors && result.errors.length > 0) {
+            throw new Error(result.errors.map((e) => e.message).join(", "));
+        }
+        return result.data;
+    }
+}
+// Singleton instance
+let clientInstance = null;
+export function getClient() {
+    if (clientInstance) {
+        return clientInstance;
+    }
+    const apiKey = process.env.VENDURE_API_KEY || null;
+    clientInstance = new GraphQLClient(apiKey);
+    return clientInstance;
+}
+export function getAdminUrl() {
+    return process.env.ADMIN_API_URL || "http://localhost:3000/admin-api";
+}
+export function getShopUrl() {
+    return process.env.SHOP_API_URL || "http://localhost:3000/shop-api";
+}

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

@@ -0,0 +1,32 @@
+/**
+ * Execute a GraphQL query on the Admin API
+ */
+export declare function adminQuery(queryString: string, variables?: Record<string, any>): Promise<any>;
+/**
+ * Execute a GraphQL mutation on the Admin API
+ */
+export declare function adminMutation(mutationString: string, variables?: Record<string, any>): Promise<any>;
+/**
+ * Execute a GraphQL query on the Shop API
+ */
+export declare function shopQuery(queryString: string, variables?: Record<string, any>): Promise<any>;
+/**
+ * Execute a GraphQL mutation on the Shop API
+ */
+export declare function shopMutation(mutationString: string, variables?: Record<string, any>): Promise<any>;
+/**
+ * Fetch the Admin GraphQL schema introspection
+ */
+export declare function getAdminSchema(): Promise<any>;
+/**
+ * Fetch the Shop GraphQL schema introspection
+ */
+export declare function getShopSchema(): Promise<any>;
+/**
+ * Fetch a summary of available queries and mutations for the Admin API
+ */
+export declare function getAdminOperations(): Promise<any>;
+/**
+ * Fetch a summary of available queries and mutations for the Shop API
+ */
+export declare function getShopOperations(): Promise<any>;

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

@@ -0,0 +1,168 @@
+import { getClient, getAdminUrl, getShopUrl } from "../client.js";
+/**
+ * Execute a GraphQL query on the Admin API
+ */
+export async function adminQuery(queryString, variables) {
+    const client = getClient();
+    return client.request(getAdminUrl(), queryString, variables);
+}
+/**
+ * Execute a GraphQL mutation on the Admin API
+ */
+export async function adminMutation(mutationString, variables) {
+    const client = getClient();
+    return client.request(getAdminUrl(), mutationString, variables);
+}
+/**
+ * Execute a GraphQL query on the Shop API
+ */
+export async function shopQuery(queryString, variables) {
+    const client = getClient();
+    return client.request(getShopUrl(), queryString, variables);
+}
+/**
+ * Execute a GraphQL mutation on the Shop API
+ */
+export async function shopMutation(mutationString, variables) {
+    const client = getClient();
+    return client.request(getShopUrl(), mutationString, variables);
+}
+const introspectionQuery = `
+  query IntrospectionQuery {
+    __schema {
+      queryType { name }
+      mutationType { name }
+      subscriptionType { name }
+      types {
+        ...FullType
+      }
+      directives {
+        name
+        description
+        locations
+        args {
+          ...InputValue
+        }
+      }
+    }
+  }
+
+  fragment FullType on __Type {
+    kind
+    name
+    description
+    fields(includeDeprecated: true) {
+      name
+      description
+      args {
+        ...InputValue
+      }
+      type {
+        ...TypeRef
+      }
+      isDeprecated
+      deprecationReason
+    }
+    inputFields {
+      ...InputValue
+    }
+    interfaces {
+      ...TypeRef
+    }
+    enums {
+      name
+      description
+      isDeprecated
+      deprecationReason
+    }
+    possibleTypes {
+      ...TypeRef
+    }
+  }
+
+  fragment InputValue on __InputValue {
+    name
+    description
+    type { ...TypeRef }
+    defaultValue
+  }
+
+  fragment TypeRef on __Type {
+    kind
+    name
+    ofType {
+      kind
+      name
+      ofType {
+        kind
+        name
+        ofType {
+          kind
+          name
+          ofType {
+            kind
+            name
+            ofType {
+              kind
+              name
+              ofType {
+                kind
+                name
+                ofType {
+                  kind
+                  name
+                }
+              }
+            }
+          }
+        }
+      }
+    }
+  }
+`;
+const operationsSummaryQuery = `
+  query OperationsSummary {
+    __schema {
+      queryType {
+        fields {
+          name
+          description
+        }
+      }
+      mutationType {
+        fields {
+          name
+          description
+        }
+      }
+    }
+  }
+`;
+/**
+ * Fetch the Admin GraphQL schema introspection
+ */
+export async function getAdminSchema() {
+    const client = getClient();
+    return client.request(getAdminUrl(), introspectionQuery);
+}
+/**
+ * Fetch the Shop GraphQL schema introspection
+ */
+export async function getShopSchema() {
+    const client = getClient();
+    return client.request(getShopUrl(), introspectionQuery);
+}
+/**
+ * Fetch a summary of available queries and mutations for the Admin API
+ */
+export async function getAdminOperations() {
+    const client = getClient();
+    return client.request(getAdminUrl(), operationsSummaryQuery);
+}
+/**
+ * Fetch a summary of available queries and mutations for the Shop API
+ */
+export async function getShopOperations() {
+    const client = getClient();
+    return client.request(getShopUrl(), operationsSummaryQuery);
+}

package/dist/src/tools/index.d.ts

@@ -0,0 +1 @@
+export * from "./graphql-operations.js";

package/dist/src/tools/index.js

@@ -0,0 +1 @@
+export * from "./graphql-operations.js";

package/dist/src/types.d.ts

@@ -0,0 +1,45 @@
+/**
+ * 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

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

package/index.ts

@@ -0,0 +1,275 @@
+#!/usr/bin/env node
+/**
+ * Vendure GraphQL MCP Server
+ * Consolidated version for both Vendure Admin and Shop APIs
+ */
+
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import {
+  CallToolRequestSchema,
+  ListToolsRequestSchema,
+  ErrorCode,
+  McpError,
+} from "@modelcontextprotocol/sdk/types.js";
+import { config } from "dotenv";
+import { resolve, dirname } from "path";
+import { fileURLToPath } from "url";
+import { existsSync } from "fs";
+
+// Load environment variables
+const __dirname = dirname(fileURLToPath(import.meta.url));
+
+// 1. Try to load from project root .env.local
+config({ path: resolve(__dirname, "../../.env.local") });
+
+// 2. Also try to load from specific vendure-api-key.env if it exists
+const apiKeyPath = resolve(__dirname, "../../vendure-api-key.env");
+if (existsSync(apiKeyPath)) {
+  const envConfig = config({ path: apiKeyPath });
+  if (envConfig.parsed?.VENDURE_API_KEY) {
+    process.env.VENDURE_API_KEY = envConfig.parsed.VENDURE_API_KEY;
+  }
+}
+
+import {
+  adminQuery,
+  adminMutation,
+  getAdminSchema,
+  getAdminOperations,
+  shopQuery,
+  shopMutation,
+  getShopSchema,
+  getShopOperations,
+} from "./src/tools/index.js";
+
+const server = new Server(
+  {
+    name: "vendure-mcp-graphql",
+    version: "1.0.0",
+  },
+  {
+    capabilities: {
+      tools: {},
+    },
+  },
+);
+
+// Define available tools
+server.setRequestHandler(ListToolsRequestSchema, async () => ({
+  tools: [
+    {
+      name: "admin_query",
+      description: "Execute a GraphQL query on the Vendure Admin API.",
+      inputSchema: {
+        type: "object",
+        properties: {
+          query: { type: "string", description: "The GraphQL query string" },
+          variables: { type: "object", description: "Optional variables" },
+        },
+        required: ["query"],
+      },
+    },
+    {
+      name: "admin_mutation",
+      description: "Execute a GraphQL mutation on the Vendure Admin API.",
+      inputSchema: {
+        type: "object",
+        properties: {
+          mutation: {
+            type: "string",
+            description: "The GraphQL mutation string",
+          },
+          variables: { type: "object", description: "Optional variables" },
+        },
+        required: ["mutation"],
+      },
+    },
+    {
+      name: "get_admin_schema",
+      description:
+        "Fetch the full Admin API GraphQL schema introspection. (Warning: Large output)",
+      inputSchema: { type: "object", properties: {}, required: [] },
+    },
+    {
+      name: "list_admin_operations",
+      description:
+        "List all available queries and mutations for the Admin API with descriptions.",
+      inputSchema: { type: "object", properties: {}, required: [] },
+    },
+    {
+      name: "shop_query",
+      description: "Execute a GraphQL query on the Vendure Shop API.",
+      inputSchema: {
+        type: "object",
+        properties: {
+          query: { type: "string", description: "The GraphQL query string" },
+          variables: { type: "object", description: "Optional variables" },
+        },
+        required: ["query"],
+      },
+    },
+    {
+      name: "shop_mutation",
+      description: "Execute a GraphQL mutation on the Vendure Shop API.",
+      inputSchema: {
+        type: "object",
+        properties: {
+          mutation: {
+            type: "string",
+            description: "The GraphQL mutation string",
+          },
+          variables: { type: "object", description: "Optional variables" },
+        },
+        required: ["mutation"],
+      },
+    },
+    {
+      name: "get_shop_schema",
+      description:
+        "Fetch the full Shop API GraphQL schema introspection. (Warning: Large output)",
+      inputSchema: { type: "object", properties: {}, required: [] },
+    },
+    {
+      name: "list_shop_operations",
+      description:
+        "List all available queries and mutations for the Shop API with descriptions.",
+      inputSchema: { type: "object", properties: {}, required: [] },
+    },
+  ],
+}));
+
+// Handle tool calls
+server.setRequestHandler(CallToolRequestSchema, async (request) => {
+  const { name, arguments: args } = request.params;
+
+  try {
+    switch (name) {
+      case "admin_query":
+        return {
+          content: [
+            {
+              type: "text",
+              text: JSON.stringify(
+                await adminQuery(
+                  args?.query as string,
+                  args?.variables as Record<string, any>,
+                ),
+                null,
+                2,
+              ),
+            },
+          ],
+        };
+      case "admin_mutation":
+        return {
+          content: [
+            {
+              type: "text",
+              text: JSON.stringify(
+                await adminMutation(
+                  args?.mutation as string,
+                  args?.variables as Record<string, any>,
+                ),
+                null,
+                2,
+              ),
+            },
+          ],
+        };
+      case "get_admin_schema":
+        return {
+          content: [
+            {
+              type: "text",
+              text: JSON.stringify(await getAdminSchema(), null, 2),
+            },
+          ],
+        };
+      case "list_admin_operations":
+        return {
+          content: [
+            {
+              type: "text",
+              text: JSON.stringify(await getAdminOperations(), null, 2),
+            },
+          ],
+        };
+      case "shop_query":
+        return {
+          content: [
+            {
+              type: "text",
+              text: JSON.stringify(
+                await shopQuery(
+                  args?.query as string,
+                  args?.variables as Record<string, any>,
+                ),
+                null,
+                2,
+              ),
+            },
+          ],
+        };
+      case "shop_mutation":
+        return {
+          content: [
+            {
+              type: "text",
+              text: JSON.stringify(
+                await shopMutation(
+                  args?.mutation as string,
+                  args?.variables as Record<string, any>,
+                ),
+                null,
+                2,
+              ),
+            },
+          ],
+        };
+      case "get_shop_schema":
+        return {
+          content: [
+            {
+              type: "text",
+              text: JSON.stringify(await getShopSchema(), null, 2),
+            },
+          ],
+        };
+      case "list_shop_operations":
+        return {
+          content: [
+            {
+              type: "text",
+              text: JSON.stringify(await getShopOperations(), null, 2),
+            },
+          ],
+        };
+      default:
+        throw new McpError(ErrorCode.MethodNotFound, `Unknown tool: ${name}`);
+    }
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    return {
+      content: [{ type: "text", text: `Error: ${message}` }],
+      isError: true,
+    };
+  }
+});
+
+// Start the server
+async function main() {
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+  console.error("Vendure GraphQL MCP server running on stdio");
+  console.error(
+    `API Key: ${process.env.VENDURE_API_KEY ? "Present" : "Missing"}`,
+  );
+  console.error(`Admin URL: ${process.env.ADMIN_API_URL || "default"}`);
+  console.error(`Shop URL: ${process.env.SHOP_API_URL || "default"}`);
+}
+
+main().catch((error) => {
+  console.error("Server error:", error);
+  process.exit(1);
+});

package/package.json

@@ -0,0 +1,24 @@
+{
+  "name": "vendure-mcp-graphql",
+  "version": "1.0.0",
+  "description": "MCP server for Vendure Admin and Shop GraphQL APIs",
+  "type": "module",
+  "bin": {
+    "vendure-mcp-graphql": "./dist/index.js"
+  },
+  "main": "dist/index.js",
+  "scripts": {
+    "build": "tsc",
+    "start": "node dist/index.js",
+    "dev": "tsx index.ts"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.0.0",
+    "dotenv": "^16.3.1"
+  },
+  "devDependencies": {
+    "@types/node": "^20.10.0",
+    "tsx": "^4.7.0",
+    "typescript": "^5.3.0"
+  }
+}

package/src/client.ts

@@ -0,0 +1,70 @@
+/**
+ * GraphQL Client for Vendure API
+ * Handles authentication via API Key for both Admin and Shop APIs
+ */
+
+export interface GraphQLResponse<T = any> {
+  data?: T;
+  errors?: Array<{ message: string; path?: string[] }>;
+}
+
+export class GraphQLClient {
+  constructor(private apiKey: string | null = null) {}
+
+  async request<T = any>(
+    url: string,
+    queryString: string,
+    variables?: Record<string, any>,
+  ): Promise<T> {
+    const headers: Record<string, string> = {
+      "Content-Type": "application/json",
+    };
+
+    if (this.apiKey) {
+      headers["vendure-api-key"] = this.apiKey;
+    }
+
+    const response = await fetch(url, {
+      method: "POST",
+      headers,
+      body: JSON.stringify({
+        query: queryString,
+        variables,
+      }),
+    });
+
+    if (!response.ok) {
+      const text = await response.text();
+      throw new Error(`HTTP Error ${response.status}: ${text}`);
+    }
+
+    const result = (await response.json()) as GraphQLResponse<T>;
+
+    if (result.errors && result.errors.length > 0) {
+      throw new Error(result.errors.map((e) => e.message).join(", "));
+    }
+
+    return result.data as T;
+  }
+}
+
+// Singleton instance
+let clientInstance: GraphQLClient | null = null;
+
+export function getClient(): GraphQLClient {
+  if (clientInstance) {
+    return clientInstance;
+  }
+
+  const apiKey = process.env.VENDURE_API_KEY || null;
+  clientInstance = new GraphQLClient(apiKey);
+  return clientInstance;
+}
+
+export function getAdminUrl(): string {
+  return process.env.ADMIN_API_URL || "http://localhost:3000/admin-api";
+}
+
+export function getShopUrl(): string {
+  return process.env.SHOP_API_URL || "http://localhost:3000/shop-api";
+}

package/src/tools/graphql-operations.ts

@@ -0,0 +1,190 @@
+import { getClient, getAdminUrl, getShopUrl } from "../client.js";
+
+/**
+ * Execute a GraphQL query on the Admin API
+ */
+export async function adminQuery(
+  queryString: string,
+  variables?: Record<string, any>,
+): Promise<any> {
+  const client = getClient();
+  return client.request(getAdminUrl(), queryString, variables);
+}
+
+/**
+ * Execute a GraphQL mutation on the Admin API
+ */
+export async function adminMutation(
+  mutationString: string,
+  variables?: Record<string, any>,
+): Promise<any> {
+  const client = getClient();
+  return client.request(getAdminUrl(), mutationString, variables);
+}
+
+/**
+ * Execute a GraphQL query on the Shop API
+ */
+export async function shopQuery(
+  queryString: string,
+  variables?: Record<string, any>,
+): Promise<any> {
+  const client = getClient();
+  return client.request(getShopUrl(), queryString, variables);
+}
+
+/**
+ * Execute a GraphQL mutation on the Shop API
+ */
+export async function shopMutation(
+  mutationString: string,
+  variables?: Record<string, any>,
+): Promise<any> {
+  const client = getClient();
+  return client.request(getShopUrl(), mutationString, variables);
+}
+
+const introspectionQuery = `
+  query IntrospectionQuery {
+    __schema {
+      queryType { name }
+      mutationType { name }
+      subscriptionType { name }
+      types {
+        ...FullType
+      }
+      directives {
+        name
+        description
+        locations
+        args {
+          ...InputValue
+        }
+      }
+    }
+  }
+
+  fragment FullType on __Type {
+    kind
+    name
+    description
+    fields(includeDeprecated: true) {
+      name
+      description
+      args {
+        ...InputValue
+      }
+      type {
+        ...TypeRef
+      }
+      isDeprecated
+      deprecationReason
+    }
+    inputFields {
+      ...InputValue
+    }
+    interfaces {
+      ...TypeRef
+    }
+    enums {
+      name
+      description
+      isDeprecated
+      deprecationReason
+    }
+    possibleTypes {
+      ...TypeRef
+    }
+  }
+
+  fragment InputValue on __InputValue {
+    name
+    description
+    type { ...TypeRef }
+    defaultValue
+  }
+
+  fragment TypeRef on __Type {
+    kind
+    name
+    ofType {
+      kind
+      name
+      ofType {
+        kind
+        name
+        ofType {
+          kind
+          name
+          ofType {
+            kind
+            name
+            ofType {
+              kind
+              name
+              ofType {
+                kind
+                name
+                ofType {
+                  kind
+                  name
+                }
+              }
+            }
+          }
+        }
+      }
+    }
+  }
+`;
+
+const operationsSummaryQuery = `
+  query OperationsSummary {
+    __schema {
+      queryType {
+        fields {
+          name
+          description
+        }
+      }
+      mutationType {
+        fields {
+          name
+          description
+        }
+      }
+    }
+  }
+`;
+
+/**
+ * Fetch the Admin GraphQL schema introspection
+ */
+export async function getAdminSchema(): Promise<any> {
+  const client = getClient();
+  return client.request(getAdminUrl(), introspectionQuery);
+}
+
+/**
+ * Fetch the Shop GraphQL schema introspection
+ */
+export async function getShopSchema(): Promise<any> {
+  const client = getClient();
+  return client.request(getShopUrl(), introspectionQuery);
+}
+
+/**
+ * Fetch a summary of available queries and mutations for the Admin API
+ */
+export async function getAdminOperations(): Promise<any> {
+  const client = getClient();
+  return client.request(getAdminUrl(), operationsSummaryQuery);
+}
+
+/**
+ * Fetch a summary of available queries and mutations for the Shop API
+ */
+export async function getShopOperations(): Promise<any> {
+  const client = getClient();
+  return client.request(getShopUrl(), operationsSummaryQuery);
+}

package/src/tools/index.ts

@@ -0,0 +1 @@
+export * from "./graphql-operations.js";

package/tsconfig.json

@@ -0,0 +1,21 @@
+{
+    "compilerOptions": {
+        "target": "ES2022",
+        "module": "ESNext",
+        "moduleResolution": "node",
+        "esModuleInterop": true,
+        "strict": true,
+        "outDir": "./dist",
+        "rootDir": ".",
+        "declaration": true,
+        "skipLibCheck": true
+    },
+    "include": [
+        "*.ts",
+        "src/**/*.ts"
+    ],
+    "exclude": [
+        "node_modules",
+        "dist"
+    ]
+}