Supervin Magento MCP Server

Configuration

Serveren kan konfigureres via environment variabler:

# .env
MAGENTO_ENDPOINT=https://dk.magento.supervin.io/efiware/page/graphql

# Admin authentication (optional - automatically used when available)
# Most queries work without authentication
MAGENTO_ADMIN_USERNAME=ai_admin
MAGENTO_ADMIN_PASSWORD=ai_admin123

Standard endpoint er: https://dk.magento.supervin.io/efiware/page/graphql

Admin Authentication: Admin credentials er optional da de fleste queries fungerer uden authentication. Når MAGENTO_ADMIN_USERNAME og MAGENTO_ADMIN_PASSWORD er konfigureret, bliver Basic Authentication automatisk brugt til alle requests.Protocol (MCP) server til integration med Supervins Magento GraphQL API. Denne server giver LLM'er mulighed for at interagere med Magento systemet gennem GraphQL queries og mutations.

Features

• GraphQL Query Execution: Udfør GraphQL queries mod Magento serveren
• GraphQL Mutation Execution: Udfør GraphQL mutations for at ændre data
• Schema Search: Søg i GraphQL schema efter specifikke queries, mutations og typer
• Schema Introspection: Få adgang til den komplette GraphQL schema
• Environment Configuration: Konfigurerbar endpoint via environment variabler
• Error Handling: Robust fejlhåndtering med detaljerede fejlmeddelelser
• TypeScript: Fuldt implementeret i TypeScript med type safety
• CLI Tool: Command-line interface til testing og debugging med samme validering som MCP serveren

Installation

# Klon projektet
git clone <repository-url>
cd supervin-magento-mcp

# Installer dependencies
bun install

# Kopier environment variabler
cp .env.example .env

# Rediger .env filen hvis nødvendigt

Configuration

Serveren kan konfigureres via environment variabler:

# .env
MAGENTO_ENDPOINT=https://dk.magento.supervin.io/efiware/page/graphql

# Admin authentication for mutations that require elevated permissions
MAGENTO_ADMIN_USERNAME=ai_admin
MAGENTO_ADMIN_PASSWORD=ai_admin123

Standard endpoint er: https://dk.magento.supervin.io/efiware/page/graphql

Admin Authentication: Nogle mutations (som fx opdatering af lagertal) kræver admin credentials. Konfigurer MAGENTO_ADMIN_USERNAME og MAGENTO_ADMIN_PASSWORD for at bruge Basic Authentication på admin operationer.

Usage

Kør serveren

# Development mode (med watch)
bun run dev

# Production mode
bun run start

# Type checking
bun run check-types

CLI Tool

Projektet inkluderer også en CLI tool til testing og debugging:

# Vis CLI hjælp
bun run cli:help

# Vis schema information
bun run cli:info

# Søg i schema
bun run bin/cli.ts search product

# Udfør GraphQL query
bun run bin/cli.ts query "{ __typename }"

# Start interaktiv mode
bun run cli:interactive

# Kør CLI tests
./bin/test-cli.sh

Se bin/README.md og bin/CLI_EXAMPLES.md for detaljerede CLI eksempler.

MCP Tools

Serveren eksponerer følgende tools:

1. execute_graphql_query

Udfør GraphQL queries mod Magento serveren.

Parameters:

• query (string): GraphQL query string
• variables (object, optional): Variables til query'en

Eksempel:

query GetProducts($limit: Int) {
  products(pageSize: $limit) {
    items {
      id
      name
      sku
      price {
        regularPrice {
          amount {
            value
            currency
          }
        }
      }
    }
  }
}

2. execute_graphql_mutation

Udfør GraphQL mutations mod Magento serveren.

Parameters:

• mutation (string): GraphQL mutation string
• variables (object, optional): Variables til mutation'en

Admin Authentication: Admin authentication bruges automatisk hvis MAGENTO_ADMIN_USERNAME og MAGENTO_ADMIN_PASSWORD er konfigureret. De fleste queries fungerer uden authentication, men admin mutations (som lageropdateringer) kræver credentials.

Eksempel - Standard mutation:

mutation AddToCart($cartId: String!, $cartItems: [CartItemInput!]!) {
  addProductsToCart(cartId: $cartId, cartItems: $cartItems) {
    cart {
      id
      items {
        id
        product {
          name
          sku
        }
        quantity
      }
    }
  }
}

Eksempel - Admin mutation (automatisk authentication):

{
  "mutation": "mutation UpdateInventory($sku: String!, $qty: Int!) { updateProductStock(sku: $sku, quantity: $qty) { success message } }",
  "variables": { "sku": "PRODUCT123", "qty": 50 }
}

3. search_graphql_schema

Søg i GraphQL schema efter specifikke termer.

Parameters:

• searchTerm (string): Søgeterm til at finde queries, mutations eller typer

Eksempel: Søg efter "product" vil returnere alle queries, mutations og typer der indeholder "product".

MCP Resources

Serveren eksponerer følgende resources:

1. schema://graphql/introspection

Komplet GraphQL schema introspection data i JSON format.

2. info://server/endpoint

Information om det aktuelle Magento GraphQL endpoint.

Architecture

Projektet er organiseret i modulære TypeScript komponenter:

├── index.ts                 # Main MCP server
├── lib/
│   ├── graphql-client.ts    # GraphQL client implementation
│   ├── schema-manager.ts    # Schema introspection and caching
│   └── types.ts             # TypeScript type definitions
├── bin/
│   ├── cli.ts              # CLI tool implementation
│   ├── README.md           # CLI documentation
│   ├── CLI_EXAMPLES.md     # CLI usage examples
│   └── test-cli.sh         # CLI test script
├── .env.example            # Environment configuration template
├── package.json            # Package configuration
├── tsconfig.json           # TypeScript configuration
└── README.md              # This file

GraphQL Client (lib/graphql-client.ts)

• Håndterer HTTP kommunikation med Magento GraphQL endpoint
• Implementerer fejlhåndtering for GraphQL errors
• Understøtter custom headers og authorization
• Fuldt typet med TypeScript interfaces

Schema Manager (lib/schema-manager.ts)

• Udfører schema introspection
• Cacher schema data for bedre performance
• Implementerer søgefunktionalitet i schema
• Type-safe med komplet TypeScript typing

Development

Type Checking

bun run check-types

Building

bun run build

Development Mode

bun run dev

TypeScript Configuration

Projektet bruger moderne TypeScript konfiguration optimeret til Bun:

• Target: ESNext for moderne JavaScript features
• Module: Preserve for optimal bundling
• Strict Mode: Aktiveret for maksimal type safety
• Module Resolution: Bundler for Bun compatibility

Error Handling

Serveren implementerer omfattende fejlhåndtering med TypeScript:

• Network Errors: HTTP fejl og netværksproblemer
• GraphQL Errors: GraphQL-specifikke fejl fra serveren
• Validation Errors: Input validering med Zod schemas
• Schema Errors: Fejl ved schema introspection
• Type Safety: Komplet TypeScript typing på tværs af alle komponenter

Alle fejl returneres som strukturerede responses med detaljerede fejlmeddelelser.

Integration med Claude Desktop

For at bruge serveren med Claude Desktop, tilføj følgende til din claude_desktop_config.json:

{
  "mcpServers": {
    "supervin-magento": {
      "command": "bun",
      "args": ["run", "/path/to/supervin-magento-mcp/index.ts"],
      "env": {
        "MAGENTO_ENDPOINT": "https://dk.magento.supervin.io/efiware/page/graphql"
      }
    }
  }
}

License

MIT License

Contributing

1. Fork projektet
2. Opret en feature branch (git checkout -b feature/new-feature)
3. Commit dine ændringer (git commit -am 'Add new feature')
4. Push til branch (git push origin feature/new-feature)
5. Opret en Pull Request

Alle bidrag skal følge TypeScript best practices og inkludere type definitioner.