QUOTEZ

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.

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

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

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

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

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

1. M1 是唯一的基础时间框架。所有更粗的时间粒度均由它派生。

2. 桶按挂钟时间计算，通过对纪元秒进行整除除法得到，绝不按位置对每 N 行进行分组。

3. 目标必须是 60 秒的整数倍。其他任何值都会引发 InvalidRequest。

4. OHLC 依次为：第一笔开盘价、最高价中的最大值、最低价中的最小值、最后一笔收盘价。

5. tick_volume 是求和值。spread 不是：它是报价的一个时间点属性，因此聚合后的 K 线报告 null。

6. K 线以其左边界标记，时间采用 UTC。

7. 不完整的尾部桶会被丢弃，不会作为部分 K 线发出。只有当输入包含该桶结束时间或之后的 K 线时，才会发出该桶。

8. 空输入返回空列表。

不变量 2 值得测试。位置分组与挂钟时间分桶在无间隙序列上结果一致，但一旦出现间隙就会产生分歧：将 360 根 K 线按每 4 根分组，会把周五的收盘价和周一的开盘价合并到一根 K 线中，并称之为四小时 K 线。不变量 7 与之配对，因为会话结束与数据耗尽不是同一事件。

安全设计

此声明是结构性的，不可配置。此代码库不包含任何写入路径。 在 src/quotez/ 中，没有 order_send、没有 order_check、没有 symbol_select、没有 MarketWatch 的修改，也没有任何文件写入。没有任何配置可以启用写入功能，因为根本没有任何东西可以启用。

有两个测试确保了这一点，其中第二个测试才是真正有意义的。第一个测试在包中搜索那三个 MetaTrader 调用：成本低廉，覆盖所有文件，并且可以通过运行时拼接的名称来满足。第二个测试遍历 mt5source.py 的 AST，并断言正向属性：此包从终端模块读取的属性集合，恰好是其自身文档字符串中命名的读取调用加上七个时间框架常量，没有通过 getattr 访问任何内容，也没有将任何内容重新绑定到第二个变量。_mt5() 返回整个 MetaTrader5 模块，因此仅凭数百个属性中缺少三个名称，其本身并不能证明什么。有五个故意破坏的代码片段会针对该遍历进行检查，以便在遍历本应失败时，我们能够确知它确实会失败。

每个工具都声明了 ToolAnnotations(read_only_hint=True, open_world_hint=False)。该声明仅是对客户端的礼貌提示，仅此而已：MCP 规范告诉客户端，除非工具注解来自受信任的服务器，否则应将其视为不可信。read_only_hint=True 描述的是工具本身，它并不约束客户端，审查者可以检查的属性是缺少相关调用，而不是存在该标志。映射到规范自身的安全注意事项，包括此服务器未满足的要求：

被阻止的符号会报告为 SymbolNotFound，并附带与拼写错误相同的消息：“Symbol 'X' is not available on this server.”。如果使用不同的“不允许”消息，则会将白名单变成操作员选择不公开的品种的发现预言机。

错误通过两个渠道之一传递，选择依据是更智能的模型是否本可以避免该失败。拼写错误的符号是可以避免的，因此 SymbolNotFound 和 InvalidRequest 是普通异常，会变成模型可以读取并重试的工具错误。而终端未运行则无法避免，因此 SourceUnavailable 会作为 MCPError 引发，这是一种协议错误，完全不返回任何结果。这里没有任何内容返回错误字符串：返回的字符串携带 is_error=False，并作为成功答案读取。有一个测试使用错误输入调用每个工具，并断言该标志。

设计决策

使用 mcp>=2.0.0,<3 和 MCPServer，而不是 v1 固定版本和 FastMCP。 SDK 仍然为尚未迁移的人提供 mcp>=1.28,<2，但 v1 时代的服务器会在三秒内暴露自己：from mcp.server.fastmcp import FastMCP。迁移指南 提供了重命名后的名称。低级别的 Server 是另一种选择，但它不再自动包装返回值，这意味着需要为八个工具手动编写 JSON Schema。

使用类型化的 Pydantic 返回值，而不是文本块。 大多数公共 MCP 服务器返回散文，让模型去解析。这里返回注解就是输出模式，因此类型化无需额外成本，并在负载离开服务器之前提供验证。

使用两个 K 线工具，而不是一个带有可选参数的。 JSON Schema 无法表达互斥性，因此单个 get_bars(count or start..end) 会将“两者选一，但不能同时”作为散文推给模型。两个工具有两个完全有效的模式，而“两者都给出，两者都不给出”的错误类则不存在。

使用生成的数据，而不是真实的数据源。 这是一个许可决策，而非偏好。MetaTrader 的导出数据是经纪商许可的数据源，对于指数和股票差价合约，底层数据是交易所许可的。Yahoo 的帮助页面明确说明了限制：您不得重新分发 Yahoo Finance 上显示或提供的信息，并且其开发者 API 条款 另外限制了出售或再许可访问权限。HistData 的常见问题解答 未授予任何再分发权利；它仅说明数据不附带任何保证，而沉默并非许可。将其中任何数据提交到 MIT 仓库，都将重新许可我无权重新许可的数据。

使用标准库，而不是 pandas 或 numpy。 对于捆绑的 CSV 规模，csv 加上 datetime 加上数据类就足够了，并且代码树保持可审计。不过，这个代码树值得诚实命名，全部列出：mcp 2.x 是一个直接依赖项，它会拉入 anyio、httpx2、jsonschema、mcp-types、opentelemetry-api、pydantic、pyjwt（及其加密扩展）、python-multipart、sse-starlette、starlette、typing-extensions、typing-inspection 和 uvicorn，以及在 Windows 上的 pywin32。加密扩展会进一步引入 cryptography、cffi 和 pycparser。这比 v1 的占用空间更大，并且有一个测试会读取已提交的 uv.lock，如果此列表与之不匹配则失败，因为一个旨在命名代码树的段落，如果只命名了代码树的大部分，那就毫无价值。

没有 run_backtest 工具。 回测的计算量无界，需要的远不止 MarketDataSource，并且会与 QUACKZ 重复，因此这对组合看起来像是两个半成品项目，而不是两个专注的项目。出于同样的原因，这里的护栏是领域本地的：输入验证、有界查询、固定的品种范围、无副作用。通用代理护栏属于 QUELLZ，不应在此重复发明。

限制

• 没有持续集成运行器在任何地方执行实时 MetaTrader 路径。 没有非 Windows 的 wheel，也没有运行器拥有终端或经纪商账户。Windows 作业仅证明扩展可以导入，并且 Mt5Source 能干净地报告缺少终端，仅此而已。Mt5Source 的字段映射是这里测试最少的代码，由假模块测试覆盖。

• MetaTrader5 仅限 Windows，并且不发布源代码分发，因此 pip install quotez[mt5] 在 macOS 和 Linux 上按设计是空操作。有一个测试断言环境标记确保了这一点。

• initialize() 会启动终端（如果尚未运行），整个操作受其 timeout 参数限制，该参数文档中默认值为 60000 毫秒。该页面没有给出启动本身的具体数值，因此请将 60 秒视为调用的上限，而不是测量的启动时间。QUOTEZ 在服务器生命周期内只打开一次连接，而不是每次调用都打开，因此无论其成本如何，都发生在启动时，而不是让第一次工具调用看起来像挂起。

• 两个数据源在 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 的 K 线。这里没有对终端的 M1 进行重采样来隐藏这一点，因为一根与操作员自己的图表不一致的 K 线，比有记录的偏移更糟糕。

• 出于同样的原因，spread 在 M1 以上的每个回放 K 线上都是 null，并在每个 MetaTrader K 线上设置。聚合会故意清除它；终端会在每个时间框架上报告自己的值，QUOTEZ 会透传该值，而不是丢弃数据源提供的数据。

• copy_rates_from_pos 和 copy_rates_range 会被终端的“图表中最大 K 线数”设置静默限制，因此即使在服务器自身限制内的请求，也可能返回不足的数据，而 MetaTrader API 中没有任何说明。

• get_bars 会跳过终端仍在构建的 K 线，因此其最新的 K 线始终是已收盘的。get_bars_range 则不会，因为边界由调用者决定：如果 end 在当前区间内，则返回该区间的部分 K 线。

• symbol_info() 对于未知符号会返回 None，而不是引发异常，symbols_get() 在出错时也是如此。这里的每个调用点都会进行检查，但这就是被包装的 API 的形状。

• MetaTrader 以 UTC 时间存储 K 线和 Tick 时间，不进行偏移，而朴素的 Python datetime 会相对于本地时区进行解析；copy_rates_range 文档 说明了这一点。每个出站时间戳都使用 tz=UTC 构建，并且朴素的输入会被拒绝，但这是一个陷阱，会静默地将整个序列偏移一个小时。

• 没有速率限制。stdio 服务器恰好是一个主机的子进程，主机负责速率限制。

• 回放数据是样本规模且是生成的：4 个品种，每个 3600 根 M1 K 线，共十个交易日。它用于演示工具和测试聚合，既不是研究数据集，也不是市场数据。

• 版本 0.1.0 是只读且仅限 stdio 的，没有提示功能，没有 SSE 或流式 HTTP 传输，也没有 OAuth。

我为什么构建这个

我在指数数据上运行向前验证研究，并保留 MetaTrader 终端用于外汇和金属部分，因此这两部分内容早已在我的工作台上。促使我写下这些的，是看到一个智能体从一个类型错误的工具中复述一个数字，仿佛它是事实，没有单位、没有时区，也没有说明其来源。在市场数据中，这并非表面问题：一个以收盘价而非开盘价标记的柱线，或一个悄然转换为本地时间的时间戳，会给出一个看似正确却偏差一小时的答案。因此，这主要涉及关于数据来源和工具可声称内容的决策，并围绕少量聚合代码展开。

开发

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

251 个测试，无需网络，耗时数秒，在 macOS、Linux 和 Windows 上结果一致。该计数基于实际运行集合断言，因为 README 中的数字是无人更新的数字。

许可证

MIT。参见 LICENSE。

属于 Q...Z 工具集的一部分，五个针对不自我宣告的失败的工具：

• QUACKZ，戳破一个仅因从两百个中选出而看似良好的回测。

• QUOTEZ，本工具：智能体可读取但无法操作的市场数据。

• QUELLZ，衡量提示注入控制在效用和攻击率上的成本。

• QUIDZ，拒绝本应重复发出的对外付款。

• QUESTZ，在爬虫从已变形的页面写入 CSV 之前阻止它。