القائمة
Use this skill ALWAYS when working with any cTrader MCP server.
التثبيت باستخدام Codex أو Claude انسخ هذا Prompt والصقه في Codex أو Claude أو مساعد آخر ليراجع صفحة Skill ويثبّتها لك.
استنادا إلى تصنيف SOC المهني
| name | ctrader-mcp-servers |
| description | Use this skill ALWAYS when working with any cTrader MCP server. |
| allowed-tools | Read, Grep, Glob, Bash(python *) |
| compatibility | Requires Python 3.12+ on PATH for the bundled scripts in scripts/. Scripts use the Python standard library only; no third-party packages are required. |
| license | Proprietary. LICENSE.txt has complete terms. |
| metadata | {"author":"Spotware Systems Ltd","quirks_registry_min_build_remote":"rest-proxy 1.0.18","quirks_registry_min_build_local":"local build observed-on 2026-05-14","last_full_audit_date":"2026-05-14"} |
The following 5 quirks are the most consequential as of the audit date. Full Detect / Workaround / Verify-fixed / Removal-criteria content lives in references/known-quirks.md; the rows below are link-only teasers. See also references/self-healing-playbook.md for the named recovery patterns.
| Quirk | Server | One-liner | Link |
|---|---|---|---|
| Q-R10 | remote | amend_position omitting a leg REMOVES it (not preserves it) | Q-R10 |
| Q-R4 | remote | MARKET REJECTS absolute SL/TP — use relativeStopLoss/relativeTakeProfit (single call) or P-REMOTE-MARKET-2STEP (fallback) | Q-R4 |
| Q-R1 | remote | period enum is 9 values, NOT 26 (delete granular claims) | Q-R1 |
| Q-L2 | local | SL is absolute price, TP is raw pips (asymmetric get_pending_orders) | Q-L2 |
| Q-K19 | both | Pipettes vs display foot-gun — silent market fills | Q-K19 |
Both ctrader-remote-mcp and ctrader-local-mcp ship as-is with documented runtime behaviors last re-verified on 2026-05-14 against rest-proxy 1.0.18 (Remote) and local build observed-on 2026-05-14 (Local). Six Remote quirks remain ACTIVE on 1.0.18 (Q-R1, Q-R2, Q-R3, Q-R5, Q-R8, Q-R10). Two quirks had their error-message format refined (Q-R4 and Q-R7 now return plain-string error envelopes with actionable hints instead of JSON envelopes — both DETECT signatures cover both formats). One quirk is likely fixed (Q-R11 — get_deals propagation lag — passed Verify-fixed on session 1 of 5; not yet removed pending 4 more confirmations). This skill describes SEMANTICS, GOTCHAS, and RECOVERY; the MCP JSON-Schema is the source of truth on SHAPE. Never duplicate schema content in this skill. Every claim about runtime behavior in this skill carries a build-stamp — either an as-of: header on a reference file, or an Observed-on: line on a quirk in references/known-quirks.md.
Every quirk in the ledger is self-deprecating: it carries a Verify-fixed probe (a session-local check the agent can run) and a Removal criteria condition (the explicit signal that the server has been fixed and the entry should be deleted). When the server is fixed, delete the matching entry from references/known-quirks.md — that is the entire cleanup cost. Optional follow-up: grep for any stale QUIRK breadcrumbs across the reference files and remove them.
On unexpected server behavior (anything deviating from BOTH the MCP JSON-Schema AND the ledger), do NOT improvise — follow references/self-healing-playbook.md. The playbook names the pre-flight gates (quote sanity, side-direction, SL/TP sidedness, volume-step, schema-fields-only, pipettes-vs-display detection, required-fields), the post-flight verification rules (re-read after every mutation; for Remote amend_position, always re-read to confirm BOTH SL and TP legs survived per Q-R10), the error-classification matrix (Zod / INVALID_REQUEST / 502 uProxy / plain-text Local / available:false / truncated / hasMore), the unknown-quirk decision tree (4 steps from STOP to provisional ledger entry), and the named patterns (P-AMEND-SAFE, P-REMOTE-MARKET-RELATIVE (preferred for MARKET+SL/TP), P-REMOTE-MARKET-2STEP (fallback for absolute-price SL/TP on MARKET), P-REMOTE-MARKET-RANGE, P-LOCAL-OLDEST-FIRST, P-REMOTE-HISTORY-CHUNK).
The skill's quirks ledger uses the Q-B<n> prefix as a reserved slot for future per-broker overrides (lotSize divergences, symbol-naming variants, broker-specific SL/TP behaviors). A future assets/broker_overrides.example.json overlay would carry these per-broker values without restructuring this skill. NOT shipped this iteration — added on demand when broker-specific divergences become a blocking class.
ctrader-local-mcp) vs Remote HTTP (ctrader-remote-mcp)The bound tool surface determines which cTrader MCP server is in front of you. Inspect tool names and response DTO shape to identify the family. Apply the routing rule below at the start of every cTrader-related interaction; cache the result for the session.
| Server family | Fingerprint to detect it | What it does best | Default routing rule |
|---|---|---|---|
Local HTTP (ctrader-local-mcp) | ping, get_accounts_list, list_charts, listChartIndicators, listPlugins, show_notification, get_server_time; volume in units; ISO 8601 with mandatory Z; symbol identified by string name ("EURUSD"). HTTP transport bound to the cTrader Desktop application. | Charts, drawings, indicators, watchlists, alerts, news, cBots, UI notifications, multi-account work. | Route here for any UI / visualization / cBot / chart-bound workflow. |
Remote HTTP (ctrader-remote-mcp) | get_version, get_assets, integer symbolId-keyed tools (get_spot_prices(symbolId), get_trendbars(symbolId)); moneyDigits field in money responses; volume in cents (1 lot of forex = 10 000 000); prices in pipettes. HTTP transport against the remote REST proxy (rest-proxy). | Headless trading, broad symbol scans, trailing stop loss, MARKET_RANGE, granular timeframe history. | Route here when no chart / UI need exists. |
| Both surfaces bound | Both fingerprints visible. | Depends on the action. | Pick by capability: drawings / cBots / charts go to Local; trailing SL / MARKET_RANGE / multi-symbol batch quotes / granular timeframes go to Remote. |
The two servers encode the same trading concepts in different units and identifier types; passing Local values to Remote (or the reverse) silently produces wrong sizes, wrong prices, or schema rejections.
| Dimension | Local HTTP encoding | Remote HTTP encoding | Conversion script |
|---|---|---|---|
| Volume | Units (integer; for forex typically 1 lot = 100 000 units, but broker-dependent — always read get_symbol_details.lotSize). | Cents (integer; 1 lot of forex = 10 000 000 cents). | scripts/units_encoding.py lots-to-units / lots-to-cents |
| Price | Display value (e.g., 1.21345). | Pipettes (integer; divide by 10^pipDigits to display). | scripts/pip_math.py (handles both directions) |
| Money (balance, commission, swap, P&L) | Display value (e.g., 12345.67). | Integer in 10^moneyDigits units (moneyDigits field on the response; typically 2). | scripts/units_encoding.py display-money / parse-money |
| Timestamp | ISO 8601 with mandatory Z suffix (2026-01-15T14:30:00Z). | Epoch milliseconds for expirationTimestamp (integer-only as of rest-proxy 1.0.13); either form for history window endpoints. | Passed through unchanged for Local; check field type for Remote. |
| Symbol identifier | String name ("EURUSD", "XAUUSD"). | Integer symbolId (resolve via get_symbols, cache for the session). | N/A (look up by ID) |
Stop loss / take profit on place_*_order / amend_order | Pip distance integer (stopLossPips, takeProfitPips). | Absolute price (stopLoss, takeProfit). | scripts/pip_math.py pips-to-price / price-to-pips |
Order-placement tools take SL / TP as pip distance from entry; position-amendment tools take SL / TP as absolute price. The convention depends on which TOOL is called, not which server.
| Tool | Server | SL / TP form |
|---|---|---|
place_market_order, place_limit_order, place_stop_order, place_stop_limit_order | Local | Pip distance (stopLossPips, takeProfitPips). |
amend_order (pending order) | Local | Pip distance (stopLossPips, takeProfitPips). |
amend_position (open position) | Local | Absolute price (stopLoss, takeProfit). |
create_order | Remote | Absolute price (stopLoss, takeProfit). See references/remote-http-server.md for MARKET-order SL/TP rejection (P-REMOTE-MARKET-2STEP). |
amend_order | Remote | Absolute price (stopLoss, takeProfit). |
amend_position | Remote | Absolute price (stopLoss, takeProfit). |
close_position | Both | N/A (no SL / TP parameter). |
When the user says "SL 30 pips below entry", convert to the form the target tool needs by running scripts/pip_math.py. Input: --pip-size <float> --digits <int> --reference-price <float> --pips <int>. Output: {"absolute_price": <float>, "pip_size_used": <float>}. The script handles both directions.
Brokers apply dynamic-leverage tiers: leverage falls as the exposure grows past tier upper bounds. Required margin is computed PER TIER and summed. Tier exposure volumes are stated in USD regardless of the traded symbol; the resulting margin in USD is then converted to the account currency.
Example. Account currency USD. Order: 1 000 000 EURUSD long @ 1.21345. Notional in USD = 1 000 000 × 1.21345 = 1 213 450 USD. Tier curve: 1:500 up to 1 000 000 USD, 1:200 from 1 000 000 to 5 000 000 USD, 1:100 above 5 000 000 USD. Margin = (1 000 000 / 500) + (213 450 / 200) = 2 000 + 1 067.25 = 3 067.25 USD.
Invoke scripts/tiered_margin.py compute to compute this for arbitrary tier curves. Input: --volume-base-units <int> --quote-rate-usd <float> --tiers '[{"upper":1000000,"leverage":500},{"upper":5000000,"leverage":200},{"upper":null,"leverage":100}]'. Output: {"margin_usd": <float>, "per_tier_breakdown": [...]}. Convert the USD margin to the account currency with scripts/conversion_rate.py compute-chain.
When a symbol's quote currency differs from the account currency, every money figure returned by the server (commission, swap, realized P&L, pip value, margin) requires conversion through a chain of spot rates. Example chains: P&L on USDJPY for a EUR account requires JPY -> USD -> EUR (using USDJPY and EURUSD); P&L on AUDCAD for an NZD account requires CAD -> USD -> NZD or a direct AUD -> NZD chain. The cTrader backend builds the shortest available chain; replicate that logic locally with scripts/conversion_rate.py.
Invoke scripts/conversion_rate.py compute-chain to derive the rate. Input: --from-asset <CCY> --to-asset <CCY> --quotes '{"EURUSD":1.0850,"USDJPY":150.3,...}'. Output: {"rate": <float>, "chain": ["EURUSD","USDJPY",...], "warnings": [...]}. Fetch the quote map up front via get_spot_prices for Local (one symbol per call) or get_spot_prices(symbolId:[...]) for Remote (batched).
Hedging accounts allow simultaneous long AND short positions on the same symbol (each gets its own positionId). Netting accounts collapse them: opening the opposite side automatically closes (or partially closes) the existing position to the net delta. Before placing the second leg of a hedge, read the existing position and the account's hedging mode (visible in get_balance and account-info responses); if the account is netting, "opening a hedge" is impossible — surface this to the user and propose either a stop-loss adjustment or a full close instead.
Brokers force-close positions when margin level = (equity / used margin) × 100% falls to or below the stop-out level (commonly 50% or 30%, broker-set). Two policies exist: fair (closes the single position consuming the most margin) and smart (closes the smallest set of positions sufficient to restore margin level above the stop-out). Before sizing additional risk, read current equity and used margin; if (equity − required_new_margin) / used_margin_after_open × 100% drops below 2× the stop-out level, warn the user before proceeding.
Swap (overnight financing) accrues at broker server time rollover (commonly 23:59:59 server time). Many brokers triple-charge swap on Wednesday (the Wed -> Thu rollover absorbs the weekend value date for T+2 instruments like forex). When projecting swap over a holding period, multiply by 3 for any Wednesday in the window. Read swap and commission values directly from get_positions and get_deals responses (they are server-computed); do not re-derive them from rate tables.
Seven end-to-end trader workflows are described step-by-step in references/trader-workflows.md. W0 (session bootstrap) auto-runs once at session start; W1–W6 are dispatched by user-intent triggers. When the user request matches any trigger, read references/trader-workflows.md and follow the corresponding recipe — do not improvise from scratch.
assets/symbol_precision_table.json, resolves active account, and sets the idempotency-key prefix. No user trigger needed.get_trendbars call returns (1000 cap on Local), e.g., "give me 5000 H1 candles of XAUUSD" or "show me the last year of D1".When the bound tool surface includes Local HTTP tools (ping, get_accounts_list, list_charts, listChartIndicators, listPlugins, show_notification, get_server_time), read references/local-http-server.md for the Local capability map, encoding rules, pagination caps, identifier types, active-chart targeting, drawing-object anchor requirements, and the destructive-operations checklist.
When the bound tool surface includes Remote HTTP tools (get_version, get_assets, integer symbolId-keyed tools, moneyDigits in responses), read references/remote-http-server.md for the Remote capability map, encoding rules, the 9-value period enum, server-side validations, timeInForce semantics, dealStatus enum, and the cache-discipline rules for get_symbols.
When both surfaces are bound, read both files.
Non-trivial computation lives in scripts/. Invoke a script whenever the math goes beyond a single multiplication or addition. Every script accepts CLI flags only (non-interactive), prints JSON to stdout, prints diagnostics to stderr, and documents itself via --help.
| Script | Purpose | Invocation pattern | Output shape |
|---|---|---|---|
scripts/pip_math.py | Convert between pip distance and absolute price (display values; operates on both servers' encoding once pipettes are decoded). | python scripts/pip_math.py pips-to-price --pip-size 0.0001 --digits 5 --reference-price 1.0850 --pips 30 | {"absolute_price": 1.08800, "pip_size_used": 0.0001} |
scripts/position_sizing.py | Compute order size from a risk-percent or risk-amount target, accounting for pip value and quote -> account-currency conversion. | python scripts/position_sizing.py from-risk-percent --balance 10000 --risk-pct 1 --sl-pips 30 --pip-value-per-lot 10 --conversion-rate 1.0 | {"units": 33333, "cents": 3333333, "risk_currency_amount": 100.0, "warnings": []} |
scripts/tiered_margin.py | Reproduce cTrader's dynamic-leverage margin formula across a tier curve. | python scripts/tiered_margin.py compute --volume-base-units 1000000 --quote-rate-usd 1.21345 --tiers '[{"upper":1000000,"leverage":500},{"upper":5000000,"leverage":200},{"upper":null,"leverage":100}]' | {"margin_usd": 3067.25, "per_tier_breakdown": [...]} |
scripts/conversion_rate.py | Build the shortest spot-rate chain to convert between two currencies. | python scripts/conversion_rate.py compute-chain --from-asset JPY --to-asset USD --quotes '{"USDJPY":150.3}' | {"rate": 0.006653, "chain": ["USDJPY"], "warnings": []} |
scripts/units_encoding.py | Convert between display lots and the wire encoding for each server (units / cents); convert between display money and moneyDigits integers. | python scripts/units_encoding.py lots-to-cents --lots 0.1 --lot-size 100000 | {"cents": 1000000} |
After any mutating call (place_*_order, create_order, amend_order, amend_position, close_position, cancel_order), re-fetch the affected entity (get_positions, get_pending_orders, or get_position_details) and verify that volume, side, entry price (for fills), SL, TP, and dealStatus match the user's stated intent. If any value mismatches, identify the mismatch class:
scripts/units_encoding.py or scripts/pip_math.py and retry with corrected inputs.dealStatus: REJECTED / INTERNALLY_REJECTED / ERROR) -> surface the rejection reason from the server response to the user and stop.Do not assume the order is filled just because the call returned without an exception.