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

npm install
npm run build

Register the server in Claude Code:

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:

{
  "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

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

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

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.