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

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.

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.