spotware/ctrader-skills/ctrader-mcp-servers

Top-5 critical quirks (inline teaser)

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.

Self-healing principle

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).

Per-broker overlay extension point

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.

Tool-surface routing: Local HTTP (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.

Units conventions across the two servers

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.

Stop loss and take profit: pip distance vs absolute price

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.