# Sage X3 GraphQL MCP Server

MCP server that enables AI agents to query Sage X3 ERP data via GraphQL. Read-only access to structure, master data, products, purchasing, and stock entities.

## Quick Start

```bash
# Install dependencies
bun install

# Run the server (sandbox mode — no credentials needed)
bun run src/index.ts
```

The server starts in **sandbox mode** by default, connecting to the public Sage X3 demo API.

## Configuration

All configuration is via environment variables:

| Variable | Required | Default | Description |
| --- | --- | --- | --- |
| `SAGE_X3_URL` | No | Demo URL | Sage X3 GraphQL API URL |
| `SAGE_X3_ENDPOINT` | Authenticated only | — | X3 endpoint name |
| `SAGE_X3_CLIENT_ID` | Authenticated only | — | Connected app client ID |
| `SAGE_X3_SECRET` | Authenticated only | — | Connected app secret |
| `SAGE_X3_USER` | Authenticated only | — | X3 user |
| `SAGE_X3_TOKEN_LIFETIME` | No | `600` | JWT lifetime in seconds |
| `SAGE_X3_TLS_REJECT_UNAUTHORIZED` | No | `true` | TLS certificate validation |
| `SAGE_X3_MODE` | No | Auto-detect | `sandbox` or `authenticated` |

Mode is auto-detected: if `SAGE_X3_CLIENT_ID`, `SAGE_X3_SECRET`, and `SAGE_X3_USER` are all set, the server uses authenticated mode. Otherwise it falls back to sandbox.

## Available Tools

### `introspect_schema`

Discover available Sage X3 GraphQL types and their fields.

```json
{ "typeName": "xtremX3Products" }
```

Without arguments, lists all X3 domain types (`xtrem*`). With a `typeName`, returns detailed field information.

### `query_entities`

Query/search Sage X3 entities with filtering, sorting, and pagination.

```json
{
  "rootType": "xtremX3MasterData",
  "entity": "businessPartner",
  "fields": ["code", "description1", "country.code"],
  "filter": "{country: {code: {_eq: 'FR'}}}",
  "first": 10
}
```

### `read_entity`

Read a single entity by its identifier.

```json
{
  "rootType": "xtremX3MasterData",
  "entity": "businessPartner",
  "id": "AE003",
  "fields": ["code", "description1", "country.code"]
}
```

### `aggregate_entities`

Run aggregation queries (min, max, count, distinctCount) on entities.

```json
{
  "rootType": "xtremX3Products",
  "entity": "product",
  "aggregateFields": [
    { "field": "productWeight", "operations": ["min", "max", "count"] }
  ]
}
```

### `execute_graphql`

Execute a raw GraphQL query. Use for complex queries with aliases, fragments, or variables.

```json
{
  "query": "{ xtremX3Products { product { query(first: 5) { edges { node { code description1 } } } } } }"
}
```

> All tools are **read-only** — mutations are blocked.

## Available Resources

Knowledge base resources for AI agent context:

| URI | Description |
| --- | --- |
| `sage-x3://knowledge/overview` | Sage X3 API overview, root types, and entity structure |
| `sage-x3://knowledge/query-patterns` | Common GraphQL query patterns and examples |
| `sage-x3://knowledge/filter-syntax` | Filter operators and expression syntax |
| `sage-x3://knowledge/pagination-sorting` | Cursor-based pagination and sorting |
| `sage-x3://knowledge/error-codes` | Error codes and troubleshooting |

## Available Prompts

| Prompt | Arguments | Description |
| --- | --- | --- |
| `search-entities` | `entity`, `criteria` | Search for entities matching criteria |
| `lookup-entity` | `entity`, `id` | Look up a specific entity by ID |
| `explore-data` | — | Explore what data is available in the X3 instance |
| `analyze-data` | `entity`, `question` | Analyze entity data with aggregation |

## Usage with MCP Clients

### OpenCode

Add to `opencode.json`:

```json
{
  "mcp": {
    "sage-x3-graphql": {
      "type": "local",
      "command": ["bun", "run", "src/index.ts"],
      "enabled": true
    }
  }
}
```

### Claude Desktop

Add to your Claude Desktop config (`claude_desktop_config.json`):

```json
{
  "mcpServers": {
    "sage-x3-graphql": {
      "command": "bun",
      "args": ["run", "src/index.ts"],
      "cwd": "/path/to/sage-graphql-mcp",
      "env": {
        "SAGE_X3_URL": "https://your-x3-instance.example.com/api",
        "SAGE_X3_CLIENT_ID": "your-client-id",
        "SAGE_X3_SECRET": "your-secret",
        "SAGE_X3_USER": "your-user"
      }
    }
  }
}
```

## Sandbox Mode

The server includes a built-in sandbox mode that connects to the public Sage X3 demo API:

- **Demo API**: `https://api-devna.dev-sagex3.com/demo/service/X3CLOUDV2_SEED/api`
- **Explorer UI**: `https://apidemo.sagex3.com/demo/service/X3CLOUDV2_SEED/explorer/`

No credentials required — just start the server and begin querying. Useful for testing, development, and exploring the X3 data model.

## Development

```bash
# Type checking
bun run typecheck

# Run tests
bun test

# Build
bun run build

# Dev mode (watch)
bun run dev
```