Tickiti
Connect AI assistants to the Tickiti helpdesk API: tickets, queries, reports and admin.
التثبيت
خطوات التثبيت موجودة في التوثيق أدناه. التوثيق
التوثيق
مأخوذ من ملف README للمشروع على GitHub ويُحدَّث أسبوعيًا. تفتح الروابط على GitHub.
المحتويات
tickiti-mcp
An MCP (Model Context Protocol) server that exposes the
Tickiti helpdesk API to AI assistants such as Claude. It is a thin shim over the
Tickiti Public API v1 (/api/v1/...): each MCP tool forwards to a v1 endpoint, adding
your bearer token and — for writes — an idempotency key. The token's abilities are the
security boundary: the server only relays calls, it never widens them, so a read-only token
gives a read-only assistant.
📖 Full documentation: https://www.tickiti.com/docs/topic/mcp_server/
Tools
The ticket tools have full, validated inputs; the rest of the API is reachable through two general tools, so the whole surface is available without a separate tool per endpoint.
Tickets
| Tool | Ability | Purpose |
|---|---|---|
create_ticket | tickets:write | Open a ticket (subject+content, template, or intervention), with assignee, priority, status and participants; is_public is required |
respond_to_ticket | tickets:write | Post a response; change status, hold, assignee, priority, queue, subject, participants; send_full_email for the whole reply by email |
close_ticket | tickets:write | Close, optionally with a final reply and a resolution |
edit_response | tickets:write | Change a response in place (whole body, find/replace, visibility) with no notification — or publish an internal note and notify |
delete_response | tickets:write | Soft-delete a response |
add_participants / remove_participants | tickets:write | Change participants |
delete_tickets / restore_ticket | tickets:write | Delete tickets (by number, or everything from one sender) and undo it |
merge_tickets | tickets:write | Merge two tickets (the older survives) |
link_tickets / unlink_tickets / list_linked_tickets | tickets:write / read | The Linked panel |
move_responses / copy_responses / split_ticket | tickets:write | Repair a thread: move or copy responses, or split them off into a new linked ticket |
change_originator | tickets:write | Change who raised a ticket |
delete_attachment | tickets:write | Remove one attachment (a malicious file, say), keeping a record of it |
get_ticket / list_responses | tickets:read | A ticket's thread, participants and links; fields / max_body_chars keep long email threads small |
get_response | tickets:read | One response by id |
query_tickets | tickets:read | Search tickets |
query_responses / export_responses | tickets:read | Responses across tickets; counts and group-by tallies; NDJSON export to disk |
get_attachment / download_attachment | tickets:read | Attachment bytes (download streams any size to a file) |
list_queues / list_teams / list_staff / list_resolutions / get_search_modes | tickets:read | Queue names and settings, team keys, staff addresses, resolution categories, the search vocabulary |
Settings, templates, mail, administration
| Tool | Ability | Purpose |
|---|---|---|
list_perspectives / get_perspective | settings:read | Saved views, with conditions and sort orders |
list_watchlists | settings:read | Watchlists |
list_stock_responses / get_stock_response | settings:read | Stock responses (search, bodies) |
create_stock_response / update_stock_response / delete_stock_response | settings:write | Edit stock responses |
get_template / search_templates / render_template | templates:read | Templates and FAQs; render one against data without sending |
create_template / update_template | templates:write | Edit templates (updates change only the fields given) |
upload_template_image | templates:write / settings:write | Upload an image for a template or stock response |
send_email / search_sent_mail | mail:write / mail:read | Send mail; search what was sent |
list_api_tokens / create_api_token / update_api_token / revoke_api_token | administration:* | API keys (a token only grants abilities it holds) |
list_workflow | workflow:read | Resolution categories, interventions, escalations |
run_report | reports:read | Analytics reports |
get_token_info | any | What this token can do: abilities, owner roles, plan |
list_instances | — | The Tickiti instances configured (see below) |
list_endpoints | — | Every API endpoint, with abilities, path and body parameters |
tickiti_call | per endpoint | Call any /api/v1 endpoint by family and action |
For anything beyond the named tools (mail, templates, workflow writes, administration,
supervisor), the assistant uses list_endpoints to discover the action, then tickiti_call
to run it — covering all of the v1 API.
Requirements
- Node.js 20 or newer
- A Tickiti API token, minted from Administration → API keys, scoped to the abilities you want the assistant to have
- An MCP-capable client — e.g. Claude Code or the Claude desktop app
Install
git clone https://github.com/tickiti/tickiti-mcp.git
cd tickiti-mcp
npm install
npm run buildThe built server is dist/server.js.
Configure
The server reads two environment variables (it fails fast on startup if either is missing):
| Variable | Purpose |
|---|---|
TICKITI_API_BASE | Your Tickiti install's public address, no trailing slash — e.g. https://support.example.com. The server appends /api/v1/…. |
TICKITI_API_TOKEN | The bearer token. Its abilities determine what the assistant can do. |
More than one instance
To reach several Tickiti installs from one server (production and staging, say), add
TICKITI_INSTANCES: JSON, or the path of a JSON file, mapping a name to { "base", "token" }.
The TICKITI_API_BASE / TICKITI_API_TOKEN pair stays the default instance, named by
TICKITI_INSTANCE_NAME (default default).
TICKITI_INSTANCE_NAME=production
TICKITI_INSTANCES='{"staging": {"base": "https://staging.example.com", "token": "…"}}'Every tool then takes an optional instance argument; list_instances shows the names.
Use with Claude Code
claude mcp add tickiti \
--env TICKITI_API_BASE=https://support.example.com \
--env TICKITI_API_TOKEN=YOUR_TICKITI_API_TOKEN \
-- node /absolute/path/to/tickiti-mcp/dist/server.jsConfirm with claude mcp list (or /mcp in a session). Remove with claude mcp remove tickiti.
Other MCP clients configure servers in their own settings file, but the shape is the same:
run node /absolute/path/to/tickiti-mcp/dist/server.js as a stdio server with
TICKITI_API_BASE and TICKITI_API_TOKEN set in its environment.
Permissions & security
The server adds no permissions of its own. Every call runs as the staff user the token belongs to, gated by the token's abilities — exactly as a direct API call would be. To limit what an assistant can do, mint a narrowly-scoped token:
- A read-only token (e.g.
tickets:read,reports:read) gives an assistant that can look but not change anything. - Grant write abilities only for the families the assistant needs to act on.
- If a call is refused, the server reports the reason (missing ability, role or plan).
The ticket-writing tools send an idempotency key with every call, so a retried request never creates a duplicate ticket or response.
Long bodies can be given as content_path (a local file) instead of content, and files and
images always go by path: the server reads them, so their bytes never pass through the model.
How it works
| File | Role |
|---|---|
src/client.ts | Request core: base URL, bearer auth, idempotency, error normalisation |
src/result.ts | Maps an API result into the MCP tool-result envelope |
src/manifest.ts | Helpers over the generated route manifest (lookup, path building) |
src/generated/manifest.ts | Auto-generated route table (do not edit) |
src/tools/tickets.ts | Ticket writes — verified input schemas |
src/tools/ticket-reads.ts | Ticket, response and attachment reads |
src/tools/ticket-operations.ts | Delete, merge, link, move, originator, attachment delete, lookups |
src/tools/settings-writes.ts | Stock responses and templates |
src/tools/admin.ts | Mail, template rendering and images, perspectives, API keys, instances |
src/tools/reads.ts | Named read tools (settings / workflow / reports) |
src/tools/generic.ts | list_endpoints + tickiti_call |
src/param-hints.ts | Body parameters list_endpoints shows for endpoints without a dedicated tool |
src/server.ts | Entry point: registers tools, connects the stdio transport |
scripts/build-manifest.mjs | Regenerates the manifest from the Tickiti route table |
Maintainers
src/generated/manifest.ts is generated from Tickiti's own route table
(php artisan route:list --json), so abilities, roles, plan gates and path params are never
hand-maintained. Regenerate against a Tickiti checkout after the API changes:
TICKITI_DIR=/path/to/tickiti npm run manifestThere is an end-to-end sweep over every endpoint in tests/all-paths.mjs
(npm run test:paths, needs a base URL and a full-ability token against a scratch instance),
and an offline check of the tool registration in tests/smoke-tools.mjs
(npm run build && node tests/smoke-tools.mjs).
Several tools call endpoints added to Tickiti in October 2026. Against an older install they
return 404; list_endpoints describes the newest API.
License
MIT © Oxenic
الأسئلة الشائعة
ما هو Tickiti؟
Connect AI assistants to the Tickiti helpdesk API: tickets, queries, reports and admin.
كيف أثبّت Tickiti؟
اتبع خطوات التثبيت في توثيقه المعروض في هذه الصفحة وفي مستودعه.
هل Tickiti مفتوح المصدر؟
نعم. شيفرته متاحة على GitHub بترخيص MIT.
من يصون Tickiti؟
ينشره tickiti. يدرجه AI.tn لكنه لا يصونه ولا يوصي به.
من سجل MCP الرسمي. الإدراج ليس توصية: راجع شيفرة الخادم وصلاحياته قبل منحه الوصول إلى بياناتك.