quant-swarm

quant-swarm

以风险优先的交易前检查把关实盘资金——包括时点数据、不变条件与数据泄漏审计、市场状态探测——以及 Shadow Tournament：在相同的市场走势中，将你的策略基因组与一支实时、自我进化的交易群体中的冠军策略进行评分比较。

由首席量化技术专家打造

由 The 1.21 Initiative 的首席量化技术专家编写——其代码路径与交易群体中把关实盘晋级和执行决策的代码路径完全相同。每个工具的存在，都是因为生产交易系统反复以两种方式失效：研究中的前视数据泄漏和生产中的仓位过大。quant-swarm 提供了可防止这两类问题的检查工具，让你能用守护已部署资金的完全相同逻辑审计自己的工作。

你的回测是静态的。群集却不是。

这个软件包背后的群集不会靠手动调优策略。一个冠军基因组在实盘运行；每个周期，群集都会培育挑战者（受层级上限约束的变异），在五种带标签的市场状态（高波动、回撤、震荡、暴涨、频繁跳空）下，使用完全相同的情景种子矩阵重放冠军和挑战者，并将配对结果记入 ELO 账本。代理先验会预先评估候选方案，以便把耗费高昂的重放资源用在关键之处。不会仅凭一次出色的回测就晋升：晋升要求至少进行 MIN_EPISODES=20 次配对情景，差异具有 Wilcoxon 显著性，在最差市场状态下的优势为正（最大最小值，而非均值），相对于有记录以来尝试过的所有试验单调递增的数量，具备去膨胀夏普比率优势，并且满足 PBO 上限。这就是 AlphaZero 式系统所推广的冠军／挑战者、自我对弈风格循环，并以严谨的方式应用于市场——同时明确说明两项无法迁移的要素：市场不会对我们做出反应，因此不存在真正的自我对弈；也没有学习得到的动态模型或树搜索；选择依据的是配对重放、ELO 和统计门槛。

重放只是其中一半。每逢周日，群集还会运行一场前瞻联赛：每个联赛基因组——包括冠军、ELO 排名靠前的挑战者、提交的基因组，以及一名其周末操作由学习模型选定的规划器参赛者——都会根据周五的因果特征，为即将到来的一周确定持仓，并在这一周开始前存储 SHA-256 承诺。下一个周期会根据实际收盘价（扣除各基因组自身成本模型计算的成本）为每个已锁定的持仓标记结果，在相同的真实周内为所有参赛者排名，并据此更新 ELO。锁定的预测无法针对接下来的一周过拟合；这就是群集的真实基准，它还会为重放缓冲区提供数据，将每个持仓分解为各个组成操作（筛选、入场、仓位规模、周末操作），从而按操作和市场状态分配功劳，而不是把策略视为一个整体。前瞻联赛于 2026-09-02 启动；首批实际结算结果将在 9 月中旬出炉，群集会保持不变地运行八周以收集这些结果。

这对你意味着：本地回测会告诉你某项策略在一条路径上的表现。Shadow Tournament 则会告诉你，在同样的路径中、在对策略最不利的市场状态下，样本量足以得出可靠判断时，它能否击败一个不断进化的冠军——而你的结果也会计入群集的 ELO 账本。选择以贡献者身份参与，你的基因组就会成为群集下一轮繁育周期中的外部挑战者（费用减半），接受重放评分；若它赢得联赛席位，也会在真实周内接受评分。这就是飞轮：每一次诚实的提交都会让冠军更难被击败，也会让每位用户面对更严苛的基准。

风险优先的原因

风险门槛不是事后报告，而是每项操作的前置条件。该软件包围绕这一约束进行组织：

• 默认采用失败即关闭策略。 未知功能映射到 C 级，缺少来源信息时返回 UNSCORABLE（绝不填入中性值），无法验证的令牌会在托管路径上被拒绝。请参阅 warden.audit_features 和 features.build 中的来源信息保护机制。

• 固定且不会漂移的不变量。 仓位规模下限（单只标的 25%，总仓位 60%）、成交模型（价差 + 滑点 + 逆向选择，双边都计入，始终对你不利）以及硬约束检查均从固定提交 SHA 的代码中引入（.github/pins.json，由 CI 逐字节验证）。一致性测试固定了三处下限副本（Python/MCP、C# 实盘引擎、Terraform），确保它们不会漂移。

• 时间点来源信息。 SQLite WAL 缓存位于 %LOCALAPPDATA%\1.21-initiative\swarm-mcp\cache.db（POSIX 上为 $XDG_CACHE_HOME/1.21-initiative/swarm-mcp）：已完成的会话绝不重新获取，进行中的会话最多每 60 s 刷新一次，财报/新闻按 fetched_at 只追加，并且 features.build 会对每一行运行无前视检查（每项特征都必须等于在 as_of 时进行的全新因果重算结果）。

• 悲观执行。 warden.cost_check 和模拟器会模拟对你不利的成交；不存在会抬高回测结果的乐观成交路径。

• 没有下单代码路径。 没有任何工具可以下单、取消订单或路由订单——此代码库无法交易，只能拒绝不安全的交易。

• 统计上诚实地拒绝。 本地绝不发布晋级判定。统计上无法判定的输出会返回 INDETERMINATE_LOCAL/UNDERPOWERED/UNSCORABLE，指出确切的缺失输入（MIN_EPISODES=20、PBO、DSR、最差市场状态的边际值），并转交给托管式 Shadow Tournament（tournament.submit）。

• 本地优先，自带密钥：仅在 BYOK 模式下运行时，才会从环境变量读取你的 Alpaca/AltData 密钥；否则，数据会通过托管中继传输。

• 你的交易代码、K 线、特征和订单绝不会离开你的设备。唯一可能离开设备的内容，是你明确传递给 tournament.submit 的内容：基因组参数向量（公开架构字段），以及——对于 策略贡献者 级别——由作者撰写的披露内容和/或你的策略代码。提交的代码绝不会执行：它会被视为惰性文本，由托管 LLM 审核者静态读取，转换为结构化说明和代码哈希，审核后即丢弃原始代码。默认情况下，评分完成后，托管端甚至会删除该向量。

通过 Smithery 一键安装： 该列表项为 blink-kt/quant-swarm（软件包和 Smithery 标识均为 quant-swarm）；Smithery stdio 启动器会启动 swarm-data-mcp，下方的托管流式 HTTP 端点则提供全部三个服务。配置是可选的——没有令牌时，服务仍会启动并列出所有工具；首次调用时会引导你免费注册。随时添加令牌，即可解锁由中继支持的工具和托管工具。

---

各服务

服务	作用	工具
swarm-data-mcp	仅提供衍生市场信号，并构建时点特征	market.pulse、market.sentiment、market.climate、market.regime、market.microstructure、volume.forecast、market.screen、market.rank、pit.analysis、features.build、cache.warm、cache.stats、cache.offline
swarm-warden-mcp	交易前不变量检查 + 泄漏门控 — 实盘资金底线与时点防护	warden.validate_order、warden.audit_features、warden.cost_check、warden.validate_genome、warden.explain_sizing、warden.promotion_verdict
swarm-gym-mcp	在本地分析市场状态脆弱性，然后参加与群集实盘冠军的 Shadow Tournament	gym.label_regimes、gym.probe_fragility、gym.paired_preview、gym.estimate_cloud_run、tournament.submit、tournament.verdict、tournament.leaderboard

原始 K 线／增强数据访问（get_bars / enrich_symbol）仅供内部使用，不再注册为工具——这些路径会回传原始数据提供方的值，而数据政策仅允许衍生数据：比率、百分位排名、标签、分桶和计数。market.pulse 和 market.sentiment 是通用替代工具；两者都接受可选的 bars 参数，因此你可以为我们未涵盖的标的提供自己的 OHLCV 行。

PIT 显著性说明（pit.analysis）

pit.analysis 回答每位另类数据买家首先应该提出的问题：这个信号是真实的吗？你如何确认？ 它读取经过发布门控的 pit_analysis/v2 存储——其行包含漏斗显著性输出的同一份数据——并针对每个标的，逐一说明每个 (dataset|metric|horizon) 系列，不作猜测：

• rolling_ir（基于经规模／行业中性化指标与中性化远期收益计算的 52 周 Spearman 横截面排名 IC）、Newey-West 双侧 p 值（t_hac，滞后 ceil(horizon/5) — 1m/6m 周期存在重叠，因此朴素的 IR·√n t 值偏于保守性不足）、n_obs、research_only 覆盖标记，以及任何数据陈旧性提示。
• 每个周期都有明确结论：SIGNIFICANT（同一次运行中的 L1 幸存项：rolling IR > 0 且 Benjamini-Hochberg q ≤ 0.05）、NOT_SIGNIFICANT（附原因 — IR 为负，或名义 p 值未通过多重检验校正）、NOT_JUDGED（未达到 26 个观测值的底线、发布数据已过时，或仅为诊断用途的原始水平）或 UNVERIFIED（没有门控产物、门控来自另一次运行，或安慰剂检验失败 — 原始 p 值本身绝不会被升级）。
• 时点处理：忽略 as_of 之后的发布点，且绝不返回原始指标值 — 仅提供衍生统计数据。

免费套餐每次调用提供简版答案（一个标的、标题计数和排名靠前的系列）；Pro 套餐解锁每次调用 10 个标的、所有系列、每个周期的完整详情，以及历史 as_of。v2 方法论（中性化 + 重叠校正推断 + 无尺度会计变体 + 数据陈旧性上限 + 日期打乱安慰剂检验）记录在每份运行清单中；v1 存储会被拒绝，不会被悄然复用。不构成投资建议。

运营区域天气（market.climate）

market.climate 面向易受天气影响的标的开展区域天气研究。对于每个标的，它会为产品生产和/或销售所在的每个运营区域获取无需密钥的 Open-Meteo 14 天预报，以及一年前相同的 14 个日历日（采用已随工具发布的 10-K 风格、按暴露权重加权的区域登记表，涵盖能源、农业、航空/旅行、零售、公用事业和住宅建筑行业的业务布局），然后将各区域的温度异常、HDD/CDD、降水/降雪、风况以及霜冻/高温日数按暴露权重汇总为标的级数据——保留各区域的详细信息，因此某个收成区域出现热浪时仍可清晰呈现。天气数据关联的是标的实际覆盖的地理区域，而不是上市交易所或总部所在城市：不会用伦敦的天气预报代替纽约生产和销售的产品所在地区的预报。对于不在随工具发布的登记表中的标的，请传入 areas（生产/销售地区），market.climate 将仅研究这些地区。该工具免费，无需提供商凭据；仅返回推导出的总和/均值/比率/计数/分档数据，不返回逐日原始序列。预报值仅作为当前研究背景，绝不可用于过去的决策日期。

影子锦标赛

gym.paired_preview 坦诚地承认其能力有限：在你缓存的窗口上，每种制度最多测试 8 个种子 × 2 次，每项统计都标记为 UNDERPOWERED，绝不作为定论。tournament.submit 可以让基因组突破这一上限：

1. 本地验证 — warden.validate_genome 返回 genome_hash；不会发送任何内容。
2. 提交 — tournament.submit(genome, contribute=false|true)。网站会收取额度（200，若设为 contribute=true 则为 100），并将任务分发给托管运行器。 contribute=true 属于基因组贡献者等级（向量以外部挑战者的形式授权）。添加 disclosure 和/或 strategy_code，即可进入策略贡献者等级：提供作者编写的决策逻辑和/或代码，供静态 LLM 审核——代码绝不会被执行；排行榜署名和联赛席位资格取决于审核结果。
3. 在相同路径上进行托管回放 — 运行器会在托管的 bars_1day 面板上，让你的基因组和群体当前的冠军沿相同路径进行回放：5 种制度 × 每种 4 次 × 5 个种子 = 100 场配对回合（超过 MIN_EPISODES=20），计算 Wilcoxon 配对 p 值、自助法 CI、各制度的差值和最差制度边际，统计硬约束违规和前视违规，并将结果分类为：CHALLENGER_BEATS_CHAMPION、CHALLENGER_LOSES 或 INCONCLUSIVE。
4. ELO — 结果会更新你的基因组对阵冠军的评分（K=16，起始值 1500），以及冠军对阵整个参赛群体的评分。tournament.leaderboard（免费）会显示匿名排行榜：仅显示 12 个字符的哈希前缀。
5. 轮询 — 调用 tournament.verdict(job_id)；轮询不收费。运行大约需要两分钟。

结果是锦标赛结果，而非晋级。晋级门槛——修正后的夏普比率边际、PBO 上限、单调试验账本——会在群体的私有注册表中，对符合条件的基因组进行检查。这条边界是有意设置的（见下文IP 边界）。回放结果是群体的快速信号；真实周的前向联赛结算则是群体缓慢但无法伪造的信号——贡献的基因组在回放中击败冠军，才能获得联赛席位；而只有已实现的周度表现才能让它留在席位上。

**发送的内容：**基因组参数向量、其哈希和 contribute 标志——此外，仅在策略贡献者等级下，还会发送披露信息和/或 strategy_code（代码绝不会被执行；托管审核员会使用 LLM 对其进行静态审查，并且只保留结构化说明和代码哈希）。绝不发送标的、K 线、特征、订单或凭据。**保留：**若 contribute=false，评分完成后会从任务记录中删除向量——哈希和结果仍会保留。若 contribute=true（基因组或策略等级），你即授权群体在其演化循环中使用该向量和结果；该向量会注册为外部挑战者（origin=external_contribution），并与群体自身的变异体一样，接受相同的分级限制锦标赛和晋级门槛。这就是贡献者费用减半的原因：你的基因组丰富了群体提案者的多样性，而每项被接受的贡献都会让下一位冠军更难击败——对所有人来说都是如此。策略等级中的披露信息还会在审核通过后带来排行榜署名和联赛席位——贡献的基因组在回放中击败冠军即可获得席位，而只有已实现的前向联赛周度表现才能让它留在席位上。

套餐与积分费率表

通过 https://1.21initiative.com/mcp/ 获取令牌。 积分是所有会产生费用的项目的计量单位——一次中继数据调用、一次托管计算模拟回合，或一场锦标赛——因此，购买积分包即可获得一定额度的所有项目，我们绝不会以亏损的方式运行托管计算。

内容	积分	说明
中继数据调用（/data/bars、/data/enrich、/data/pit）	1	符号数量不超过套餐上限时，均计为一次调用
托管的单次 Pro 工具（features.build、warden.promotion_verdict、gym.label_regimes、gym.estimate_cloud_run）	1	仅在托管端点调用时收费
托管 gym 回合（gym.probe_fragility、gym.paired_preview）	每回合 1	5 种机制 × per_regime × 种子数（配对预览还需 × 2 个基因组）；gym.estimate_cloud_run 可在运行前为任意配置估价
Shadow Tournament（tournament.submit）	200——设置 contribute=true 时为 100	按固定价格进行完整的 100 场配对回合配置，与冠军对战
tournament.verdict、tournament.leaderboard、所有 warden 检查器、cache.*、任何工具的本地 stdio 运行	0	本地执行永不计量——使用的是你的 CPU 和电力

• 免费（注册时即时获取令牌）：所有 warden 检查器、派生快照 market.pulse / market.sentiment / market.climate / market.regime、 pit.analysis lite（每次调用一个符号，仅提供标题计数和排名靠前的类别；Pro 可解锁 10 个符号、所有类别、每个时间范围的完整详情和历史 as_of）、 cache.stats、cache.offline，以及 tournament.leaderboard（每次调用 10 个符号、 每月 250 次中继调用、回溯 365 天）。不包含托管计算， 除中继额度外，不会代你产生 GCP 费用。
• Pro——一次性积分包，自助购买：10,000 积分，£19，或 100,000 积分，£149， 有效期 90 天，无订阅，无不限量套餐。解锁 features.build、cache.warm、Pro 派生工具（market.microstructure、volume.forecast、market.screen、market.rank；每次 调用 50 个符号，支持完整回溯）、所有 gym 工具、warden.promotion_verdict，以及 tournament.submit / tournament.verdict。一个 Starter 积分包可参加 50 场锦标赛；作为贡献者可参加 100 场。
• 机构版（定制报价）：策略验证审计项目、自定义范围、托管联赛运行、SLA。

积分池已用尽或超过 90 天有效期的 Pro 令牌，经验证后会显示 status: exhausted / expired，并采用免费功能集——再次购买前，Pro 工具将拒绝调用。套餐限制由服务端强制执行（中继、/api/mcp/meter、/api/mcp/verify 和托管的 streamable-HTTP 端点会返回结构化的 402 拒绝响应，并附带 upgrade_url）。此开源 客户端的套餐检查仅供参考：免费令牌调用 Pro 工具时会收到 UPGRADE_REQUIRED 响应——该工具仍会列出，调用尝试会指向升级页面。没有 DRM；免费套餐本来就是零成本服务。

真正的时点数据

由 LLM 驱动的研究会不断重新运行单元格；每次重跑都会消耗 AltData（60 req/min）和 Alpaca（200 req/min）的配额，重新拉取相同的历史数据——然后悄无声息地使用决策时点尚不存在的数据构建 特征。swarm-data-mcp 同时解决这两个问题：

• SQLite（WAL）缓存位于 %LOCALAPPDATA%\1.21-initiative\swarm-mcp\cache.db （POSIX 系统上位于 $XDG_CACHE_HOME/1.21-initiative/swarm-mcp）。
• 已结束的交易时段永不重新获取——可无限次零成本重放。进行中的交易时段最多每 60 s 刷新一次；数据补充每 300 s 刷新一次。
• 盈利和新闻数据按 fetched_at 仅追加：后续获取绝不会改写较早的 as_of。
• 每个提供商都使用令牌桶，并采用 429 指数退避（1s·2ⁿ）。
• features.build 会对每一行运行无前视检查（每个特征都必须等于在 as_of 时点进行的全新因果重算结果），并对每个字段运行溯源检查。 没有记录时点证据的 Tier-B/C 字段会返回 UNSCORABLE——绝不会用 0.0 静默填充为中性值。

每个响应都包含 coverage（缓存与 API 的数据来源，以及每个标的最早/最新交易时段）和 limits（本地数据深度，单位为周；以及磁带深度门槛：Tier-A 快速通道为 8 周， 符合磁带资格需 26 周）。未达到门槛时，响应会包含 escalation 区块，指出满足要求的托管 bars_1day 面板。Tier 磁带重放仍在路线图中，目前不可用——我们不会作出误导性暗示。

监管者

warden.validate_order 与拒绝实时订单的函数相同：单个标的最多占权益的 25%， 总敞口上限为 60%。允许按基金覆盖默认值，但响应始终会报告你相对于统一底线的偏差。warden.audit_features 会标记被禁止的实际值来源 （open-meteo.archive 等返回的是实际值，而不是过去某个星期五的预测内容）、早于磁带起始时间的特征，以及未明确列出的特征；后者会默认归入 Tier C 并拒绝放行。 warden.cost_check 会在悲观成交模型下，将声称的总毛边际收益换算为扣除成本后的实际收益（价差 + 滑点 + 逆向选择，交易两腿都计算，且始终按对你不利的方向处理）。 warden.explain_sizing 会逐步镜像 C# 实时风险引擎，并通过一致性测试将底线与 terraform 和 guardrails 固定在一起，确保三份副本不会出现偏差。

训练场

gym.probe_fragility 会在确定性的 Tier-A 模拟器上重放你的基因组，并报告各市场状态下的净 bps、最差市场状态、换手率和硬约束违规情况——绝不晋级。种子数上限为 8，per_regime 上限为 2：这是对统计诚实的坚持，并非人为制造稀缺。针对冠军的 Tier-B/C 变异会触发训练场的 TierScoringRefusal（UNSCORABLE），而不会悄悄用价格面板无法提供的特征填充中性值。gym.paired_preview 会在相同市场路径上比较冠军与挑战者，绕过晋级门槛，并将每项统计都标记为 样本量不足；同时指出达到 MIN_EPISODES=20 所需的确切种子数——每个无法判定的结果最后都会附带一个 cloud_job 区块，其中就是解决该问题的 tournament.submit 调用。

安装

需要 Python ≥ 3.11。有两种连接方式：

• 远程 — 托管的可流式传输 HTTP 端点（与注册表条目中的 URL 相同）： https://swarm-mcp-503318750546.europe-west1.run.app/mcp/data （以及 /mcp/warden、/mcp/gym）。通过 Authorization: Bearer <token>（或 ?apiToken=<token>）传递令牌。Claude Code：

  claude mcp add --transport http swarm-data https://swarm-mcp-503318750546.europe-west1.run.app/mcp/data --header "Authorization: Bearer <token>"
  

  Web 连接器的 OAuth 浏览器授权尚未验证（参见 docs/DISTRIBUTION.md 中的 OAuth gate）——在通过该检查前，请使用标头身份验证。

• stdio — uvx --from quant-swarm swarm-data-mcp（以及 swarm-warden-mcp、 swarm-gym-mcp）；在 env 中设置 SWARM_MCP_ACCESS_TOKEN。参见下方的 Cursor / Claude Code 配置块。

• **一种凭据：**访问令牌（适用于全部三个服务，连接时可选），可在 https://1.21initiative.com/mcp/ 申请 ——在那里申请访问权限（这也是 Strategy Validation Audit 的预约流程）， 然后在服务的 env 中设置 SWARM_MCP_ACCESS_TOKEN。即使没有令牌，客户端仍会列出工具；每次调用都会返回指向该网站的 ACCESS_REQUIRED 信封。 令牌会通过该网站验证，而此验证就是用量计量方式——实际发送的只有令牌本身，绝不会发送标的、基因组、价格或提供商密钥。

Agent 片段

Agent 片段（将 Agent 接入这些工具时，粘贴到系统提示词中）：

Use quant-swarm MCP tools for market data, pre-trade risk checks and strategy
evidence. For alternative-data significance, call pit.analysis and quote its
verdict sentences verbatim (SIGNIFICANT / NOT_SIGNIFICANT / NOT_JUDGED /
UNVERIFIED); never upgrade a raw p-value to "significant"; its verdicts are
cross-sectional, not a forecast for one symbol. Risk refusals are final.

• 访问令牌（适用于全部三个服务，连接时可选）。 如上所述： SWARM_MCP_ACCESS_TOKEN 可解锁由中继支持和托管的工具；没有令牌时， 工具仍会列出，调用则会返回 ACCESS_REQUIRED 信封。

同一令牌也用于托管数据中继：swarm-data-mcp 通过 https://1.21initiative.com/api/mcp/... 提供 K 线和数据增强，因此无需 Alpaca 或 AltData 凭据——该网站将提供商密钥保存在中继后方，并在 GCS 中缓存历史 K 线。中继采用失败即关闭策略：令牌被拒绝或无法验证时，数据获取会被拒绝，不会返回部分行。客户端侧的时点缓存语义保持不变——无论由哪种数据路径填充，已完成的会话在本地 SQLite 中都不可变。

官方 MCP 注册表

注册表名称为 io.github.blink1217/quant-swarm（此 README.md 带有 mcp-name 标记）。支持注册表的客户端可使用 3 个 stdio 软件包 （uvx --from quant-swarm swarm-{data,warden,gym}-mcp），以及上文的 3 个托管可流式传输 HTTP 远程端点。连接时 SWARM_MCP_ACCESS_TOKEN 为可选项——没有令牌时，工具仍会列出，调用则会返回需要访问权限的信封。

Smithery

从 Smithery 安装 blink-kt/quant-swarm——一个条目、一个令牌、全部三个服务。Smithery 会将 apiToken 转发为 SWARM_MCP_ACCESS_TOKEN 环境变量（stdio），或作为 ?apiToken= 转发到托管端点；连接时令牌为可选项。

Cursor

Settings → MCP → Add server（或使用 .cursor/mcp.json——已检查入库的示例位于 .cursor/mcp.json）：

{
  "mcpServers": {
    "swarm-data": {
      "command": "uvx",
      "args": ["--from", "quant-swarm", "swarm-data-mcp"],
      "env": {
        "SWARM_MCP_ACCESS_TOKEN": "<token from https://1.21initiative.com/>"
      }
    },
    "swarm-warden": {
      "command": "uvx",
      "args": ["--from", "quant-swarm", "swarm-warden-mcp"],
      "env": { "SWARM_MCP_ACCESS_TOKEN": "<token from https://1.21initiative.com/>" }
    },
    "swarm-gym": {
      "command": "uvx",
      "args": ["--from", "quant-swarm", "swarm-gym-mcp"],
      "env": { "SWARM_MCP_ACCESS_TOKEN": "<token from https://1.21initiative.com/>" }
    }
  }
}

更喜欢使用深层链接？scripts/make_deeplinks.py 会为全部三个服务打印 cursor://…/mcp/install 链接（stdio 配置的 base64 编码，因此不会与上方的 JSON 配置不一致）； 生成的列表已检查入库，位于 .cursor/DEEPLINKS.md。

Claude Desktop

claude_desktop_config.json——使用与上方相同的 mcpServers 块。

Claude Code

stdio：

claude mcp add swarm-data   --env SWARM_MCP_ACCESS_TOKEN=<token> -- uvx --from quant-swarm swarm-data-mcp
claude mcp add swarm-warden --env SWARM_MCP_ACCESS_TOKEN=<token> -- uvx --from quant-swarm swarm-warden-mcp
claude mcp add swarm-gym    --env SWARM_MCP_ACCESS_TOKEN=<token> -- uvx --from quant-swarm swarm-gym-mcp

远程（标头身份验证）：

claude mcp add --transport http swarm-data https://swarm-mcp-503318750546.europe-west1.run.app/mcp/data --header "Authorization: Bearer <token>"

Windsurf

~/.codeium/windsurf/mcp_config.json — 与上文 Cursor 配置块相同的 stdio JSON 格式。对于托管端点，请改用 serverUrl 格式：

{
  "mcpServers": {
    "swarm-data-remote": {
      "serverUrl": "https://swarm-mcp-503318750546.europe-west1.run.app/mcp/data"
    }
  }
}

（托管端点接受通过 Authorization: Bearer <token> 或 ?apiToken=<token> 传入的令牌。）

warden 和 gym 都是纯检查器，数据服务通过托管中继获取数据，因此无需任何服务配置提供商密钥——只需要访问令牌。

**本地开发：**此仓库的操作者可以通过将 SWARM_MCP_LOCAL_TOKEN 设置为与 SWARM_MCP_ACCESS_TOKEN 相同的值来离线启动（文档中说明的绕过方式；会跳过针对站点的令牌验证，并为令牌授予完整的 Pro 权限——这是仅在你自己的机器上生效的本地覆盖设置）。

**Swarm 操作者（内部）：**若要直接从提供商获取数据，而不是通过中继，请在 swarm-data-mcp 上设置 SWARM_MCP_BYOK=1，以及 ALPACA_API_KEY/ALPACA_SECRET/ALTDATA_API_KEY。公共用户应让 SWARM_MCP_BYOK 保持未设置状态。

自行托管远程端点：swarm-mcp-http 会验证 Host 标头（DNS 重绑定防护）。默认允许 1.21initiative.com、项目的 Cloud Run 主机名、Smithery 网关和 localhost；SWARM_MCP_ALLOWED_HOSTS（逗号分隔）会在默认值基础上扩展允许列表——绝不会替换默认值，因此自定义域名不会意外导致 Cloud Run URL 无法访问。SWARM_MCP_REMOTE_URL 用于覆盖公布的端点基址，SWARM_MCP_TOKEN_VERIFY_URL 用于覆盖验证端点。容器配置方式请参阅 Dockerfile。

托管端点会计量计算用量（swarm_mcp/metering.py）：在运行 Pro 计算工具前，会携带调用者的令牌向 {SWARM_MCP_RELAY_URL}/meter 发送 POST 请求；如果计量服务拒绝请求或无法访问，则拒绝执行（JSON-RPC -32003、HTTP 402/429/503）——托管计算绝不会在未计量的情况下提供。Shadow Tournament runner 也运行在同一服务中：站点会向 POST /internal/tournament/run 分发任务，并通过共享密钥 SWARM_MCP_INTERNAL_KEY 进行保护；runner 使用 SWARM_MCP_SERVICE_TOKEN（机构令牌，因此不会向用户收取 runner 自身数据的费用）通过中继填充其面板，依据 SWARM_MCP_CHAMPION_GENOME 评分（指向注册表当前冠军的路径；必须设置 SWARM_MCP_CHAMPION_GENOME，且不提供打包的备用值），然后回调 POST {relay}/tournament/complete。SWARM_MCP_TOURNAMENT_UNIVERSE 和 SWARM_MCP_TOURNAMENT_LOOKBACK_DAYS 用于设定托管面板的范围。runner 会在返回 202 后于后台任务中评分，因此 Cloud Run 服务必须配置为始终分配 CPU（--no-cpu-throttling），且请求超时至少为 300 s；如果使用基于请求的 CPU 分配，任务会在响应后因资源不足而停滞，作业也会被退款并标记为失败。

---

IP 边界（包含什么，不包含什么）

本仓库只提供检查器：订单检查、来源保护机制、悲观成交模型、基因组架构、来源等级、硬约束检查、门槛阈值、A 级健身房模拟器和市场状态标注器——均通过固定的提交 SHA 引入（.github/pins.json，由 CI 验证）。

筛选机制保留在服务端，不包含在本仓库中：目标评分、Deflated Sharpe 估算和晋级门槛决策。任何晋级判定请求都会返回 INDETERMINATE_LOCAL，并附上准确的缺失统计输入（MIN_EPISODES=20、通过组合对称拆分计算的 PBO ≤ 0.30、基于单调试验台账的 DSR 边际值、覆盖全部 5 个市场状态 × 种子的最差市场状态边际值），以及：

• audit_request 区块——基因组哈希 + 违规摘要，不含专有负载；
• cloud_job 规范，即用于解决该问题的 tournament.submit 调用。

本仓库中的 Shadow Tournament 运行器会在相同路径上计算配对统计数据和结果；它不包含目标函数、DSR 估算器或晋级决策，而 CI 测试（tests/test_ip_boundary.py）也会禁止加入这些内容。击败冠军的贡献基因组会交给 swarm 的私有注册表，由那里运行这些门槛。对于多基因组联赛、自定义市场范围和受 NDA 约束的实时指标，请通过 https://1.21initiative.com/ 上的策略验证审计。

遥测

默认关闭，仅可选择启用（SWARM_MCP_TELEMETRY_OPT_IN=opt-in），且只收集计数器（工具名称、成功标志、粗略耗时）。绝不收集代码、基因组、价格或凭据。机构买家会查阅源码；静默地向外发送数据会毁掉竞争优势。贡献者还需在提交中披露遥测范围（见上文的策略贡献者等级）。

以下情况属于明确约定的例外：

• 访问令牌验证。 设置了令牌且没有匹配的本地引导令牌时，令牌会通过 POST 请求发送到验证端点（默认值为 https://1.21initiative.com/api/mcp/verify，可通过 SWARM_MCP_TOKEN_VERIFY_URL 覆盖），每个进程最多每 5 分钟发送一次。只会发送令牌；如果无法访问端点或端点拒绝令牌，门禁会默认拒绝。
• 中继数据调用会携带令牌以及你请求的代码和天数（即请求内容）。中继调用会在服务端按次计量。
• tournament.submit 会发送基因组向量、其哈希和 contribute 标志——这是唯一会发送策略工件的工具，并且每次都会在其输出中明确说明这一点。

开发

pip install -e ".[test]"
py -3.11 -m pytest                          # full suite (see Step 2 count in docs/DISTRIBUTION.md)
scripts\vendor.ps1                          # re-vendor the pinned checker subset
py -3.11 scripts\check_pin.py               # vendored tree == pins.json

引入依赖时，会使用私有仓库在固定 SHA 处的同级检出版本（在固定提交存在之前，-FromWorktree 会执行引导）。CI 会镜像 swarm 自身的 guardrails-invariants 门禁：检出固定的 SHA，并逐字节验证已提交的引入树（同时逐变换验证去除后的子集），然后在固定 SHA 处运行 guardrails 自身的不变量测试套件。

许可证

封装代码：MIT（见 LICENSE）。swarm_mcp/vendored/guardrails/ 下引入的 guardrails 检查器子集遵循 swarm_mcp/vendored/guardrails/LICENSE.md 中的源码可用条款分发。被排除的筛选机制不在许可范围内。

---

健身房是 A 级价格子集。tape_replay 服务不对公众开放。B/C 级评分仅托管于服务端。Shadow Tournament 只返回配对结果，从不做晋级决策。其他任何说法都是伪造证据——而本仓库拒绝造假。