milele-mcp

Read-only MCP server for Milele Prime. Lets a verified client connect their own AI (Claude / ChatGPT) to their own trading account and read account data — no order execution in phase 1.

Stack

TypeScript · Node 22 · Express · @modelcontextprotocol/sdk · Zod · Postgres (Supabase) · opaque revocable tokens · Vitest · Railway.

The core idea: two interfaces are the swap point

Everything in src/ talks to two interfaces, never to a real API:

• IdentityProvider (src/providers/interfaces/identity.ts) — Brokeret fills this
• TradingDataProvider (src/providers/interfaces/trading.ts) — MT5 Manager API fills this

Today both run as mocks. When credentials land, set IDENTITY_PROVIDER=real and TRADING_PROVIDER=real in .env and fill the two stub adapters in src/providers/real/. Nothing else changes.

Run it

npm install
cp .env.example .env      # defaults to mock providers, no infra needed
npm run dev               # boots on :8080
npm test                  # runs the isolation suite (6 tests)

Security model (proven by the test suite)

Every tool call goes through AuthGate.resolve() which:

1. validates the token (exists, not revoked),
2. confirms via the CRM that the token's login is owned by that client,
3. confirms the account is KYC-approved and live, then runs the tool with the login the gate resolved — never a login from the caller. A client cannot pass a login and read another account. test/isolation.test.ts proves: own-account read works, cross-account is blocked, forged/revoked/garbage tokens are rejected, suspended accounts are blocked.

Build sequence (status)

• [x] Server skeleton + config + factory (swap point)
• [x] Two provider interfaces
• [x] Mock implementations of both
• [x] Token service (in-memory; Postgres schema in db/migrations/001_init.sql)
• [x] Authorization gate + audit log + tool runner
• [x] One tool end to end: get_account_summary
• [x] Cross-account isolation test passing
• [ ] Remaining six read tools (positions, orders, history, quote, price_history, instrument_details)
• [ ] Swap token store + audit to Supabase Postgres
• [ ] Mount the real MCP SDK streamable-HTTP transport + OAuth
• [x] CRM "Connect AI Assistant" portal flow (replaces /dev/connect) — POST /connect/initiate|revoke, GET /connect/activity
• [ ] Fill the two real adapters when credentials land

Adding a tool

1. Add the method to TradingDataProvider + both mock and real impls.
2. Add a tool function in src/tools/index.ts using runTool(...) (gate + audit are automatic).
3. Add a route (or MCP tool registration) in src/server.ts.
4. Add an isolation assertion for it in test/isolation.test.ts.

Tomorrow's go-live delta

Fill src/providers/real/identity.ts (Brokeret endpoints) and src/providers/real/trading.ts (MT5 Manager API), set the two env flags to real, point the base URLs at the sandboxes, and run npm test against live data. The gate, tools, tokens, and audit are unchanged.