184 lines
4.7 KiB
Markdown
184 lines
4.7 KiB
Markdown
# 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
|
|
```
|