Moqui GraphQL DSL MCP Server

[!TIP] Production Status: This MCP server is published on the global npm registry under the package @gurveenbagga/moqui-graphql-dsl-mcp. You can run it instantly using npx without checking out the source code!

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.

🚀 Quick Start (IDE Integration)

To integrate this server directly into your Claude Desktop, Cursor, IntelliJ, or VS Code settings, add it to your configuration file (e.g., claude_desktop_config.json):

{
  "mcpServers": {
    "moqui-graphql-dsl-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "@gurveenbagga/moqui-graphql-dsl-mcp"
      ],
      "env": {
        "MOQUI_REPO_PATH": "/Users/gurveenkaur/Documents/Work/git/oms/moqui-framework"
      }
    }
  }
}

Make sure to replace the MOQUI_REPO_PATH environment variable with your local path to your moqui-framework repository.

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 Developer Setup

If you wish to clone this repository and modify the source code locally, follow these steps:

Prerequisites

• Node.js: v20 or higher
• Package Manager: npm

1. Install Dependencies

npm install

2. Build the Server

Compiles the TypeScript codebase inside src/ to standard ES Modules JavaScript in the dist/ directory.

npm run build

3. Run Tests

Ensure all unit and smoke tests are passing:

npm run test

4. Start the MCP Server in Developer Mode

Run the server locally with live TypeScript compilation and hot-reloading:

npm run dev

5. Local IDE Configuration

If running your local compiled build instead of the global npm release, point your configuration to the local dist/server.js file:

{
  "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"
      }
    }
  }
}