@alfe.ai/ctrader-mcp 0.1.0

package/dist/server.js

@@ -0,0 +1,1311 @@
+#!/usr/bin/env node
+import { createRequire } from "node:module";
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { resolveConfig } from "@alfe.ai/config";
+import { AgentApiClient } from "@alfe.ai/agent-api-client";
+import { randomUUID } from "node:crypto";
+import * as tls from "node:tls";
+import { fileURLToPath } from "node:url";
+import { dirname, join } from "node:path";
+import protobuf from "protobufjs";
+import { z } from "zod";
+//#region src/config.ts
+/**
+* cTrader MCP server configuration.
+*
+* Like the other Alfe MCP servers, this one self-fetches its credentials at
+* startup via `@alfe.ai/agent-api-client`. The primary path is the
+* multi-account accessor `getCTraderAccounts()`: a single cTrader OAuth grant
+* covers ALL of the user's trading accounts on one shared `accessToken`, with
+* the SST-global app credentials (`clientId`/`clientSecret`) hoisted to the top
+* level. Only the `ctidTraderAccountId` and the protobuf socket `host` (live vs
+* demo) differ per account. We build an account *registry* from that set here
+* — one entry per account, grouped by host so a distinct socket serves each
+* distinct host (live vs demo). The cTrader Open API app-auth handshake needs
+* the raw client id/secret + access token on the box, which is why the connect
+* endpoint returns the full set rather than brokering each socket request.
+*/
+/** cTrader Open API TLS endpoints. Port is always 5035. */
+const CTRADER_LIVE_HOST = "live.ctraderapi.com";
+const CTRADER_DEMO_HOST = "demo.ctraderapi.com";
+const CTRADER_PORT = 5035;
+/** Raised when the fetched credential set is missing or malformed. */
+var ConfigError = class extends Error {
+	constructor(message) {
+		super(message);
+		this.name = "ConfigError";
+	}
+};
+/**
+* Resolve the TLS host from a live/demo hint.
+*
+* Accepts either a full hostname (`live.ctraderapi.com` /
+* `demo.ctraderapi.com`) or a short alias (`live` / `demo`). Defaults to
+* demo when unset — demo is the safe default because full-trading orders
+* move real money on a live account.
+*/
+function resolveHost(raw) {
+	const value = (raw ?? "").trim().toLowerCase();
+	if (value === "" || value === "demo") return CTRADER_DEMO_HOST;
+	if (value === "live") return CTRADER_LIVE_HOST;
+	if (value === "live.ctraderapi.com" || value === "demo.ctraderapi.com") return value;
+	throw new ConfigError(`Invalid cTrader host "${raw ?? ""}". Expected "live", "demo", "${CTRADER_LIVE_HOST}", or "${CTRADER_DEMO_HOST}".`);
+}
+/**
+* Assemble the account registry from the multi-account credential set returned
+* by `getCTraderAccounts()`. This is the primary startup path.
+*
+* Throws `ConfigError` (→ MCP startup failure, fail closed) when:
+*  - `accounts` is empty (no cTrader Connection — there is nothing to trade);
+*  - the shared app credentials (`clientId`/`clientSecret`/`accessToken`) are
+*    missing (every account needs them to authenticate);
+*  - after validating each account, no valid account remains.
+*
+* Individual accounts with an unparseable `ctidTraderAccountId` are skipped
+* (logged by the caller), but if that leaves the registry empty we fail closed
+* rather than start a server that can trade on nothing.
+*/
+function buildRegistry(creds) {
+	const clientId = creds.clientId.trim();
+	const clientSecret = creds.clientSecret.trim();
+	const accessToken = creds.accessToken.trim();
+	if (creds.accounts.length === 0) throw new ConfigError("No cTrader trading accounts are authorized for this agent. Connect a cTrader account (OAuth) for this agent, then retry.");
+	const missing = [];
+	if (!clientId) missing.push("clientId");
+	if (!clientSecret) missing.push("clientSecret");
+	if (!accessToken) missing.push("accessToken");
+	if (missing.length > 0) throw new ConfigError(`The cTrader connection is missing shared credential field(s): ${missing.join(", ")}. Connect a cTrader account (OAuth) for this agent, then retry.`);
+	const registry = /* @__PURE__ */ new Map();
+	for (const account of creds.accounts) {
+		const idRaw = account.ctidTraderAccountId.trim();
+		const accountId = Number(idRaw);
+		if (!idRaw || !Number.isInteger(accountId) || accountId <= 0) continue;
+		const host = resolveHost(account.host);
+		registry.set(idRaw, {
+			clientId,
+			clientSecret,
+			accessToken,
+			accountId,
+			host,
+			isLive: account.isLive,
+			...account.brokerName != null ? { brokerName: account.brokerName } : {},
+			...account.accountNumber != null ? { accountNumber: account.accountNumber } : {}
+		});
+	}
+	if (registry.size === 0) throw new ConfigError("Every cTrader account returned had an unusable ctidTraderAccountId; cannot build a trading registry. Re-connect the cTrader account (OAuth).");
+	return registry;
+}
+//#endregion
+//#region src/payload-types.ts
+/**
+* cTrader Open API payloadType numbers.
+*
+* Every message on the wire is wrapped in a `ProtoMessage` envelope whose
+* `payloadType` field is the numeric enum value below. These are transcribed
+* verbatim from Spotware's `OpenApiCommonModelMessages.proto` (common layer)
+* and `OpenApiModelMessages.proto` (OA layer). They are load-bearing — a wrong
+* number silently routes a message to the wrong decoder.
+*
+* Source: github.com/spotware/openapi-proto-messages
+*/
+const PayloadType = {
+	PROTO_MESSAGE: 5,
+	ERROR_RES: 50,
+	HEARTBEAT_EVENT: 51,
+	OA_APPLICATION_AUTH_REQ: 2100,
+	OA_APPLICATION_AUTH_RES: 2101,
+	OA_ACCOUNT_AUTH_REQ: 2102,
+	OA_ACCOUNT_AUTH_RES: 2103,
+	OA_NEW_ORDER_REQ: 2106,
+	OA_CANCEL_ORDER_REQ: 2108,
+	OA_AMEND_ORDER_REQ: 2109,
+	OA_AMEND_POSITION_SLTP_REQ: 2110,
+	OA_CLOSE_POSITION_REQ: 2111,
+	OA_SYMBOLS_LIST_REQ: 2114,
+	OA_SYMBOLS_LIST_RES: 2115,
+	OA_SYMBOL_BY_ID_REQ: 2116,
+	OA_SYMBOL_BY_ID_RES: 2117,
+	OA_TRADER_REQ: 2121,
+	OA_TRADER_RES: 2122,
+	OA_RECONCILE_REQ: 2124,
+	OA_RECONCILE_RES: 2125,
+	OA_EXECUTION_EVENT: 2126,
+	OA_SUBSCRIBE_SPOTS_REQ: 2127,
+	OA_SUBSCRIBE_SPOTS_RES: 2128,
+	OA_SPOT_EVENT: 2131,
+	OA_ORDER_ERROR_EVENT: 2132,
+	OA_GET_TRENDBARS_REQ: 2137,
+	OA_GET_TRENDBARS_RES: 2138,
+	OA_ERROR_RES: 2142,
+	OA_GET_ACCOUNT_LIST_BY_ACCESS_TOKEN_REQ: 2149,
+	OA_GET_ACCOUNT_LIST_BY_ACCESS_TOKEN_RES: 2150
+};
+/**
+* Map each request payloadType to the fully-qualified proto message name used
+* to encode its payload. Keeping this table beside the numbers lets the client
+* encode/route generically instead of hand-writing an encode call per op.
+*/
+const REQUEST_MESSAGE = {
+	[PayloadType.HEARTBEAT_EVENT]: "ctrader.ProtoHeartbeatEvent",
+	[PayloadType.OA_APPLICATION_AUTH_REQ]: "ctrader.ProtoOAApplicationAuthReq",
+	[PayloadType.OA_ACCOUNT_AUTH_REQ]: "ctrader.ProtoOAAccountAuthReq",
+	[PayloadType.OA_GET_ACCOUNT_LIST_BY_ACCESS_TOKEN_REQ]: "ctrader.ProtoOAGetAccountListByAccessTokenReq",
+	[PayloadType.OA_TRADER_REQ]: "ctrader.ProtoOATraderReq",
+	[PayloadType.OA_RECONCILE_REQ]: "ctrader.ProtoOAReconcileReq",
+	[PayloadType.OA_SYMBOLS_LIST_REQ]: "ctrader.ProtoOASymbolsListReq",
+	[PayloadType.OA_SYMBOL_BY_ID_REQ]: "ctrader.ProtoOASymbolByIdReq",
+	[PayloadType.OA_GET_TRENDBARS_REQ]: "ctrader.ProtoOAGetTrendbarsReq",
+	[PayloadType.OA_SUBSCRIBE_SPOTS_REQ]: "ctrader.ProtoOASubscribeSpotsReq",
+	[PayloadType.OA_NEW_ORDER_REQ]: "ctrader.ProtoOANewOrderReq",
+	[PayloadType.OA_AMEND_ORDER_REQ]: "ctrader.ProtoOAAmendOrderReq",
+	[PayloadType.OA_AMEND_POSITION_SLTP_REQ]: "ctrader.ProtoOAAmendPositionSLTPReq",
+	[PayloadType.OA_CLOSE_POSITION_REQ]: "ctrader.ProtoOAClosePositionReq",
+	[PayloadType.OA_CANCEL_ORDER_REQ]: "ctrader.ProtoOACancelOrderReq"
+};
+/** Map each response/event payloadType to the proto message name to decode it. */
+const RESPONSE_MESSAGE = {
+	[PayloadType.ERROR_RES]: "ctrader.ProtoErrorRes",
+	[PayloadType.HEARTBEAT_EVENT]: "ctrader.ProtoHeartbeatEvent",
+	[PayloadType.OA_APPLICATION_AUTH_RES]: "ctrader.ProtoOAApplicationAuthRes",
+	[PayloadType.OA_ACCOUNT_AUTH_RES]: "ctrader.ProtoOAAccountAuthRes",
+	[PayloadType.OA_GET_ACCOUNT_LIST_BY_ACCESS_TOKEN_RES]: "ctrader.ProtoOAGetAccountListByAccessTokenRes",
+	[PayloadType.OA_TRADER_RES]: "ctrader.ProtoOATraderRes",
+	[PayloadType.OA_RECONCILE_RES]: "ctrader.ProtoOAReconcileRes",
+	[PayloadType.OA_SYMBOLS_LIST_RES]: "ctrader.ProtoOASymbolsListRes",
+	[PayloadType.OA_SYMBOL_BY_ID_RES]: "ctrader.ProtoOASymbolByIdRes",
+	[PayloadType.OA_GET_TRENDBARS_RES]: "ctrader.ProtoOAGetTrendbarsRes",
+	[PayloadType.OA_SUBSCRIBE_SPOTS_RES]: "ctrader.ProtoOASubscribeSpotsRes",
+	[PayloadType.OA_SPOT_EVENT]: "ctrader.ProtoOASpotEvent",
+	[PayloadType.OA_EXECUTION_EVENT]: "ctrader.ProtoOAExecutionEvent",
+	[PayloadType.OA_ORDER_ERROR_EVENT]: "ctrader.ProtoOAOrderErrorEvent",
+	[PayloadType.OA_ERROR_RES]: "ctrader.ProtoOAErrorRes"
+};
+//#endregion
+//#region src/proto.ts
+/**
+* protobuf schema loading + the length-prefixed `ProtoMessage` wire codec.
+*
+* Foundation decision: we load Spotware's message subset from a vendored
+* `.proto` (see `proto/ctrader.proto`) with `protobufjs` at runtime, rather
+* than depending on the abandoned `@reiryoku/ctrader-layer` npm package
+* (last published 2022, pins protobufjs@5 + axios@0.21). See README.
+*
+* Wire framing (verified against Spotware OpenApiPy `Int32StringReceiver`):
+*   [ 4-byte big-endian uint32 length ][ serialized ProtoMessage bytes ]
+*/
+/** Decode an envelope's payload using a given payloadType→message-name table. */
+function decodeWith(root, envelopeBytes, table) {
+	const env = root.lookupType("ctrader.ProtoMessage").decode(envelopeBytes);
+	const messageName = table[env.payloadType];
+	let message = {};
+	if (messageName && env.payload) {
+		const InnerType = root.lookupType(messageName);
+		message = InnerType.toObject(InnerType.decode(env.payload), {
+			longs: String,
+			enums: Number,
+			defaults: false
+		});
+	}
+	return {
+		payloadType: env.payloadType,
+		clientMsgId: env.clientMsgId,
+		message
+	};
+}
+createRequire(import.meta.url);
+/**
+* Resolve the vendored `.proto`. It ships in the package `files` array at
+* `proto/ctrader.proto`; the compiled server lives at `dist/server.js`, so the
+* proto is one directory up from `dist/`. During tests we run from `src/`, so
+* the same `../proto` relative hop resolves correctly there too.
+*/
+function resolveProtoPath() {
+	return join(dirname(fileURLToPath(import.meta.url)), "..", "proto", "ctrader.proto");
+}
+let cachedRoot = null;
+/** Load (and memoise) the protobuf root from the vendored schema. */
+function loadRoot(protoPath = resolveProtoPath()) {
+	cachedRoot ??= protobuf.loadSync(protoPath);
+	return cachedRoot;
+}
+/**
+* Encode an outbound request into a fully-framed buffer:
+* length prefix + ProtoMessage(payloadType, payload, clientMsgId).
+*/
+function encodeRequest(root, payloadType, payload, clientMsgId) {
+	const messageName = REQUEST_MESSAGE[payloadType];
+	if (!messageName) throw new Error(`No request message registered for payloadType ${String(payloadType)}`);
+	const InnerType = root.lookupType(messageName);
+	const innerErr = InnerType.verify(payload);
+	if (innerErr) throw new Error(`Invalid ${messageName} payload: ${innerErr}`);
+	const innerBytes = InnerType.encode(InnerType.create(payload)).finish();
+	const Envelope = root.lookupType("ctrader.ProtoMessage");
+	const envelopeBytes = Envelope.encode(Envelope.create({
+		payloadType,
+		payload: innerBytes,
+		clientMsgId
+	})).finish();
+	const frame = Buffer.allocUnsafe(4 + envelopeBytes.length);
+	frame.writeUInt32BE(envelopeBytes.length, 0);
+	Buffer.from(envelopeBytes).copy(frame, 4);
+	return frame;
+}
+/** Decode a single ProtoMessage envelope (already de-framed) into its payload. */
+function decodeEnvelope(root, envelopeBytes) {
+	return decodeWith(root, envelopeBytes, RESPONSE_MESSAGE);
+}
+/**
+* Incremental frame de-chunker for a TLS byte stream.
+*
+* `push` appends received bytes and returns every complete envelope now
+* available (a single TCP read may contain 0, 1, or many frames, or a partial
+* frame that stays buffered until the rest arrives).
+*/
+var FrameParser = class {
+	buffer = Buffer.alloc(0);
+	push(chunk) {
+		this.buffer = Buffer.concat([this.buffer, chunk]);
+		const frames = [];
+		for (;;) {
+			if (this.buffer.length < 4) break;
+			const length = this.buffer.readUInt32BE(0);
+			if (this.buffer.length < 4 + length) break;
+			frames.push(this.buffer.subarray(4, 4 + length));
+			this.buffer = this.buffer.subarray(4 + length);
+		}
+		return frames;
+	}
+	/** Bytes currently buffered awaiting completion (diagnostics / tests). */
+	get pending() {
+		return this.buffer.length;
+	}
+};
+//#endregion
+//#region src/convert.ts
+/**
+* Unit conversions for the cTrader Open API.
+*
+* cTrader speaks in integer minor-units to avoid floats on the wire:
+*  - money (balance) is scaled by `moneyDigits` (default 2 → cents)
+*  - volume is in "centi-units" (0.01 of the base asset); `symbol.lotSize`
+*    is already the centi-unit volume of one lot
+*  - trendbar / spot prices are integers scaled by 10^5 (relative-price units)
+*
+* These are pure and unit-tested — the risky arithmetic lives here, not
+* scattered through the tools.
+*/
+/**
+* Safely stringify an untyped wire value (protobufjs returns int64 fields as
+* strings via `longs: String`, numbers otherwise). Objects — which should
+* never appear on scalar fields — collapse to `""` rather than
+* `[object Object]`, keeping the JSON output clean.
+*/
+function str(v) {
+	if (v == null) return "";
+	if (typeof v === "string") return v;
+	if (typeof v === "number" || typeof v === "bigint" || typeof v === "boolean") return String(v);
+	return "";
+}
+/**
+* Convert an integer money value to its real currency figure.
+* `moneyDigits` is optional on the wire; default 2 (legacy cents behaviour).
+*/
+function moneyToDecimal(raw, moneyDigits = 2) {
+	return raw / 10 ** moneyDigits;
+}
+/**
+* Convert a lot count to protocol volume (centi-units) for an order.
+* `lotSize` comes from `ProtoOASymbol.lotSize` and is already in centi-units,
+* so `volume = lots * lotSize`. Do NOT hardcode 100000 — lotSize varies by
+* symbol.
+*/
+function lotsToVolume(lots, lotSize) {
+	return Math.round(lots * lotSize);
+}
+/** Inverse of {@link lotsToVolume}: protocol volume → lot count. */
+function volumeToLots(volume, lotSize) {
+	if (lotSize === 0) return 0;
+	return volume / lotSize;
+}
+/**
+* Validate an order volume against a symbol's min / max / step, all of which
+* are in the same centi-unit space. Returns an error string, or null if valid.
+*/
+function validateVolume(volume, minVolume, maxVolume, stepVolume) {
+	if (volume < minVolume) return `volume ${String(volume)} is below the symbol minimum ${String(minVolume)}`;
+	if (maxVolume > 0 && volume > maxVolume) return `volume ${String(volume)} exceeds the symbol maximum ${String(maxVolume)}`;
+	if (stepVolume > 0 && (volume - minVolume) % stepVolume !== 0) return `volume ${String(volume)} does not align to the symbol step ${String(stepVolume)} (offset from min ${String(minVolume)})`;
+	return null;
+}
+/** cTrader trendbar/spot integer prices are scaled by 10^5. */
+const PRICE_SCALE = 1e5;
+/** Convert a raw wire price integer to a real price. */
+function priceToDecimal(raw) {
+	return raw / PRICE_SCALE;
+}
+/**
+* Reconstruct a trendbar's OHLC from its delta encoding. cTrader stores the
+* bar `low` absolutely and open/high/close as unsigned deltas above the low.
+*/
+function decodeTrendbar(bar) {
+	const low = Number(bar.low ?? 0);
+	const open = low + Number(bar.deltaOpen ?? 0);
+	const high = low + Number(bar.deltaHigh ?? 0);
+	const close = low + Number(bar.deltaClose ?? 0);
+	const minutes = Number(bar.utcTimestampInMinutes ?? 0);
+	return {
+		open: priceToDecimal(open),
+		high: priceToDecimal(high),
+		low: priceToDecimal(low),
+		close: priceToDecimal(close),
+		volume: Number(bar.volume ?? 0),
+		timestamp: (/* @__PURE__ */ new Date(minutes * 6e4)).toISOString()
+	};
+}
+//#endregion
+//#region src/client.ts
+/**
+* cTrader Open API client: manages the TLS socket lifecycle, the
+* application + account auth handshake, request/response correlation, the
+* 10-second heartbeat, reconnect-on-drop, and cTrader-error mapping.
+*
+* ── Multi-account model ──
+* A single cTrader OAuth grant covers ALL of the user's trading accounts on one
+* shared access token; only the `ctidTraderAccountId` and the socket `host`
+* (live vs demo) differ per account. But one TLS socket dials exactly ONE host.
+* So the topology is:
+*
+*   CTraderPool  ── owns the account registry, one HostSocket per DISTINCT host
+*      │
+*      ├─ HostSocket(live.ctraderapi.com)  ── app-auth once; account-auth each
+*      │                                       live account on demand
+*      └─ HostSocket(demo.ctraderapi.com)  ── app-auth once; account-auth each
+*                                              demo account on demand
+*
+* `CTraderPool.request(accountId, ...)` resolves the account → its host socket,
+* ensures that account is account-authed on that socket, then sends the request
+* carrying the account's `ctidTraderAccountId`. Routing by account id → host is
+* the core money-safety property: a demo account MUST NOT be served by the live
+* socket and vice-versa.
+*
+* The transport is injectable (`connect` factory) so the request/response
+* plumbing and handshake can be unit-tested against a mock duplex without any
+* real network. Production uses `tlsConnect` (node `tls.connect`).
+*/
+/** Error carrying a cTrader `errorCode` so tools can surface it verbatim. */
+var CTraderError = class extends Error {
+	errorCode;
+	/** Present when the reject came back tied to a specific order/position. */
+	orderId;
+	positionId;
+	constructor(errorCode, description, refs) {
+		super(description ? `${errorCode}: ${description}` : errorCode);
+		this.name = "CTraderError";
+		this.errorCode = errorCode;
+		if (refs?.orderId != null) this.orderId = refs.orderId;
+		if (refs?.positionId != null) this.positionId = refs.positionId;
+	}
+};
+const HEARTBEAT_INTERVAL_MS = 1e4;
+const REQUEST_TIMEOUT_MS = 2e4;
+const RECONNECT_BASE_MS = 1e3;
+const RECONNECT_MAX_MS = 3e4;
+function log$1(msg) {
+	process.stderr.write(`[ctrader-mcp] ${msg}\n`);
+}
+/** Production TLS transport. */
+const tlsConnect = (host, port) => new Promise((resolve, reject) => {
+	const socket = tls.connect({
+		host,
+		port,
+		servername: host
+	}, () => {
+		resolve(socket);
+	});
+	socket.once("error", reject);
+});
+/**
+* A single authenticated socket to ONE cTrader host (live or demo).
+*
+* On `start()` it opens the socket and runs the app-auth handshake once. Each
+* account that will be traded on this host is account-authed lazily via
+* `authenticateAccount()` (deduped — an account is only account-authed once per
+* live socket, and re-authed after a reconnect). `request()` carries an
+* explicit `ctidTraderAccountId` so a single socket can serve several accounts
+* on the same host.
+*/
+var HostSocket = class {
+	host;
+	clientId;
+	clientSecret;
+	connectFn;
+	root;
+	conn = null;
+	parser = new FrameParser();
+	pending = /* @__PURE__ */ new Map();
+	heartbeatTimer = null;
+	reconnectAttempts = 0;
+	closing = false;
+	connectPromise = null;
+	/** ctidTraderAccountId → accessToken used to account-auth it on this socket. */
+	authedAccounts = /* @__PURE__ */ new Map();
+	/** Serializes account-auth so concurrent tool calls don't double-auth. */
+	accountAuthPromises = /* @__PURE__ */ new Map();
+	constructor(host, clientId, clientSecret, connectFn = tlsConnect, root = loadRoot()) {
+		this.host = host;
+		this.clientId = clientId;
+		this.clientSecret = clientSecret;
+		this.connectFn = connectFn;
+		this.root = root;
+	}
+	/** Connect the socket and run the app-auth handshake. Idempotent. */
+	async start() {
+		this.connectPromise ??= this.doStart();
+		return this.connectPromise;
+	}
+	async doStart() {
+		this.conn = await this.connectFn(this.host, CTRADER_PORT);
+		this.wireConnection(this.conn);
+		await this.appAuth();
+		this.startHeartbeat();
+		log$1(`Connected + app-authenticated to ${this.host}`);
+	}
+	/**
+	* Ensure `accountId` is account-authed on this socket. Deduped: an account is
+	* account-authed at most once per live socket. Concurrent callers share the
+	* same in-flight auth promise.
+	*/
+	async authenticateAccount(accountId, accessToken) {
+		await this.start();
+		if (this.authedAccounts.get(accountId) === accessToken) return;
+		let inFlight = this.accountAuthPromises.get(accountId);
+		if (!inFlight) {
+			inFlight = this.request(PayloadType.OA_ACCOUNT_AUTH_REQ, {
+				ctidTraderAccountId: accountId,
+				accessToken
+			}).then(() => {
+				this.authedAccounts.set(accountId, accessToken);
+			}).finally(() => {
+				this.accountAuthPromises.delete(accountId);
+			});
+			this.accountAuthPromises.set(accountId, inFlight);
+		}
+		await inFlight;
+	}
+	wireConnection(conn) {
+		conn.on("data", (chunk) => {
+			for (const frame of this.parser.push(chunk)) this.dispatch(frame);
+		});
+		conn.on("error", (err) => {
+			log$1(`Socket error (${this.host}): ${err.message}`);
+		});
+		conn.on("close", () => {
+			if (!this.closing) this.handleDrop();
+		});
+	}
+	async appAuth() {
+		await this.request(PayloadType.OA_APPLICATION_AUTH_REQ, {
+			clientId: this.clientId,
+			clientSecret: this.clientSecret
+		});
+	}
+	startHeartbeat() {
+		this.stopHeartbeat();
+		this.heartbeatTimer = setInterval(() => {
+			if (!this.conn) return;
+			try {
+				const frame = encodeRequest(this.root, PayloadType.HEARTBEAT_EVENT, {}, randomUUID());
+				this.conn.write(frame);
+			} catch (err) {
+				log$1(`Heartbeat send failed (${this.host}): ${err instanceof Error ? err.message : String(err)}`);
+			}
+		}, HEARTBEAT_INTERVAL_MS);
+		this.heartbeatTimer.unref();
+	}
+	stopHeartbeat() {
+		if (this.heartbeatTimer) {
+			clearInterval(this.heartbeatTimer);
+			this.heartbeatTimer = null;
+		}
+	}
+	handleDrop() {
+		log$1(`Socket dropped (${this.host}) — attempting reconnect`);
+		this.stopHeartbeat();
+		this.conn = null;
+		this.parser = new FrameParser();
+		this.authedAccounts.clear();
+		for (const [id, req] of this.pending) {
+			clearTimeout(req.timer);
+			req.reject(new CTraderError("CONNECTION_DROPPED", "Socket closed before a response arrived"));
+			this.pending.delete(id);
+		}
+		this.reconnect();
+	}
+	async reconnect() {
+		if (this.closing) return;
+		const delay = Math.min(RECONNECT_BASE_MS * 2 ** this.reconnectAttempts, RECONNECT_MAX_MS);
+		this.reconnectAttempts += 1;
+		await new Promise((r) => setTimeout(r, delay));
+		if (this.closing) return;
+		try {
+			this.conn = await this.connectFn(this.host, CTRADER_PORT);
+			this.wireConnection(this.conn);
+			await this.appAuth();
+			this.startHeartbeat();
+			this.reconnectAttempts = 0;
+			log$1(`Reconnected + re-app-authenticated (${this.host})`);
+		} catch (err) {
+			log$1(`Reconnect failed (${this.host}): ${err instanceof Error ? err.message : String(err)}`);
+			this.reconnect();
+		}
+	}
+	dispatch(frame) {
+		let decoded;
+		try {
+			decoded = decodeEnvelope(this.root, frame);
+		} catch (err) {
+			log$1(`Failed to decode a frame (${this.host}): ${err instanceof Error ? err.message : String(err)}`);
+			return;
+		}
+		if (decoded.payloadType === PayloadType.HEARTBEAT_EVENT) return;
+		const id = decoded.clientMsgId;
+		if (!id) return;
+		const waiter = this.pending.get(id);
+		if (!waiter) return;
+		clearTimeout(waiter.timer);
+		this.pending.delete(id);
+		const err = this.extractError(decoded.payloadType, decoded.message);
+		if (err) {
+			waiter.reject(err);
+			return;
+		}
+		waiter.resolve({
+			payloadType: decoded.payloadType,
+			message: decoded.message
+		});
+	}
+	/**
+	* Map a cTrader error response to a `CTraderError`. Both the common-layer
+	* `ProtoErrorRes` (50) and the OA-layer `ProtoOAErrorRes` (2142) carry an
+	* `errorCode`; a broker-rejected order comes back as a dedicated
+	* `ProtoOAOrderErrorEvent` (2132) echoing the request `clientMsgId`, and
+	* some order-op rejections ride an execution event with `errorCode` set.
+	* Every one of these is a money-path reject — it MUST become a
+	* `CTraderError`, never resolve as success.
+	*/
+	extractError(payloadType, message) {
+		if (payloadType === PayloadType.ERROR_RES || payloadType === PayloadType.OA_ERROR_RES) return new CTraderError(typeof message.errorCode === "string" ? message.errorCode : "UNKNOWN_ERROR", typeof message.description === "string" ? message.description : void 0);
+		if (payloadType === PayloadType.OA_ORDER_ERROR_EVENT) return new CTraderError(typeof message.errorCode === "string" ? message.errorCode : "ORDER_ERROR", typeof message.description === "string" ? message.description : void 0, {
+			orderId: str(message.orderId) || void 0,
+			positionId: str(message.positionId) || void 0
+		});
+		if (payloadType === PayloadType.OA_EXECUTION_EVENT && typeof message.errorCode === "string") return new CTraderError(message.errorCode);
+		return null;
+	}
+	/**
+	* Send a request and await the correlated response (matched by clientMsgId).
+	* Rejects with `CTraderError` on a cTrader error or timeout.
+	*/
+	async request(payloadType, payload) {
+		if (!this.conn) throw new CTraderError("NOT_CONNECTED", `The cTrader socket to ${this.host} is not connected`);
+		const clientMsgId = randomUUID();
+		const frame = encodeRequest(this.root, payloadType, payload, clientMsgId);
+		return new Promise((resolve, reject) => {
+			const timer = setTimeout(() => {
+				this.pending.delete(clientMsgId);
+				reject(new CTraderError("REQUEST_TIMEOUT", `No response for payloadType ${String(payloadType)} within ${String(REQUEST_TIMEOUT_MS)}ms`));
+			}, REQUEST_TIMEOUT_MS);
+			timer.unref();
+			this.pending.set(clientMsgId, {
+				resolve,
+				reject,
+				timer
+			});
+			this.conn?.write(frame);
+		});
+	}
+	/** Clean shutdown: stop heartbeat, fail waiters, destroy the socket. */
+	close() {
+		this.closing = true;
+		this.stopHeartbeat();
+		for (const [id, req] of this.pending) {
+			clearTimeout(req.timer);
+			req.reject(new CTraderError("CLIENT_CLOSED", "Client is shutting down"));
+			this.pending.delete(id);
+		}
+		this.conn?.destroy();
+		this.conn = null;
+		this.authedAccounts.clear();
+	}
+};
+/**
+* The account router. Owns the account registry and one `HostSocket` per
+* DISTINCT host, created lazily on first use. Tools resolve an account through
+* this pool: `request(accountId, payloadType, payload)` finds the account's
+* host socket, ensures the account is account-authed there, and routes the
+* request with the account's `ctidTraderAccountId` injected.
+*/
+var CTraderPool = class {
+	registry;
+	connectFn;
+	root;
+	/** host → the single socket serving that host. Lazily populated. */
+	sockets = /* @__PURE__ */ new Map();
+	constructor(registry, connectFn = tlsConnect, root = loadRoot()) {
+		this.registry = registry;
+		this.connectFn = connectFn;
+		this.root = root;
+	}
+	/** The account registry (read-only view for tools that list/resolve). */
+	get accounts() {
+		return this.registry;
+	}
+	/** How many accounts are connected. Drives the required-vs-optional selector. */
+	get size() {
+		return this.registry.size;
+	}
+	/** The sole account's id when exactly one is connected, else null. */
+	get soleAccountId() {
+		if (this.registry.size !== 1) return null;
+		const [only] = this.registry.keys();
+		return only;
+	}
+	/** Look up an account's config by ctidTraderAccountId (string), or null. */
+	resolve(accountId) {
+		return this.registry.get(accountId) ?? null;
+	}
+	/** Lazily create + return the socket for a host (does not auth accounts). */
+	socketFor(config) {
+		let socket = this.sockets.get(config.host);
+		if (!socket) {
+			socket = new HostSocket(config.host, config.clientId, config.clientSecret, this.connectFn, this.root);
+			this.sockets.set(config.host, socket);
+		}
+		return socket;
+	}
+	/**
+	* Route a request to a specific account. Resolves the account → its host
+	* socket, ensures the socket is connected + app-authed and the account is
+	* account-authed, then sends the request. Every account-scoped request must
+	* go through here so it lands on the RIGHT host socket. The account's
+	* `ctidTraderAccountId` is NOT auto-injected into the payload — callers pass
+	* the full payload — but the request is guaranteed to run on the socket that
+	* serves this account's host.
+	*
+	* Throws `CTraderError("UNKNOWN_ACCOUNT")` if the id isn't in the registry
+	* (fail closed — never fall back to another account).
+	*/
+	async request(accountId, payloadType, payload) {
+		const config = this.resolve(accountId);
+		if (!config) throw new CTraderError("UNKNOWN_ACCOUNT", `Account ${accountId} is not connected`);
+		const socket = this.socketFor(config);
+		await socket.authenticateAccount(config.accountId, config.accessToken);
+		return socket.request(payloadType, payload);
+	}
+	/** Close every host socket. */
+	close() {
+		for (const socket of this.sockets.values()) socket.close();
+		this.sockets.clear();
+	}
+};
+//#endregion
+//#region src/tools.ts
+/**
+* MCP tool registration for the cTrader MCP server.
+*
+* Read tools:  get_accounts, get_account_details, get_positions, get_orders,
+*              get_symbols, get_market_data
+* Write tools: place_order, modify_order, close_position, cancel_order
+*
+* ── Account routing (money-safety) ──
+* Every tool that acts on an account takes an OPTIONAL `accountId`
+* (= ctidTraderAccountId):
+*   - exactly ONE account connected → `accountId` optional, defaults to it;
+*   - MULTIPLE accounts connected → `accountId` REQUIRED. If it's omitted or
+*     not in the registry, the tool returns an `isError` result that LISTS the
+*     available accounts so the agent can choose. It NEVER defaults to an
+*     arbitrary account when several exist — trading on the wrong (e.g. live vs
+*     demo) account is the exact failure this guards against.
+* The resolved account is routed through `CTraderPool` to its host socket with
+* its own `ctidTraderAccountId`.
+*
+* Every tool has a strict zod input schema, maps cTrader errors to MCP tool
+* errors, and returns structured JSON. Volume is accepted as lots
+* (human-friendly) and converted to protocol centi-units via the symbol's
+* lotSize.
+*/
+const ORDER_TYPE = {
+	MARKET: 1,
+	LIMIT: 2,
+	STOP: 3
+};
+const TRADE_SIDE = {
+	BUY: 1,
+	SELL: 2
+};
+/**
+* ProtoOAExecutionType (OpenApiModelMessages.proto). The number the broker
+* returns on a ProtoOAExecutionEvent tells us the real outcome — a bare
+* "placed: true" hides a REJECTED/CANCELLED fill. Values transcribed verbatim.
+*/
+const EXECUTION_TYPE_NAME = {
+	2: "ORDER_ACCEPTED",
+	3: "ORDER_FILLED",
+	4: "ORDER_REPLACED",
+	5: "ORDER_CANCELLED",
+	6: "ORDER_EXPIRED",
+	7: "ORDER_REJECTED",
+	8: "ORDER_CANCEL_REJECTED",
+	9: "SWAP",
+	10: "DEPOSIT_WITHDRAW",
+	11: "ORDER_PARTIAL_FILL",
+	12: "BONUS_DEPOSIT_WITHDRAW"
+};
+/** Execution types that mean the write did NOT succeed as intended. */
+const FAILED_EXECUTION_TYPES = new Set([
+	5,
+	6,
+	7,
+	8
+]);
+const TRENDBAR_PERIOD = {
+	M1: 1,
+	M2: 2,
+	M3: 3,
+	M4: 4,
+	M5: 5,
+	M10: 6,
+	M15: 7,
+	M30: 8,
+	H1: 9,
+	H4: 10,
+	H12: 11,
+	D1: 12,
+	W1: 13,
+	MN1: 14
+};
+function ok(data) {
+	return { content: [{
+		type: "text",
+		text: JSON.stringify(data, null, 2)
+	}] };
+}
+function fail(err) {
+	const message = err instanceof CTraderError ? err.message : err instanceof Error ? err.message : String(err);
+	const errorCode = err instanceof CTraderError ? err.errorCode : "TOOL_ERROR";
+	return {
+		content: [{
+			type: "text",
+			text: JSON.stringify({
+				error: errorCode,
+				message
+			}, null, 2)
+		}],
+		isError: true
+	};
+}
+function num(v) {
+	return Number(v ?? 0);
+}
+/** Serialize an account for a listing (both the registry and error payloads). */
+function describeAccount(config) {
+	return {
+		accountId: String(config.accountId),
+		isLive: config.isLive,
+		host: config.host,
+		broker: config.brokerName ?? null,
+		accountNumber: config.accountNumber ?? null
+	};
+}
+/**
+* Resolve the account an account-scoped tool should act on.
+*
+*  - MULTIPLE accounts + `accountId` omitted  → error listing the accounts
+*    (REQUIRED-selector case: never default to an arbitrary account).
+*  - `accountId` given but not in the registry → error listing the accounts.
+*  - single account + `accountId` omitted      → default to the sole account.
+*  - `accountId` given and valid               → that account.
+*
+* Returns the resolved `CTraderConfig` on success, or a `ToolResult` (isError)
+* describing the ambiguity/miss on failure. This IS the money-safety gate.
+*/
+function resolveAccount(pool, accountId) {
+	const listing = () => [...pool.accounts.values()].map(describeAccount);
+	if (accountId == null) {
+		const sole = pool.soleAccountId;
+		if (sole == null) return {
+			content: [{
+				type: "text",
+				text: JSON.stringify({
+					error: "ACCOUNT_ID_REQUIRED",
+					message: "Multiple cTrader accounts are connected — pass `accountId` (ctidTraderAccountId) to choose one. This tool will NOT default to an account when several exist, to avoid trading on the wrong (e.g. live vs demo) account.",
+					accounts: listing()
+				}, null, 2)
+			}],
+			isError: true
+		};
+		const config = pool.resolve(sole);
+		if (config) return config;
+	} else {
+		const config = pool.resolve(accountId);
+		if (config) return config;
+	}
+	return {
+		content: [{
+			type: "text",
+			text: JSON.stringify({
+				error: "UNKNOWN_ACCOUNT",
+				message: `No connected cTrader account with ctidTraderAccountId "${accountId ?? ""}". Pick one of the accounts below (by its accountId).`,
+				accounts: listing()
+			}, null, 2)
+		}],
+		isError: true
+	};
+}
+/** Narrow a resolveAccount() return to its error branch. */
+function isToolError(v) {
+	return "content" in v;
+}
+/** Fetch a symbol's full detail (for lotSize / volume rules / digits). */
+async function getSymbolDetail(pool, accountId, numericAccountId, symbolId) {
+	const symbols = (await pool.request(accountId, PayloadType.OA_SYMBOL_BY_ID_REQ, {
+		ctidTraderAccountId: numericAccountId,
+		symbolId: [symbolId]
+	})).message.symbol ?? [];
+	if (symbols.length === 0) throw new CTraderError("SYMBOL_NOT_FOUND", `No symbol with id ${String(symbolId)} on this account`);
+	return symbols[0];
+}
+/**
+* The shared `accountId` selector for account-scoped tools. Optional at the
+* schema level (single-account convenience); `resolveAccount` enforces the
+* required-when-multiple rule at runtime so the model gets a helpful listing
+* instead of a bare validation error.
+*/
+const accountIdField = z.string().optional().describe("ctidTraderAccountId of the account to act on (from get_accounts). Optional when exactly one account is connected; REQUIRED when several are — this tool never defaults to an arbitrary account.");
+function registerTools(server, pool) {
+	const register = server.registerTool.bind(server);
+	register("get_accounts", {
+		description: "List the cTrader trading accounts connected for this agent. Returns each account's ctidTraderAccountId, live/demo flag, host, broker, and number. Use an accountId here as the `accountId` argument on the other tools.",
+		inputSchema: {}
+	}, () => {
+		return ok({
+			count: pool.size,
+			defaultAccountId: pool.soleAccountId,
+			accounts: [...pool.accounts.values()].map(describeAccount)
+		});
+	});
+	register("get_account_details", {
+		description: "Get balance and account details for a connected cTrader account. Balance is returned as a real currency figure (converted from wire units via moneyDigits). Pass `accountId` when several accounts are connected.",
+		inputSchema: { accountId: accountIdField }
+	}, async (args) => {
+		const resolved = resolveAccount(pool, args.accountId);
+		if (isToolError(resolved)) return resolved;
+		try {
+			const trader = (await pool.request(String(resolved.accountId), PayloadType.OA_TRADER_REQ, { ctidTraderAccountId: resolved.accountId })).message.trader ?? {};
+			const moneyDigits = trader.moneyDigits != null ? num(trader.moneyDigits) : 2;
+			return ok({
+				ctidTraderAccountId: str(trader.ctidTraderAccountId) || String(resolved.accountId),
+				balance: moneyToDecimal(num(trader.balance), moneyDigits),
+				balanceRaw: str(trader.balance) || "0",
+				moneyDigits,
+				depositAssetId: str(trader.depositAssetId) || null,
+				maxLeverage: trader.maxLeverage ?? null,
+				brokerName: trader.brokerName ?? null,
+				accountType: trader.accountType ?? null
+			});
+		} catch (err) {
+			return fail(err);
+		}
+	});
+	register("get_positions", {
+		description: "List open positions on a connected cTrader account, with entry price, volume, side, SL/TP, and swap. Pass `accountId` when several accounts are connected.",
+		inputSchema: { accountId: accountIdField }
+	}, async (args) => {
+		const resolved = resolveAccount(pool, args.accountId);
+		if (isToolError(resolved)) return resolved;
+		try {
+			const positions = (await pool.request(String(resolved.accountId), PayloadType.OA_RECONCILE_REQ, {
+				ctidTraderAccountId: resolved.accountId,
+				returnProtectionOrders: true
+			})).message.position ?? [];
+			return ok({
+				accountId: String(resolved.accountId),
+				positions: positions.map((p) => {
+					const td = p.tradeData ?? {};
+					return {
+						positionId: str(p.positionId),
+						symbolId: str(td.symbolId),
+						side: num(td.tradeSide) === TRADE_SIDE.SELL ? "SELL" : "BUY",
+						volume: str(td.volume) || "0",
+						entryPrice: p.price ?? null,
+						stopLoss: p.stopLoss ?? null,
+						takeProfit: p.takeProfit ?? null,
+						swap: str(p.swap) || null
+					};
+				})
+			});
+		} catch (err) {
+			return fail(err);
+		}
+	});
+	register("get_orders", {
+		description: "List pending (not-yet-filled) orders on a connected cTrader account, with type, side, volume, and trigger prices. Pass `accountId` when several accounts are connected.",
+		inputSchema: { accountId: accountIdField }
+	}, async (args) => {
+		const resolved = resolveAccount(pool, args.accountId);
+		if (isToolError(resolved)) return resolved;
+		try {
+			const orders = (await pool.request(String(resolved.accountId), PayloadType.OA_RECONCILE_REQ, {
+				ctidTraderAccountId: resolved.accountId,
+				returnProtectionOrders: true
+			})).message.order ?? [];
+			const typeName = (v) => v === ORDER_TYPE.LIMIT ? "LIMIT" : v === ORDER_TYPE.STOP ? "STOP" : v === ORDER_TYPE.MARKET ? "MARKET" : String(v);
+			return ok({
+				accountId: String(resolved.accountId),
+				orders: orders.map((o) => {
+					const td = o.tradeData ?? {};
+					return {
+						orderId: str(o.orderId),
+						symbolId: str(td.symbolId),
+						orderType: typeName(num(o.orderType)),
+						side: num(td.tradeSide) === TRADE_SIDE.SELL ? "SELL" : "BUY",
+						volume: str(td.volume) || "0",
+						limitPrice: o.limitPrice ?? null,
+						stopPrice: o.stopPrice ?? null,
+						stopLoss: o.stopLoss ?? null,
+						takeProfit: o.takeProfit ?? null
+					};
+				})
+			});
+		} catch (err) {
+			return fail(err);
+		}
+	});
+	register("get_symbols", {
+		description: "List tradable symbols on a connected cTrader account (symbol lists are per-account). Optionally filter by a name substring (case-insensitive, e.g. \"EURUSD\"). Returns symbolId + name — use symbolId on order and market-data tools. Pass `accountId` when several accounts are connected.",
+		inputSchema: {
+			accountId: accountIdField,
+			nameFilter: z.string().optional().describe("Case-insensitive substring to filter symbol names, e.g. \"EUR\"")
+		}
+	}, async (args) => {
+		const resolved = resolveAccount(pool, args.accountId);
+		if (isToolError(resolved)) return resolved;
+		try {
+			let symbols = (await pool.request(String(resolved.accountId), PayloadType.OA_SYMBOLS_LIST_REQ, {
+				ctidTraderAccountId: resolved.accountId,
+				includeArchivedSymbols: false
+			})).message.symbol ?? [];
+			if (args.nameFilter) {
+				const needle = args.nameFilter.toLowerCase();
+				symbols = symbols.filter((s) => str(s.symbolName).toLowerCase().includes(needle));
+			}
+			return ok({
+				accountId: String(resolved.accountId),
+				count: symbols.length,
+				symbols: symbols.map((s) => ({
+					symbolId: str(s.symbolId),
+					name: s.symbolName ?? null,
+					enabled: Boolean(s.enabled),
+					description: s.description ?? null
+				}))
+			});
+		} catch (err) {
+			return fail(err);
+		}
+	});
+	register("get_market_data", {
+		description: "Get recent OHLC candles (trendbars) for a symbol on a connected cTrader account. Specify symbolId (from get_symbols), a period, and how many bars. Prices are returned as real decimal prices. Pass `accountId` when several accounts are connected.",
+		inputSchema: {
+			accountId: accountIdField,
+			symbolId: z.number().int().positive().describe("The symbol id from get_symbols"),
+			period: z.enum(Object.keys(TRENDBAR_PERIOD)).default("H1").describe("Candle period: M1, M5, M15, M30, H1, H4, D1, W1, MN1, etc."),
+			count: z.number().int().min(1).max(1e3).default(50).describe("Number of most-recent bars to return (1-1000)")
+		}
+	}, async (args) => {
+		const resolved = resolveAccount(pool, args.accountId);
+		if (isToolError(resolved)) return resolved;
+		try {
+			const period = TRENDBAR_PERIOD[args.period];
+			const bars = (await pool.request(String(resolved.accountId), PayloadType.OA_GET_TRENDBARS_REQ, {
+				ctidTraderAccountId: resolved.accountId,
+				symbolId: args.symbolId,
+				period,
+				count: args.count
+			})).message.trendbar ?? [];
+			return ok({
+				accountId: String(resolved.accountId),
+				symbolId: String(args.symbolId),
+				period: args.period,
+				bars: bars.map((b) => decodeTrendbar(b))
+			});
+		} catch (err) {
+			return fail(err);
+		}
+	});
+	register("place_order", {
+		description: "Place a MARKET or LIMIT order on a connected cTrader account. Volume is in LOTS and is converted to the symbol's protocol volume (validated against min/max/step). For LIMIT you must pass limitPrice. SL/TP are absolute prices. Pass `accountId` when several accounts are connected. WARNING: on a live account this moves real money.",
+		inputSchema: {
+			accountId: accountIdField,
+			symbolId: z.number().int().positive().describe("Symbol id from get_symbols"),
+			side: z.enum(["BUY", "SELL"]).describe("Trade side"),
+			orderType: z.enum(["MARKET", "LIMIT"]).default("MARKET").describe("MARKET fills now; LIMIT rests at limitPrice"),
+			volumeLots: z.number().positive().describe("Order size in lots (e.g. 0.1). Converted to protocol volume via the symbol lotSize."),
+			limitPrice: z.number().positive().optional().describe("Required for LIMIT orders — the price to rest the order at"),
+			stopLoss: z.number().positive().optional().describe("Absolute stop-loss price"),
+			takeProfit: z.number().positive().optional().describe("Absolute take-profit price"),
+			label: z.string().optional().describe("Optional client label for the order")
+		}
+	}, async (args) => {
+		const resolved = resolveAccount(pool, args.accountId);
+		if (isToolError(resolved)) return resolved;
+		const accountId = String(resolved.accountId);
+		try {
+			if (args.orderType === "LIMIT" && args.limitPrice == null) return fail(new CTraderError("LIMIT_PRICE_REQUIRED", "LIMIT orders require limitPrice"));
+			const symbol = await getSymbolDetail(pool, accountId, resolved.accountId, args.symbolId);
+			const lotSize = num(symbol.lotSize);
+			if (lotSize <= 0) return fail(new CTraderError("SYMBOL_NO_LOTSIZE", `Symbol ${String(args.symbolId)} has no lotSize; cannot size the order`));
+			const volume = lotsToVolume(args.volumeLots, lotSize);
+			const volErr = validateVolume(volume, num(symbol.minVolume), num(symbol.maxVolume), num(symbol.stepVolume));
+			if (volErr) return fail(new CTraderError("INVALID_VOLUME", volErr));
+			const payload = {
+				ctidTraderAccountId: resolved.accountId,
+				symbolId: args.symbolId,
+				orderType: ORDER_TYPE[args.orderType],
+				tradeSide: TRADE_SIDE[args.side],
+				volume
+			};
+			if (args.limitPrice != null) payload.limitPrice = args.limitPrice;
+			if (args.stopLoss != null) payload.stopLoss = args.stopLoss;
+			if (args.takeProfit != null) payload.takeProfit = args.takeProfit;
+			if (args.label != null) payload.label = args.label;
+			const { executionType, summary } = assertExecution(await pool.request(accountId, PayloadType.OA_NEW_ORDER_REQ, payload));
+			return ok({
+				accountId,
+				executionType,
+				volume,
+				volumeLots: volumeToLots(volume, lotSize),
+				execution: summary
+			});
+		} catch (err) {
+			return fail(err);
+		}
+	});
+	register("modify_order", {
+		description: "Modify an existing order on a connected cTrader account. For a PENDING order (by orderId) you can change limitPrice/stopPrice/SL/TP. For an OPEN position's protection, pass positionId to set stopLoss/takeProfit. Provide exactly one of orderId or positionId. Pass `accountId` when several accounts are connected.",
+		inputSchema: {
+			accountId: accountIdField,
+			orderId: z.number().int().positive().optional().describe("Pending order id (from get_orders) to amend"),
+			positionId: z.number().int().positive().optional().describe("Open position id (from get_positions) to set SL/TP on"),
+			limitPrice: z.number().positive().optional().describe("New limit price (pending order only)"),
+			stopPrice: z.number().positive().optional().describe("New stop price (pending order only)"),
+			stopLoss: z.number().positive().optional().describe("New absolute stop-loss price"),
+			takeProfit: z.number().positive().optional().describe("New absolute take-profit price")
+		}
+	}, async (args) => {
+		const resolved = resolveAccount(pool, args.accountId);
+		if (isToolError(resolved)) return resolved;
+		const accountId = String(resolved.accountId);
+		try {
+			if (args.orderId == null === (args.positionId == null)) return fail(new CTraderError("INVALID_TARGET", "Provide exactly one of orderId or positionId"));
+			if (args.positionId != null) {
+				const payload = {
+					ctidTraderAccountId: resolved.accountId,
+					positionId: args.positionId
+				};
+				if (args.stopLoss != null) payload.stopLoss = args.stopLoss;
+				if (args.takeProfit != null) payload.takeProfit = args.takeProfit;
+				const { executionType, summary } = assertExecution(await pool.request(accountId, PayloadType.OA_AMEND_POSITION_SLTP_REQ, payload));
+				return ok({
+					accountId,
+					executionType,
+					positionId: String(args.positionId),
+					execution: summary
+				});
+			}
+			const payload = {
+				ctidTraderAccountId: resolved.accountId,
+				orderId: args.orderId
+			};
+			if (args.limitPrice != null) payload.limitPrice = args.limitPrice;
+			if (args.stopPrice != null) payload.stopPrice = args.stopPrice;
+			if (args.stopLoss != null) payload.stopLoss = args.stopLoss;
+			if (args.takeProfit != null) payload.takeProfit = args.takeProfit;
+			const { executionType, summary } = assertExecution(await pool.request(accountId, PayloadType.OA_AMEND_ORDER_REQ, payload));
+			return ok({
+				accountId,
+				executionType,
+				orderId: String(args.orderId),
+				execution: summary
+			});
+		} catch (err) {
+			return fail(err);
+		}
+	});
+	register("close_position", {
+		description: "Close an open position (fully or partially) on a connected cTrader account. Pass the positionId from get_positions. volumeLots defaults to the full position size when omitted. Pass `accountId` when several accounts are connected.",
+		inputSchema: {
+			accountId: accountIdField,
+			positionId: z.number().int().positive().describe("Position id from get_positions"),
+			volumeLots: z.number().positive().optional().describe("Lots to close; omit to close the whole position")
+		}
+	}, async (args) => {
+		const resolved = resolveAccount(pool, args.accountId);
+		if (isToolError(resolved)) return resolved;
+		const accountId = String(resolved.accountId);
+		try {
+			const pos = ((await pool.request(accountId, PayloadType.OA_RECONCILE_REQ, {
+				ctidTraderAccountId: resolved.accountId,
+				returnProtectionOrders: true
+			})).message.position ?? []).find((p) => str(p.positionId) === String(args.positionId));
+			if (!pos) return fail(new CTraderError("POSITION_NOT_FOUND", `No open position ${String(args.positionId)}`));
+			const td = pos.tradeData ?? {};
+			const fullVolume = num(td.volume);
+			let volume = fullVolume;
+			if (args.volumeLots != null) {
+				const symbol = await getSymbolDetail(pool, accountId, resolved.accountId, num(td.symbolId));
+				volume = lotsToVolume(args.volumeLots, num(symbol.lotSize));
+				if (volume > fullVolume) return fail(new CTraderError("VOLUME_EXCEEDS_POSITION", `Requested ${String(volume)} exceeds position volume ${String(fullVolume)}`));
+			}
+			const { executionType, summary } = assertExecution(await pool.request(accountId, PayloadType.OA_CLOSE_POSITION_REQ, {
+				ctidTraderAccountId: resolved.accountId,
+				positionId: args.positionId,
+				volume
+			}));
+			return ok({
+				accountId,
+				executionType,
+				positionId: String(args.positionId),
+				volume,
+				execution: summary
+			});
+		} catch (err) {
+			return fail(err);
+		}
+	});
+	register("cancel_order", {
+		description: "Cancel a pending (not-yet-filled) order on a connected cTrader account. Pass the orderId from get_orders. Pass `accountId` when several accounts are connected.",
+		inputSchema: {
+			accountId: accountIdField,
+			orderId: z.number().int().positive().describe("Pending order id from get_orders")
+		}
+	}, async (args) => {
+		const resolved = resolveAccount(pool, args.accountId);
+		if (isToolError(resolved)) return resolved;
+		const accountId = String(resolved.accountId);
+		try {
+			const { executionType, summary } = assertExecution(await pool.request(accountId, PayloadType.OA_CANCEL_ORDER_REQ, {
+				ctidTraderAccountId: resolved.accountId,
+				orderId: args.orderId
+			}), new Set([5]));
+			return ok({
+				accountId,
+				executionType,
+				orderId: String(args.orderId),
+				execution: summary
+			});
+		} catch (err) {
+			return fail(err);
+		}
+	});
+}
+/** Compact the ProtoOAExecutionEvent response into a stable summary. */
+function summariseExecution(message) {
+	const order = message.order;
+	const position = message.position;
+	const executionTypeCode = message.executionType != null ? num(message.executionType) : null;
+	return {
+		executionType: executionTypeCode != null ? EXECUTION_TYPE_NAME[executionTypeCode] ?? String(executionTypeCode) : null,
+		executionTypeCode,
+		orderId: str(order?.orderId) || null,
+		positionId: str(position?.positionId) || null,
+		executionPrice: order?.executionPrice ?? position?.price ?? null
+	};
+}
+/**
+* Turn a write-tool reply into a definite outcome. A cTrader order op is
+* expected to come back as a ProtoOAExecutionEvent (2126); anything else means
+* we can't confirm the write landed, and a rejection/cancel executionType means
+* it explicitly did NOT. In both cases we throw a CTraderError so the tool
+* result is an unambiguous error rather than a bare success — this is a money
+* path and must fail closed.
+*/
+function assertExecution(res, extraOkTypes = /* @__PURE__ */ new Set()) {
+	if (res.payloadType !== PayloadType.OA_EXECUTION_EVENT) throw new CTraderError("UNEXPECTED_EXECUTION_REPLY", `Expected an execution event (${String(PayloadType.OA_EXECUTION_EVENT)}) but got payloadType ${String(res.payloadType)}; cannot confirm the order`);
+	const summary = summariseExecution(res.message);
+	const code = res.message.executionType != null ? num(res.message.executionType) : null;
+	const executionType = typeof summary.executionType === "string" ? summary.executionType : "UNKNOWN";
+	if (code != null && FAILED_EXECUTION_TYPES.has(code) && !extraOkTypes.has(code)) throw new CTraderError(executionType, `cTrader returned a non-fill execution (${executionType})`, {
+		orderId: str(summary.orderId) || void 0,
+		positionId: str(summary.positionId) || void 0
+	});
+	return {
+		executionType,
+		summary
+	};
+}
+//#endregion
+//#region src/server.ts
+/**
+* cTrader MCP Server
+*
+* Standalone stdio MCP server wrapping the cTrader Open API (protobuf over a
+* persistent TLS socket, port 5035). Unlike the OpenClaw plugin packages this
+* is runtime-agnostic — it is spawned via `npx -y @alfe.ai/ctrader-mcp` from an
+* integration manifest and speaks MCP over stdio, so it runs under any runtime
+* that can spawn `npx`.
+*
+* Architecture:
+*   Agent runtime ←(stdio/MCP)→ this server ←(protobuf/TLS 5035)→ cTrader Open API
+*
+* ── Multi-account ──
+* Credentials are self-fetched at startup (the atlassian/google pattern):
+* `resolveConfig()` yields the agent's `{ apiKey, apiUrl }`, and
+* `AgentApiClient.getCTraderAccounts()` returns the full set of authorized
+* trading accounts on one OAuth grant — one shared `accessToken` +
+* SST-global `clientId`/`clientSecret`, with a per-account `ctidTraderAccountId`
+* and `host` (live vs demo). We build an account registry and drive a
+* `CTraderPool` that opens one authenticated socket per distinct host and
+* routes each tool call to the account it names (see client.ts). No account is
+* ever chosen implicitly when several are connected — the tools require an
+* explicit `accountId` in that case.
+*/
+function log(msg) {
+	process.stderr.write(`[ctrader-mcp] ${msg}\n`);
+}
+async function main() {
+	const { apiKey, apiUrl } = resolveConfig();
+	const apiClient = new AgentApiClient({
+		apiKey,
+		apiUrl
+	});
+	let registry;
+	try {
+		registry = buildRegistry(await apiClient.getCTraderAccounts());
+	} catch (err) {
+		if (err instanceof ConfigError) log(`No usable cTrader connection: ${err.message}`);
+		else log(`Failed to resolve cTrader accounts: ${err instanceof Error ? err.message : String(err)}`);
+		process.exit(1);
+	}
+	const pool = new CTraderPool(registry);
+	const server = new McpServer({
+		name: "ctrader-mcp-server",
+		version: "0.0.1"
+	});
+	registerTools(server, pool);
+	const shutdown = () => {
+		pool.close();
+		process.exit(0);
+	};
+	for (const signal of ["SIGTERM", "SIGINT"]) process.on(signal, shutdown);
+	const transport = new StdioServerTransport();
+	await server.connect(transport);
+	const hosts = [...new Set([...registry.values()].map((c) => c.host))].join(", ");
+	log(`cTrader MCP server running (${String(registry.size)} account(s) across host(s): ${hosts}) with full-trading tools`);
+}
+main().catch((err) => {
+	log(`Fatal: ${err instanceof Error ? err.message : String(err)}`);
+	process.exit(1);
+});
+//#endregion
+export {};