simple-support-system-mcp

<!-- Author: Fabian Bitter (fabian@bitter.de) -->

# simple-support-system-mcp

Local MCP server (stdio) for the REST API of the Simple Support System add-on for Concrete CMS. It lets an assistant work a support queue the way a human would: find the ticket, read it with its history, write a reply, move it to the next state. Projects, attachments and moderation are covered as well.

The server talks to any site that runs the package. Nothing is hardcoded, the site URL and the API key come from environment variables. It speaks stdio only and never opens a port.

## Install

```bash
npm install
npm run build
```

Register the server in Claude Code:

```bash
claude mcp add simple-support-system \
  -e SIMPLE_SUPPORT_SYSTEM_BASE_URL=https://support.example.com \
  -e SIMPLE_SUPPORT_SYSTEM_API_KEY=your-api-key \
  -- node "/absolute/path/to/simple-support-system-mcp/dist/src/index.js"
```

Or in `~/.claude.json` / `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "simple-support-system": {
      "command": "node",
      "args": ["/absolute/path/to/simple-support-system-mcp/dist/src/index.js"],
      "env": {
        "SIMPLE_SUPPORT_SYSTEM_BASE_URL": "https://support.example.com",
        "SIMPLE_SUPPORT_SYSTEM_API_KEY": "your-api-key"
      }
    }
  }
}
```

## Environment

| Variable | Purpose |
| --- | --- |
| `SIMPLE_SUPPORT_SYSTEM_BASE_URL` | Required. Base URL of the Concrete CMS site, for example `https://support.example.com`. The API path `/index.php/api/v1` is appended automatically, a URL that already ends in `/api/v1` is used as it is. |
| `SIMPLE_SUPPORT_SYSTEM_API_KEY` | API key of the installation, sent as the `X-Api-Key` header. Without it only the public part of the API is reachable. |
| `SIMPLE_SUPPORT_SYSTEM_API_PATH` | Optional. Overrides the default API path for sites that do not use the `index.php` dispatcher, for example `/api/v1`. |
| `SIMPLE_SUPPORT_SYSTEM_PROJECT_TOKEN` | Optional. Default access token for private projects, used when a tool call passes no token of its own. |
| `SIMPLE_SUPPORT_SYSTEM_TIMEOUT_MS` | Optional. Request timeout in milliseconds, default `30000`. |

The API key is generated when the package is installed and lives in the site config under `simple_support_system.api_key`. Calls without it run as an anonymous visitor: reading public projects and their approved tickets, creating tickets and writing comments still work, everything administrative (state changes, deleting, approving, projects) does not.

## Tools

The three everyday tools are `list_tickets`, `get_ticket` and `reply_to_ticket`, plus `set_ticket_state` to move a ticket along.

| Tool | Purpose |
| --- | --- |
| `list_tickets` | Lists tickets with filters for project, state, type, priority, assignee, text search and change date, sorted and paged. Compact summaries by default. |
| `get_ticket` | Reads one ticket with its attachments and, unless switched off, all of its comments. |
| `reply_to_ticket` | Posts a reply as a comment on a ticket and triggers the notification mails. |
| `set_ticket_state` | Moves a ticket to another workflow state and notifies everyone involved. |
| `create_ticket` | Creates a ticket in a project, by project id or project handle, optionally with uploaded files. |
| `update_ticket` | Changes title, content, type, priority or assignee. Only the given fields are touched. |
| `approve_ticket` | Approves a moderated ticket. |
| `delete_ticket` | Deletes a ticket with all comments and attachment links. Irreversible, needs `confirm: true`. |
| `list_ticket_comments` | Lists the comments of a ticket. |
| `update_comment` | Replaces the text of a comment. |
| `approve_comment` | Approves a moderated comment. |
| `delete_comment` | Deletes a comment. Irreversible, needs `confirm: true`. |
| `list_projects` | Lists the support projects, with access tokens when an API key is configured. |
| `get_project` | Reads one project by id. |
| `create_project` | Creates a project, private projects get a generated access token. |
| `update_project` | Changes name, handle or visibility of a project. |
| `delete_project` | Deletes a project with every ticket and comment inside it. Irreversible, needs `confirm: true`. |
| `list_ticket_attachments` | Lists the files attached to a ticket. |
| `upload_attachment` | Uploads a local file into the file manager and returns its file id. |
| `add_ticket_attachments` | Links uploaded file ids to a ticket. |
| `download_attachment` | Resolves the download URL of an attachment and can save it to a local path. |
| `delete_attachment` | Removes a file from a ticket. Irreversible, needs `confirm: true`. |
| `get_server_info` | Shows the configured API URL, whether a key is present and the accepted states, types and priorities. The key itself is never returned. |

Reading tools are annotated as read only, the four `delete_` tools as destructive. All of them additionally require `confirm: true`, so a delete cannot happen as a side effect of a vague instruction. There is no trash and no restore on the API side, a deleted ticket, comment or project is gone.

### Working a ticket

```text
list_tickets   { "state": "open", "sortBy": "updatedAt" }
get_ticket     { "ticketId": 42 }
reply_to_ticket{ "ticketId": 42, "comment": "Thanks for the report, we are on it." }
set_ticket_state { "ticketId": 42, "state": "in_progress" }
```

`list_tickets` also takes `projectHandle` instead of `projectId` and resolves it through the project list first.

### Values the API accepts

- States: `new`, `open`, `in_progress`, `on_hold`, `resolved`, `duplicate`, `invalid`, `wont_fix`, `closed`. `set_ticket_state` accepts all of them except `new`, which is only set when a ticket is created.
- Types: `bug`, `enhancement`, `proposal`, `task`
- Priorities: `trivial`, `minor`, `major`, `critical`, `blocker`
- Tickets in the state `closed` or `invalid` are locked: the API refuses edits of the ticket, its comments and its attachments until the state changes.

### Attachments

```text
upload_attachment      { "filePath": "/tmp/screenshot.png" }      -> fileId
add_ticket_attachments { "ticketId": 42, "fileIds": [123] }
```

`upload_attachment` puts the file into the file manager of the site without linking it anywhere, the second call attaches it. `create_ticket` takes the same ids in `attachmentFileIds`.

### Private projects

A private project is only reachable with its access token. Pass it per call as `token`, or set `SIMPLE_SUPPORT_SYSTEM_PROJECT_TOKEN` as the default. With an API key the token is not needed, the key already grants full access.

## Notes on the API

The package answers in several shapes, the server normalises all of them so tools return the bare resource:

- Collections come back as a plain array, single tickets and comments inside a `ticket` or `comment` key, attachments inside `data`.
- Failures arrive either as `{"errors": [...]}` or as a Concrete `EditResponse` with an `error` flag. The second one can come with status 200, so a 200 alone is not treated as success. Every error becomes a tool error with the message the API sent.
- `create_ticket` answers with a status envelope and not with the new record, so the id of a freshly created ticket has to be looked up with `list_tickets`.
- `download_attachment` follows the redirect the API returns and reports the resolved URL.

## Verification

```bash
npm run build
npm test
```

The tests run against a stubbed HTTP layer, they never touch a live site and need no credentials. They cover the URL and form encoding the PHP controllers expect (including PHP boolean and array notation), the response envelopes, the error mapping, the filtering and sorting of `list_tickets`, and the guard rails of the destructive tools.

## License

MIT, see [LICENSE](LICENSE).