# Spark Ordernet MCP

Read-only MCP access to Spark / Ordernet brokerage accounts, including Meitav
Trade. The server exposes current holdings, transactions, orders, returns,
security lookup, price history, standing orders, and market news.

The authenticated client is constrained to an exact GET allowlist.
Authentication is the only POST request; order entry, cancellation, money
movement, currency conversion, and account changes are not reachable.

## Requirements

- Python 3.11 or newer
- [uv](https://docs.astral.sh/uv/)
- A supported Spark / Ordernet brokerage login

## Run the MCP server

Use the packaged command directly from GitHub:

```bash
uvx --from git+https://github.com/anhermon/spark-ordernet-mcp \
  spark-ordernet-mcp
```

Configure an MCP client with credentials supplied only through its environment:

```json
{
  "mcpServers": {
    "ordernet": {
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/anhermon/spark-ordernet-mcp",
        "spark-ordernet-mcp"
      ],
      "env": {
        "ORDERNET_BROKER": "meitav",
        "ORDERNET_USERNAME": "${ORDERNET_USERNAME}",
        "ORDERNET_PASSWORD": "${ORDERNET_PASSWORD}"
      }
    }
  }
}
```

Supported broker slugs include `meitav`, `psagot`, `ibi`, `nesua`, and `gaon`.

## Install the Codex skill

Ask Codex to install:

```text
https://github.com/anhermon/spark-ordernet-mcp/tree/main/spark-ordernet
```

Or clone the repository and copy `spark-ordernet/` into
`~/.codex/skills/spark-ordernet/`.

## Private portfolio report

After cloning the repository, create the ignored credential file and run:

```bash
cp .env.example .env
# Edit .env locally.
uv run --env-file .env python scripts/generate_portfolio_report.py
```

The report is written atomically to `reports/portfolio-analysis.html` with mode
`0600`. Reusable broker snapshots are stored under the ignored
`reports/.spark-cache/` directory with owner-only permissions. Completed years
are reused automatically, making subsequent reports faster and less dependent
on the broker's availability.

The report resolves numeric instrument IDs to safe public names when possible,
normalizes income and fees to ILS using transaction-date FX, provides sortable
historical-position columns, and plots indexed price action only across recorded
holding lifecycles. Missing FX or market history is shown explicitly instead of
being guessed.

- `--refresh` refreshes all historical snapshots.
- `--offline` reproduces the last successful cached report.
- `--no-cache` disables cache reads and writes for one run.
- `--cache-ttl 300` controls reuse of recent current-year snapshots.

The generated report and cache contain private financial data. They are ignored
by Git and must not be published.

## Development checks

Install the Git hooks once per clone:

```bash
uvx --from pre-commit pre-commit install
```

The hooks reject source and configuration files longer than 800 lines, run
Ruff, and execute the unit-test suite. Run the same checks across the repository
before pushing:

```bash
uvx --from pre-commit pre-commit run --all-files
```

GitHub Actions runs this command on every push and pull request. Individual
checks can also be run directly:

```bash
uv run python scripts/check_file_size.py .
uv run python -m unittest discover -s tests
uv run --with ruff ruff check .
```

## License

MIT — see [LICENSE](LICENSE).