# CIMS MCP Server

An MCP (Model Context Protocol) server for [Roots CIMS](https://www.rootsfi.com/products/cims) — the Chain-based Interbanking Messaging System. CIMS routes transfers through standardized, bank-readable IDs such as `R-233-2993204` instead of raw wallet addresses, acting as crypto's equivalent of SEPA/ACH/SWIFT on a non-custodial network (currently Base Sepolia, chain ID 84532, USDC + ETH).

This server lets AI assistants resolve CIMS parties, quote and send transfers, handle attestation, and track intent lifecycles — with safety rails built in.

## Quick start

```bash
npm install
npm run build
npm start          # stdio MCP server with the mock adapter
```

MCP client configuration (e.g. Claude Desktop, VS Code):

```json
{
  "mcpServers": {
    "cims": {
      "command": "node",
      "args": ["/path/to/rootsfi-cims-MCP/dist/index.js"],
      "env": { "CIMS_ADAPTER": "mock" }
    }
  }
}
```

## Adapters

| Adapter | Selection | Notes |
|---|---|---|
| **mock** (default) | `CIMS_ADAPTER` unset or `mock` | In-memory directory, institutions, and full intent lifecycle. No credentials needed — ideal for demos and development. |
| **live** | `CIMS_ADAPTER=live` | HTTP client for the Roots CIMS relay. Requires `CIMS_RELAY_URL` and `CIMS_API_KEY` (see `.env.example`). RootsFi does not yet publish a public API reference, so endpoint shapes are best-effort and isolated behind the `CimsAdapter` interface for easy correction. |

## Tools

| Tool | Kind | Description |
|---|---|---|
| `cims_validate_id` | read-only | Parse/validate CIMS ID format (`R-institution-account`). Pure check, flags raw addresses. |
| `cims_resolve` | read-only | Resolve a name, handle, or CIMS ID to a routable party. Refuses raw `0x` addresses. |
| `cims_institution` | read-only | Institution status, supported rails, and attestation policy by index. |
| `cims_quote` | read-only | Price and policy-check a transfer (name check, AML, attestation). No funds moved. |
| `cims_send` | write | Create an intent from a quote. Requires `confirm=true` after user review. |
| `cims_attest` | write | Operator approval/rejection of an `attestation_required` intent. |
| `cims_cancel` | write | Cancel a pending intent inside the cancel window. |
| `cims_status` | read-only | Intent status, cancel window, tx hash when finalized. |
| `cims_list_intents` | read-only | List intents, filterable by status/asset. |

## Resources & prompts

- `cims://docs/overview` — CIMS concepts, ID format, transfer modes, safety model
- `cims://docs/lifecycle` — intent status transition diagram and timing windows
- Prompt `cims-send-money` — guided, safe transfer flow (resolve → quote → user confirm → send → track)

## Intent lifecycle

```
quoted → send(confirm) → pending ──window elapses──▶ finalized
                       ↘ attestation_required ──approve──▶ pending
                                              ──reject───▶ reverted
pending / attestation_required ──cancel (inside window)──▶ cancelled
```

- **direct** mode: ~30s pending window (small, repeat counterparties)
- **delayed** mode: ~12h pending window (default for first-time or ≥ 1,000)
- Contract-level max finality: 30 days

## Safety model

1. **No raw addresses** — `0x…` inputs are refused everywhere; parties must resolve via CIMS ID or directory name.
2. **Confirm before send** — `cims_send` requires `confirm=true`, intended to be set only after the user has reviewed the quote.
3. **Policy at quote time** — inactive institutions and unsupported rails are refused; name check, AML (review ≥ 50,000), and attestation requirements (≥ 10,000 or institution policy) are reported on every quote.
4. **Attestation gate** — flagged intents stay in `attestation_required` until an operator approves via `cims_attest`.
5. **Errors as data** — tool failures return `isError` content (not protocol errors), so assistants can read and explain them.

## Development

```bash
npm run dev    # run from source with tsx
npm test       # vitest: policy units, adapter lifecycle, server integration
npm run build  # tsc → dist/
```

Layout: `src/types.ts` (domain model) · `src/policy.ts` (ID parsing, mode/window/threshold rules) · `src/tools.ts` (MCP tool registration) · `src/resources.ts` (docs resources + prompt) · `src/adapters/` (mock + live behind `CimsAdapter`) · `test/` (vitest).