ctrader-mcp-servers

重大な注意点トップ5（概要）

監査日時点で、以下の5つの注意点は特に重大です。検出／回避策／修正確認／削除基準の詳細は references/known-quirks.md に記載されています。以下の行はリンク先の概要のみです。名前付きの復旧パターンについては、references/self-healing-playbook.md も参照してください。

注意点	サーバー	概要	リンク
Q-R10	リモート	amend_position でポジションの一部を省略すると、その部分は保持されず削除されます	Q-R10
Q-R4	リモート	MARKET では絶対値の SL／TP は拒否されます。relativeStopLoss／relativeTakeProfit（単一呼び出し）、または P-REMOTE-MARKET-2STEP（代替手段）を使用してください	Q-R4
Q-R1	リモート	period の列挙値は9個であり、26個ではありません（細分化された値に関する記述は削除してください）	Q-R1
Q-L2	ローカル	非対称な get_pending_orders では、SL は絶対価格、TP は生の pips 値です	Q-L2
Q-K19	両方	ピペットと表示値の取り違えに注意してください。市場注文が通知なしで約定します	Q-K19

自己修復の原則

ctrader-remote-mcp と ctrader-local-mcp はどちらも、そのままの状態で提供されています。文書化されたランタイム動作は、rest-proxy 1.0.18（Remote）および 2026-05-14 に確認されたローカルビルド（Local）を対象に、2026-05-14 に再検証されています。Remote の既知の挙動のうち、6 件が 1.0.18 で引き続き有効です（Q-R1、Q-R2、Q-R3、Q-R5、Q-R8、Q-R10）。2 件の既知の挙動では、エラーメッセージ形式が改良されました（Q-R4 と Q-R7 は、JSON エンベロープの代わりに、実行可能なヒントを含むプレーン文字列のエラーエンベロープを返すようになりました。どちらも DETECT 署名は両方の形式に対応しています）。1 件の既知の挙動は修正された可能性があります（Q-R11 — get_deals の反映遅延 — 5 セッション中 1 セッション目で修正確認に合格しました。あと 4 回確認するまで、削除は保留されています）。このスキルでは、セマンティクス、注意点、復旧方法を説明します。形状の正とする情報源は MCP JSON-Schema です。このスキル内でスキーマの内容を重複させないでください。このスキルでランタイム動作について述べる際は、すべてビルド時点を示してください。参照ファイルの as-of: ヘッダー、または references/known-quirks.md の既知の挙動に記載された Observed-on: 行のいずれかを使用します。

台帳に記載された既知の挙動には、すべて自己解消の仕組みがあります。エージェントが実行できるセッション内チェックである Verify-fixed プローブと、サーバーが修正され、エントリーを削除すべきことを示す明示的なシグナルである Removal criteria 条件を備えています。サーバーが修正されたら、references/known-quirks.md から該当するエントリーを削除してください。必要なクリーンアップはこれだけです。任意の追加作業として、参照ファイル全体で古い QUIRK の痕跡を grep し、削除できます。

サーバーの予期しない動作（MCP JSON-Schema と台帳の両方から逸脱する動作）が発生した場合、即興で対応せず、references/self-healing-playbook.md に従ってください。このプレイブックでは、実行前チェック（クォートの妥当性、売買方向、SL/TP の側、ボリュームのステップ、スキーマフィールドのみを使用、ピペットと表示値の判別、必須フィールド）、実行後の検証ルール（変更のたびに再読み込みすること。Remote の amend_position では、Q-R10 に従って SL と TP の両方が維持されたことを確認するため、必ず再読み込みすること）、エラー分類マトリックス（Zod / INVALID_REQUEST / 502 uProxy / Local のプレーンテキスト / available:false / truncated / hasMore）、未知の既知の挙動に対する判断ツリー（STOP から暫定的な台帳エントリーまでの 4 ステップ）、および名前付きパターン（P-AMEND-SAFE、P-REMOTE-MARKET-RELATIVE（MARKET+SL/TP で推奨）、P-REMOTE-MARKET-2STEP（MARKET で絶対価格の SL/TP を使う場合のフォールバック）、P-REMOTE-MARKET-RANGE、P-LOCAL-OLDEST-FIRST、P-REMOTE-HISTORY-CHUNK）が説明されています。

ブローカー別オーバーレイの拡張ポイント

このスキルの既知の挙動の台帳では、将来的なブローカー別オーバーライド（lotSize の相違、シンボル命名のバリエーション、ブローカー固有の SL/TP の動作）用に、Q-B<n> プレフィックスを予約しています。将来の assets/broker_overrides.example.json オーバーレイを使えば、このスキルの構成を変更せずに、ブローカーごとの値を保持できます。今回のイテレーションでは提供していません — ブローカー固有の相違が、対応を阻む種類の問題になった場合に追加します。

ツールサーフェスのルーティング：ローカル HTTP（ctrader-local-mcp）とリモート HTTP（ctrader-remote-mcp）

バインドされているツールサーフェスによって、どちらの cTrader MCP サーバーが接続先かが決まります。ツール名とレスポンスの DTO 形式を確認して、どのファミリーかを特定してください。cTrader 関連のやり取りを始めるたびに、以下のルーティングルールを適用し、結果をセッション中は保持してください。

サーバーファミリー	検出用の指紋	得意な用途	デフォルトのルーティングルール
ローカル HTTP（ctrader-local-mcp）	ping、get_accounts_list、list_charts、listChartIndicators、listPlugins、show_notification、get_server_time。ボリュームの単位はユニット。日時は必須の Z を含む ISO 8601 形式。シンボルは文字列名（"EURUSD"）で識別。HTTP トランスポートは cTrader Desktop アプリケーションにバインドされています。	チャート、描画、インジケーター、ウォッチリスト、アラート、ニュース、cBot、UI 通知、複数アカウントでの作業。	UI／可視化／cBot／チャートに関連するワークフローでは、こちらにルーティングしてください。
リモート HTTP（ctrader-remote-mcp）	get_version、get_assets、整数の symbolId をキーとするツール（get_spot_prices(symbolId)、get_trendbars(symbolId)）。金額レスポンスに moneyDigits フィールドがあります。ボリュームの単位はセント（FX の 1 ロット = 10 000 000）。価格の単位はピペットです。HTTP トランスポートはリモート REST プロキシ（rest-proxy）を介します。	ヘッドレス取引、幅広いシンボルのスキャン、トレーリングストップロス、MARKET_RANGE、細分化された時間足の履歴。	チャート／UI が不要な場合は、こちらにルーティングしてください。
両方のサーフェスがバインドされている場合	両方の指紋が確認できます。	アクションによって異なります。	機能に応じて選択してください。描画／cBot／チャートはローカルへ、トレーリング SL／MARKET_RANGE／複数シンボルの一括気配値／細分化された時間足はリモートへルーティングしてください。

2 つのサーバー間での単位の規則

2 つのサーバーでは同じ取引の概念が異なる単位と識別子の型でエンコードされます。Local の値を Remote に渡す（またはその逆を行う）と、サイズや価格が誤った値になるか、スキーマによって拒否されます。

項目	Local HTTP のエンコード	Remote HTTP のエンコード	変換スクリプト
取引量	単位（整数。外国為替では通常 1 ロット = 100 000 単位ですが、ブローカーによって異なります。必ず get_symbol_details.lotSize を読み取ってください）。	セント（整数。外国為替の 1 ロット = 10 000 000 セント）。	scripts/units_encoding.py lots-to-units / lots-to-cents
価格	表示値（例：1.21345）。	ピペット（整数。表示するには 10^pipDigits で割ります）。	scripts/pip_math.py（両方向に対応）
金額（残高、手数料、スワップ、損益）	表示値（例：12345.67）。	10^moneyDigits 単位の整数（レスポンスの moneyDigits フィールドで指定。通常は 2）。	scripts/units_encoding.py display-money / parse-money
タイムスタンプ	Z サフィックス必須の ISO 8601 形式（2026-01-15T14:30:00Z）。	expirationTimestamp はエポックミリ秒（rest-proxy 1.0.13 以降は整数のみ）。履歴ウィンドウのエンドポイントはどちらの形式でも指定できます。	Local では変更せずに渡します。Remote ではフィールドの型を確認してください。
銘柄識別子	文字列名（"EURUSD"、"XAUUSD"）。	整数の symbolId（get_symbols で解決し、セッション中はキャッシュします）。	該当なし（ID で検索）
place_*_order / amend_order の損切り / 利食い	ピップ距離の整数（stopLossPips、takeProfitPips）。	絶対価格（stopLoss、takeProfit）。	scripts/pip_math.py pips-to-price / price-to-pips

ストップロスとテイクプロフィット：ピップ距離と絶対価格

注文発注ツールでは SL / TP をエントリー価格からのピップ距離で指定し、ポジション変更ツールでは SL / TP を絶対価格で指定します。この規約は、どのサーバーかではなく、どのツールを呼び出すかによって決まります。

ツール	サーバー	SL / TP の形式
place_market_order, place_limit_order, place_stop_order, place_stop_limit_order	ローカル	ピップ距離（stopLossPips、takeProfitPips）。
amend_order（保留中の注文）	ローカル	ピップ距離（stopLossPips、takeProfitPips）。
amend_position（オープンポジション）	ローカル	絶対価格（stopLoss、takeProfit）。
create_order	リモート	絶対価格（stopLoss、takeProfit）。MARKET 注文の SL / TP が拒否されるケース（P-REMOTE-MARKET-2STEP）については、references/remote-http-server.md を参照してください。
amend_order	リモート	絶対価格（stopLoss、takeProfit）。
amend_position	リモート	絶対価格（stopLoss、takeProfit）。
close_position	両方	該当なし（SL / TP パラメーターなし）。

ユーザーが「エントリー価格より30ピップ下にSL」と指定した場合は、scripts/pip_math.py を実行して、対象のツールが必要とする形式に変換します。入力：--pip-size <float> --digits <int> --reference-price <float> --pips <int>。出力：{"absolute_price": <float>, "pip_size_used": <float>}。このスクリプトは両方向に対応します。

ダイナミックレバレッジの証拠金計算

ブローカーはダイナミックレバレッジの階層を適用します。エクスポージャーが階層の上限を超えて増加すると、レバレッジは低下します。必要証拠金は階層ごとに計算し、合算します。階層のエクスポージャー量は、取引する銘柄にかかわらずUSDで示されます。その後、算出された証拠金（USD）は口座通貨に換算されます。

例。 口座通貨は USD。注文：EURUSD を 1 000 000 単位、1.21345 でロング。USD 建ての想定元本 = 1 000 000 × 1.21345 = 1 213 450 USD。レバレッジ階層：1 000 000 USD までは 1:500、1 000 000～5 000 000 USD は 1:200、5 000 000 USD 超は 1:100。証拠金 = (1 000 000 / 500) + (213 450 / 200) = 2 000 + 1 067.25 = 3 067.25 USD。

任意の階層カーブについて計算するには、scripts/tiered_margin.py compute を実行します。入力：--volume-base-units <int> --quote-rate-usd <float> --tiers '[{"upper":1000000,"leverage":500},{"upper":5000000,"leverage":200},{"upper":null,"leverage":100}]'。出力：{"margin_usd": <float>, "per_tier_breakdown": [...]}。USD 建ての証拠金は、scripts/conversion_rate.py compute-chain を使って口座通貨に換算します。

通貨換算：決済通貨と口座通貨

銘柄の決済通貨が口座通貨と異なる場合、サーバーから返されるすべての金額（手数料、スワップ、実現損益、ピップ値、証拠金）の換算には、スポットレートの連鎖が必要です。連鎖の例：EUR 口座での USDJPY の損益には、JPY -> USD -> EUR（USDJPY と EURUSD を使用）が必要です。NZD 口座での AUDCAD の損益には、CAD -> USD -> NZD、または AUD -> NZD の直接的な連鎖が必要です。cTrader バックエンドは利用可能な最短の連鎖を構築します。scripts/conversion_rate.py を使って、ローカルで同じロジックを再現してください。

レートを算出するには、scripts/conversion_rate.py compute-chain を実行します。入力：--from-asset <CCY> --to-asset <CCY> --quotes '{"EURUSD":1.0850,"USDJPY":150.3,...}'。出力：{"rate": <float>, "chain": ["EURUSD","USDJPY",...], "warnings": [...]}。Local では get_spot_prices を使って（1 回の呼び出しにつき 1 銘柄）、Remote では get_spot_prices(symbolId:[...]) を使って（一括取得）、あらかじめクオートマップを取得してください。

ヘッジ口座とネッティング口座

ヘッジ口座では、同じ銘柄でロングとショートのポジションを同時に保有でき（それぞれに独自の positionId が付与されます）、ネッティング口座ではポジションが統合されます。反対方向のポジションを建てると、既存のポジションが自動的に決済（または一部決済）され、差し引きのポジションになります。ヘッジの 2 本目のポジションを発注する前に、既存のポジションと口座のヘッジモード（get_balance および口座情報のレスポンスで確認できます）を読み取ってください。口座がネッティング方式の場合、「ヘッジを建てる」ことはできません。その旨をユーザーに伝え、代わりにストップロスの調整または全決済を提案してください。

ストップアウトと証拠金維持率

証拠金維持率（equity / used margin × 100%）がストップアウト水準（一般的に 50% または 30%、ブローカーが設定）以下になると、ブローカーはポジションを強制決済します。ポリシーには fair（最も多くの証拠金を消費している単一のポジションを決済）と smart（証拠金維持率をストップアウト水準より上に戻すために必要な最小限のポジションを決済）の 2 種類があります。追加リスクの規模を決める前に、現在の有効証拠金と使用中の証拠金を読み取ってください。(equity − required_new_margin) / used_margin_after_open × 100% がストップアウト水準の 2 倍を下回る場合は、続行する前にユーザーに警告してください。

スワップの計上タイミング

スワップ（オーバーナイト金利）は、ブローカーのサーバー時間におけるロールオーバー時（一般的にはサーバー時間の 23:59:59）に計上されます。多くのブローカーでは水曜日にスワップが 3 倍になります（T+2 の外国為替商品では、水曜日から木曜日へのロールオーバーに週末の受渡日が含まれるためです）。保有期間中のスワップを予測する場合は、期間内に水曜日があれば 3 倍してください。スワップと手数料の値は get_positions および get_deals のレスポンスから直接読み取ってください（サーバー側で計算済みです）。レート表から再計算しないでください。

組み合わせ可能なトレーダーのワークフロー

エンドツーエンドのトレーダーワークフローが7つ、references/trader-workflows.md に手順ごとに記載されています。W0（セッションの初期化）はセッション開始時に1回自動実行され、W1～W6はユーザーの意図に応じたトリガーによって実行されます。ユーザーのリクエストがいずれかのトリガーに該当する場合は、references/trader-workflows.md を読み、該当する手順に従ってください。ゼロから独自に手順を組み立てないでください。

0. W0 — セッションの初期化 — セッション開始時に自動実行されます。サーバーファミリーを特定し、稼働中のビルドを確認し、assets/symbol_precision_table.json からシンボルの精度の基準値をキャッシュし、アクティブなアカウントを特定して、冪等性キーのプレフィックスを設定します。ユーザーによるトリガーは不要です。
1. リスク率に基づくポジションサイジング — ユーザーが「買い／売りはいくらにすればよいか」「ストップロスをNピップスにした場合のサイズ」「この取引で口座のX%をリスクにさらす」など、リスク割合とストップロスの距離を組み合わせた質問をした場合に、この手順を選択します。
2. 取引前のブリーフィング — ユーザーが「Xを取引すべきか」「エントリー前にXの状況を教えて」「今のXはどんな状況か」と尋ねた場合や、銘柄詳細、価格、直近の履歴をまとめて尋ねた場合に、この手順を選択します。
3. 取引コストの比較 — ユーザーが「AとBではどちらの取引コストが安いか」「銘柄間のスプレッド／手数料／スワップを比較して」と尋ねた場合や、取引可能な銘柄をコスト順に並べるよう求めた場合に、この手順を選択します。
4. リスク／リワードを注釈して取引を発注し、可視化する — ユーザーが「取引を発注してチャートに表示して」「EURUSDにリスクリワードを描画して」と依頼し、Local HTTP サーバーがバインドされている場合に、この手順を選択します（このワークフローでは描画機能が必要です）。
5. 複数ウィンドウにわたる過去データの取得 — ユーザーが1回の get_trendbars 呼び出しで取得できる本数を超えるバーを求めた場合に、この手順を選択します（Local の上限は1000本です）。たとえば、「XAUUSDのH1ローソク足を5000本取得して」「過去1年分のD1を表示して」などです。
6. 安全な全ポジションのクローズ — ユーザーが「すべて決済して」「注文をすべてキャンセルして」「ポジションをすべて解消して」など、1つ以上の銘柄について保留中の注文とオープンポジションを一括でクローズするよう求めた場合に、この手順を選択します。

サーバー固有のリファレンスファイル

バインドされたツール群に Local HTTP ツール（ping、get_accounts_list、list_charts、listChartIndicators、listPlugins、show_notification、get_server_time）が含まれている場合は、Local の機能マップ、エンコーディング規則、ページネーションの上限、識別子の型、アクティブなチャートの指定、描画オブジェクトに必要なアンカー、破壊的操作のチェックリストについて、references/local-http-server.md を読んでください。

バインドされたツール群に Remote HTTP ツール（get_version、get_assets、整数の symbolId をキーとするツール、レスポンス内の moneyDigits）が含まれている場合は、Remote の機能マップ、エンコーディング規則、9種類の値を持つ period 列挙型、サーバー側の検証、timeInForce のセマンティクス、dealStatus 列挙型、get_symbols のキャッシュ運用ルールについて、references/remote-http-server.md を読んでください。

両方のツール群がバインドされている場合は、両方のファイルを読んでください。

同梱スクリプト

複雑な計算は scripts/ にあります。計算が単一の乗算または加算を超える場合は、必ずスクリプトを実行してください。各スクリプトは CLI フラグのみを受け付ける（対話形式ではない）もので、JSON を stdout に出力し、診断情報を stderr に出力します。また、--help で使い方を確認できます。

スクリプト	目的	実行パターン	出力形式
scripts/pip_math.py	pip 距離と絶対価格を相互に変換します（表示値を対象とし、ピペットをデコードした後、両サーバーのエンコーディングに対応して動作します）。	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	pip 値と建値通貨から口座通貨への換算を考慮し、リスク率またはリスク額の目標値から注文サイズを計算します。	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	cTrader の段階的レバレッジにおける証拠金計算式を、段階的なカーブに沿って再現します。	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	2 つの通貨間を換算する、最短のスポットレートの連鎖を構築します。	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	表示ロットと各サーバーの通信エンコーディング（units / cents）を相互に変換し、表示上の金額と moneyDigits の整数値を相互に変換します。	python scripts/units_encoding.py lots-to-cents --lots 0.1 --lot-size 100000	{"cents": 1000000}

注文後の検証ループ

変更を伴う呼び出し（place_*_order、create_order、amend_order、amend_position、close_position、cancel_order）の後は、対象のエンティティ（get_positions、get_pending_orders、または get_position_details）を再取得し、数量、売買方向、約定価格（約定の場合）、SL、TP、および dealStatus がユーザーの指定した意図と一致することを確認してください。値に不一致がある場合は、不一致の種類を特定してください。

• エンコーディングエラー -> scripts/units_encoding.py または scripts/pip_math.py を再実行し、入力を修正して再試行してください。
• ブローカーによる拒否（dealStatus: REJECTED ／ INTERNALLY_REJECTED ／ ERROR）-> サーバーの応答にある拒否理由をユーザーに伝え、処理を中止してください。

呼び出しが例外なく返されたからといって、注文が約定したと見なしてはいけません。