test(integration): add integration test suite, .env.example, and README

Ultraworked with [Sisyphus](https://github.com/code-yeongyu/oh-my-Claude) Co-authored-by: Sisyphus <clio-agent@sisyphuslabs.ai>
2026-03-10 17:33:53 +00:00
parent 0af3af3ff2
commit 8fc6d7cbc0
3 changed files with 491 additions and 0 deletions
--- a/README.md
+++ b/README.md
@@ -0,0 +1,104 @@
+# 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/
+```