casemargin-mcp-server

# CaseMargin MCP Server

CaseMargin MCP server exposes support case reasoning tools — generate structured case briefs and check escalation readiness from any MCP-compatible AI client (Claude Desktop, Claude Code, Cursor, and others). It sits **above** helpdesk data layers: it doesn't read tickets from Zendesk or any ticketing system — you pass ticket content in, it returns structured analysis powered by the same AI that runs [casemargin.com](https://casemargin.com).

## Tools

### `generate_case_brief`

Generate a structured case brief from a support ticket thread. Returns an assessment, what has been tried, current status, and recommended next step.

**Input:** `ticket_content` (string) — the full ticket thread: messages, internal notes, whatever you paste or pipe in. 10–50,000 characters.

**Output (structured JSON):**

```json
{
  "quick_scan": {
    "assessment": "…what this case is about and how serious it is…",
    "next_step": "…the single action the receiving agent should take now…",
    "status": "Waiting on customer"
  },
  "full_brief": {
    "current_problem": "…symptoms, blockers, business impact…",
    "actions_taken": ["action → outcome", "…"],
    "key_context": "…customer plan, history, logs, error codes…"
  },
  "metadata": {
    "input_length": 4210,
    "brief_length": 1250,
    "compression_ratio": 0.3
  }
}
```

### `check_escalation_readiness`

Analyze whether a support ticket is ready to escalate to L2. Returns a readiness score (0–100), dimensional breakdown, predicted L2 questions, and missing items.

**Input:** `ticket_content` (string) — the ticket notes to evaluate. 10–20,000 characters.

**Output (structured JSON):**

```json
{
  "overall_score": 62,
  "readiness": "borderline",
  "dimensions": {
    "problem_clarity": { "score": 80, "note": "…" },
    "troubleshooting_evidence": { "score": 55, "note": "…" },
    "business_impact": { "score": 40, "note": "…" },
    "next_action": { "score": 70, "note": "…" },
    "billing_defensibility": { "score": 65, "note": "…" }
  },
  "predicted_l2_questions": ["…", "…"],
  "missing_items": ["…", "…"]
}
```

## Installation

Nothing to install ahead of time — `npx` fetches the package on first run. Add this to your `claude_desktop_config.json` and restart Claude Desktop:

```json
{
  "mcpServers": {
    "casemargin": {
      "command": "npx",
      "args": ["-y", "casemargin-mcp-server"],
      "env": {
        "CASEMARGIN_API_KEY": "your-api-key-here"
      }
    }
  }
}
```

Cursor and Claude Code take the same shape of config in their own files. The config lives at `~/Library/Application Support/Claude/` on macOS and `%APPDATA%\Claude\` on Windows. Quit and reopen the app rather than closing the window — the config is read at process start.

The API key is optional — without it, brief generation runs on the anonymous per-IP tier. Get a free key (8 briefs/month) at [casemargin.com/signup](https://casemargin.com/signup). The escalation readiness check is free and needs no key. Drop the whole `env` block to run keyless.

Also on the [MCP Registry](https://registry.modelcontextprotocol.io/v0.1/servers?search=com.casemargin) as `com.casemargin/casemargin-mcp-server`, and on [npm](https://www.npmjs.com/package/casemargin-mcp-server).

### Running from source

Only needed if you're modifying the server:

```bash
git clone https://github.com/Casemargin/casemargin-mcp-server.git
cd casemargin-mcp-server
npm install
npm run build
```

Then point `command` at `node` and `args` at the absolute path of the built `dist/index.js`.

## Example usage

### "What's happening with this ticket?"

Paste a ticket thread into your AI client and ask what's going on:

> **You:** What's happening with this ticket?
>
> Customer reports VPN drops every ~30 min since Monday. Rebooted router, reinstalled client v4.2, issue persists. Firewall logs show DHCP lease renewing every 30 min. Customer is on the Premium SLA, CFO is affected. Told them we'd escalate if not fixed by Friday…

Claude calls `generate_case_brief` and returns a structured brief:

> **Quick scan** — Recurring VPN disconnects tied to a 30-minute DHCP lease renewal on a Premium SLA account with an executive affected; moderate-to-high urgency.
> **Next step:** Extend the DHCP lease time on the affected scope and confirm whether the drops track lease renewals.
> **Status:** Actively being worked.
>
> …plus the full breakdown of current problem, actions already taken (each with outcome), and key context.

### "Is this ticket ready to escalate?"

> **You:** Is this ticket ready to escalate to L2?
>
> *(pastes the same thread)*

Claude calls `check_escalation_readiness` and returns the score with a breakdown:

> **62/100 — borderline.** Problem clarity is strong (80), but troubleshooting evidence is thin (55) — no packet capture or client logs attached — and business impact is asserted, not quantified (40). Before escalating, L2 will ask: "What do the VPN client logs show at the moment of the drop?" and "Does the issue follow the user across networks?"

## Security and privacy

The server makes network calls and reads environment variables, so supply-chain scanners flag both. [SECURITY.md](SECURITY.md) documents the full extent: one outbound origin, two environment variables, and no filesystem, subprocess, dynamic-code, install-script, or telemetry access at all.

Two things worth knowing up front. Only the `ticket_content` you pass to a tool leaves your machine — nothing else is collected, and raw ticket text is never stored server-side. And because the API key travels as a request header, the server **refuses to start** if `CASEMARGIN_API_URL` points at a non-`https` origin other than loopback, rather than silently sending your key in cleartext.

Releases are published from GitHub Actions with npm provenance, so you can verify the tarball came from this repository:

```bash
npm audit signatures
```

## About CaseMargin

CaseMargin turns raw support tickets into structured case briefs so the next agent picks up cold in seconds, not minutes. The web app, Zendesk integration, and free Escalation Readiness Score tool live at [casemargin.com](https://casemargin.com).