Metadata-Version: 2.5
Name: rigosis-smax-mcp
Version: 0.14.1
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;
  agent-level EMS permissions are the tenant's role configuration.
- **`smax-mcp-user`** — 11 self-service (ESS) portal tools, live-verified
  against real tenants: search the portal (articles, news, offerings),
  browse the entitled service catalog, conduct an offering's form
  field-by-field via the portal's own form engine (valid values,
  dependencies, entity-link lookups, mandatory base fields), create and
  track requests behind a duplicate/related-news confirmation gate,
  comment, and approve or deny approval tasks. Everything runs strictly
  as the signed-in end user under the portal's own entitlements — the
  ESS toolset gains no agent capability from any role.

> 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. **Every PAT-using account needs the
  "Access OData API" role** — without it SMAX hides the Personal Access
  Tokens screen, so the user cannot create a PAT. The role only gates PAT
  management: it does not grant EMS record/offering access and does not
  make an end user an agent — `smax-mcp-user` stays entirely inside the
  portal's own entitlement-scoped ESS endpoints.

## 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. It installs the end-user toolset (`smax-mcp-user`) by default;
operators run `smax-mcp-setup --agent` instead to wire up `smax-mcp-agent`. If it ends with a success confirmation,
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 (`user` or `agent`) for admin-distributed setup commands; `--agent` on the command line wins over it. 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`. The setup wizard also registers the server under a slug of this name (e.g. `dodesk`; `smax` when unbranded), so end users can address the server by the name they know in any MCP client. Renaming a branded install requires removing the old key manually first |

**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.
