---
name: supportmcp-tools
description: >
  How to use every SupportMCP (TicketApp MCP) tool against production or local:
  active vs historical tickets, customer history, closed reports, commercial
  Super_User reads, Synergy job cards, HOS governance tools, and lifecycle writes.
  Use when the user asks about SupportMCP tools, TicketApp MCP, ticket history,
  closed tickets, list_tickets_by_customer, search_tickets, Harvest/USANGU
  customer reports, Help Desk MCP, supportmcp.pos.co.zm, or how to call any
  ticketapp / SupportMCP tool.
license: MIT
compatibility: opencode,grok,claude
metadata:
  product: SupportMCP
  mcp_endpoint: https://supportmcp.pos.co.zm/mcp
  health: https://supportmcp.pos.co.zm/health
  owner: supportmcp
  version: "1.0"
---

# SupportMCP — How to Use All Tools

## What SupportMCP is

SupportMCP is a **remote MCP connector** at `https://supportmcp.pos.co.zm/mcp`. It translates tool calls into HTTP against:

- **TicketApp** — tickets, customers, commercial panel (`customer/v2/*`)
- **SynergyApi** — apps, tags, dev tasks, project job cards

It owns **no** upstream data. OAuth maps the caller to a TicketApp user type; tools are policy-filtered.

**Health:** https://supportmcp.pos.co.zm/health (expect `tools: 46` when fully deployed)

**Authoritative API contract:** workspace `TicketApp-SynergyApi-Integration-Guide.md`  
**Full arg tables:** [references/tool-catalog.md](references/tool-catalog.md)

---

## Hard rules (never violate)

1. **Active ≠ history.** `list_tickets_by_customer` **without** `from`/`to` returns **active only**. For closed/history you **must** use `search_tickets` or history mode (`from`+`to`).
2. **Never pass numeric clientID as Ticket Search `client`.** Use `customerId` (MCP resolves name) or `clientName` substring.
3. **Status spelling:** `IN PROGRESS` has a **space**. Note field is capital **`Note`**.
4. **Today is not a multi-day search.** Use `list_tickets_activity_today` for Closed/Created Today; use `search_tickets` for date ranges.
5. **Super_User only:** subscriptions, invoices, quotes, payments, Synergy job cards, Synergy catalog/tag/dev-task/create-development tools.
6. **Fail loud.** Empty active list does not mean “no history.” Check history tools before concluding zero tickets.
7. **Do not invent rows.** If HOS `closedState.available` is false, a date window is missing — do not fabricate closed tickets.

---

## Decision tree — “tickets for customer X”

```
Need open work now?
  → list_tickets_by_customer({ customerId })                    # active only

Need closed / multi-month / filtered history?
  → search_tickets({ customerId, from, to, status?, limit? })  # preferred
  → OR list_tickets_by_customer({ customerId, from, to, status?, limit? })

Need Closed Today / Created Today?
  → list_tickets_activity_today({ status: "CLOSED" })           # or dateField

Need Support/Dev/Tech closed department report?
  → search_tickets({ from, to, status: "CLOSED", department })
```

### Worked examples

**USANGU LOGISTICS (7457) — closed last two months:**

```json
search_tickets({
  "customerId": 7457,
  "from": "2026-05-30",
  "to": "2026-07-31",
  "status": "CLOSED",
  "limit": 100
})
```

**Same customer — active only (what bare list_tickets_by_customer does):**

```json
list_tickets_by_customer({ "customerId": 7457 })
```

**HARVEST GROUP (9196) — history mode on customer tool:**

```json
list_tickets_by_customer({
  "customerId": 9196,
  "from": "2026-05-30",
  "to": "2026-07-31",
  "status": "CLOSED",
  "limit": 100
})
```

If `truncated: true`, raise `limit` (max 200) or narrow `from`/`to`.

---

## Tool catalog by job (all 46)

### Identity

| Tool | When |
|------|------|
| `whoami` | Confirm user id, type, and allowed tool set |

### Customers & commercial

| Tool | When | Who |
|------|------|-----|
| `list_customers` | Find customer id by name/TPIN | Directory |
| `list_tickets_by_customer` | Active tickets; **or** history if `from`+`to` | Privileged/actor |
| `get_customer_subscriptions` | Subscription lines in a window | **Super_User** |
| `get_customer_invoices` | Invoices (`customer/v2/getInvoices`) | **Super_User** |
| `get_customer_quotes` | Quotes | **Super_User** |
| `get_customer_payments` | Payments | **Super_User** |
| `list_customer_job_cards` | Synergy **project** job cards by customer | **Super_User** |

Default date window for commercial tools when omitted: about one year before → one year after today.

### Ticket search & history (closed / windows)

| Tool | When |
|------|------|
| **`search_tickets`** | **Primary** closed history, date windows, department closed reports, customer history |
| `list_tickets_activity_today` | Closed Today / Created Today only |
| `list_tickets_by_customer` + from/to | Customer-scoped history (same backend as search) |

**`search_tickets` args:** required `from`, `to`; optional `status` (`OPEN` \| `IN PROGRESS` \| `PENDING` \| `CLOSED`), `customerId`, `clientName`, `department`, `assignedUserId` / `assignedUsername`, `urgency`, `dateColumn` (`createdDate` default \| `lastUpdated` \| `dueDate`), `limit` (1–200, default 50).

### Active department queues

| Tool | When |
|------|------|
| `list_support_tickets` | Active Support queue + filters |
| `list_development_tickets` | Active Developer queue + filters |
| `list_technician_jobcards` | Active Technician **Job Card tickets** (TicketApp type, not Synergy project cards) |
| `list_overdue_tickets` | Overdue Support/Development |
| `list_tickets_by_user` | Active tickets for one assignee |

### Ticket detail & lifecycle

| Tool | When |
|------|------|
| `get_ticket` | Single ticket |
| `enrich_ticket` | Ticket + store + debtor + notes + attachments |
| `list_ticket_notes` | Notes only |
| `list_ticket_types` | Type/subtype catalog |
| `list_ticketapp_users` | User directory |
| `update_ticket_status` | Status change |
| `post_ticket_note` | Timeline note |
| `close_ticket` | Formal close + resolution |
| `reassign_ticket` | Governed reassignment |

### Synergy (Super_User)

| Tool | When |
|------|------|
| `list_synergy_apps` | App catalog |
| `list_synergy_tags` | Tag catalog |
| `tag_ticket` | Link tag to ticket |
| `get_dev_tasks_by_ticket` | Dev tasks for a ticket |
| `create_development_ticket` | Create + optional Synergy app/tag by name |

### HOS (privileged / Super_User surface)

| Tool | When |
|------|------|
| `hos_list_ticket_population` | Roster population; closed needs `status=CLOSED` or `includeClosed` **plus** full created/changed date window |
| `hos_get_ticket_history` | MCP evidence ledger history |
| `hos_resolve_roles` | HOS / heads / after-hours owner |
| `hos_list_user_registry` | User registry |
| `hos_get_last_assignment` | Last assignment evidence |
| `hos_get_ticket_clocks` | Clock / SLA readout |
| `hos_get_ticket_relationships` | Assembled relationships |
| `hos_list_ticket_notes` | HOS-paginated notes |
| `hos_note_delivery_status` | Note delivery block |
| `hos_intake_ticket` | Governed intake |
| `hos_list_unfinished_intakes` | Incomplete intakes |
| `hos_create_relationship` / `hos_list_relationships` | Source links |
| `hos_create_tag` / `hos_remove_tag` / `hos_correct_tag` | Tag governance |
| `hos_set_ticket_application` | Application association |

---

## Common workflows

### 1. Customer full picture (tickets + commercial)

1. `list_customers` → get `id` (e.g. 7457).
2. `list_tickets_by_customer({ customerId })` → active.
3. `search_tickets({ customerId, from, to, status: "CLOSED", limit: 100 })` → closed history.
4. Super_User: `get_customer_invoices` / `get_customer_quotes` / `get_customer_payments` / `get_customer_subscriptions` with same window.
5. Super_User: `list_customer_job_cards({ customerId })` for Synergy project job cards.

### 2. Closed Support last week

```json
search_tickets({
  "from": "2026-07-24",
  "to": "2026-07-31",
  "status": "CLOSED",
  "department": "Support",
  "limit": 200
})
```

### 3. Closed today (dashboard)

```json
list_tickets_activity_today({ "dateField": "lastUpdated", "status": "CLOSED" })
```

### 4. Open ticket deep dive

1. `get_ticket` or `enrich_ticket`
2. `list_ticket_notes`
3. Super_User: `get_dev_tasks_by_ticket` if development work

### 5. Create development work

1. `list_ticket_types` / `list_synergy_apps` / `list_synergy_tags` as needed  
2. `create_development_ticket`  
3. `tag_ticket` if tagging after create  

### 6. HOS closed population

```json
hos_list_ticket_population({
  "departments": ["Support"],
  "status": "CLOSED",
  "createdAfter": "2026-05-01T00:00:00.000Z",
  "createdBefore": "2026-07-31T23:59:59.000Z",
  "pageSize": 50
})
```

Without a complete date window, `closedState.available` stays false (CAPABILITY_BLOCKED) — use `search_tickets` instead if you only need a report.

---

## Who can call what (summary)

| Audience | Typical tools |
|----------|----------------|
| Any authenticated | `whoami`, `list_ticket_types`, often `list_customers` |
| Support / Dev / Tech / staff (actor) | Own-scoped reads, department lists, notes/status within policy |
| Compliance / Admin | Privileged ticket reads (search, activity, customer tickets, HOS reads) |
| **Super_User** | Everything + financial commercial + Synergy workflow |

Always run `whoami` if a tool returns ACCESS_DENIED.

---

## Process for agents

1. Load this skill when the task involves SupportMCP / TicketApp MCP tools.
2. Run `whoami` if authority is unclear.
3. Choose tool from the decision tree (active vs history vs today vs commercial).
4. Prefer `search_tickets` for any closed or multi-day customer history.
5. On empty active results, **still** try history before claiming “no tickets.”
6. On `truncated: true`, page with higher limit or split the date window.
7. Never invent closed rows or hardcode customer fixtures.

---

## Validation

- Public health `tools` count should match registry (46 as of release `3ac826b`).
- After deploy, smoke: `search_tickets` for a known customer with `status=CLOSED` and a window that returned rows in Help Desk.
- Policy: Super_User-only tools must fail for non–Super_User (ACCESS_DENIED).

## Related paths

| Resource | Path / URL |
|----------|------------|
| This skill (project) | `C:\Software\mcps\SupportMCP\.opencode\skills\supportmcp-tools\SKILL.md` |
| Tool catalog reference | `C:\Software\mcps\SupportMCP\.opencode\skills\supportmcp-tools\references\tool-catalog.md` |
| MCP endpoint | https://supportmcp.pos.co.zm/mcp |
| Health | https://supportmcp.pos.co.zm/health |
| Integration guide | `C:\Software\mcps\SupportMCP\TicketApp-SynergyApi-Integration-Guide.md` |
| Connector README | `C:\Software\mcps\SupportMCP\ticketapp-mcp-server\README.md` |