feat: everything
This commit is contained in:
183
README.md
Normal file
183
README.md
Normal file
@@ -0,0 +1,183 @@
|
||||
# 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
|
||||
```
|
||||
Reference in New Issue
Block a user