Metadata-Version: 2.5
Name: rigosis-smax-mcp
Version: 0.5.0
Summary: MCP server by Rigosis for OpenText™ Service Management (SMAX): EMS records, comments, attachments. Not an OpenText product.
Author: Rigosis Development Team
License-Expression: LicenseRef-Proprietary
License-File: LICENSE
License-File: NOTICE
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: System Administrators
Classifier: Programming Language :: Python :: 3.12
Requires-Python: >=3.12
Requires-Dist: httpx<1,>=0.27
Requires-Dist: mcp<3,>=2.0
Requires-Dist: python-dotenv<2,>=1.0
Description-Content-Type: text/markdown

# rigosis-smax-mcp

MCP server for OpenText SMAX. The server has **two modes**, auto-detected at
startup via a capability probe (forceable with `SMAX_MCP_MODE`): **agent**
mode — work with EMS records (Incidents, Requests, Changes, People, Devices,
custom types), comments, and attachments from any MCP client; fifteen generic
tools including live schema discovery (`describe_entity`,
`list_entity_types`) and warn-first write validation; requires the "Access
OData API" role — and **end-user (ESS)** mode — 11 self-service portal tools,
live-verified against a real tenant; no OData role needed.

> rigosis-smax-mcp is developed and licensed by Rigosis for integration with
> OpenText™ Service Management software, formerly known as SMAX. It is not
> an OpenText product.

## Requirements

- [uv](https://docs.astral.sh/uv/) (provides `uvx`; installs its own Python)
- A SMAX user and a Personal Access Token (Service Portal → Personal Access
  Tokens), or username/password. **Agent mode** additionally needs the
  **"Access OData API"** role; **end-user (ESS) mode** does not.

## Quick setup (recommended)

```bash
uvx --refresh --from rigosis-smax-mcp smax-mcp-setup
```

An interactive wizard: asks for your connection details, tests them live
against your tenant, writes the Claude Desktop config for you (backing up any
existing file), and prints ready-to-paste snippets for every other MCP
client. If it ends with a green checkmark, you're done — the sections below
are the manual alternative.

## Verify your setup first

```bash
uvx --from rigosis-smax-mcp smax-mcp-verify
```

This checks configuration and authenticates against your tenant before you
wire up any client. It reads the environment variables below (a `.env` file
found from the working directory upward also works).

## Configuration

| Variable | Meaning |
|---|---|
| `SMAX_MCP_BASE_URL` | e.g. `https://smax.example.com` (required) |
| `SMAX_MCP_TENANT_ID` | numeric tenant id (required) |
| `SMAX_MCP_USERNAME` | Service Portal login (required) |
| `SMAX_MCP_PAT` | Personal Access Token — recommended; paired with the username that created it |
| `SMAX_MCP_PASSWORD` | alternative to PAT: password auth (JWT fetched automatically) |
| `SMAX_MCP_VERIFY_SSL` | default `true` |
| `SMAX_MCP_CA_BUNDLE` | CA bundle path for private CAs |
| `SMAX_MCP_READ_ONLY` | `true` registers only read tools (default `false`) |
| `SMAX_MCP_ATTACHMENTS_DIR` | sandbox directory for attachment upload/download (required for attachment tools) |
| `SMAX_MCP_MAX_ATTACHMENT_MB` | default `10` |
| `SMAX_MCP_SKIP_SCHEMA_CHECK` | `true` disables the warn-only pre-write schema check |
| `SMAX_MCP_MODE` | default `auto`; `agent`/`ess` force a mode and skip the startup capability probe (a restricted agent may otherwise probe as `ess`) |
| `SMAX_MCP_SETUP_LANG` | **`smax-mcp-setup` only** — wizard guidance language, `en` (default) or `tr`. Never written into the generated config. The end user's *chat* language is read live from their SMAX profile |

**Preconfigured install.** An admin can bake the org's connection into one
command by pre-setting `SMAX_MCP_BASE_URL`, `SMAX_MCP_TENANT_ID`, and
`SMAX_MCP_SETUP_LANG`; the wizard then skips those questions and each end
user only types their own username and token. In **ESS mode** the server
also reads the signed-in user's SMAX language (`person/me` Locale) at
startup and asks the model to reply in that language.

Use a least-privilege SMAX integration account — every tool acts as that one
configured user.

## Connect an MCP client

The server speaks MCP over stdio. Generic client configuration:

- command: `uvx`
- args: `["--from", "rigosis-smax-mcp", "smax-mcp"]`
- environment: the variables above

**Claude Code:**

```bash
claude mcp add smax \
  --env SMAX_MCP_BASE_URL=https://smax.example.com \
  --env SMAX_MCP_TENANT_ID=123456789 \
  --env SMAX_MCP_USERNAME=integration.user \
  --env SMAX_MCP_PAT=your-token \
  --env SMAX_MCP_ATTACHMENTS_DIR=/path/to/attachments \
  -- uvx --from rigosis-smax-mcp smax-mcp
```

**Claude Desktop** (`claude_desktop_config.json`):

```json
{
  "mcpServers": {
    "smax": {
      "command": "uvx",
      "args": ["--from", "rigosis-smax-mcp", "smax-mcp"],
      "env": {
        "SMAX_MCP_BASE_URL": "https://smax.example.com",
        "SMAX_MCP_TENANT_ID": "123456789",
        "SMAX_MCP_USERNAME": "integration.user",
        "SMAX_MCP_PAT": "your-token",
        "SMAX_MCP_ATTACHMENTS_DIR": "C:\\smax-attachments"
      }
    }
  }
}
```

Windows note: `SMAX_MCP_ATTACHMENTS_DIR` takes a normal Windows path; create
the directory before first use.

In a session, call `whoami` first as a connectivity smoke test.

## Support

Contact your Rigosis representative. Use of this software is governed by the
LICENSE file and your agreement with Rigosis Information Systems.
