{ "ok": false, "error_code": "SECURITY_ESCALATION_REQUIRED", "draft": null, "refusal": { "filed_category": "hardware", "escalate_to": "security_team", "indicators": [{ "id": "attachment_or_link_then_behavior_change", "kb_ref": "KB-006", "evidence": ["attachment", "slow"] }] } } ``` The refusal is auditable. It does not assert authority, it shows its work. ## Design notes **The server never sees the answer key.** Tickets derive from Project 1's 26-case golden suite, but only the `input` blocks. The grader's `expected` block — which contains the true category — is excluded at build time and never served. A guardrail keyed to it would evaporate the moment a live Freshdesk adapter was swapped in, which is exactly what the data-source adapter pattern exists to prevent. **The guardrail has no model in the loop.** It is deterministic regex over ticket text. A guardrail that called a model to decide would inherit the negotiability it exists to remove. **Drafts are grounded, and the grounding is returned.** `draft_response` performs its own retrieval and returns the excerpts alongside the draft. The calling model may improve the phrasing; it may not add a fact absent from `grounding`. The KB contains no phone numbers, so a phone number in a reply is fabricated by definition. **Staff documents never reach customers.** KB-000 (triage priority matrix) and KB-006 (incident response) are internal end to end, plus block-level filtering for staff instructions like "NEVER issue a temporary password". `search_kb` still serves them — a technician looking up escalation policy should find it — but they cannot ground a customer-facing draft. This was a real bug: the lockout draft originally opened with KB-006's incident checklist, because that block contains the words "account lockout" and outranked the actual lockout runbook. **The write gate is a token, not a boolean.** `update_ticket` used to commit when called with `confirm=true`, which the same adversarial review correctly called caller policy rather than a code gate — a boolean the caller sets is a request wearing a parameter's clothes, and any model that wanted to skip the preview simply passed it on the first call. It now takes two calls, always. The first is a dry run returning a field-by-field before/after preview, `CONFIRMATION_REQUIRED`, and a server-minted `confirmation_token`. The second passes that token back. There is no single-call form, and the token cannot be constructed by the caller, so the commit path is unreachable without first producing a preview. The token binds to the change, not just to the ticket. It is single-use, expires, and carries a digest of the exact field/before/after set plus a version stamp of the ticket's mutable state. Preview a note and try to spend that approval on a status change and it is refused — otherwise the preview would be theatre, since a user could approve one thing and have another committed against their agreement. If the ticket moved since the preview, the before/after the user saw no longer describes reality, and the token is refused as stale. **And the honest limit:** a token proves a preview was *issued* and that this commit matches it. It cannot prove a human *read* it. Where the client advertises elicitation the server closes that gap — it prompts the user directly via `ctx.elicit()` and aborts on decline, cancel, or a prompt that errors. Where the client does not, the result says so: `confirmation_method` comes back as `token_only` with a note stating that no one was asked. Same rule the classifier follows in regex-only mode — the weaker mode is disclosed, never silently substituted. `ToolAnnotations` carry `readOnlyHint=false` and `idempotentHint=false`. The second was previously `true` and was wrong: `note` appends, so an identical repeat call adds a second note. **Tool descriptions are design work.** Each states what it does, what it explicitly does *not* do, when to prefer a sibling tool, and what each error code means. The reader is a capable model with no other context. ## Error contract | Code | Meaning | What the caller should do | |---|---|---| | `TICKET_NOT_FOUND` | No ticket with that ID | Find the right ID via `search_tickets` | | `KB_NO_MATCH` | Corpus loaded; nothing scored above threshold | Retry with different content words, then say the KB doesn't cover it | | `KB_UNAVAILABLE` | Corpus could not be read at all | A server fault, not a coverage gap. Don't retry, don't answer from general knowledge, don't report it as "nothing found" | | `SECURITY_ESCALATION_REQUIRED` | Refusal | Escalate to the security team; do not compose a reply yourself | | `CONFIRMATION_REQUIRED` | Dry run, not a failure | Show the preview, then re-call with the `confirmation_token` it returned | | `CONFIRMATION_INVALID` | Token fabricated, reused, expired, issued for a different change, or the ticket moved | Nothing changed. Re-run the dry run; do not retry the same token | | `CONFIRMATION_DECLINED` | The user was asked and said no | Nothing changed. Do not re-attempt; ask what they want instead | | `CONFIRMATION_UNAVAILABLE` | Token was valid; the client's prompt channel failed | Nothing changed. A fresh token fails the same way — tell the user it couldn't be confirmed | | `INVALID_FIELD` | Value outside the allowed set | Fix the value; nothing was changed | ## Setup Requires Python 3.11+ and [uv](https://docs.astral.sh/uv/). ```powershell git clone https://github.com/Jackson-DM/msp-tools-mcp cd msp-tools-mcp uv sync uv run python scripts/build_tickets.py # regenerates data/tickets.json uv run pytest -q ``` `scripts/build_tickets.py` expects `msp-triage-agent` beside this repo. The generated `data/tickets.json` is committed, so the server runs without it.

If uv sync fails with invalid peer certificate: UnknownIssuer

Antivirus or a corporate proxy is re-signing HTTPS traffic, and uv ships its own certificate store rather than reading the platform's. Trust the system store: ```powershell uv sync --system-certs setx UV_SYSTEM_CERTS 1 # so Claude Desktop's uv inherits it too ``` This trusts the roots Windows already trusts; it does not disable verification (which `--allow-insecure-host` would).

## Claude Desktop Config location depends on how Claude Desktop was installed: | Install | Path | |---|---| | Standalone installer | `%AppData%\Claude\claude_desktop_config.json` | | Microsoft Store (MSIX) | `%LocalAppData%\Packages\Claude_\LocalCache\Roaming\Claude\claude_desktop_config.json` | Packaged Store apps run under filesystem virtualization: writes to `AppData\Roaming` are redirected into the package's private `LocalCache`. Every published guide gives the standalone path, so on a Store install the config looks correct, sits in a real folder, and is never read — with no error and no log directory to show for it. **Don't guess which you have.** Settings → Developer → *Edit Config* opens the file the app actually reads. Merge into that one rather than overwriting; on this build the file also holds unrelated app preferences. Config contents: ```json { "mcpServers": { "msp-tools": { "command": "C:\\Users\\\\.local\\bin\\uv.exe", "args": [ "--directory", "C:\\Users\\\\projects\\msp-tools-mcp", "run", "--no-sync", "python", "-m", "msp_tools.server" ] } } }

msp-tools-mcp

Installation