Metadata-Version: 2.5
Name: rigosis-smax-mcp
Version: 0.9.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, distributed as **two deterministic entry
points** — the command you run determines the toolset permanently, with no
runtime probing or switching:

- **`smax-mcp-agent`** — 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.
- **`smax-mcp-user`** — 11 self-service (ESS) 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. `smax-mcp-agent` additionally needs the
  **"Access OData API"** role; `smax-mcp-user` does not.

## Quick setup (recommended)

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

An interactive wizard: asks "End user or Agent?" (which determines whether it
wires up `smax-mcp-user` or `smax-mcp-agent`), 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.

### Migrating from 0.8.x

The old single `smax-mcp` command and its mode-switching environment
variable are gone; rerun `smax-mcp-setup` to regenerate your client config.

## Verify your setup first

```bash
uvx --from rigosis-smax-mcp smax-mcp-verify --profile agent   # or --profile user
```

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). `--profile` also checks
that profile's API surface: `user` does one harmless ESS read; `agent` checks
EMS `Request` access — a 403 there prints a warning but still exits 0 (a
restricted agent account is still a valid agent login); any other failure
exits 1.

## 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_SETUP_PROFILE` | **`smax-mcp-setup` only** — prefill the profile question (`user` or `agent`) for admin-distributed setup commands. Never used by the servers or written into the generated config |
| `SMAX_MCP_LANG` | Force the assistant's response language (a base code like `tr`, `de`, `fr`); overrides the profile locale. Unset = auto-detect from the user's SMAX profile. Written into the config when prefilled; also the default for the wizard's display language |
| `SMAX_MCP_SETUP_LANG` | **`smax-mcp-setup` only** — override the wizard's display language (`en`/`tr`); defaults to `SMAX_MCP_LANG`. Never written into the generated config |
| `SMAX_MCP_SYSTEM_NAME` | Customer-facing name your org calls this system (default `SMAX`, e.g. `DODESK`). The assistant uses it in user-facing wording; "OpenText SMAX" stays the technical product name. Written into the generated config and returned by `whoami` |

**Preconfigured install.** An admin can bake the whole org setup into one
command by pre-setting `SMAX_MCP_BASE_URL`, `SMAX_MCP_TENANT_ID`,
`SMAX_MCP_SYSTEM_NAME`, `SMAX_MCP_SETUP_PROFILE`, and `SMAX_MCP_LANG`; the
wizard then skips every question (and, when the profile is preset, the
profile-confirmation prompt) and each end user only types their username and
token. `SMAX_MCP_LANG` sets both the wizard's display language and the
assistant's runtime response language, so one variable covers a
single-language org. Without `SMAX_MCP_LANG`, `smax-mcp-user` auto-detects
the response language from the signed-in user's SMAX profile
(`person/me` Locale).

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. Pick the command for your profile —
`smax-mcp-agent` (shown below) or `smax-mcp-user`. Generic client
configuration:

- command: `uvx`
- args: `["--from", "rigosis-smax-mcp", "smax-mcp-agent"]`
- 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-agent
```

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

```json
{
  "mcpServers": {
    "smax": {
      "command": "uvx",
      "args": ["--from", "rigosis-smax-mcp", "smax-mcp-agent"],
      "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.
