<!-- 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

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.