QUOTEZ

エージェントのための市場データ。設定ではなく、設計によって読み取り専用。

MetaTrader 5の市場データを、LLMエージェントが呼び出せる型付きの読み取り専用ツールとして公開するMCPサーバーです。Python 3.11以降、ランタイム依存関係は1つ、stdioトランスポートを使用。バッジは3.13で止まっていますが、これは分類子がそこまでだからです。CIは3.14のレグもアドバイザリとして実行しており、3.14が十分に安定して「期待」ではなく「約束」になったところでバッジに加わります。

エージェントは、与えられたツールの質に左右されます。市場データでは、ずさんなツールが実際の損害を引き起こします。モデルはツールが返したものをそのまま事実として受け止めるため、単位もタイムゾーンも出所もないペイロードは、誰かが行動を起こすかもしれない価格についての自信に満ちた文章になります。QUOTEZは、テキストの塊ではなく生成された出力スキーマで応答し、UTCを標準とし、すべてのペイロードにsyntheticフラグを付け、コード内に書き込みパスはありません。

これは、損害を起こせないように構築された1つのツールです。これは、エージェント全体がツールを信頼できるかどうかという大きな問題よりも、より小さく、検証可能な問いです。その大きな問題はQUELLZが扱います。

範囲と制限

• 読み取り専用：order_send、order_check、symbol_select、その他いかなる書き込みもありません。

• ライブMetaTraderデータにはWindowsと実行中のターミナルが必要です。ホイールはwin_amd64のみです。

• デフォルトのソースは生成されたデータを再生し、すべてのペイロードにsynthetic: trueとラベル付けします。

• 時刻はUTCで、各バーはその開始時点（間隔の左端）でラベル付けされます。

エージェントセッションの例

実際の出力であり、貼り付けではありません。uv run python examples/agent_session.pyで再生成してください。tests/test_readme.pyは、このブロックがそのコマンドの標準出力とバイト単位で一致することをアサートします。再生価格は生成されたものであり、いかなる市場から記録されたものではありません。

QUOTEZ over an in-memory MCP client, source=replay.
Every price below is generated. This repository bundles no real market data.

>>> list_symbols(group="*FX*")
{
  "source": "replay",
  "synthetic": true,
  "count": 2,
  "symbols": [
    {"name": "SYNTH_FX_ALPHA", "description": "Synthetic FX pair Alpha", "digits": 5, "point": 1e-05},
    {"name": "SYNTH_FX_BETA", "description": "Synthetic FX pair Beta", "digits": 3, "point": 0.001}
  ]
}

>>> get_quote(symbol="SYNTH_FX_ALPHA")
{
  "symbol": "SYNTH_FX_ALPHA",
  "time": "2026-06-12T13:59:00Z",
  "bid": 1.08044,
  "ask": 1.08056,
  "spread_points": 12,
  "source": "replay",
  "synthetic": true
}

>>> get_bars(symbol="SYNTH_FX_ALPHA", timeframe="H1", count=5)
{
  "symbol": "SYNTH_FX_ALPHA",
  "timeframe": "H1",
  "source": "replay",
  "synthetic": true,
  "count": 5,
  "bars": [
    {"time": "2026-06-12T08:00:00Z", "open": 1.07985, "high": 1.08231, "low": 1.07978, "close": 1.08125, "tick_volume": 4257, "spread": null},
    {"time": "2026-06-12T09:00:00Z", "open": 1.08125, "high": 1.0844, "low": 1.08113, "close": 1.08302, "tick_volume": 2501, "spread": null},
    {"time": "2026-06-12T10:00:00Z", "open": 1.08302, "high": 1.08439, "low": 1.08298, "close": 1.08368, "tick_volume": 1643, "spread": null},
    {"time": "2026-06-12T11:00:00Z", "open": 1.08368, "high": 1.08395, "low": 1.08036, "close": 1.08097, "tick_volume": 1570, "spread": null},
    {"time": "2026-06-12T12:00:00Z", "open": 1.08097, "high": 1.08284, "low": 1.08084, "close": 1.08159, "tick_volume": 2589, "spread": null}
  ]
}

>>> symbol_info(symbol="SYNTH_FX_ALPHA")
{
  "name": "SYNTH_FX_ALPHA",
  "description": "Synthetic FX pair Alpha",
  "digits": 5,
  "point": 1e-05,
  "spread": 12,
  "spread_float": true,
  "trade_stops_level": 10,
  "trade_freeze_level": 0,
  "trade_tick_value": 1.0,
  "trade_tick_size": 1e-05,
  "trade_contract_size": 100000.0,
  "volume_min": 0.01,
  "volume_max": 100.0,
  "volume_step": 0.01,
  "currency_base": "SYA",
  "currency_profit": "SYN",
  "currency_margin": "SYA",
  "source": "replay",
  "synthetic": true
}

A symbol that does not exist, to show what the model actually sees:

>>> get_quote(symbol="NOT_A_SYMBOL")
is_error: true
Error executing tool get_quote: Symbol 'NOT_A_SYMBOL' is not available on this server.

クイックスタート

1つのコマンド、設定不要、MetaTraderのインストールも不要：

uvx --from git+https://github.com/PNX89/QUOTEZ quotez --source replay

QUOTEZはPyPIに公開されていないため、git形式がインストール方法です。@main、タグ、またはコミットを追加して参照を固定します（uvの依存関係ドキュメント参照）。その後、ハングしているように見えます。これは、標準出力がJSON-RPCのワイヤであり、ホストがそれを駆動するためです。ホストなしで動作を確認するには、リポジトリをクローンしてサンプルセッションを実行します。これは、インプロセスクライアントから同じサーバーを駆動します：

git clone https://github.com/PNX89/QUOTEZ && cd QUOTEZ
uv run python examples/agent_session.py

Windowsで、すでに実行中でログイン済みのターミナルに対して：

uvx --from "quotez[mt5] @ git+https://github.com/PNX89/QUOTEZ" quotez --source mt5

コンソールスクリプトはフラグを受け取る唯一のエントリポイントであり、フラグは環境変数より優先されます。mcp run src/quotez/server.pyも、モジュールレベルのmcpグローバルを通じてこのサーバーを提供しますが、何も転送しないため、そのパスは変数を読み取ります。

ホストに接続する

ホスト間で設定キーが一致しておらず、mcpServersとserversを間違えることが、サーバーが表示されない一般的な原因です。

{
  "mcpServers": {
    "quotez": {
      "command": "/absolute/path/to/uv",
      "args": ["tool", "run", "--from", "git+https://github.com/PNX89/QUOTEZ",
               "quotez", "--source", "replay"]
    }
  }
}

commandはwhich uvの絶対パスでなければなりません。 ホストはほぼ空のPATHでサーバーを起動するため、ベアのuvはサーバーが静かに接続に失敗する最も一般的な理由です。

ツール

8つのツールがこの順序で登録されています。これはtools/listが返す順序であり、クライアントはそのリストをキャッシュするため、順序は意図的に固定されています。1つのリソースsymbols://listが、application/jsonと同じ計測器ユニバースを提供します。

list_symbolsは、独自の構文を発明するのではなく、MetaTrader独自のグループフィルター構文を受け取ります：パターンの先頭と末尾での*ワイルドカード、カンマ区切りの条件、否定のための!。包含は除外の前に来なければならないため、"*, !*USD*"はUSD計測器以外のすべて、"!*USD*, *"はすべてに一致します。Mt5Sourceは文字列をsymbols_getに渡します。再生ソースは同じ構文をquotez.groupsで実行するため、両方ともフィルターに対して同じように応答します。

すべてのツールはPydanticモデルを返すため、SDKは戻り値のアノテーションからoutputSchemaを導出し、structuredContentを埋め、サーバーから送信される前にペイロードを検証します。BaseModelはラップされずに使用されるため、get_barsは{"result": ...}ではなく、barsキーを持つオブジェクトを返します。

仕組み

flowchart LR
    host["MCP host<br/>Claude Desktop, Cursor, VS Code"]
    server["quotez.server<br/>8 tools, 1 resource"]
    proto["MarketDataSource<br/>Protocol"]
    replay["ReplaySource<br/>bundled CSVs, any OS"]
    mt5["Mt5Source<br/>Windows only, lazy import"]
    term["MetaTrader 5 terminal"]
    host -- "JSON-RPC over stdio" --> server
    server --> proto
    proto --> replay
    proto --> mt5
    mt5 -- "read calls only" --> term

MarketDataSourceは、サーバー全体が書かれている継ぎ目です。その上にあるものはMetaTrader5をインポートせず、Mt5Sourceはモジュールインポート時ではなく、ファーストユース時にプライベートヘルパー内で拡張機能を解決するため、import quotezはホイールが存在しない場所でも動作します。これにより、ReplaySourceがモックではなく第一級の実装となる理由です。ツール層は両者を区別できないため、スイート全体がターミナルをインストールせずに実際のコードパスを実行します。

バンドルデータは、4つの生成された計測器（SYNTH_FX_ALPHA、SYNTH_FX_BETA、SYNTH_IDX_GAMMA、SYNTH_MTL_DELTA）、それぞれ3600のM1バー、2026-06-01から2026-06-12までの平日08:00から14:00 UTC、その中に9回のセッション中断（8回は夜間、1回は週末をまたぐ）を含みます。ギャップのないシリーズは集計バグを隠すからです。scripts/generate_replay_data.pyは、シードされたrandom.Randomからファイルを一度生成し、出力はコミットされています。CSVはimportlib.resourcesを通じて読み取られ、Path(__file__).parentは使用されません。後者はチェックアウトでは動作しますが、uvxが実行するzipインストールでは壊れます。

ツールとリソースは同じものではない

ツールはモデルが呼び出すことを決定するものです。リソースはアプリケーションがロードすることを決定するものです。get_barsはモデル駆動型です。推論の途中でシンボル、タイムフレーム、カウントを選択します。symbols://listはアプリケーション駆動型です。ホストはモデルが何かを決定する前に、一度だけユニバースをコンテキストに固定します。そのため、これはlist_symbolsの偶発的な重複ではありません。list_symbolsはモデルが意図的に実行するフィルタリング検索です。

明らかな次のリソースであるbars://{symbol}/{timeframe}は意図的に構築されていません。同じデータに対してget_barsを複製するものであり、プレースホルダー付きのURIはリソーステンプレートとなり、resources/listをresources/templates/listに分離し、多くのホストでうまく表示されないか、まったく表示されません。テストでは、リソーステンプレートが登録されていないことをアサートします。

タイムフレーム集計

再生ソースは1つのベースタイムフレームであるM1を保存し、quotez.aggregateがM5、M15、M30、H1、H4、D1をロールアップします。1つの保存コピー、1つのロールアップ、単独でテスト可能。これは、その障害モードが静かであるため重要です。間違った集計は、永遠に妥当な数値を返し、決してエラーを発生させません。

MetaTraderソースは何もロールアップしません。ターミナルはすでにすべての期間を保持しているため、直接タイムフレームが要求されます。M1から再導出すると遅くなり、オペレーターが開いているチャートと一致しなくなります。したがって、2つのソースは、D1、H4、およびspreadについて、同じ呼び出しに対してわずかに異なる回答を返します。これは「制限事項」で説明されており、ユーザーが発見するために残されているわけではありません。

ロールアップの不変条件（それぞれがテスト名です）：

1. M1 が唯一の基本時間枠です。それより粗いものはすべて派生です。

2. バケットは壁時計であり、エポック秒の床除算によって計算され、N 行ごとに位置的にグループ化されることはありません。

3. ターゲットは 60 秒の整数倍です。それ以外は InvalidRequest を発生させます。

4. OHLC は、最初の始値、最大高値、最小安値、最後の終値です。

5. tick_volume は合計されます。spread は合計されません。これはクォートの時点のプロパティであるため、集約されたバーは null を報告します。

6. バーは UTC で左端のラベルが付けられます。

7. 不完全な末尾のバケットは、部分的なバーとして出力されるのではなく、ドロップされます。バケットは、そのバケットの終了時点以降のバーが入力に含まれている場合にのみ出力されます。

8. 空の入力は空のリストを返します。

不変条件 2 はテストによって正当性が証明されます。位置的なグループ化は、ギャップのない系列では壁時計のバケットと一致しますが、穴がある瞬間に不一致が生じます。360 バーのセッションを 4 つずつグループ化すると、金曜日の終値と月曜日の始値が 1 つのバーに入り、4 時間足と呼ばれます。不変条件 7 はそのペアです。セッションの終了はデータが尽きることと同じイベントではないからです。

安全性の設計

この主張は構造的なものであり、設定可能なものではありません。このコードベースには書き込みパスはありません。 src/quotez/ のどこにも order_send、order_check、symbol_select、MarketWatch の変更、ファイルの書き込みはありません。書き込みを有効にする設定はありません。有効にするものがないからです。

2 つのテストがそれを維持しており、2 つ目のテストが意味のあるものです。1 つ目は、パッケージ内でそれら 3 つの MetaTrader 呼び出しを grep します。これは安価で、すべてのファイルをカバーし、実行時に組み立てられた名前によって満たされます。2 つ目は mt5source.py の AST をウォークし、代わりに肯定的なプロパティをアサートします。つまり、このパッケージがターミナルモジュールから読み取る属性のセットは、独自の docstring で名前が付けられた読み取り呼び出しと 7 つの時間枠定数だけであり、getattr を介して到達されるものや、2 番目の変数に再バインドされるものはありません。_mt5() は MetaTrader5 モジュール全体を返すため、数百の属性のうち 3 つの名前がないだけでは、それ自体ではほとんど証明になりません。5 つの意図的に壊されたスニペットがそのウォークに対してチェックされているため、ウォーク自体は失敗すべきときに失敗することがわかっています。

すべてのツールは ToolAnnotations(read_only_hint=True, open_world_hint=False) で宣言されています。その宣言はクライアントに対する礼儀に過ぎません。MCP 仕様は、信頼できるサーバーからのものでない限り、クライアントはツールアノテーションを信頼されていないものとして扱うよう指示しています。read_only_hint=True はツールを説明するものであり、クライアントを制約するものではなく、レビュー担当者が確認できるプロパティは、フラグの存在ではなく、呼び出しの欠如です。仕様自身の ツールのセキュリティに関する考慮事項 にマッピングされ、このサーバーが満たさない要件も含みます。

ブロックされたシンボルは、タイプミスが受けるメッセージ「シンボル 'X' はこのサーバーでは利用できません。」とともに SymbolNotFound として報告されます。明確な「許可されていません」は、オペレーターが公開しないことを選択したインストゥルメントのディスカバリーオラクルにホワイトリストを変えてしまいます。

エラーは 2 つのチャネルのいずれかを取ります。よりスマートなモデルが失敗を回避できたかどうかによって選択されます。スペルミスのシンボルは回避できた可能性があるため、SymbolNotFound と InvalidRequest は通常の例外であり、モデルが読み取って再試行できるツールエラーになります。実行されていないターミナルは回避できなかったため、SourceUnavailable は MCPError、つまり結果がまったくないプロトコルエラーとして発生します。ここではエラー文字列は返されません。返される文字列は is_error=False を保持し、成功した回答として読み取られます。テストはすべてのツールを不正な入力で呼び出し、フラグをアサートします。

設計上の決定

mcp>=2.0.0,<3 と MCPServer、v1 ピンと FastMCP ではありません。 SDK はまだ移行していない人のために mcp>=1.28,<2 を提供していますが、v1 時代のサーバーは 3 秒でそれとわかります。from mcp.server.fastmcp import FastMCP。 移行ガイド に名前の変更があります。低レベルの Server は代替手段でしたが、戻り値を自動ラップしなくなったため、8 つのツールに対して JSON スキーマを手書きすることを意味しました。

型付けされた Pydantic の戻り値、テキストブロブではありません。 ほとんどの公開 MCP サーバーは散文を返し、モデルに解析を任せます。ここでは戻り値のアノテーションが出力スキーマであるため、型付けはコストがかからず、ペイロードがサーバーを離れる前に検証を購入します。

2 つのバーツール、オプションの引数を持つ 1 つではありません。 JSON スキーマは相互排他性を表現できないため、単一の get_bars(count or start..end) は「これらのいずれか、ただし両方ではない」という制約を散文としてモデルに押し付けることになります。2 つのツールは 2 つの完全に有効なスキーマを持ち、「両方指定、どちらも指定なし」のエラークラスは存在しなくなります。

生成されたデータ、実際のフィードではありません。 ライセンス上の決定であり、好みではありません。MetaTrader のエクスポートはブローカーのライセンス供与されたフィードであり、インデックスおよび株式 CFD の場合、原資産は取引所のライセンス供与を受けています。Yahoo のヘルプページは制限を明確に述べており、Yahoo Finance に表示または提供される情報を再配布してはなりません。また、その デベロッパー API 利用規約 は、アクセスの販売またはサブライセンスを個別に制限しています。HistData の FAQ は再配布権を一切付与しておらず、データは保証なしで提供されることのみを述べており、沈黙はライセンスではありません。それらのいずれかを MIT リポジトリにコミットすることは、再ライセンスする権利のないデータを再ライセンスすることになります。

標準ライブラリ、pandas や numpy ではありません。 バンドルされた CSV スケールでは、csv と datetime とデータクラスで十分であり、ツリーは監査可能なままです。ただし、そのツリーは正直に名前を付ける価値があります。mcp 2.x は 1 つの直接依存関係であり、anyio、httpx2、jsonschema、mcp-types、opentelemetry-api、pydantic、pyjwt（crypto エクストラ付き）、python-multipart、sse-starlette、starlette、typing-extensions、typing-inspection、uvicorn、さらに Windows では pywin32 を引き込みます。crypto エクストラは、背後に cryptography、cffi、pycparser をもたらします。これは v1 よりも大きなフットプリントであり、テストはコミットされた uv.lock を読み取り、このリストがそれと一致しなくなった場合に失敗します。これはツリーに名前を付けるために存在する段落が、ツリーの大部分に名前を付けなければ何の価値もないからです。

run_backtest ツールはありません。 バックテストは計算量が無制限であり、MarketDataSource よりもはるかに多くのものを必要とし、QUACKZ を複製することになります。そのため、このペアは 2 つの焦点を絞ったプロジェクトではなく、2 つの半プロジェクトとして読まれることになります。同じ理由で、ここでのガードレールはドメインローカルです。入力検証、制限付きクエリ、固定されたインストゥルメントユニバース、副作用なし。一般的なエージェントガードレールは QUELLZ に属し、5 回再発明されるべきではありません。

制限事項

• ライブの MetaTrader パスを実行する継続的インテグレーションランナーはありません、どこにも。非 Windows ホイールはなく、ターミナルやブローカーアカウントを持つランナーもありません。Windows ジョブは、拡張機能がインポートされることと、Mt5Source が欠落したターミナルを正常に報告することを証明し、それだけです。Mt5Source のフィールドマッピングは、ここで最もテストされていないコードであり、フェイクモジュールテストでカバーされています。

• MetaTrader5 は Windows 専用であり、ソース配布を公開していないため、pip install quotez[mt5] は macOS と Linux では設計上何も行いません。テストは、環境マーカーがその状態を維持することをアサートします。

• initialize() は、ターミナルがまだ実行されていない場合に起動し、操作全体はその timeout 引数によって制限され、デフォルトは 60000 ミリ秒と文書化されています。ページは起動自体の数値を示していないため、60 秒を測定された起動時間としてではなく、呼び出しの上限として扱ってください。QUOTEZ は、サーバーの有効期間中に 1 回接続を開くのであって、呼び出しごとではないため、そのコストは、最初のツール呼び出しをハングさせているように見せる代わりに、起動時に発生します。

• 2 つのソースは、D1 または H4 バケットがどこから始まるかについて一致しません。 リプレイロールアップはエポック秒で床除算されるため、D1 は UTC 00:00 に、H4 は UTC 00、04、08、12、16、20 に開きます。MetaTrader ターミナルは、D1 と H4 をブローカーのサーバー日に合わせます。これは通常 UTC+2 または UTC+3 です。そのため、同じ get_bars(symbol, "D1") は、設定されたソースに応じて、異なる開始時間と異なる OHLC を持つローソク足を返します。ここでは、オペレーター自身のチャートと一致しないバーは、文書化されたオフセットよりも悪いため、ターミナルの M1 をリサンプリングしてそれを隠すことはしません。

• 同じ理由で、spread は M1 より上のすべてのリプレイバーでは null であり、すべての MetaTrader バーでは設定されています。ロールアップは意図的にそれをクリアします。ターミナルはすべての時間枠で独自の値を報告し、QUOTEZ はソースが与えたデータを破棄するのではなく、それを通過させます。

• copy_rates_from_pos と copy_rates_range は、ターミナルの「チャートの最大バー数」設定によって暗黙的に制限されるため、サーバー自身の上限内のリクエストでも、まだ短く返ってくることがあり、MetaTrader API のどこにもそのことは書かれていません。

• get_bars はターミナルがまだ構築中のバーをスキップするため、その最新のバーは常に確定しています。get_bars_range はそうではありません。境界は呼び出し元のものであり、現在の間隔内の end はその間隔の部分的なバーを返します。

• symbol_info() は不明なシンボルに対して None を返します。エラー時に symbols_get() も同様です。ここではすべての呼び出しサイトでチェックしていますが、それがラップされている API の形状です。

• MetaTrader はバーとティックの時間を UTC でシフトなしで保存しますが、ナイーブな Python datetime はローカルゾーンに対して解決します。copy_rates_range のドキュメント はそのように述べています。すべての送信タイムスタンプは tz=UTC で構築され、ナイーブな入力は拒否されますが、これが系列全体を 1 時間静かにシフトさせる罠です。

• レート制限はありません。stdio サーバーは 1 つのホストの子プロセスであり、ホストがそれを所有します。

• リプレイデータはサンプル規模で生成されています。4 つのインストゥルメント、3600 の M1 バー、10 取引日。ツールをデモンストレーションし、集約を実行しますが、研究データセットでもマーケットでもありません。

• バージョン 0.1.0 は読み取り専用かつ stdio のみであり、プロンプト機能、SSE やストリーミング可能な HTTP トランスポート、OAuth はありません。

なぜこれを構築したのか

私はインデックスデータでウォークフォワード分析を実行し、FXと金属の部分についてはMetaTraderターミナルを常備しているため、この両方の要素はすでに私のデスクにありました。これを書くきっかけとなったのは、エージェントが型の不適切なツールから数字を取得し、単位もタイムゾーンも出典も示さずにあたかも事実であるかのように言い換えるのを目撃したことです。市場データにおいてこれは表面的な問題ではありません。終値でラベル付けされたバーではなく始値だったり、タイムスタンプが気付かれずにローカルタイムに変換されたりすると、一見正しく見える答えが1時間ずれてしまいます。そのため、これは主にデータの出所とツールが主張できる内容に関する決定であり、その周りに小さな集計コードをラップしたものです。

Development

uv sync --dev
uv run pytest
uv run ruff check .
uv run ruff format --check .
uv run mypy

251テスト、ネットワーク不要、数秒で処理完了、macOS、Linux、Windowsで同一の結果。この数値は実際のコレクション実行に基づいて主張されています。なぜなら、READMEに書かれた数字は誰も更新しないからです。

License

MIT。 LICENSE を参照。

Q...Zツールセットの一部。自らを告知しない障害に対する5つのツール：

• QUACKZ — 200のうちから選ばれたために良く見えるだけのバックテストをデフレートします。

• QUOTEZ（本ツール） — エージェントが読めるが行動できない市場データ。

• QUELLZ — プロンプトインジェクションの封じ込めがユーティリティと攻撃率の両方に与えるコストを測定します。

• QUIDZ — 二重に送金されそうになった送金を拒否します。

• QUESTZ — スクレイパーが形状の変わったページからCSVを書き出す前に停止します。