@gurveenbagga/moqui-graphql-dsl-mcp 1.0.0

package/README.md

@@ -0,0 +1,83 @@
+# Moqui GraphQL DSL MCP Server
+
+> [!NOTE]
+> **Project Status**: This MCP server is currently intended for **local execution and testing**. A global distribution roadmap (e.g., via npm and `npx`) is yet to be planned. Refer to the Local Setup steps below to integrate it locally with your IDE config.
+
+Internal MCP (Model Context Protocol) server for planning, generating, applying, and validating Moqui GraphQL DSL snippets for Shopify Admin GraphQL use cases.
+
+This server bridges your AI tools (e.g. Claude Desktop, Cursor, IntelliJ, VS Code) with your local `moqui-framework` repository, enabling automated, robust, policy-compliant Shopify API connector development.
+
+---
+
+## Features & Tools
+
+### 📋 1. Planning & Service Generation
+* **`plan_graphql_dsl_change`**: Translates your natural language intent into a structural plan, identifying the operation type (queries/mutations) and mapping any required policy safeguards.
+* **`generate_graphql_dsl_service_code`**: Generates a standard Moqui `<service>` XML block with a fully operational GraphQL DSL script calling `GraphqlFacade`.
+* **`apply_graphql_dsl_service_change`**: Writes the generated Moqui service cleanly to disk (supporting creation and seamless updates). Features a **soft-gate** validation warning system to guide external AI clients (like Codex) through validation checks.
+
+### 🧪 2. Test-Driven Development (TDD)
+* **`generate_graphql_dsl_test_code`**: Automatically generates Groovy Spock test blocks mocking standard contexts (`ec.service.sync`) and matching inputs/outputs.
+* **`apply_graphql_dsl_test_change`**: injects the Spock test block directly inside the target Groovy test file.
+
+### 🛡️ 3. Safeguards & Validation
+* **`validate_graphql_dsl`**: Evaluates custom Moqui-Shopify standards, checking for:
+  * Proper naming conventions (`Dsl` noun suffixes).
+  * Safe pagination limits (both literal bounds and variables).
+  * Missing pagination parameters like `pageInfo` on connections.
+  * Correct mutation schemas and required `userErrors`/`id` parameters.
+
+---
+
+## Local Setup
+
+### Prerequisites
+* **Node.js**: `v20` or higher
+* **Package Manager**: `npm`
+
+### 1. Install Dependencies
+```bash
+npm install
+```
+
+### 2. Build the Server
+Compiles the TypeScript codebase inside `src/` to standard ES Modules JavaScript in the `dist/` directory.
+```bash
+npm run build
+```
+
+### 3. Run Tests
+Ensure all unit and smoke tests are passing:
+```bash
+npm run test
+```
+
+### 4. Start the MCP Server in Developer Mode
+Run the server locally with live TypeScript compilation and hot-reloading (great for testing integrations):
+```bash
+npm run dev
+```
+
+---
+
+## IDE Integration Configuration
+
+To integrate this server into your Claude Desktop, Cursor, or VS Code settings, add it to your configuration file (e.g., `claude_desktop_config.json`):
+
+```json
+{
+  "mcpServers": {
+    "moqui-graphql-dsl-mcp": {
+      "command": "node",
+      "args": [
+        "/Users/gurveenkaur/Documents/Work/git/moqui-graphql-dsl-mcp/dist/server.js"
+      ],
+      "env": {
+        "MOQUI_REPO_PATH": "/Users/gurveenkaur/Documents/Work/git/oms/moqui-framework"
+      }
+    }
+  }
+}
+```
+
+Make sure to run `npm run build` after any changes to `src/` so the compiled file in `dist/` is up-to-date!

package/dist/core/paths.js

@@ -0,0 +1,11 @@
+import { resolve } from "node:path";
+export const DEFAULT_MOQUI_REPO_PATH = process.env.MOQUI_REPO_PATH
+    ? resolve(process.env.MOQUI_REPO_PATH)
+    : "/Users/gurveenkaur/Documents/Work/git/oms/moqui-framework";
+export function resolveTargetRepoPath(inputPath) {
+    return resolve((inputPath && inputPath.trim()) || DEFAULT_MOQUI_REPO_PATH);
+}
+export function isWithinRepo(repoPath, absolutePath) {
+    const normalizedRepo = repoPath.endsWith("/") ? repoPath : `${repoPath}/`;
+    return absolutePath === repoPath || absolutePath.startsWith(normalizedRepo);
+}

package/dist/core/policy.js

@@ -0,0 +1,37 @@
+import { readFileSync } from "node:fs";
+import { resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+let policy;
+try {
+    const __dirname = resolve(fileURLToPath(import.meta.url), "..");
+    const policyFilePath = resolve(__dirname, "../../src/policies/shopify_admin_policy.json");
+    const rawData = readFileSync(policyFilePath, "utf8");
+    policy = JSON.parse(rawData);
+}
+catch (e) {
+    // Graceful fallback defaults in case of file reading issues
+    policy = {
+        api: "admin",
+        naming: {
+            enforceNounSuffix: "GraphqlDsl",
+            enforceCamelCase: true
+        },
+        mutations: {
+            alwaysIncludeUserErrors: true,
+            alwaysIncludeIdOnCreate: true
+        },
+        connections: {
+            maxPageLimit: 250,
+            enforcePageInfo: true
+        },
+        defaults: {
+            enforceVariables: true
+        }
+    };
+}
+export function getPolicy() {
+    return policy;
+}
+export function defaults() {
+    return policy.defaults;
+}

package/dist/policies/shopify_admin_policy.json

@@ -0,0 +1,14 @@
+{
+    "api": "admin",
+    "rules": [
+        {
+            "rootField": "inventorySetQuantities",
+            "fromVersion": "2026-04",
+            "requiresIdempotentDirective": true
+        }
+    ],
+    "defaults": {
+        "enforceVariables": true,
+        "includeUserErrorsOnMutations": true
+    }
+}

package/dist/schemas/applyGraphqlDslServiceChange.js

@@ -0,0 +1,27 @@
+import { z } from "zod";
+export const applyGraphqlDslServiceChangeInputSchema = z.object({
+    targetRepoPath: z.string().min(1).optional(),
+    targetFilePath: z.string().min(1),
+    serviceXml: z.string().min(1),
+    insertMode: z.enum(["create_service", "update_service", "auto"]).default("auto"),
+    serviceName: z.string().optional(),
+    insertAfterService: z.string().optional(),
+    shopifyValidated: z.boolean().default(false)
+});
+export const applyGraphqlDslServiceChangeOutputSchema = z.object({
+    status: z.enum(["ok", "error"]),
+    changedFiles: z.array(z.object({
+        path: z.string(),
+        changeType: z.enum(["created", "updated"]),
+        serviceName: z.string().optional()
+    })),
+    diffSummary: z.string().optional(),
+    mandatoryNextSteps: z.array(z.object({
+        step: z.number(),
+        server: z.string(),
+        tool: z.string(),
+        description: z.string()
+    })).optional(),
+    validationWarnings: z.array(z.string()).optional(),
+    errors: z.array(z.string())
+});

package/dist/schemas/applyGraphqlDslTestChange.js

@@ -0,0 +1,16 @@
+import { z } from "zod";
+export const applyGraphqlDslTestChangeInputSchema = z.object({
+    targetRepoPath: z.string().min(1).optional(),
+    targetFilePath: z.string().min(1),
+    testCode: z.string().min(1)
+});
+export const applyGraphqlDslTestChangeOutputSchema = z.object({
+    status: z.enum(["ok", "error"]),
+    changedFiles: z.array(z.object({
+        path: z.string(),
+        changeType: z.enum(["updated"]),
+        testClassName: z.string().optional()
+    })),
+    diffSummary: z.string().optional(),
+    errors: z.array(z.string())
+});

package/dist/schemas/generateGraphqlDsl.js

@@ -0,0 +1,62 @@
+import { z } from "zod";
+export const generateGraphqlDslInputSchema = z.object({
+    api: z.literal("admin"),
+    apiVersion: z.string().min(1),
+    taskName: z.string().min(1),
+    intent: z.string().min(1),
+    operationType: z.enum(["QUERY", "MUTATION"]),
+    rootField: z.string().min(1),
+    idempotencyRequired: z.boolean().optional(),
+    constraints: z
+        .object({
+        enforceVariables: z.boolean().optional(),
+        includeUserErrors: z.boolean().optional(),
+        useConnectionHelpers: z.boolean().optional()
+    })
+        .optional(),
+    inputs: z
+        .object({
+        businessParams: z.record(z.string()).optional(),
+        argVars: z
+            .array(z.object({
+            argName: z.string(),
+            varName: z.string(),
+            type: z.string(),
+            nonNull: z.boolean().optional(),
+            value: z.unknown().optional()
+        }))
+            .optional(),
+        argLiterals: z.record(z.unknown()).optional(),
+        variables: z
+            .array(z.object({
+            name: z.string(),
+            type: z.string(),
+            nonNull: z.boolean().optional(),
+            value: z.unknown().optional()
+        }))
+            .optional(),
+        selectionFields: z.array(z.string()).optional()
+    })
+        .optional(),
+    selectionHint: z.array(z.string()).optional(),
+    outputTargets: z
+        .object({
+        serviceXml: z.string().optional(),
+        testFile: z.string().optional()
+    })
+        .optional()
+});
+export const generateGraphqlDslOutputSchema = z.object({
+    status: z.enum(["ok", "needs_input", "error"]),
+    serviceName: z.string().optional(),
+    dslSnippet: z.string().optional(),
+    expectedGraphql: z.string().optional(),
+    expectedVariablesSchema: z.record(z.string()).optional(),
+    appliedPolicies: z.array(z.object({
+        name: z.string(),
+        source: z.string(),
+        effect: z.string()
+    })),
+    warnings: z.array(z.string()),
+    errors: z.array(z.string())
+});

package/dist/schemas/generateGraphqlDslServiceCode.js

@@ -0,0 +1,28 @@
+import { z } from "zod";
+export const generateGraphqlDslServiceCodeInputSchema = z.object({
+    plan: z.object({
+        operationType: z.enum(["QUERY", "MUTATION"]),
+        rootField: z.string().min(1),
+        serviceVerb: z.string().min(1),
+        serviceNoun: z.string().min(1),
+        variables: z.array(z.object({ name: z.string(), type: z.string(), required: z.boolean() })),
+        selectionTree: z.object({ fields: z.array(z.string()) }),
+        policyRequirements: z.array(z.string()),
+        isConnection: z.boolean().optional()
+    }),
+    format: z.literal("service_xml").default("service_xml")
+});
+export const generateGraphqlDslServiceCodeOutputSchema = z.object({
+    status: z.enum(["ok", "error"]),
+    serviceName: z.string().optional(),
+    serviceXml: z.string().optional(),
+    expectedQueryShape: z.record(z.unknown()).optional(),
+    mandatoryNextSteps: z.array(z.object({
+        step: z.number(),
+        server: z.string(),
+        tool: z.string(),
+        description: z.string()
+    })).optional(),
+    warnings: z.array(z.string()),
+    errors: z.array(z.string())
+});

package/dist/schemas/generateGraphqlDslTestCode.js

@@ -0,0 +1,20 @@
+import { z } from "zod";
+export const generateGraphqlDslTestCodeInputSchema = z.object({
+    plan: z.object({
+        operationType: z.enum(["QUERY", "MUTATION"]),
+        rootField: z.string().min(1),
+        serviceVerb: z.string().min(1),
+        serviceNoun: z.string().min(1),
+        variables: z.array(z.object({ name: z.string(), type: z.string(), required: z.boolean() })),
+        selectionTree: z.object({ fields: z.array(z.string()) }),
+        policyRequirements: z.array(z.string()).optional(),
+        isConnection: z.boolean()
+    }),
+    format: z.literal("groovy").default("groovy")
+});
+export const generateGraphqlDslTestCodeOutputSchema = z.object({
+    status: z.enum(["ok", "error"]),
+    testCode: z.string().optional(),
+    warnings: z.array(z.string()),
+    errors: z.array(z.string())
+});

package/dist/schemas/planGraphqlDslChange.js

@@ -0,0 +1,41 @@
+import { z } from "zod";
+export const planGraphqlDslChangeInputSchema = z.object({
+    targetRepoPath: z.string().min(1).optional(),
+    targetFilePath: z.string().min(1),
+    intent: z.string().min(1),
+    serviceVerb: z.string().min(1).default("build"),
+    serviceNoun: z.string().min(1).optional(),
+    api: z.literal("admin").default("admin"),
+    apiVersion: z.string().min(1).default("2026-01"),
+    selectionHint: z.array(z.string().min(1)).optional(),
+    sampleInputs: z.record(z.unknown()).optional(),
+    insertMode: z.enum(["create_service", "update_service", "auto"]).default("auto"),
+    insertAfterService: z.string().optional(),
+    rootField: z.string().min(1).optional(),
+    operationType: z.enum(["QUERY", "MUTATION"]).optional(),
+    isConnection: z.boolean().optional()
+});
+export const mandatoryNextStepSchema = z.object({
+    step: z.number(),
+    server: z.string(),
+    tool: z.string(),
+    description: z.string()
+});
+export const planGraphqlDslChangeOutputSchema = z.object({
+    status: z.enum(["ok", "error"]),
+    plan: z
+        .object({
+        operationType: z.enum(["QUERY", "MUTATION"]),
+        rootField: z.string(),
+        serviceVerb: z.string(),
+        serviceNoun: z.string(),
+        variables: z.array(z.object({ name: z.string(), type: z.string(), required: z.boolean() })),
+        selectionTree: z.object({ fields: z.array(z.string()) }),
+        policyRequirements: z.array(z.string()),
+        isConnection: z.boolean()
+    })
+        .optional(),
+    mandatoryNextSteps: z.array(mandatoryNextStepSchema).optional(),
+    warnings: z.array(z.string()),
+    errors: z.array(z.string())
+});

package/dist/schemas/validateGraphqlDsl.js

@@ -0,0 +1,29 @@
+import { z } from "zod";
+export const validateGraphqlDslInputSchema = z.object({
+    api: z.literal("admin"),
+    apiVersion: z.string().min(1),
+    operationType: z.enum(["QUERY", "MUTATION"]),
+    rootField: z.string().min(1),
+    graphql: z.string().min(1),
+    variablesSample: z.record(z.unknown()).optional(),
+    policyContext: z
+        .object({
+        idempotencyRequired: z.boolean().optional()
+    })
+        .optional()
+});
+export const validateGraphqlDslOutputSchema = z.object({
+    status: z.enum(["passed", "failed"]),
+    schemaValidation: z.object({
+        performed: z.boolean(),
+        provider: z.enum(["shopify-mcp", "local", "none"])
+    }),
+    issues: z.array(z.object({
+        code: z.string(),
+        message: z.string(),
+        path: z.string().optional(),
+        severity: z.enum(["error", "warning"]),
+        suggestion: z.string().optional()
+    })),
+    normalizedGraphql: z.string().optional()
+});

package/dist/server.js

@@ -0,0 +1,162 @@
+#!/usr/bin/env node
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import pino from "pino";
+import { z } from "zod";
+import { generateGraphqlDsl } from "./tools/generateGraphqlDsl.js";
+import { validateGraphqlDsl } from "./tools/validateGraphqlDsl.js";
+import { planGraphqlDslChange } from "./tools/planGraphqlDslChange.js";
+import { generateGraphqlDslServiceCode } from "./tools/generateGraphqlDslServiceCode.js";
+import { applyGraphqlDslServiceChange } from "./tools/applyGraphqlDslServiceChange.js";
+import { planGraphqlDslChangeInputSchema } from "./schemas/planGraphqlDslChange.js";
+import { generateGraphqlDslServiceCodeInputSchema } from "./schemas/generateGraphqlDslServiceCode.js";
+import { generateGraphqlDslTestCode } from "./tools/generateGraphqlDslTestCode.js";
+import { applyGraphqlDslTestChange } from "./tools/applyGraphqlDslTestChange.js";
+import { generateGraphqlDslTestCodeInputSchema } from "./schemas/generateGraphqlDslTestCode.js";
+import { applyGraphqlDslTestChangeInputSchema } from "./schemas/applyGraphqlDslTestChange.js";
+// MCP uses stdout for protocol frames, so all logs must go to stderr.
+const logger = pino({ level: process.env.LOG_LEVEL ?? "info" }, pino.destination(2));
+const server = new McpServer({
+    name: "moqui-graphql-dsl-mcp",
+    version: "1.0.0"
+});
+server.registerTool("generate_graphql_dsl", {
+    title: "Generate GraphQL DSL",
+    description: "MANDATORY: Call this tool whenever the user asks to write, build, or generate a Moqui Groovy GraphQL DSL snippet or mock query for a Shopify API operation. Never guess the syntax manually.",
+    inputSchema: {
+        api: z.literal("admin"),
+        apiVersion: z.string(),
+        taskName: z.string(),
+        intent: z.string(),
+        operationType: z.enum(["QUERY", "MUTATION"]),
+        rootField: z.string(),
+        idempotencyRequired: z.boolean().optional(),
+        constraints: z
+            .object({
+            enforceVariables: z.boolean().optional(),
+            includeUserErrors: z.boolean().optional(),
+            useConnectionHelpers: z.boolean().optional()
+        })
+            .optional(),
+        inputs: z
+            .object({
+            businessParams: z.record(z.string()).optional(),
+            argVars: z
+                .array(z.object({
+                argName: z.string(),
+                varName: z.string(),
+                type: z.string(),
+                nonNull: z.boolean().optional(),
+                value: z.unknown().optional()
+            }))
+                .optional(),
+            argLiterals: z.record(z.unknown()).optional(),
+            variables: z
+                .array(z.object({
+                name: z.string(),
+                type: z.string(),
+                nonNull: z.boolean().optional(),
+                value: z.unknown().optional()
+            }))
+                .optional(),
+            selectionFields: z.array(z.string()).optional()
+        })
+            .optional(),
+        selectionHint: z.array(z.string()).optional(),
+        outputTargets: z
+            .object({
+            serviceXml: z.string().optional(),
+            testFile: z.string().optional()
+        })
+            .optional()
+    }
+}, async (input) => {
+    const output = generateGraphqlDsl(input);
+    return {
+        content: [{ type: "text", text: JSON.stringify(output, null, 2) }]
+    };
+});
+server.registerTool("plan_graphql_dsl_change", {
+    title: "Plan GraphQL DSL Change",
+    description: "MANDATORY: Call this tool at the very beginning of a Moqui GraphQL DSL task to plan service changes, analyze intents, check constraints, and set mandatory next steps.",
+    inputSchema: planGraphqlDslChangeInputSchema.shape
+}, async (input) => {
+    const output = planGraphqlDslChange(input);
+    return {
+        content: [{ type: "text", text: JSON.stringify(output, null, 2) }]
+    };
+});
+server.registerTool("generate_graphql_dsl_service_code", {
+    title: "Generate GraphQL DSL Service Code",
+    description: "MANDATORY: Call this tool to generate the formal Moqui service XML wrapper holding the GraphqlFacade builder script. Do not write the service XML manually.",
+    inputSchema: generateGraphqlDslServiceCodeInputSchema.shape
+}, async (input) => {
+    const output = generateGraphqlDslServiceCode(input);
+    return {
+        content: [{ type: "text", text: JSON.stringify(output, null, 2) }]
+    };
+});
+server.registerTool("apply_graphql_dsl_service_change", {
+    title: "Apply GraphQL DSL Service Change",
+    description: "MANDATORY: Call this tool to write or update the generated Moqui GraphQL service XML block on disk inside the target repository. Safe for creating new or merging into existing files.",
+    inputSchema: {
+        targetRepoPath: z.string().optional(),
+        targetFilePath: z.string(),
+        serviceXml: z.string(),
+        insertMode: z.enum(["create_service", "update_service", "auto"]).default("auto"),
+        serviceName: z.string().optional(),
+        insertAfterService: z.string().optional()
+    }
+}, async (input) => {
+    const output = await applyGraphqlDslServiceChange(input);
+    return {
+        content: [{ type: "text", text: JSON.stringify(output, null, 2) }]
+    };
+});
+server.registerTool("validate_graphql_dsl", {
+    title: "Validate GraphQL DSL Output",
+    description: "MANDATORY: Call this tool to validate generated GraphQL operations against Moqui local integration policies (idempotency, connections, userErrors, noun suffixes, limit checks).",
+    inputSchema: {
+        api: z.literal("admin"),
+        apiVersion: z.string(),
+        operationType: z.enum(["QUERY", "MUTATION"]),
+        rootField: z.string(),
+        graphql: z.string(),
+        variablesSample: z.record(z.unknown()).optional(),
+        policyContext: z.object({ idempotencyRequired: z.boolean().optional() }).optional()
+    }
+}, async (input) => {
+    const output = validateGraphqlDsl(input);
+    return {
+        content: [{ type: "text", text: JSON.stringify(output, null, 2) }]
+    };
+});
+server.registerTool("generate_graphql_dsl_test_code", {
+    title: "Generate GraphQL DSL Test Code",
+    description: "MANDATORY: Call this tool to generate a Groovy Spock unit test method mimicking the service's GraphQL operation and mocking execution context parameters.",
+    inputSchema: generateGraphqlDslTestCodeInputSchema.shape
+}, async (input) => {
+    const output = generateGraphqlDslTestCode(input);
+    return {
+        content: [{ type: "text", text: JSON.stringify(output, null, 2) }]
+    };
+});
+server.registerTool("apply_graphql_dsl_test_change", {
+    title: "Apply GraphQL DSL Test Change",
+    description: "MANDATORY: Call this tool to inject/insert the generated Spock Groovy unit test block into the target test file inside the Moqui repository.",
+    inputSchema: applyGraphqlDslTestChangeInputSchema.shape
+}, async (input) => {
+    const output = await applyGraphqlDslTestChange(input);
+    return {
+        content: [{ type: "text", text: JSON.stringify(output, null, 2) }]
+    };
+});
+async function main() {
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    logger.info("moqui-graphql-dsl-mcp started");
+}
+main().catch((error) => {
+    logger.error({ error }, "Server failed to start");
+    process.exit(1);
+});

package/dist/tools/applyGraphqlDslServiceChange.js

@@ -0,0 +1,103 @@
+import { readFile, writeFile } from "node:fs/promises";
+import { resolve } from "node:path";
+import { applyGraphqlDslServiceChangeInputSchema } from "../schemas/applyGraphqlDslServiceChange.js";
+import { resolveTargetRepoPath, isWithinRepo } from "../core/paths.js";
+function extractServiceNameFromXml(serviceXml) {
+    const match = serviceXml.match(/<service\s+verb="([^"]+)"\s+noun="([^"]+)"/);
+    if (!match)
+        return undefined;
+    return `${match[1]}#${match[2]}`;
+}
+function extractServiceBlockRange(fileText, verb, noun) {
+    const startMarker = `<service verb="${verb}" noun="${noun}">`;
+    const startIdx = fileText.indexOf(startMarker);
+    if (startIdx === -1)
+        return null;
+    const endMarker = "</service>";
+    const endIdx = fileText.indexOf(endMarker, startIdx);
+    if (endIdx === -1)
+        return null;
+    return [startIdx, endIdx + endMarker.length];
+}
+const TEST_GENERATION_NEXT_STEPS = [
+    {
+        step: 1,
+        server: "moqui-graphql-dsl-mcp",
+        tool: "generate_graphql_dsl_test_code",
+        description: "Generate a Spock test case for the service that was just written to disk."
+    },
+    {
+        step: 2,
+        server: "moqui-graphql-dsl-mcp",
+        tool: "apply_graphql_dsl_test_change",
+        description: "Inject the generated Spock test into the target test file in the Moqui component."
+    }
+];
+export async function applyGraphqlDslServiceChange(raw) {
+    const parsed = applyGraphqlDslServiceChangeInputSchema.safeParse(raw);
+    if (!parsed.success) {
+        return {
+            status: "error",
+            changedFiles: [],
+            errors: parsed.error.issues.map((i) => `${i.path.join(".")}: ${i.message}`)
+        };
+    }
+    const input = parsed.data;
+    const validationWarnings = [];
+    // Soft gate: flag if Shopify schema validation was not explicitly confirmed.
+    // We do not block the write — external AI clients may have run validation
+    // via shopify-dev-mcp without knowing to pass shopifyValidated: true.
+    // The mandatoryNextSteps in plan/generate tools handle proactive education.
+    if (!input.shopifyValidated) {
+        validationWarnings.push("SHOPIFY_VALIDATION_NOT_CONFIRMED: This service was written without explicit Shopify schema " +
+            "validation confirmation. Ensure validate_graphql_codeblocks (shopify-dev-mcp) has been run " +
+            "on the generated query before deploying. Pass shopifyValidated: true to suppress this warning.");
+    }
+    const repoPath = resolveTargetRepoPath(input.targetRepoPath);
+    const absolutePath = resolve(repoPath, input.targetFilePath);
+    if (!isWithinRepo(repoPath, absolutePath)) {
+        return { status: "error", changedFiles: [], errors: [`targetFilePath resolves outside target repo: ${absolutePath}`] };
+    }
+    const original = await readFile(absolutePath, "utf8");
+    const derivedServiceName = input.serviceName ?? extractServiceNameFromXml(input.serviceXml);
+    const [verb, noun] = derivedServiceName?.split("#") ?? [];
+    if ((input.insertMode === "update_service" || input.insertMode === "auto") && verb && noun) {
+        const blockRange = extractServiceBlockRange(original, verb, noun);
+        if (blockRange) {
+            const [start, end] = blockRange;
+            const updated = `${original.slice(0, start)}${input.serviceXml}${original.slice(end)}`;
+            await writeFile(absolutePath, updated, "utf8");
+            return {
+                status: "ok",
+                changedFiles: [{ path: absolutePath, changeType: "updated", serviceName: derivedServiceName }],
+                diffSummary: `Updated existing service ${derivedServiceName} in ${input.targetFilePath}`,
+                mandatoryNextSteps: TEST_GENERATION_NEXT_STEPS,
+                validationWarnings,
+                errors: []
+            };
+        }
+        if (input.insertMode === "update_service") {
+            return {
+                status: "error",
+                changedFiles: [],
+                errors: [`Service ${derivedServiceName} not found for update in ${input.targetFilePath}`]
+            };
+        }
+    }
+    const marker = "</services>";
+    const markerIdx = original.lastIndexOf(marker);
+    if (markerIdx === -1) {
+        return { status: "error", changedFiles: [], errors: ["Invalid service XML: missing </services>"] };
+    }
+    const insertion = `\n\n    ${input.serviceXml}\n`;
+    const updated = original.slice(0, markerIdx) + insertion + original.slice(markerIdx);
+    await writeFile(absolutePath, updated, "utf8");
+    return {
+        status: "ok",
+        changedFiles: [{ path: absolutePath, changeType: "updated", serviceName: derivedServiceName }],
+        diffSummary: `Inserted service block into ${input.targetFilePath}`,
+        mandatoryNextSteps: TEST_GENERATION_NEXT_STEPS,
+        validationWarnings,
+        errors: []
+    };
+}

package/dist/tools/applyGraphqlDslTestChange.js

@@ -0,0 +1,63 @@
+import { readFile, writeFile } from "node:fs/promises";
+import { resolve } from "node:path";
+import { applyGraphqlDslTestChangeInputSchema } from "../schemas/applyGraphqlDslTestChange.js";
+import { resolveTargetRepoPath, isWithinRepo } from "../core/paths.js";
+export async function applyGraphqlDslTestChange(raw) {
+    const parsed = applyGraphqlDslTestChangeInputSchema.safeParse(raw);
+    if (!parsed.success) {
+        return {
+            status: "error",
+            changedFiles: [],
+            errors: parsed.error.issues.map((i) => `${i.path.join(".")}: ${i.message}`)
+        };
+    }
+    const input = parsed.data;
+    const repoPath = resolveTargetRepoPath(input.targetRepoPath);
+    const absolutePath = resolve(repoPath, input.targetFilePath);
+    if (!isWithinRepo(repoPath, absolutePath)) {
+        return {
+            status: "error",
+            changedFiles: [],
+            errors: [`targetFilePath resolves outside target repo: ${absolutePath}`]
+        };
+    }
+    let original = "";
+    try {
+        original = await readFile(absolutePath, "utf8");
+    }
+    catch (e) {
+        return {
+            status: "error",
+            changedFiles: [],
+            errors: [`Cannot read Spock test file: ${absolutePath}`, String(e)]
+        };
+    }
+    const trimmed = original.trimEnd();
+    const lastBraceIdx = trimmed.lastIndexOf("}");
+    if (lastBraceIdx === -1) {
+        return {
+            status: "error",
+            changedFiles: [],
+            errors: [`Could not find closing class brace '}' in Spock test file: ${absolutePath}`]
+        };
+    }
+    const beforeBrace = trimmed.slice(0, lastBraceIdx);
+    const afterBrace = trimmed.slice(lastBraceIdx);
+    const updated = `${beforeBrace.trimEnd()}\n\n${input.testCode}\n${afterBrace}\n`;
+    await writeFile(absolutePath, updated, "utf8");
+    // Try to extract class name for reporting
+    const classMatch = original.match(/class\s+(\w+)/);
+    const testClassName = classMatch ? classMatch[1] : undefined;
+    return {
+        status: "ok",
+        changedFiles: [
+            {
+                path: absolutePath,
+                changeType: "updated",
+                testClassName
+            }
+        ],
+        diffSummary: `Injected new Spock test case into ${testClassName ?? input.targetFilePath}`,
+        errors: []
+    };
+}

package/dist/tools/generateGraphqlDsl.js

@@ -0,0 +1,89 @@
+import { generateGraphqlDslInputSchema } from "../schemas/generateGraphqlDsl.js";
+import { defaults } from "../core/policy.js";
+function buildServiceName(taskName) {
+    return `build#${taskName}Dsl`;
+}
+function buildExpectedGraphql(input, requireIdempotent) {
+    const op = input.operationType.toLowerCase();
+    const argVars = input.inputs?.argVars ?? [];
+    const variables = input.inputs?.variables ?? [];
+    const allVars = [
+        ...argVars.map((v) => ({ name: v.varName, type: v.type, nonNull: v.nonNull })),
+        ...variables.map((v) => ({ name: v.name, type: v.type, nonNull: v.nonNull }))
+    ];
+    const varSignature = allVars.length
+        ? `(${allVars.map((v) => `$${v.name}: ${v.type}${v.nonNull ? "!" : ""}`).join(", ")})`
+        : "";
+    const fieldArgs = argVars.length ? `(${argVars.map((v) => `${v.argName}: $${v.varName}`).join(", ")})` : "";
+    const literalArgs = input.inputs?.argLiterals
+        ? Object.entries(input.inputs.argLiterals).map(([k, v]) => `${k}: ${JSON.stringify(v)}`)
+        : [];
+    const mergedArgs = literalArgs.length && fieldArgs
+        ? `(${fieldArgs.slice(1, -1)}, ${literalArgs.join(", ")})`
+        : literalArgs.length
+            ? `(${literalArgs.join(", ")})`
+            : fieldArgs;
+    const idempotentPart = requireIdempotent || input.idempotencyRequired ? " @idempotent(key: $idempotencyKey)" : "";
+    const fields = input.inputs?.selectionFields?.length ? input.inputs.selectionFields : input.selectionHint?.length ? input.selectionHint : ["id"];
+    return `${op} ${input.taskName}${varSignature} {\\n  ${input.rootField}${mergedArgs}${idempotentPart} {\\n    ${fields.join("\\n    ")}\\n  }\\n}`;
+}
+function buildDsl(input, requireIdempotent) {
+    const lines = [];
+    lines.push(`def builder = GraphqlFacade.root("${input.rootField}")`);
+    lines.push(`    .operation("${input.operationType}")`);
+    lines.push(`    .name("${input.taskName}")`);
+    (input.inputs?.argVars ?? []).forEach((v) => {
+        const value = v.value === undefined ? "null" : JSON.stringify(v.value);
+        lines.push(`    .argVar("${v.argName}", "${v.varName}", "${v.type}", ${Boolean(v.nonNull)}, ${value})`);
+    });
+    Object.entries(input.inputs?.argLiterals ?? {}).forEach(([k, v]) => {
+        lines.push(`    .argLiteral("${k}", ${JSON.stringify(v)})`);
+    });
+    (input.inputs?.variables ?? []).forEach((v) => {
+        const name = v.name;
+        const value = v.value === undefined ? "null" : JSON.stringify(v.value);
+        lines.push(`    .variable("${name}", "${v.type}", ${Boolean(v.nonNull)}, ${value})`);
+    });
+    if (requireIdempotent || input.idempotencyRequired) {
+        lines.push(`builder.rootDirective(builder.dir("idempotent", [key: builder.varRef("idempotencyKey")]))`);
+    }
+    const fields = input.inputs?.selectionFields?.length ? input.inputs.selectionFields : input.selectionHint?.length ? input.selectionHint : ["id"];
+    lines.push("");
+    lines.push("def result = builder.select {");
+    fields.forEach((f) => lines.push(`    field("${f}")`));
+    if (input.operationType === "MUTATION") {
+        lines.push('    field("userErrors") { field("field", "message") }');
+    }
+    lines.push("}.build()");
+    return lines.join("\n");
+}
+export function generateGraphqlDsl(raw) {
+    const parsed = generateGraphqlDslInputSchema.safeParse(raw);
+    if (!parsed.success) {
+        return {
+            status: "error",
+            appliedPolicies: [],
+            warnings: [],
+            errors: parsed.error.issues.map((i) => `${i.path.join(".")}: ${i.message}`)
+        };
+    }
+    const input = parsed.data;
+    const policyDefaults = defaults();
+    const policyRequires = false;
+    return {
+        status: "ok",
+        serviceName: buildServiceName(input.taskName),
+        dslSnippet: buildDsl(input, policyRequires),
+        expectedGraphql: buildExpectedGraphql(input, policyRequires),
+        expectedVariablesSchema: {},
+        appliedPolicies: [
+            {
+                name: "defaults",
+                source: "shopify_admin_policy.json",
+                effect: `enforceVariables=${policyDefaults.enforceVariables}`
+            }
+        ],
+        warnings: [],
+        errors: []
+    };
+}

package/dist/tools/generateGraphqlDslServiceCode.js

@@ -0,0 +1,77 @@
+import { generateGraphqlDslServiceCodeInputSchema } from "../schemas/generateGraphqlDslServiceCode.js";
+function buildServiceXml(plan) {
+    const isConnection = plan.isConnection !== undefined
+        ? plan.isConnection
+        : (plan.rootField.endsWith("s") && !plan.rootField.endsWith("ss"));
+    const fields = plan.selectionTree.fields.map((f) => `                            field("${f}")`).join("\n");
+    const connectionArgs = isConnection
+        ? `\n                        .connection([first: first as int, after: after]) {\n${fields}\n                        }`
+        : `\n                        .select {\n${fields}\n                        }`;
+    const inParams = isConnection
+        ? `\n            <parameter name="first" type="Integer" required="true"/>\n            <parameter name="after"/>`
+        : "";
+    return `<service verb="${plan.serviceVerb}" noun="${plan.serviceNoun}">
+        <in-parameters>${inParams}
+        </in-parameters>
+        <out-parameters>
+            <parameter name="query" type="String"/>
+            <parameter name="variables" type="Map"/>
+        </out-parameters>
+        <actions>
+            <script><![CDATA[
+                import co.hotwax.shopify.graphql.GraphqlFacade
+
+                def result = GraphqlFacade.root("${plan.rootField}")
+                        .operation("${plan.operationType}")
+                        .name("${plan.serviceNoun}")${connectionArgs}
+                        .build()
+
+                context.put("query", result.query)
+                context.put("variables", result.variables)
+            ]]></script>
+        </actions>
+    </service>`;
+}
+export function generateGraphqlDslServiceCode(raw) {
+    const parsed = generateGraphqlDslServiceCodeInputSchema.safeParse(raw);
+    if (!parsed.success) {
+        return {
+            status: "error",
+            warnings: [],
+            errors: parsed.error.issues.map((i) => `${i.path.join(".")}: ${i.message}`)
+        };
+    }
+    const { plan } = parsed.data;
+    return {
+        status: "ok",
+        serviceName: `${plan.serviceVerb}#${plan.serviceNoun}`,
+        serviceXml: buildServiceXml(plan),
+        expectedQueryShape: {
+            operationType: plan.operationType,
+            rootField: plan.rootField,
+            selectedFields: plan.selectionTree.fields
+        },
+        mandatoryNextSteps: [
+            {
+                step: 1,
+                server: "shopify-dev-mcp",
+                tool: "learn_shopify_api",
+                description: "Initialize Shopify Admin API context (api: 'admin') to get a conversationId required for subsequent steps."
+            },
+            {
+                step: 2,
+                server: "shopify-dev-mcp",
+                tool: "search_docs_chunks",
+                description: `Verify field names, argument names, and API behavior for rootField '${plan.rootField}' are correct before writing to disk.`
+            },
+            {
+                step: 3,
+                server: "shopify-dev-mcp",
+                tool: "validate_graphql_codeblocks",
+                description: "Validate the generated GraphQL operation against Shopify's live schema. You MUST pass shopifyValidated: true to apply_graphql_dsl_service_change — the tool will reject the write otherwise."
+            }
+        ],
+        warnings: [],
+        errors: []
+    };
+}

package/dist/tools/generateGraphqlDslTestCode.js

@@ -0,0 +1,96 @@
+import { generateGraphqlDslTestCodeInputSchema } from "../schemas/generateGraphqlDslTestCode.js";
+function getMockValue(name, type) {
+    const lowerName = name.toLowerCase();
+    const lowerType = type.toLowerCase();
+    if (lowerType.includes("int") || lowerType.includes("long")) {
+        return "10";
+    }
+    if (lowerType.includes("float") || lowerType.includes("double") || lowerType.includes("bigdecimal")) {
+        return "100.00";
+    }
+    if (lowerType.includes("boolean")) {
+        return "true";
+    }
+    if (lowerType.includes("id")) {
+        return `"gid://shopify/Customer/1"`;
+    }
+    if (lowerName.includes("cursor") || lowerName.includes("after")) {
+        return `"eyJjcmVhdGVkX2F0IjoiMjAyNi0wNS0yNSAxNTowMDowMCJ9"`;
+    }
+    return `"test_${name}"`;
+}
+function buildSpockMethod(plan) {
+    const methodName = `build ${plan.rootField} query using dsl connection helper`;
+    const normalizedMethodName = methodName.replace(/[^a-zA-Z0-9\s]/g, "");
+    // Generate mock parameters map
+    const mockParamsList = [];
+    if (plan.isConnection) {
+        mockParamsList.push(`                        first: 10`);
+        mockParamsList.push(`                        after: null`);
+    }
+    plan.variables.forEach((v) => {
+        // Avoid duplicate pagination params
+        if (plan.isConnection && (v.name === "first" || v.name === "after")) {
+            return;
+        }
+        const val = getMockValue(v.name, v.type);
+        mockParamsList.push(`                        ${v.name}: ${val}`);
+    });
+    const mockParams = mockParamsList.length
+        ? `\n${mockParamsList.join(",\n")}\n                `
+        : "";
+    const assertions = [];
+    const queryVarCheck = plan.operationType.toLowerCase();
+    assertions.push(`        result.query`);
+    assertions.push(`        result.variables`);
+    // Verify variable declarations in the GraphQL header signature
+    if (plan.isConnection) {
+        assertions.push(`        normalize(result.query).contains("(\$first: Int!, \$after: String)")`);
+        assertions.push(`        normalize(result.query).contains("${plan.rootField}(first: \$first, after: \$after)")`);
+        assertions.push(`        normalize(result.query).contains("edges { node {")`);
+    }
+    else {
+        const headerVars = plan.variables.map((v) => `\$${v.name}: ${v.type}${v.required ? "!" : ""}`).join(", ");
+        if (headerVars) {
+            assertions.push(`        normalize(result.query).contains("(${headerVars})")`);
+        }
+        const args = plan.variables.map((v) => `${v.name}: \$${v.name}`).join(", ");
+        if (args) {
+            assertions.push(`        normalize(result.query).contains("${plan.rootField}(${args})")`);
+        }
+        else {
+            assertions.push(`        normalize(result.query).contains("${plan.rootField}")`);
+        }
+    }
+    // Verify selection fields are present in compiled query
+    plan.selectionTree.fields.forEach((f) => {
+        assertions.push(`        normalize(result.query).contains("${f}")`);
+    });
+    return `    def "${normalizedMethodName}"() {
+        when:
+        Map result = ec.service.sync()
+                .name("build#${plan.serviceNoun}")
+                .parameters([${mockParams}])
+                .call()
+
+        then:
+${assertions.join("\n")}
+    }`;
+}
+export function generateGraphqlDslTestCode(raw) {
+    const parsed = generateGraphqlDslTestCodeInputSchema.safeParse(raw);
+    if (!parsed.success) {
+        return {
+            status: "error",
+            warnings: [],
+            errors: parsed.error.issues.map((i) => `${i.path.join(".")}: ${i.message}`)
+        };
+    }
+    const { plan } = parsed.data;
+    return {
+        status: "ok",
+        testCode: buildSpockMethod(plan),
+        warnings: [],
+        errors: []
+    };
+}

package/dist/tools/planGraphqlDslChange.js

@@ -0,0 +1,114 @@
+import { planGraphqlDslChangeInputSchema } from "../schemas/planGraphqlDslChange.js";
+import { readFileSync } from "node:fs";
+import { resolve } from "node:path";
+import { resolveTargetRepoPath, isWithinRepo } from "../core/paths.js";
+export function planGraphqlDslChange(raw) {
+    const parsed = planGraphqlDslChangeInputSchema.safeParse(raw);
+    if (!parsed.success) {
+        return {
+            status: "error",
+            warnings: [],
+            errors: parsed.error.issues.map((i) => `${i.path.join(".")}: ${i.message}`)
+        };
+    }
+    const input = parsed.data;
+    const repoPath = resolveTargetRepoPath(input.targetRepoPath);
+    const absolutePath = resolve(repoPath, input.targetFilePath);
+    if (!isWithinRepo(repoPath, absolutePath)) {
+        return {
+            status: "error",
+            warnings: [],
+            errors: [`targetFilePath resolves outside target repo: ${absolutePath}`]
+        };
+    }
+    let fileText = "";
+    try {
+        fileText = readFileSync(absolutePath, "utf8");
+    }
+    catch (e) {
+        return {
+            status: "error",
+            warnings: [],
+            errors: [`Cannot read target file: ${absolutePath}`, String(e)]
+        };
+    }
+    const lowerIntent = input.intent.toLowerCase();
+    const operationType = input.operationType ?? (lowerIntent.includes("mutation") ||
+        /create|update|delete|set|add|remove|stage|publish|cancel/.test(lowerIntent)
+        ? "MUTATION"
+        : "QUERY");
+    function extractRootField(intent) {
+        const words = intent.split(/[^a-zA-Z0-9]/).filter(w => w.length > 0);
+        const stopWords = new Set([
+            "fetch", "get", "query", "find", "retrieve", "list", "mutation",
+            "create", "update", "delete", "set", "add", "remove", "stage",
+            "publish", "cancel", "a", "an", "the", "with", "for", "of", "on", "in", "to", "run"
+        ]);
+        const contentWords = words.filter(w => !stopWords.has(w.toLowerCase()));
+        const noun = contentWords.length > 0 ? contentWords[0] : "orders";
+        const verbs = ["create", "update", "delete", "set", "add", "remove", "stage", "publish", "cancel"];
+        const foundVerb = verbs.find(v => lowerIntent.includes(v));
+        if (foundVerb) {
+            const capitalizedVerb = foundVerb.charAt(0).toUpperCase() + foundVerb.slice(1);
+            if (!noun.toLowerCase().includes(foundVerb)) {
+                return `${noun}${capitalizedVerb}`;
+            }
+        }
+        return noun;
+    }
+    const rootField = input.rootField ?? extractRootField(input.intent);
+    const isConnection = input.isConnection !== undefined
+        ? input.isConnection
+        : (rootField.endsWith("s") && !rootField.endsWith("ss")) ||
+            /connection|edges|node|pageinfo|list|all|paginate|pagination/.test(lowerIntent);
+    const fields = input.selectionHint?.length ? input.selectionHint : ["id", "name"];
+    const serviceNoun = input.serviceNoun ?? `${rootField.charAt(0).toUpperCase()}${rootField.slice(1)}GraphqlDsl`;
+    const serviceSignature = `<service verb="${input.serviceVerb}" noun="${serviceNoun}">`;
+    const existsInFile = fileText.includes(serviceSignature);
+    const requestedMode = input.insertMode;
+    const resolvedMode = requestedMode === "auto" ? (existsInFile ? "update_service" : "create_service") : requestedMode;
+    const variables = isConnection
+        ? [
+            { name: "first", type: "Integer", required: true },
+            { name: "after", type: "String", required: false }
+        ]
+        : [];
+    return {
+        status: "ok",
+        plan: {
+            operationType,
+            rootField,
+            serviceVerb: input.serviceVerb,
+            serviceNoun,
+            variables,
+            selectionTree: { fields },
+            policyRequirements: [
+                ...(operationType === "MUTATION" ? ["idempotency_review_required"] : []),
+                `change_mode=${resolvedMode}`
+            ],
+            isConnection
+        },
+        mandatoryNextSteps: [
+            {
+                step: 1,
+                server: "shopify-dev-mcp",
+                tool: "learn_shopify_api",
+                description: "Initialize Shopify Admin API context (api: 'admin') to get a conversationId required for subsequent steps."
+            },
+            {
+                step: 2,
+                server: "shopify-dev-mcp",
+                tool: "search_docs_chunks",
+                description: `Verify field names, argument names, and API behavior for the planned rootField '${rootField}' before generating any code.`
+            },
+            {
+                step: 3,
+                server: "shopify-dev-mcp",
+                tool: "validate_graphql_codeblocks",
+                description: "Validate the final generated GraphQL operation against Shopify's live schema. Pass shopifyValidated: true to apply_graphql_dsl_service_change only after this passes."
+            }
+        ],
+        warnings: existsInFile ? [`Service already exists in target file; planned mode: ${resolvedMode}`] : [],
+        errors: []
+    };
+}

package/dist/tools/validateGraphqlDsl.js

@@ -0,0 +1,141 @@
+import { validateGraphqlDslInputSchema } from "../schemas/validateGraphqlDsl.js";
+import { getPolicy } from "../core/policy.js";
+function normalizeGraphql(graphql) {
+    return graphql.replace(/\s+/g, " ").trim();
+}
+export function validateGraphqlDsl(raw) {
+    const parsed = validateGraphqlDslInputSchema.safeParse(raw);
+    if (!parsed.success) {
+        return {
+            status: "failed",
+            schemaValidation: { performed: false, provider: "none" },
+            issues: parsed.error.issues.map((i) => ({
+                code: "INPUT_VALIDATION_ERROR",
+                message: i.message,
+                path: i.path.join("."),
+                severity: "error"
+            }))
+        };
+    }
+    const input = parsed.data;
+    const policy = getPolicy();
+    const issues = [];
+    const normalized = normalizeGraphql(input.graphql);
+    // 1. Naming Suffix check
+    if (policy.naming?.enforceNounSuffix) {
+        const opMatch = normalized.match(/^\s*(query|mutation)\s+(\w+)/i);
+        if (opMatch) {
+            const opName = opMatch[2];
+            const suffix = policy.naming.enforceNounSuffix;
+            if (!opName.endsWith(suffix)) {
+                issues.push({
+                    code: "INVALID_SERVICE_NOUN_SUFFIX",
+                    message: `Operation name "${opName}" does not end with mandated Moqui suffix "${suffix}".`,
+                    path: "operationName",
+                    severity: "warning",
+                    suggestion: `Add suffix "${suffix}" to your service noun or operation name.`
+                });
+            }
+        }
+    }
+    // 2. Connection-specific checks
+    const isConnectionQuery = (input.rootField.endsWith("s") && !input.rootField.endsWith("ss")) ||
+        normalized.includes("edges") ||
+        normalized.includes("node");
+    if (isConnectionQuery) {
+        // 2.A Max Page Limit check (literal)
+        if (policy.connections?.maxPageLimit) {
+            const limit = policy.connections.maxPageLimit;
+            const literalMatches = normalized.matchAll(/first\s*:\s*(\d+)/g);
+            for (const match of literalMatches) {
+                const val = parseInt(match[1], 10);
+                if (val > limit) {
+                    issues.push({
+                        code: "PAGINATION_LIMIT_EXCEEDED",
+                        message: `Requested pagination size of ${val} exceeds the maximum allowed policy limit of ${limit}.`,
+                        path: "first",
+                        severity: "error",
+                        suggestion: `Reduce the "first" argument value to be <= ${limit}.`
+                    });
+                }
+            }
+            // 2.B Max Page Limit check (variable sample)
+            if (input.variablesSample) {
+                const varMatches = normalized.matchAll(/first\s*:\s*\$(\w+)/g);
+                for (const match of varMatches) {
+                    const varName = match[1];
+                    const varVal = input.variablesSample[varName];
+                    if (typeof varVal === "number" && varVal > limit) {
+                        issues.push({
+                            code: "PAGINATION_LIMIT_EXCEEDED",
+                            message: `Variable "$${varName}" has value ${varVal} which exceeds maximum allowed policy limit of ${limit}.`,
+                            path: varName,
+                            severity: "error",
+                            suggestion: `Pass a value <= ${limit} for the variable "$${varName}".`
+                        });
+                    }
+                }
+            }
+        }
+        // 2.C PageInfo Selection check
+        if (policy.connections?.enforcePageInfo) {
+            if (!normalized.toLowerCase().includes("pageinfo")) {
+                issues.push({
+                    code: "MISSING_PAGE_INFO",
+                    message: "Enforced 'pageInfo' block selection is missing in connection query fields.",
+                    path: input.rootField,
+                    severity: "warning",
+                    suggestion: "Include 'pageInfo { hasNextPage endCursor }' in connection query fields."
+                });
+            }
+        }
+    }
+    // 3. Mutation-specific checks
+    if (input.operationType === "MUTATION") {
+        // 3.A Mandatory userErrors check
+        if (policy.mutations?.alwaysIncludeUserErrors) {
+            if (!normalized.includes("userErrors")) {
+                issues.push({
+                    code: "MISSING_USER_ERRORS",
+                    message: "Mandatory 'userErrors' block selection is missing in mutation return projection.",
+                    path: input.rootField,
+                    severity: "warning",
+                    suggestion: "Include 'userErrors { field message }' in the mutation selection."
+                });
+            }
+        }
+        // 3.B Mandatory id on Create mutation check
+        if (policy.mutations?.alwaysIncludeIdOnCreate && input.rootField.endsWith("Create")) {
+            const match = normalized.match(new RegExp(`${input.rootField}\\s*\\([^)]*\\)\\s*\\{([^}]+)\\}`));
+            if (match) {
+                const selectionSet = match[1];
+                if (!selectionSet.includes("id")) {
+                    issues.push({
+                        code: "MISSING_ID_ON_CREATE",
+                        message: `Mandatory 'id' field is missing from return projection of creation mutation "${input.rootField}".`,
+                        path: input.rootField,
+                        severity: "error",
+                        suggestion: "Include 'id' in your mutation return selection fields."
+                    });
+                }
+            }
+        }
+    }
+    // 4. Idempotency Check
+    const mustHaveIdempotent = input.policyContext?.idempotencyRequired ?? false;
+    if (mustHaveIdempotent && !/@idempotent\s*\(\s*key\s*:\s*\$?\w+\s*\)/.test(normalized)) {
+        issues.push({
+            code: "MISSING_IDEMPOTENT_DIRECTIVE",
+            message: "Expected @idempotent(key: ...) directive is missing for this mutation/version policy.",
+            path: input.rootField,
+            severity: "error",
+            suggestion: "Add builder.rootDirective(builder.dir(\"idempotent\", [key: builder.varRef(\"idempotencyKey\")]))"
+        });
+    }
+    return {
+        status: issues.some((i) => i.severity === "error") ? "failed" : "passed",
+        schemaValidation: { performed: true, provider: "local" },
+        issues,
+        normalizedGraphql: normalized
+    };
+}

package/package.json

@@ -0,0 +1,33 @@
+{
+    "name": "@gurveenbagga/moqui-graphql-dsl-mcp",
+    "version": "1.0.0",
+    "description": "Internal MCP server for Moqui GraphQL DSL generation and validation",
+    "type": "module",
+    "bin": {
+        "moqui-graphql-dsl-mcp": "./dist/server.js"
+    },
+    "files": [
+        "dist"
+    ],
+    "scripts": {
+        "build": "tsc -p tsconfig.json",
+        "dev": "tsx src/server.ts",
+        "start": "node dist/server.js",
+        "prepublishOnly": "npm run build",
+        "test": "vitest run"
+    },
+    "engines": {
+        "node": ">=20"
+    },
+    "dependencies": {
+        "@modelcontextprotocol/sdk": "^1.12.0",
+        "pino": "^9.7.0",
+        "zod": "^3.25.67"
+    },
+    "devDependencies": {
+        "@types/node": "^22.15.32",
+        "tsx": "^4.20.3",
+        "typescript": "^5.8.3",
+        "vitest": "^3.2.4"
+    }
+}