@alfe.ai/ctrader-mcp 0.1.0

package/package.json

@@ -0,0 +1,48 @@
+{
+  "name": "@alfe.ai/ctrader-mcp",
+  "version": "0.1.0",
+  "description": "cTrader MCP server — full trading (place/modify/close orders + read) over the cTrader Open API (protobuf/TLS)",
+  "type": "module",
+  "main": "./dist/server.js",
+  "bin": {
+    "ctrader-mcp-server": "./dist/server.js"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/server.d.ts",
+      "import": "./dist/server.js"
+    }
+  },
+  "files": [
+    "dist",
+    "proto"
+  ],
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.29.0",
+    "protobufjs": "^8.7.0",
+    "zod": "^4.0.5",
+    "@alfe.ai/agent-api-client": "0.10.0",
+    "@alfe.ai/config": "0.3.0"
+  },
+  "license": "UNLICENSED",
+  "homepage": "https://alfe.ai",
+  "author": "Alfe (https://alfe.ai)",
+  "keywords": [
+    "alfe",
+    "ai-agents",
+    "agent",
+    "llm",
+    "mcp",
+    "model-context-protocol",
+    "ctrader",
+    "trading",
+    "forex"
+  ],
+  "scripts": {
+    "build": "tsdown",
+    "dev": "tsdown --watch",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "lint": "eslint ."
+  }
+}

package/proto/ctrader.proto

@@ -0,0 +1,447 @@
+syntax = "proto2";
+
+// Minimal, self-contained subset of Spotware's cTrader Open API protobuf
+// schema — only the messages and enums this MCP server sends or receives.
+//
+// Field numbers, message names and enum values are transcribed verbatim from
+// Spotware's official proto files (github.com/spotware/openapi-proto-messages,
+// files OpenApiCommonMessages.proto, OpenApiCommonModelMessages.proto,
+// OpenApiMessages.proto, OpenApiModelMessages.proto). Payload-type numbers are
+// carried in the ProtoMessage envelope, not encoded here, so this file omits
+// the giant ProtoOAPayloadType enum; the numbers live in payload-types.ts.
+//
+// We keep this vendored (rather than pulling the full upstream .proto tree)
+// so the published tarball has no dependency on an external, unpinned schema
+// and only carries the surface we actually use.
+
+package ctrader;
+
+// ── Envelope (OpenApiCommonMessages.proto) ──────────────────────────────
+
+message ProtoMessage {
+  required uint32 payloadType = 1;
+  optional bytes  payload     = 2;
+  optional string clientMsgId = 3;
+}
+
+// Common-layer error (payloadType 50). Framing / connection-level errors.
+message ProtoErrorRes {
+  optional uint32 payloadType   = 1;
+  required string errorCode     = 2;
+  optional string description   = 3;
+  optional int64  maintenanceEndTimestamp = 4;
+}
+
+// Heartbeat (payloadType 51). Keep-alive; no fields beyond payloadType.
+message ProtoHeartbeatEvent {
+  optional uint32 payloadType = 1;
+}
+
+// ── Enums (OpenApiModelMessages.proto) ──────────────────────────────────
+
+enum ProtoOAOrderType {
+  MARKET = 1;
+  LIMIT = 2;
+  STOP = 3;
+  STOP_LOSS_TAKE_PROFIT = 4;
+  MARKET_RANGE = 5;
+  STOP_LIMIT = 6;
+}
+
+enum ProtoOATradeSide {
+  BUY = 1;
+  SELL = 2;
+}
+
+enum ProtoOATrendbarPeriod {
+  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;
+}
+
+// ── OA-layer error (payloadType 2142) ───────────────────────────────────
+
+message ProtoOAErrorRes {
+  optional uint32 payloadType         = 1;
+  optional int64  ctidTraderAccountId = 2;
+  required string errorCode           = 3;
+  optional string description         = 4;
+  optional int64  maintenanceEndTimestamp = 5;
+}
+
+// ── Auth handshake ──────────────────────────────────────────────────────
+
+message ProtoOAApplicationAuthReq {
+  optional uint32 payloadType  = 1;
+  required string clientId     = 2;
+  required string clientSecret = 3;
+}
+
+message ProtoOAApplicationAuthRes {
+  optional uint32 payloadType = 1;
+}
+
+message ProtoOAAccountAuthReq {
+  optional uint32 payloadType         = 1;
+  required int64  ctidTraderAccountId = 2;
+  required string accessToken         = 3;
+}
+
+message ProtoOAAccountAuthRes {
+  optional uint32 payloadType         = 1;
+  required int64  ctidTraderAccountId = 2;
+}
+
+// ── Accounts list ───────────────────────────────────────────────────────
+
+message ProtoOAGetAccountListByAccessTokenReq {
+  optional uint32 payloadType = 1;
+  required string accessToken = 2;
+}
+
+message ProtoOACtidTraderAccount {
+  required uint64 ctidTraderAccountId = 1;
+  optional bool   isLive              = 2;
+  optional uint64 traderLogin         = 3;
+  optional int64  lastClosingDealTimestamp = 4;
+  optional int64  lastBalanceUpdateTimestamp = 5;
+  optional string brokerTitleShort    = 6;
+}
+
+message ProtoOAGetAccountListByAccessTokenRes {
+  optional uint32 payloadType                       = 1;
+  required string accessToken                       = 2;
+  repeated ProtoOACtidTraderAccount ctidTraderAccount = 3;
+  optional bool   permissionScope                   = 4;
+}
+
+// ── Trader (balance / account details) ──────────────────────────────────
+
+message ProtoOATraderReq {
+  optional uint32 payloadType         = 1;
+  required int64  ctidTraderAccountId = 2;
+}
+
+message ProtoOATrader {
+  required int64  ctidTraderAccountId  = 1;
+  required int64  balance              = 2;
+  optional int64  balanceVersion       = 3;
+  optional int64  managerBonus         = 4;
+  optional int64  ibBonus              = 5;
+  optional int64  nonWithdrawableBonus = 6;
+  optional int64  accessRights         = 7;
+  required int64  depositAssetId       = 8;
+  optional bool   swapFree             = 9;
+  optional uint32 leverageInCents      = 10;
+  optional uint32 totalMarginCalculationType = 11;
+  optional uint32 maxLeverage          = 12;
+  optional bool   frenchRisk           = 13;
+  optional int64  traderLogin          = 14;
+  optional uint32 accountType          = 15;
+  optional string brokerName           = 16;
+  optional int64  registrationTimestamp = 17;
+  optional bool   isLimitedRisk        = 18;
+  optional uint32 limitedRiskMarginCalculationStrategy = 19;
+  optional uint32 moneyDigits          = 20;
+  optional int64  fairStopOut          = 21;
+}
+
+message ProtoOATraderRes {
+  optional uint32       payloadType = 1;
+  required ProtoOATrader trader     = 2;
+}
+
+// ── Reconcile (open positions + pending orders) ─────────────────────────
+
+message ProtoOATradeData {
+  required int64            symbolId  = 1;
+  required int64            volume    = 2;
+  required ProtoOATradeSide tradeSide = 3;
+  optional int64            openTimestamp = 4;
+  optional string           label     = 5;
+  optional bool             guaranteedStopLoss = 6;
+  optional string           comment   = 7;
+  optional double           measurementUnits = 8;
+}
+
+message ProtoOAPosition {
+  required int64            positionId    = 1;
+  required ProtoOATradeData tradeData     = 2;
+  required uint32           positionStatus = 3;
+  required int64            swap          = 4;
+  optional double           price         = 5;
+  optional double           stopLoss      = 6;
+  optional double           takeProfit    = 7;
+  optional int64            utcLastUpdateTimestamp = 8;
+  optional int64            commission    = 9;
+  optional double           marginRate    = 10;
+  optional int64            mirroringCommission = 11;
+  optional bool             guaranteedStopLoss = 12;
+  optional int64            usedMargin    = 13;
+  optional uint32           stopLossTriggerMethod = 14;
+  optional uint32           moneyDigits   = 15;
+  optional bool             trailingStopLoss = 16;
+}
+
+message ProtoOAOrder {
+  required int64            orderId       = 1;
+  required ProtoOATradeData tradeData     = 2;
+  required ProtoOAOrderType orderType     = 3;
+  required uint32           orderStatus   = 4;
+  optional int64            expirationTimestamp = 5;
+  optional double           executionPrice = 6;
+  optional int64            executedVolume = 7;
+  optional int64            utcLastUpdateTimestamp = 8;
+  optional double           baseSlippagePrice = 9;
+  optional int64            slippageInPoints = 10;
+  optional bool             closingOrder  = 11;
+  optional double           limitPrice    = 12;
+  optional double           stopPrice     = 13;
+  optional double           stopLoss      = 14;
+  optional double           takeProfit    = 15;
+  optional string           clientOrderId = 16;
+  optional uint32           timeInForce   = 17;
+  optional int64            positionId    = 18;
+  optional double           relativeStopLoss = 19;
+  optional double           relativeTakeProfit = 20;
+  optional bool             isStopOut     = 21;
+  optional bool             trailingStopLoss = 22;
+  optional uint32           stopTriggerMethod = 23;
+}
+
+message ProtoOAReconcileReq {
+  optional uint32 payloadType         = 1;
+  required int64  ctidTraderAccountId = 2;
+  optional bool   returnProtectionOrders = 3;
+}
+
+message ProtoOAReconcileRes {
+  optional uint32          payloadType         = 1;
+  required int64           ctidTraderAccountId = 2;
+  repeated ProtoOAPosition position            = 3;
+  repeated ProtoOAOrder    order               = 4;
+}
+
+// ── Symbols ─────────────────────────────────────────────────────────────
+
+message ProtoOALightSymbol {
+  required int64  symbolId    = 1;
+  optional string symbolName  = 2;
+  optional bool   enabled     = 3;
+  optional int64  baseAssetId = 4;
+  optional int64  quoteAssetId = 5;
+  optional int64  symbolCategoryId = 6;
+  optional string description = 7;
+}
+
+message ProtoOASymbolsListReq {
+  optional uint32 payloadType             = 1;
+  required int64  ctidTraderAccountId     = 2;
+  optional bool   includeArchivedSymbols  = 3;
+}
+
+message ProtoOAArchivedSymbol {
+  required int64  symbolId    = 1;
+  required string name        = 2;
+  optional int64  utcLastUpdateTimestamp = 3;
+  optional string description = 4;
+}
+
+message ProtoOASymbolsListRes {
+  optional uint32             payloadType         = 1;
+  required int64              ctidTraderAccountId = 2;
+  repeated ProtoOALightSymbol symbol              = 3;
+  repeated ProtoOAArchivedSymbol archivedSymbol   = 4;
+}
+
+message ProtoOASymbol {
+  required int64  symbolId    = 1;
+  optional int64  digits      = 2;
+  optional int64  pipPosition = 3;
+  optional bool   enableShortSelling = 4;
+  optional bool   guaranteedStopLoss = 5;
+  optional uint32 swapRollover3Days  = 6;
+  optional bool   swapLong           = 7;
+  optional bool   swapShort          = 8;
+  optional int64  maxVolume          = 9;
+  optional int64  minVolume          = 10;
+  optional int64  stepVolume         = 11;
+  optional int64  maxExposure        = 12;
+  optional int64  lotSize            = 21;
+}
+
+message ProtoOASymbolByIdReq {
+  optional uint32 payloadType         = 1;
+  required int64  ctidTraderAccountId = 2;
+  repeated int64  symbolId            = 3;
+}
+
+message ProtoOASymbolByIdRes {
+  optional uint32        payloadType         = 1;
+  required int64         ctidTraderAccountId = 2;
+  repeated ProtoOASymbol symbol              = 3;
+  repeated ProtoOAArchivedSymbol archivedSymbol = 4;
+}
+
+// ── Trendbars (market data / candles) ───────────────────────────────────
+
+message ProtoOATrendbar {
+  optional uint32 volume              = 3;
+  optional ProtoOATrendbarPeriod period = 4;
+  optional int64  low                 = 5;
+  optional uint64 deltaOpen           = 6;
+  optional uint64 deltaClose          = 7;
+  optional uint64 deltaHigh           = 8;
+  optional uint32 utcTimestampInMinutes = 9;
+}
+
+message ProtoOAGetTrendbarsReq {
+  optional uint32                payloadType         = 1;
+  required int64                 ctidTraderAccountId = 2;
+  optional int64                 fromTimestamp       = 3;
+  optional int64                 toTimestamp         = 4;
+  required ProtoOATrendbarPeriod period              = 5;
+  required int64                 symbolId            = 6;
+  optional uint32                count               = 7;
+}
+
+message ProtoOAGetTrendbarsRes {
+  optional uint32          payloadType         = 1;
+  required int64           ctidTraderAccountId = 2;
+  required ProtoOATrendbarPeriod period        = 3;
+  optional int64           timestamp           = 4;
+  repeated ProtoOATrendbar trendbar            = 5;
+  optional int64           symbolId            = 6;
+}
+
+// ── Live spot subscription ──────────────────────────────────────────────
+
+message ProtoOASubscribeSpotsReq {
+  optional uint32 payloadType         = 1;
+  required int64  ctidTraderAccountId = 2;
+  repeated int64  symbolId            = 3;
+  optional bool   subscribeToSpotTimestamp = 4;
+}
+
+message ProtoOASubscribeSpotsRes {
+  optional uint32 payloadType         = 1;
+  required int64  ctidTraderAccountId = 2;
+}
+
+message ProtoOASpotEvent {
+  optional uint32 payloadType         = 1;
+  required int64  ctidTraderAccountId = 2;
+  required int64  symbolId            = 3;
+  optional uint64 bid                 = 4;
+  optional uint64 ask                 = 5;
+  repeated ProtoOATrendbar trendbar   = 6;
+  optional uint64 sessionClose        = 7;
+  optional int64  timestamp           = 8;
+}
+
+// ── Order mutations (all respond via ProtoOAExecutionEvent, 2126) ───────
+
+message ProtoOANewOrderReq {
+  optional uint32           payloadType         = 1;
+  required int64            ctidTraderAccountId = 2;
+  required int64            symbolId            = 3;
+  required ProtoOAOrderType orderType           = 4;
+  required ProtoOATradeSide tradeSide           = 5;
+  required int64            volume              = 6;
+  optional double           limitPrice          = 7;
+  optional double           stopPrice           = 8;
+  optional uint32           timeInForce         = 9;
+  optional int64            expirationTimestamp = 10;
+  optional double           stopLoss            = 11;
+  optional double           takeProfit          = 12;
+  optional string           comment             = 13;
+  optional double           baseSlippagePrice   = 14;
+  optional int32            slippageInPoints     = 15;
+  optional string           label               = 16;
+  optional int64            positionId          = 17;
+  optional string           clientOrderId       = 18;
+  optional int64            relativeStopLoss    = 19;
+  optional int64            relativeTakeProfit  = 20;
+  optional bool             guaranteedStopLoss  = 21;
+  optional bool             trailingStopLoss    = 22;
+  optional uint32           stopTriggerMethod   = 23;
+}
+
+message ProtoOAAmendOrderReq {
+  optional uint32 payloadType         = 1;
+  required int64  ctidTraderAccountId = 2;
+  required int64  orderId             = 3;
+  optional int64  volume              = 4;
+  optional double limitPrice          = 5;
+  optional double stopPrice           = 6;
+  optional int64  expirationTimestamp = 7;
+  optional double stopLoss            = 8;
+  optional double takeProfit          = 9;
+  optional int64  relativeStopLoss    = 10;
+  optional int64  relativeTakeProfit  = 11;
+  optional bool   guaranteedStopLoss  = 12;
+  optional bool   trailingStopLoss    = 13;
+  optional uint32 stopTriggerMethod   = 14;
+}
+
+message ProtoOAAmendPositionSLTPReq {
+  optional uint32 payloadType         = 1;
+  required int64  ctidTraderAccountId = 2;
+  required int64  positionId          = 3;
+  optional double stopLoss            = 4;
+  optional double takeProfit          = 5;
+  optional bool   guaranteedStopLoss  = 6;
+  optional double stopLossTriggerMethod = 7;
+  optional bool   trailingStopLoss    = 8;
+  optional double relativeStopLoss    = 9;
+  optional double relativeTakeProfit  = 10;
+}
+
+message ProtoOAClosePositionReq {
+  optional uint32 payloadType         = 1;
+  required int64  ctidTraderAccountId = 2;
+  required int64  positionId          = 3;
+  required int64  volume              = 4;
+}
+
+message ProtoOACancelOrderReq {
+  optional uint32 payloadType         = 1;
+  required int64  ctidTraderAccountId = 2;
+  required int64  orderId             = 3;
+}
+
+message ProtoOAExecutionEvent {
+  optional uint32          payloadType         = 1;
+  required int64           ctidTraderAccountId = 2;
+  required uint32          executionType       = 3;
+  optional ProtoOAPosition position            = 4;
+  optional ProtoOAOrder    order               = 5;
+  optional string          errorCode           = 8;
+  optional bool            isServerEvent       = 9;
+}
+
+// ── Order-error event (payloadType 2132) ────────────────────────────────
+//
+// Emitted when the broker rejects an order submission (bad price, out of
+// hours, insufficient margin, etc.). Field numbers/types transcribed from
+// Spotware's ProtoOAOrderErrorEvent (OpenApiMessages.proto). This is a REJECT
+// on a money path — it MUST map to a CTraderError, never resolve as success.
+message ProtoOAOrderErrorEvent {
+  optional uint32 payloadType         = 1;
+  required int64  ctidTraderAccountId = 2;
+  required string errorCode           = 3;
+  optional int64  orderId             = 4;
+  optional int64  positionId          = 5;
+  optional string description         = 6;
+}