# 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/
```