# clio-mcp

A standalone, firm-controlled MCP server that drives Clio matters and documents from Claude Desktop.

## Install (one-click, recommended)

1. Download **`ClioMCP.mcpb`**.
2. In Claude Desktop: Settings → Extensions → **Install Extension…** → pick the file.
3. Enter your Clio **OAuth Client ID** and **Client Secret** (region defaults to `us`) in the form. Secrets are stored in your OS keychain.
4. Just ask Claude to use Clio — e.g. *"find my open matters."* The first request opens Clio's consent page in your browser; approve it and the request completes. No terminal, no separate login.

> First-time auth: if approval takes more than ~55s, Claude will say "approve in your browser, then ask again" — the connection finishes in the background and your next request works.

### Tool sets

Clio MCP ships ~46 tools across seven groups: `core` (matters/contacts/documents), `billing` (time/expense + bills), `calendar`, `tasks`, `comms` (communications + notes), `fields` (custom fields), and `lookups` (practice areas/users/activity descriptions).

By default **all** are enabled. To scope a deployment to a subset, set the **Tool sets** field (or `CLIO_TOOLSETS`) to a comma list, e.g. `core,billing,calendar`. Unknown names are ignored; an empty result falls back to `core`.

## Manual setup (dev / headless)

1. Register **one** OAuth app in your firm's Clio developer account (US region). Note the client key and secret. Set the redirect URI to `http://127.0.0.1:9991/callback` (loopback login) — and additionally Clio's `oauth/approval` page if you use `--manual`.
2. Create `~/.clio-mcp/config.json`:
   ```json
   { "region": "us", "clientId": "<clio app key>", "clientSecret": "<clio app secret>" }
   ```
3. Install and build:
   ```bash
   npm install && npm run build
   ```
4. Authorize as yourself:
   ```bash
   node dist/cli.js login          # opens a browser (loopback)
   # or, on a locked-down machine:
   node dist/cli.js login --manual # paste the code from Clio's approval page
   ```

## Claude Desktop config

Add to `claude_desktop_config.json`:
```json
{
  "mcpServers": {
    "clio": {
      "command": "node",
      "args": ["/absolute/path/to/ClioMCP/dist/cli.js", "serve"]
    }
  }
}
```

## What it can do (Phase 1)

Matters: find, get, create, update (incl. close), add note, create task. Contacts: find, get, create. Documents: browse, get, download, upload, create folder. Destructive ops (rename/new-version, move, delete document, delete folder) require a two-step confirmation.

## Controls

- Per-user OAuth; refresh token encrypted at rest (OS keychain or AES-256-GCM file).
- Every tool call is recorded in `~/.clio-mcp/audit.log` (JSONL) — never tokens or document contents.
- Destructive actions return a preview + `confirm_token` first and only execute when the token is echoed back.
- Rate-limit aware (serialized queue honoring Clio's headers).

## Phase 2 (Delegant)

The governance seam (`src/governance/seam.ts`) is the swap point: replace `localGuard` with a `delegant` implementation to get firm-wide policy, human approval gates, and tamper-evident central audit — no tool rewrites.