fxabsolute-mcp

Connects a coding agent directly to FXAbsolute's candle history over MCP.

The point is to stop the model looking at pictures of charts. A screenshot forces it to recover prices from pixels; these tools hand it the numbers, so "what does the New York open actually do" becomes a query instead of a guess.

Setup

From inside this repo, nothing to do — .mcp.json at the repo root already registers the server, so any agent started in /root/fxabsolute picks it up. Approve it once when prompted.

Anywhere else:

claude mcp add fxabsolute -- node /root/fxabsolute/mcp/src/index.js

Verify with claude mcp list, or run the checks directly:

cd mcp && npm run smoke      # every tool against real data
node test/proto.mjs          # stdio protocol round-trip

Where the data comes from

In order:

1. FXA_DATA_DIR — an explicit directory of .bin files
2. ../public/data — automatic when running inside the checkout
3. FXA_ORIGIN (default https://www.fxabsolute.com) — fetched once per instrument and cached under ~/.cache/fxabsolute-mcp, so it works from any machine

~38 MB per instrument, downloaded lazily and only once.

Tools

Tool	What it answers
fxa_instruments	What's available, how many bars, what fields exist
fxa_candles	Raw OHLC over a date range at any timeframe M1–W1
fxa_session_scan	Specific bars of a trading session across months, summarised
fxa_bucket_stats	Movement grouped by hour / weekday / month / year
fxa_level_touches	Whether a price level actually held, and the reaction it produced

Live chart bridge

Tool	Purpose
fxa_connect_chart	Pair with an open chart using the code in its AI tab
fxa_wait_for_message	Block until the trader types or speaks; returns their words + chart state
fxa_reply	Answer into their chart panel
fxa_set_thinking	Show the thinking indicator during a long lookup
fxa_disconnect_chart	Leave the session

A trader opens the backtester, switches to the AI tab, and reads out the six-character code. Their agent calls fxa_connect_chart, then loops on fxa_wait_for_message → answer → fxa_reply. The site holds no API key and pays for no inference — every trader brings their own agent.

Each message carries a snapshot of the chart: instrument, timeframe, replay position, the current candle, every drawing as real geometry (height in pips, bars spanned, slope per bar, fib levels, whether price sits inside a box), open trades and running performance. The agent reads numbers, so it can check a claim with fxa_session_scan instead of guessing from an image.

Transport is a Supabase Realtime broadcast channel, so the browser and the agent need not be on the same machine — a chart on a phone pairs with a terminal on a laptop. Credentials come from /bridge-config.json on the site, which carries only the publishable key already present in every visitor's browser bundle, so pairing needs no setup.

The replay position is included with a note telling the agent not to reveal bars the trader has not reached. Backtesting is worthless if the assistant spoils the future.

The motivating query — the first 5-minute candle of the New York session, every day, for six months — is one call:

{ "instrument": "SPX500", "session": "nyse", "timeframe": "M5",
  "bars": [1], "from": "2024-01-01", "to": "2024-07-01" }

Two things worth knowing

There is no volume. The binary format is 20 bytes per candle: uint32 timestamp plus four float32 OHLC values. Volume was never stored, so no tool reports it and none invents a proxy silently — rangePips is offered instead, and every relevant response says so. Adding real volume means re-fetching all ~543 MB from Dukascopy into a wider record format.

Timeframes are bucketed on wall-clock time, not by array index. The browser chart aggregates every N bars, which is right for bar-by-bar replay but drifts for analysis: forex data has weekend and holiday gaps, so the Nth group of 60 M1 bars stops lining up with a real clock hour and an "H1 candle" can straddle a weekend. Here, bars are bucketed on floor(ts / period), so every bar sits on a true boundary and gaps produce no bar rather than a synthetic one.

Session windows are evaluated in exchange-local time with daylight saving resolved to the second, so "the 09:30 bar" is the 09:30 bar in both January and July rather than drifting an hour each spring.

fxa_session_scan also reports coverage: how many weekdays in the window produced no data at all. This matters more than it sounds — SPX500 is missing about 19% of weekdays in the first half of 2024, and without the warning a scan over that period returns clean-looking statistics built on a fifth less data than you asked for.