repi
8fc6d7cbc0
Ultraworked with [Sisyphus](https://github.com/code-yeongyu/oh-my-Claude) Co-authored-by: Sisyphus <clio-agent@sisyphuslabs.ai>
105 lines
3.1 KiB
Markdown
105 lines
3.1 KiB
Markdown
# sage-mcp-server
|
|
|
|
MCP server providing read-only access to Sage X3 ERP data through both REST and SOAP APIs. Exposes 9 tools that let LLMs query business objects, read records, search data, and inspect entity schemas — all without modifying any X3 data.
|
|
|
|
## Quick Start
|
|
|
|
```bash
|
|
npm install
|
|
cp .env.example .env # edit with your X3 credentials
|
|
npm run build
|
|
npm start
|
|
```
|
|
|
|
## Tools
|
|
|
|
| Tool | Description |
|
|
|------|-------------|
|
|
| `sage_health` | Check X3 REST and SOAP API connectivity |
|
|
| `sage_query` | Query records via REST with pagination, filtering, and sorting |
|
|
| `sage_read` | Read a single record by primary key via REST |
|
|
| `sage_search` | Search records with flexible text matching across fields |
|
|
| `sage_list_entities` | Discover available REST entity types on the endpoint |
|
|
| `sage_get_context` | Get entity field names and sample structure |
|
|
| `sage_soap_read` | Read a single record via SOAP by key fields |
|
|
| `sage_soap_query` | Query records via SOAP with list size control |
|
|
| `sage_describe_entity` | Get field definitions with types, lengths, and labels |
|
|
|
|
All tools are annotated as `readOnlyHint: true` — they never modify X3 data.
|
|
|
|
## Configuration
|
|
|
|
| Variable | Required | Default | Description |
|
|
|----------|----------|---------|-------------|
|
|
| `SAGE_X3_URL` | Yes | — | Base URL of X3 server (e.g. `http://x3-server:8124`) |
|
|
| `SAGE_X3_USER` | Yes | — | Web service user with API access |
|
|
| `SAGE_X3_PASSWORD` | Yes | — | Password for the web service user |
|
|
| `SAGE_X3_ENDPOINT` | Yes | — | X3 endpoint folder (e.g. `X3V12`, `SEED`) |
|
|
| `SAGE_X3_POOL_ALIAS` | No | `SEED` | SOAP connection pool alias |
|
|
| `SAGE_X3_LANGUAGE` | No | `ENG` | Language code for SOAP responses |
|
|
| `SAGE_X3_REJECT_UNAUTHORIZED` | No | `true` | Set to `false` for self-signed TLS certificates |
|
|
| `MCP_TRANSPORT` | No | `stdio` | Transport mode: `stdio` or `http` |
|
|
| `MCP_HTTP_PORT` | No | `3000` | Port for HTTP transport mode |
|
|
|
|
## Usage Examples
|
|
|
|
### Claude Desktop
|
|
|
|
Add to `claude_desktop_config.json`:
|
|
|
|
```json
|
|
{
|
|
"mcpServers": {
|
|
"sage-x3": {
|
|
"command": "node",
|
|
"args": ["/path/to/sage-mcp-server/dist/index.js"],
|
|
"env": {
|
|
"SAGE_X3_URL": "http://your-x3-server:8124",
|
|
"SAGE_X3_USER": "your_user",
|
|
"SAGE_X3_PASSWORD": "your_password",
|
|
"SAGE_X3_ENDPOINT": "X3V12"
|
|
}
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
### Opencode
|
|
|
|
Add to `opencode.json`:
|
|
|
|
```json
|
|
{
|
|
"mcp": {
|
|
"sage-x3": {
|
|
"type": "local",
|
|
"command": ["node", "/path/to/sage-mcp-server/dist/index.js"],
|
|
"env": {
|
|
"SAGE_X3_URL": "http://your-x3-server:8124",
|
|
"SAGE_X3_USER": "your_user",
|
|
"SAGE_X3_PASSWORD": "your_password",
|
|
"SAGE_X3_ENDPOINT": "X3V12"
|
|
}
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
### HTTP Transport
|
|
|
|
```bash
|
|
MCP_TRANSPORT=http MCP_HTTP_PORT=3000 npm start
|
|
```
|
|
|
|
The server listens on `POST /mcp` for Streamable HTTP MCP connections.
|
|
|
|
## Development
|
|
|
|
```bash
|
|
npm run dev # run with tsx (hot reload)
|
|
npm test # run all tests
|
|
npm run test:watch # watch mode
|
|
npm run typecheck # type check without emitting
|
|
npm run build # compile TypeScript to dist/
|
|
```
|