# Aurify MCP Gateway

An [MCP](https://modelcontextprotocol.io) server that lets an AI agent (Hermes,
Claude, any MCP client) do anything a user can do in the Aurify web app.

## What it is, and what it deliberately is not

It is an **adapter**, not a microservice. It owns no database, no aggregate, no
events, and no migrations. Every tool is a translation of an MCP call into a
request against `refina-web-bff` — the same REST surface the web frontend uses —
so there is exactly one implementation of every business rule, and it lives in
the domain services.

```
Hermes ──MCP (Streamable HTTP)──► aurify-mcp ──REST──► refina-web-bff ──gRPC──► wallet / transaction / …
                Bearer aur_pat_…       │                    Bearer <5-min JWT>
                                       └──► refina-auth  (PAT → JWT exchange)
```

It is intentionally **not** folded into the BFF: the BFF is the hot path for the
browser, tuned with a Redis read cache and a rate limiter for that traffic,
whereas this needs long-lived protocol sessions, tool schema discovery, scope
enforcement, and an audit trail. Different lifecycle, different blast radius.

## Authentication

The agent presents an Aurify **personal access token**; the gateway exchanges it
for a five-minute JWT and calls the BFF with that.

The exchanged JWT carries exactly the claims the BFF already expects, so **no
downstream service needed any change** to support agents. The PAT is the durable
credential and can be revoked at any time; the access token it yields is too
short-lived to be worth stealing.

Scopes are enforced **here**, before any network call. The BFF still only checks
the signature, exactly as it does for the browser.

### Getting a token

```bash
# 1. Log in to Aurify and grab your JWT, then mint a PAT with only the scopes
#    the agent actually needs.
curl -X POST http://localhost:8080/auth/pat \
  -H "Authorization: Bearer <your login JWT>" \
  -H "Content-Type: application/json" \
  -d '{"name":"hermes","scopes":["wallet:read","transaction:read","transaction:write"]}'

# 2. Copy the `token` from the response — it is shown once and never again.

# 3. Revoke it whenever you like:
curl -X DELETE http://localhost:8080/auth/pat/<id> -H "Authorization: Bearer <JWT>"
```

Available scopes: `wallet:read`, `wallet:write`, `transaction:read`,
`transaction:write`, `budget:read`, `budget:write`, `investment:read`,
`investment:write`, `analytics:read`, `profile:read`, `profile:write`.

## Tools

28 tools by default. Reads are unrestricted; writes are annotated
`readOnlyHint: false` so the client prompts for confirmation.

| Group | Read | Write |
|---|---|---|
| Wallets | `list_wallets`, `get_wallet`, `get_wallet_summary`, `list_wallet_types` | `create_wallet`, `update_wallet` |
| Transactions | `list_transactions`, `get_transaction`, `list_categories` | `create_transaction`, `create_fund_transfer`, `update_transaction` |
| Budgets | `list_budgets` | `create_budget`, `update_budget`, `reset_budget` |
| Analytics | `get_financial_summary`, `get_balance_history`, `get_net_worth`, `get_transaction_analytics`, `get_category_transactions` | — |
| Investments | `list_investments`, `get_investment_summary`, `list_asset_codes` | `create_investment` |
| Profile | `get_profile` | `update_profile` |
| System | — | `refresh_cache` |

`delete_wallet`, `delete_transaction`, `delete_budget` and `sell_investment` are
**not registered at all** unless `MCP_ALLOW_DELETE=true`. Filtering rather than
rejecting means an agent never even sees them advertised.

Two conveniences are built in, because the web UI solves them in the frontend:

- `create_fund_transfer` fills in the reserved Cash In / Cash Out category ids
  itself, so they are absent from the tool schema.
- Tool descriptions explain the credit-line balance convention, so an agent does
  not mistake available credit for money owned.

## Credit cards

A wallet whose `wallet_type_nature` is `liability` is a credit line. Its
`balance` is the credit **still available**: spending lowers it, and paying the
bill — a fund transfer into the wallet — restores it. Available credit is never
part of net worth. The tool descriptions state this so the model does not have
to infer it.

## Running

```bash
npm install
cp .env.example .env      # point BFF_BASE_URL / AUTH_BASE_URL at your services
npm run build
npm start                 # POST /mcp, GET /health
```

```bash
npm test                  # unit tests
npm run lint              # typecheck
```

## Configuration

| Variable | Default | Purpose |
|---|---|---|
| `PORT` | `8080` | Listen port |
| `BFF_BASE_URL` | *(required)* | refina-web-bff base URL |
| `AUTH_BASE_URL` | *(required)* | refina-auth base URL, for PAT exchange |
| `MCP_ALLOW_DELETE` | `false` | Register destructive tools |
| `REQUEST_TIMEOUT_MS` | `15000` | Upstream request timeout |

No JWT signing secret is needed: the gateway never mints tokens, it only asks
the auth service for them.

## Wiring up Hermes

Add to `~/.hermes/config.yaml` and run `/reload-mcp`:

```yaml
mcp_servers:
  aurify:
    url: http://127.0.0.1:8090/mcp
    headers:
      Authorization: Bearer aur_pat_xxxxxxxx
    enabled: true
    tools:
      include: [list_*, get_*, create_transaction, create_fund_transfer,
                update_transaction, create_budget, update_budget, refresh_cache]
      resources: false
      prompts: false
```

Verify with `hermes mcp test aurify`.

Use `tools.include` (an allowlist) rather than `exclude` — this is financial
data, and an allowlist fails closed when new tools are added.

## Operational notes

- **Stateless.** Each request builds its own server and transport, both torn
  down when the response ends. One caller's token can never leak into another's
  session, and the process can be restarted or scaled freely.
- **Session cache.** Exchanged JWTs are cached per token until 30s before
  expiry, and concurrent misses collapse into one exchange. In practice the
  first tool call in a turn costs a round trip to auth and the rest do not.
- **Audit log.** One JSON line per tool call on stdout, recording the tool,
  scope, outcome and duration. Argument *keys* are logged, never values — enough
  to audit without copying the user's financial data into the logs.
- **Bind to localhost.** Hermes runs as a host process, so publishing
  `127.0.0.1:8090` is sufficient. This gateway should not be exposed publicly.
- **Shared rate limiter.** The BFF's Redis rate limiter is shared with browser
  traffic, and its read cache can serve stale figures right after a write —
  hence the `refresh_cache` tool.