# Origin Read-only MCP

An **unofficial**, local MCP server scaffold for reading Origin Financial data from OpenClaw and other MCP clients.

**Status: runnable synthetic demo. Live Origin integration is not implemented or authenticated.** This project is not affiliated with or endorsed by Origin Financial. It does not provide investment advice.

## Quick start

Requires Node.js 24 and npm. After extracting or cloning this repository:

```sh
npm ci
npm run build
node dist/cli.js --demo
```

The last command waits for an MCP client on stdin. It is not an interactive chat. The demo contains handwritten January 2026 examples, including pending purchases and transfers. Every financial result is labeled `synthetic-demo`.

There are no credentials to configure. The default mode is `live`, which reports `LIVE_NOT_READY` for financial reads. This prevents an omitted configuration from silently returning fictional finances.

## Connect OpenClaw

Build first. Replace `/absolute/path/to/origin-readonly-mcp` with your checkout path on the machine running OpenClaw:

```sh
openclaw mcp add origin-readonly-demo \
  --command node \
  --arg dist/cli.js \
  --arg --demo \
  --cwd /absolute/path/to/origin-readonly-mcp
openclaw mcp doctor origin-readonly-demo --probe
```

Ask: “Using the Origin demo, list posted transactions for January 2026.” The probe verifies the MCP process, not an Origin login. This command follows [OpenClaw's MCP documentation](https://docs.openclaw.ai/tools/mcp). If your installed version differs, use its Settings → MCP screen with command `node`, arguments `dist/cli.js --demo`, and the checkout directory.

Other MCP clients can adapt [examples/mcp-client.json](examples/mcp-client.json). Use `node` directly for the server process so npm progress messages do not interfere with stdio.

## Tools

| Tool | Inputs | Result |
| --- | --- | --- |
| `list_accounts` | None | Account aliases, types, signed balances |
| `list_transactions` | Required inclusive dates; optional account, category, status, page, page size | One page and pagination metadata |
| `list_categories` | None | Category IDs and labels |
| `get_budget_summary` | `month`, such as `2026-01` | Planned and spent amounts by category |
| `get_connection_status` | None | Local readiness, mode, and whether upstream was checked |

Amounts use decimal **strings of integer minor units**, a currency code, and fraction digits. USD `"-5200"` with `fractionDigits: 2` is a $52.00 outflow. Account liabilities are negative. The demo's balance snapshots are independent of its short transaction sample. See [the tool contract](docs/tool-contract.md).

## What works

- MCP initialization, discovery, structured results, input validation, and stdio transport.
- Demo filtering, bounded paging, explicit transfer/pending status, and synthetic budget summaries.
- Strict output schemas and fixed, credential-free public error messages.
- An internal HTTP transport seam with fixed GET operations, redirect refusal, a timeout, and a streamed response limit. The server does not invoke it.
- A design and roadmap for implementing live access.

## What remains

- Local sign-in and secure credential storage, including MFA/SSO behavior.
- Verified Origin response schemas and domain mappings.
- Verified date/filter/page parameters and pagination completeness.
- Token refresh, rate-limit coordination, and reconciliation against the Origin UI.

No password capture, HAR upload, browser-session scraping, public HTTP listener, or write tools are included. Authentication must be completed outside the model's tool inputs. “Read-only” describes connector behavior; it does not establish that an Origin session token has read-only permissions.

## Design

- [Architecture and decisions](docs/design.md)
- [Tool contract](docs/tool-contract.md)
- [Research evidence and unknowns](docs/research.md)
- [Implementation milestones](docs/roadmap.md)
- [Security boundaries](SECURITY.md)

The repository is public. Never commit session tokens, financial exports, browser profiles, or network captures.

The source uses the MIT license. `private: true` in `package.json` prevents accidental npm publication and does not prevent a public GitHub repository.