quant-swarm 0.3.0__tar.gz
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- quant_swarm-0.3.0/LICENSE +31 -0
- quant_swarm-0.3.0/PKG-INFO +313 -0
- quant_swarm-0.3.0/README.md +285 -0
- quant_swarm-0.3.0/pyproject.toml +50 -0
- quant_swarm-0.3.0/quant_swarm.egg-info/PKG-INFO +313 -0
- quant_swarm-0.3.0/quant_swarm.egg-info/SOURCES.txt +79 -0
- quant_swarm-0.3.0/quant_swarm.egg-info/dependency_links.txt +1 -0
- quant_swarm-0.3.0/quant_swarm.egg-info/entry_points.txt +5 -0
- quant_swarm-0.3.0/quant_swarm.egg-info/requires.txt +12 -0
- quant_swarm-0.3.0/quant_swarm.egg-info/top_level.txt +1 -0
- quant_swarm-0.3.0/setup.cfg +4 -0
- quant_swarm-0.3.0/swarm_mcp/__init__.py +14 -0
- quant_swarm-0.3.0/swarm_mcp/access.py +199 -0
- quant_swarm-0.3.0/swarm_mcp/cache/__init__.py +1 -0
- quant_swarm-0.3.0/swarm_mcp/cache/bars.py +193 -0
- quant_swarm-0.3.0/swarm_mcp/cache/db.py +232 -0
- quant_swarm-0.3.0/swarm_mcp/cache/enrich.py +80 -0
- quant_swarm-0.3.0/swarm_mcp/cache/freshness.py +47 -0
- quant_swarm-0.3.0/swarm_mcp/cache/rate_limit.py +68 -0
- quant_swarm-0.3.0/swarm_mcp/envelope.py +152 -0
- quant_swarm-0.3.0/swarm_mcp/mcp_compat.py +17 -0
- quant_swarm-0.3.0/swarm_mcp/plans.py +84 -0
- quant_swarm-0.3.0/swarm_mcp/redaction.py +48 -0
- quant_swarm-0.3.0/swarm_mcp/relay.py +206 -0
- quant_swarm-0.3.0/swarm_mcp/request_context.py +18 -0
- quant_swarm-0.3.0/swarm_mcp/server_meta.py +35 -0
- quant_swarm-0.3.0/swarm_mcp/servers/__init__.py +1 -0
- quant_swarm-0.3.0/swarm_mcp/servers/data_server.py +424 -0
- quant_swarm-0.3.0/swarm_mcp/servers/gym_server.py +251 -0
- quant_swarm-0.3.0/swarm_mcp/servers/http_server.py +362 -0
- quant_swarm-0.3.0/swarm_mcp/servers/warden_server.py +302 -0
- quant_swarm-0.3.0/swarm_mcp/telemetry.py +34 -0
- quant_swarm-0.3.0/swarm_mcp/tool_runner.py +43 -0
- quant_swarm-0.3.0/swarm_mcp/tools/__init__.py +1 -0
- quant_swarm-0.3.0/swarm_mcp/tools/data_tools.py +686 -0
- quant_swarm-0.3.0/swarm_mcp/tools/gym_tools.py +346 -0
- quant_swarm-0.3.0/swarm_mcp/tools/warden_tools.py +310 -0
- quant_swarm-0.3.0/swarm_mcp/vendor_path.py +28 -0
- quant_swarm-0.3.0/swarm_mcp/vendored/__init__.py +0 -0
- quant_swarm-0.3.0/swarm_mcp/vendored/alpha/__init__.py +0 -0
- quant_swarm-0.3.0/swarm_mcp/vendored/alpha/bars_fetch.py +56 -0
- quant_swarm-0.3.0/swarm_mcp/vendored/alpha/guardrails_path.py +32 -0
- quant_swarm-0.3.0/swarm_mcp/vendored/alpha/gym/__init__.py +13 -0
- quant_swarm-0.3.0/swarm_mcp/vendored/alpha/gym/panel.py +136 -0
- quant_swarm-0.3.0/swarm_mcp/vendored/alpha/gym/policy_head.py +60 -0
- quant_swarm-0.3.0/swarm_mcp/vendored/alpha/gym/regime.py +107 -0
- quant_swarm-0.3.0/swarm_mcp/vendored/alpha/gym/simulator.py +242 -0
- quant_swarm-0.3.0/swarm_mcp/vendored/alpha/microstructure.py +142 -0
- quant_swarm-0.3.0/swarm_mcp/vendored/alpha/order_checks.py +81 -0
- quant_swarm-0.3.0/swarm_mcp/vendored/alpha/shared/__init__.py +1 -0
- quant_swarm-0.3.0/swarm_mcp/vendored/alpha/shared/swing_screens.py +126 -0
- quant_swarm-0.3.0/swarm_mcp/vendored/guardrails/LICENSE.md +16 -0
- quant_swarm-0.3.0/swarm_mcp/vendored/guardrails/__init__.py +0 -0
- quant_swarm-0.3.0/swarm_mcp/vendored/guardrails/budget.py +100 -0
- quant_swarm-0.3.0/swarm_mcp/vendored/guardrails/fill_model.py +29 -0
- quant_swarm-0.3.0/swarm_mcp/vendored/guardrails/gates.py +127 -0
- quant_swarm-0.3.0/swarm_mcp/vendored/guardrails/genome_schema.json +83 -0
- quant_swarm-0.3.0/swarm_mcp/vendored/guardrails/genome_schema.py +114 -0
- quant_swarm-0.3.0/swarm_mcp/vendored/guardrails/objective.py +73 -0
- quant_swarm-0.3.0/swarm_mcp/vendored/guardrails/provenance.py +92 -0
- quant_swarm-0.3.0/swarm_mcp/vendored/guardrails/tiers.py +142 -0
- quant_swarm-0.3.0/tests/test_access_gate.py +110 -0
- quant_swarm-0.3.0/tests/test_audit_features.py +78 -0
- quant_swarm-0.3.0/tests/test_build_features.py +70 -0
- quant_swarm-0.3.0/tests/test_cache_determinism.py +69 -0
- quant_swarm-0.3.0/tests/test_derived_tools.py +172 -0
- quant_swarm-0.3.0/tests/test_entitlements.py +194 -0
- quant_swarm-0.3.0/tests/test_floors_parity.py +73 -0
- quant_swarm-0.3.0/tests/test_gym_tools.py +106 -0
- quant_swarm-0.3.0/tests/test_ip_boundary.py +56 -0
- quant_swarm-0.3.0/tests/test_no_lookahead_port.py +95 -0
- quant_swarm-0.3.0/tests/test_no_order_paths.py +43 -0
- quant_swarm-0.3.0/tests/test_offline_mode.py +38 -0
- quant_swarm-0.3.0/tests/test_order_checks_parity.py +90 -0
- quant_swarm-0.3.0/tests/test_pins.py +15 -0
- quant_swarm-0.3.0/tests/test_redaction.py +57 -0
- quant_swarm-0.3.0/tests/test_registry_metadata.py +74 -0
- quant_swarm-0.3.0/tests/test_relay.py +280 -0
- quant_swarm-0.3.0/tests/test_remote_http.py +331 -0
- quant_swarm-0.3.0/tests/test_sizing_parity.py +67 -0
- quant_swarm-0.3.0/tests/test_tier_refusal_port.py +78 -0
|
@@ -0,0 +1,31 @@
|
|
|
1
|
+
MIT License
|
|
2
|
+
|
|
3
|
+
Copyright (c) 2026 The 1.21 Initiative
|
|
4
|
+
|
|
5
|
+
Permission is hereby granted, free of charge, to any person obtaining a copy
|
|
6
|
+
of this software and associated documentation files (the "Software"), to deal
|
|
7
|
+
in the Software without restriction, including without limitation the rights
|
|
8
|
+
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
|
|
9
|
+
copies of the Software, and to permit persons to whom the Software is
|
|
10
|
+
furnished to do so, subject to the following conditions:
|
|
11
|
+
|
|
12
|
+
The above copyright notice and this permission notice shall be included in all
|
|
13
|
+
copies or substantial portions of the Software.
|
|
14
|
+
|
|
15
|
+
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
|
|
16
|
+
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
|
|
17
|
+
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
|
|
18
|
+
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
|
|
19
|
+
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
|
|
20
|
+
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
|
|
21
|
+
SOFTWARE.
|
|
22
|
+
|
|
23
|
+
---
|
|
24
|
+
|
|
25
|
+
NOTICE: `swarm_mcp/vendored/guardrails/` contains a CHECKER SUBSET of the
|
|
26
|
+
privately developed trading-swarm-guardrails rules layer, vendored at a pinned
|
|
27
|
+
commit SHA. Those files are NOT covered by the MIT license above; they are
|
|
28
|
+
distributed under the source-available terms in
|
|
29
|
+
`swarm_mcp/vendored/guardrails/LICENSE.md`. The selection machinery
|
|
30
|
+
(objective scoring, deflated-Sharpe estimation, promotion-gate decisions) is
|
|
31
|
+
deliberately excluded from this repository and remains server-side.
|
|
@@ -0,0 +1,313 @@
|
|
|
1
|
+
Metadata-Version: 2.4
|
|
2
|
+
Name: quant-swarm
|
|
3
|
+
Version: 0.3.0
|
|
4
|
+
Summary: Local stdio MCP servers extracted from the trading swarm: point-in-time data assembly, pre-trade invariant + leakage auditing, and regime-fragility probing.
|
|
5
|
+
Author: The 1.21 Initiative
|
|
6
|
+
License: MIT
|
|
7
|
+
Project-URL: Homepage, https://github.com/blink1217/trading-swarm-mcp
|
|
8
|
+
Keywords: mcp,trading,backtest-audit,point-in-time,regimes
|
|
9
|
+
Classifier: Development Status :: 4 - Beta
|
|
10
|
+
Classifier: Intended Audience :: Financial and Insurance Industry
|
|
11
|
+
Classifier: License :: OSI Approved :: MIT License
|
|
12
|
+
Classifier: Programming Language :: Python :: 3.11
|
|
13
|
+
Classifier: Topic :: Office/Business :: Financial :: Investment
|
|
14
|
+
Requires-Python: >=3.11
|
|
15
|
+
Description-Content-Type: text/markdown
|
|
16
|
+
License-File: LICENSE
|
|
17
|
+
Requires-Dist: mcp>=2.0
|
|
18
|
+
Requires-Dist: httpx>=0.27
|
|
19
|
+
Requires-Dist: numpy>=1.26
|
|
20
|
+
Requires-Dist: pandas>=2.0
|
|
21
|
+
Requires-Dist: scipy>=1.11
|
|
22
|
+
Provides-Extra: test
|
|
23
|
+
Requires-Dist: pytest>=8; extra == "test"
|
|
24
|
+
Provides-Extra: remote
|
|
25
|
+
Requires-Dist: uvicorn>=0.30; extra == "remote"
|
|
26
|
+
Requires-Dist: starlette>=0.37; extra == "remote"
|
|
27
|
+
Dynamic: license-file
|
|
28
|
+
|
|
29
|
+
# quant-swarm
|
|
30
|
+
|
|
31
|
+
Risk-first pre-trade checks that gate live capital — point-in-time data, invariant and leakage audits, regime probes.
|
|
32
|
+
|
|
33
|
+
<!-- mcp-name: io.github.blink1217/quant-swarm -->
|
|
34
|
+
|
|
35
|
+
## Built by a Principal Quantitative Technologist
|
|
36
|
+
|
|
37
|
+
Authored by the Principal Quantitative Technologist at [The 1.21 Initiative](https://1.21initiative.com) — the same code path that gates live promotion and execution decisions in the trading swarm. Every tool exists because production trading systems fail in two repeatable ways: **lookahead leakage in research** and **an oversized position in production**. `quant-swarm` ships the checkers that prevent both, so you can audit your own work with the exact logic that guards deployed capital.
|
|
38
|
+
|
|
39
|
+
## Why risk-first
|
|
40
|
+
|
|
41
|
+
Risk gates are not post-hoc reports — they are the pre-condition for every action. The package is organized around that constraint:
|
|
42
|
+
|
|
43
|
+
- **Fail-closed by default.** Unknown features map to tier C, missing provenance returns `UNSCORABLE` (never neutral-filled), and unverifiable tokens are refused on the hosted path. See `warden.audit_features` and `features.build` provenance guards.
|
|
44
|
+
- **Pinned, non-drifting invariants.** Order sizing floors (per-name 25%, gross 60%), fill model (spread + slippage + adverse selection, both legs, always against you), and hard-constraint checks are vendored at pinned commit SHAs (`.github/pins.json`, verified byte-for-byte by CI). A parity test pins the three copies of the floors (Python/MCP, C# live engine, Terraform) so they cannot drift.
|
|
45
|
+
- **Point-in-time provenance.** SQLite WAL cache at `%LOCALAPPDATA%\1.21-initiative\swarm-mcp\cache.db` (`$XDG_CACHE_HOME/1.21-initiative/swarm-mcp` on POSIX): finalized sessions are never re-fetched, in-progress sessions refresh at most every 60 s, earnings/news are append-only on `fetched_at`, and `features.build` runs the no-lookahead guard on every row (each feature must equal a fresh causal recomputation at `as_of`).
|
|
46
|
+
- **Pessimistic execution.** `warden.cost_check` and the simulator model the fill that hurts you; there is no optimistic fill path to inflate backtests.
|
|
47
|
+
- **No order-placement code path.** No tool can place, cancel, or route an order — this repository cannot trade, only refuse unsafe trades.
|
|
48
|
+
- **Statistically honest refusals.** Promotion verdicts are **never** issued locally. Statistically undecidable outputs return `INDETERMINATE_LOCAL`/`UNDERPOWERED`/`UNSCORABLE`, name the exact missing inputs (`MIN_EPISODES=20`, PBO, DSR, worst-regime margins), and hand off to the hosted tournament / Strategy Validation Audit.
|
|
49
|
+
|
|
50
|
+
- Local-first, BYO-key: your Alpaca/Finnhub keys are read from env only when operating in BYOK mode; otherwise data flows through the hosted relay.
|
|
51
|
+
- Your symbols, genomes, and alpha never leave your machine except as an `audit_request` (genome hash + violation summary, no proprietary payload) when you explicitly escalate.
|
|
52
|
+
|
|
53
|
+
**One-click install on [Smithery](https://smithery.ai/servers/blink-kt/quant-swarm):**
|
|
54
|
+
the listing is [`blink-kt/quant-swarm`](https://smithery.ai/servers/blink-kt/quant-swarm) (package and Smithery slug are both `quant-swarm`), and it carries all three servers. Configuration is optional — without a token the servers still start and list every tool; the first call points you at the free signup. Add a token any time to unlock the relay-backed tools.
|
|
55
|
+
|
|
56
|
+
---
|
|
57
|
+
|
|
58
|
+
## The servers
|
|
59
|
+
|
|
60
|
+
| Server | Hook | Tools |
|
|
61
|
+
| --- | --- | --- |
|
|
62
|
+
| `swarm-data-mcp` | Derived-only market signals plus point-in-time feature building | `market.pulse`, `market.sentiment`, `features.build`, `cache.warm`, `cache.stats`, `cache.offline` |
|
|
63
|
+
| `swarm-warden-mcp` | Pre-trade invariant + leakage gate — the live-capital floors and the point-in-time guards | `warden.validate_order`, `warden.audit_features`, `warden.cost_check`, `warden.validate_genome`, `warden.explain_sizing`, `warden.promotion_verdict` |
|
|
64
|
+
| `swarm-gym-mcp` | Regime fragility: *which regime kills it, and is your sample even large enough to have an opinion?* | `gym.label_regimes`, `gym.probe_fragility`, `gym.paired_preview`, `gym.estimate_cloud_run` |
|
|
65
|
+
|
|
66
|
+
Raw bar/enrichment access (`get_bars` / `enrich_symbol`) is internal only and no longer
|
|
67
|
+
registered as tools — those paths echo raw provider values, and the data policy is
|
|
68
|
+
derived-only: ratios, percentile ranks, labels, buckets and counts. `market.pulse` and
|
|
69
|
+
`market.sentiment` are the general-purpose replacements; both accept an optional `bars`
|
|
70
|
+
argument so you can supply your own OHLCV rows for symbols we don'"'"'t carry.
|
|
71
|
+
|
|
72
|
+
## Plans
|
|
73
|
+
|
|
74
|
+
Access is tokened through [https://1.21initiative.com/](https://1.21initiative.com/).
|
|
75
|
+
|
|
76
|
+
- **Free** (instant token at signup): all warden checkers (`warden.validate_order`, `warden.cost_check`,
|
|
77
|
+
`warden.explain_sizing`, `warden.validate_genome`, `warden.audit_features`), the derived snapshots
|
|
78
|
+
`market.pulse` / `market.sentiment` / `market.regime` (shared-relay symbols capped at
|
|
79
|
+
10 per call, ~250 relay data calls/month), plus `cache.stats` and `cache.offline`.
|
|
80
|
+
- **Pro** (paid by one-time credit packs, self-serve at the site): everything else — `features.build`,
|
|
81
|
+
`cache.warm` bulk backfill, all gym tools, `warden.promotion_verdict`, and the Pro
|
|
82
|
+
derived tools (`market.microstructure`, `volume.forecast`, `market.screen`,
|
|
83
|
+
`market.rank`), paid by one-time credit packs (10k or 100k relay calls, 90-day validity — no subscription, no unlimited plan) with 50 symbols/call.
|
|
84
|
+
- **Institutional** (custom-quoted): Strategy Validation Audit engagements, custom
|
|
85
|
+
universes, hosted evolution runs, SLA.
|
|
86
|
+
|
|
87
|
+
Plan limits are enforced server-side (the relay, `/api/mcp/verify`, and the hosted
|
|
88
|
+
streamable-HTTP endpoint return structured `402` refusals with an `upgrade_url`). This
|
|
89
|
+
open-source client'"'"'s plan check is **advisory**: a free token calling a Pro tool gets an
|
|
90
|
+
`UPGRADE_REQUIRED` envelope — the tool still lists, and the attempt points at the upgrade
|
|
91
|
+
page. No DRM; the free plan is deliberately the zero-cost surface.
|
|
92
|
+
|
|
93
|
+
### Point-in-time data, for real
|
|
94
|
+
|
|
95
|
+
LLM-driven research re-runs cells constantly; each re-run burns Finnhub (60 req/min) and
|
|
96
|
+
Alpaca (200 req/min) budgets re-pulling identical history — and then silently builds
|
|
97
|
+
features from data that did not exist at decision time. `swarm-data-mcp` fixes both:
|
|
98
|
+
|
|
99
|
+
- SQLite (WAL) cache at `%LOCALAPPDATA%\1.21-initiative\swarm-mcp\cache.db`
|
|
100
|
+
(`$XDG_CACHE_HOME/1.21-initiative/swarm-mcp` on POSIX).
|
|
101
|
+
- **Finalized sessions are never re-fetched** — zero-cost replays forever. The
|
|
102
|
+
in-progress session refreshes at most every 60 s; enrichment every 300 s.
|
|
103
|
+
- Earnings/news are append-only on `fetched_at`: a later fetch can never rewrite an
|
|
104
|
+
earlier `as_of`.
|
|
105
|
+
- Per-provider token buckets + `429` exponential backoff (`1s\u00b72\u207f`).
|
|
106
|
+
- `features.build` runs the no-lookahead guard on every row (each feature must equal a
|
|
107
|
+
fresh causal recomputation at `as_of`) and the provenance guards on every field.
|
|
108
|
+
Tier-B/C fields without recorded point-in-time evidence come back `UNSCORABLE` —
|
|
109
|
+
never neutral-filled with `0.0`.
|
|
110
|
+
|
|
111
|
+
Every response carries `coverage` (cache vs API, oldest/newest session per symbol) and
|
|
112
|
+
`limits` (your local depth in weeks vs the tape-depth gates: 8 weeks for the tier-A
|
|
113
|
+
fast path, 26 weeks for tape eligibility). Below the gates you get an `escalation`
|
|
114
|
+
block naming the hosted `bars_1day` panel that satisfies them. Tape-tier replay is
|
|
115
|
+
**roadmap, not available** — we will not imply otherwise.
|
|
116
|
+
|
|
117
|
+
### The warden
|
|
118
|
+
|
|
119
|
+
`warden.validate_order` is the same function that rejects live orders: per-name 25% of equity,
|
|
120
|
+
gross cap 60%. Per-fund overrides are allowed, but the response always reports your
|
|
121
|
+
deviation from the house floors. `warden.audit_features` flags banned actuals sources
|
|
122
|
+
(`open-meteo.archive` and friends return *actuals*, not what the forecast said on a past
|
|
123
|
+
Friday), features predating tape start, and unknown features fail closed to tier C.
|
|
124
|
+
`warden.cost_check` converts a claimed gross edge into net-of-cost reality under the pessimistic
|
|
125
|
+
fill model (spread + slippage + adverse selection, both legs, always against you).
|
|
126
|
+
`warden.explain_sizing` is a step-by-step mirror of the C# live risk engine, and a parity test
|
|
127
|
+
pins the floors against terraform and guardrails so the three copies cannot drift.
|
|
128
|
+
|
|
129
|
+
### The gym
|
|
130
|
+
|
|
131
|
+
`gym.probe_fragility` replays your genome over the deterministic tier-A simulator and reports
|
|
132
|
+
per-regime net bps, the worst regime, turnover, and hard-constraint violations — never a
|
|
133
|
+
promotion. Seeds are capped at 8 and `per_regime` at 2: **statistical honesty, not
|
|
134
|
+
artificial scarcity**. Tier-B/C mutations against a champion raise the gym'"'"'s
|
|
135
|
+
`TierScoringRefusal` (UNSCORABLE) instead of silently neutral-filling features the price
|
|
136
|
+
panel cannot provide. `gym.paired_preview` compares champion vs challenger on identical
|
|
137
|
+
market paths with the promotion gate bypassed and every statistic labelled
|
|
138
|
+
**UNDERPOWERED**, naming the exact seed count needed to clear `MIN_EPISODES=20`.
|
|
139
|
+
|
|
140
|
+
---
|
|
141
|
+
|
|
142
|
+
## Install
|
|
143
|
+
|
|
144
|
+
Requires Python \u2265 3.11. One kind of credential:
|
|
145
|
+
|
|
146
|
+
- **Access token (all three servers, required).** Every tool call is gated on a token
|
|
147
|
+
issued by [https://1.21initiative.com/](https://1.21initiative.com/) — request access
|
|
148
|
+
there (that'"'"'s also the Strategy Validation Audit booking flow), then set
|
|
149
|
+
`SWARM_MCP_ACCESS_TOKEN` in the server'"'"'s `env`. Clients still list the tools without a
|
|
150
|
+
token; every call returns an `ACCESS_REQUIRED` envelope pointing back to the site.
|
|
151
|
+
The token is verified against the site, and that verification is the usage meter —
|
|
152
|
+
only the token itself is ever sent, never symbols, genomes, prices, or provider keys.
|
|
153
|
+
|
|
154
|
+
The same token also feeds the **hosted data relay**: `swarm-data-mcp` serves bars and
|
|
155
|
+
enrichment through `https://1.21initiative.com/api/mcp/...`, so **no Alpaca or Finnhub
|
|
156
|
+
credentials are required** — the site holds the provider keys behind the relay and caches
|
|
157
|
+
historical bars in GCS. The relay is fail-closed: a rejected or unverifiable token means a
|
|
158
|
+
refused data fetch, never partial rows. The point-in-time cache semantics on the client
|
|
159
|
+
side are unchanged — finalized sessions are immutable in local SQLite regardless of which
|
|
160
|
+
data path filled them.
|
|
161
|
+
|
|
162
|
+
### Smithery
|
|
163
|
+
|
|
164
|
+
Install [`blink-kt/quant-swarm`](https://smithery.ai/servers/blink-kt/quant-swarm) from
|
|
165
|
+
Smithery — one listing, one token, all three servers. Smithery forwards `apiToken` as the
|
|
166
|
+
`SWARM_MCP_ACCESS_TOKEN` env var (stdio) or as `?apiToken=` on the hosted endpoints; the
|
|
167
|
+
token is optional at connect time.
|
|
168
|
+
|
|
169
|
+
### Cursor
|
|
170
|
+
|
|
171
|
+
`Settings \u2192 MCP \u2192 Add server` (or `.cursor/mcp.json` — a checked-in example lives at
|
|
172
|
+
[.cursor/mcp.json](.cursor/mcp.json)):
|
|
173
|
+
|
|
174
|
+
```json
|
|
175
|
+
{
|
|
176
|
+
"mcpServers": {
|
|
177
|
+
"swarm-data": {
|
|
178
|
+
"command": "uvx",
|
|
179
|
+
"args": ["--from", "quant-swarm", "swarm-data-mcp"],
|
|
180
|
+
"env": {
|
|
181
|
+
"SWARM_MCP_ACCESS_TOKEN": "<token from https://1.21initiative.com/>"
|
|
182
|
+
}
|
|
183
|
+
},
|
|
184
|
+
"swarm-warden": {
|
|
185
|
+
"command": "uvx",
|
|
186
|
+
"args": ["--from", "quant-swarm", "swarm-warden-mcp"],
|
|
187
|
+
"env": { "SWARM_MCP_ACCESS_TOKEN": "<token from https://1.21initiative.com/>" }
|
|
188
|
+
},
|
|
189
|
+
"swarm-gym": {
|
|
190
|
+
"command": "uvx",
|
|
191
|
+
"args": ["--from", "quant-swarm", "swarm-gym-mcp"],
|
|
192
|
+
"env": { "SWARM_MCP_ACCESS_TOKEN": "<token from https://1.21initiative.com/>" }
|
|
193
|
+
}
|
|
194
|
+
}
|
|
195
|
+
}
|
|
196
|
+
```
|
|
197
|
+
|
|
198
|
+
Prefer a deeplink? `scripts/make_deeplinks.py` prints `cursor://\u2026/mcp/install` links for
|
|
199
|
+
all three servers (base64 of the stdio config, so they cannot drift from the JSON above);
|
|
200
|
+
the generated list is checked in at [.cursor/DEEPLINKS.md](.cursor/DEEPLINKS.md).
|
|
201
|
+
|
|
202
|
+
### Claude Desktop
|
|
203
|
+
|
|
204
|
+
`claude_desktop_config.json` \u2014 identical `mcpServers` block as above.
|
|
205
|
+
|
|
206
|
+
### Claude Code
|
|
207
|
+
|
|
208
|
+
```bash
|
|
209
|
+
claude mcp add swarm-data --env SWARM_MCP_ACCESS_TOKEN=<token> -- uvx --from quant-swarm swarm-data-mcp
|
|
210
|
+
claude mcp add swarm-warden --env SWARM_MCP_ACCESS_TOKEN=<token> -- uvx --from quant-swarm swarm-warden-mcp
|
|
211
|
+
claude mcp add swarm-gym --env SWARM_MCP_ACCESS_TOKEN=<token> -- uvx --from quant-swarm swarm-gym-mcp
|
|
212
|
+
```
|
|
213
|
+
|
|
214
|
+
### Windsurf
|
|
215
|
+
|
|
216
|
+
`~/.codeium/windsurf/mcp_config.json` \u2014 the same stdio JSON shape as the Cursor block
|
|
217
|
+
above. For the hosted endpoints use the `serverUrl` form instead:
|
|
218
|
+
|
|
219
|
+
```json
|
|
220
|
+
{
|
|
221
|
+
"mcpServers": {
|
|
222
|
+
"swarm-data-remote": {
|
|
223
|
+
"serverUrl": "https://swarm-mcp-503318750546.europe-west1.run.app/mcp/data"
|
|
224
|
+
}
|
|
225
|
+
}
|
|
226
|
+
}
|
|
227
|
+
```
|
|
228
|
+
|
|
229
|
+
(The hosted endpoints accept the token as `Authorization: Bearer <token>` or as
|
|
230
|
+
`?apiToken=<token>`.)
|
|
231
|
+
|
|
232
|
+
The warden and gym are pure checkers and the data server fetches through the hosted
|
|
233
|
+
relay, so **no server needs provider keys** \u2014 only the access token.
|
|
234
|
+
|
|
235
|
+
**Local development:** operators of this repo can bootstrap offline by setting
|
|
236
|
+
`SWARM_MCP_LOCAL_TOKEN` to the same value as `SWARM_MCP_ACCESS_TOKEN` (documented
|
|
237
|
+
bypass; token verification against the site is skipped and the token gets the full
|
|
238
|
+
Pro entitlement \u2014 it is a local override on your own machine).
|
|
239
|
+
|
|
240
|
+
**Swarm operators (internal):** to fetch directly from the providers instead of the
|
|
241
|
+
relay, set `SWARM_MCP_BYOK=1` plus `ALPACA_API_KEY`/`ALPACA_SECRET`/`FINNHUB_API_KEY`
|
|
242
|
+
on `swarm-data-mcp`. Public users should leave `SWARM_MCP_BYOK` unset.
|
|
243
|
+
|
|
244
|
+
**Hosting the remote endpoint yourself:** `swarm-mcp-http` validates the `Host` header
|
|
245
|
+
(DNS-rebinding protection). The defaults allow `1.21initiative.com`, the project'"'"'s Cloud
|
|
246
|
+
Run hostname, the Smithery gateway, and localhost; `SWARM_MCP_ALLOWED_HOSTS`
|
|
247
|
+
(comma-separated) **extends** the defaults \u2014 it never replaces them, so a custom domain
|
|
248
|
+
cannot accidentally lock out the Cloud Run URL. `SWARM_MCP_REMOTE_URL` overrides the
|
|
249
|
+
advertised endpoint base, and `SWARM_MCP_TOKEN_VERIFY_URL` overrides the verify endpoint.
|
|
250
|
+
See the Dockerfile for the container form.
|
|
251
|
+
|
|
252
|
+
---
|
|
253
|
+
|
|
254
|
+
## The IP boundary (what ships, what doesn'"'"'t)
|
|
255
|
+
|
|
256
|
+
This repository ships **checkers only**: order checks, provenance guards, the
|
|
257
|
+
pessimistic fill model, the genome schema, provenance tiers, hard-constraint checking,
|
|
258
|
+
gate thresholds, the tier-A gym simulator, and the regime labeller \u2014 vendored at pinned
|
|
259
|
+
commit SHAs (`.github/pins.json`, verified by CI).
|
|
260
|
+
|
|
261
|
+
The **selection machinery stays server-side** and is not in this repo: objective scoring,
|
|
262
|
+
deflated-Sharpe estimation, and the promotion-gate decision. Any request for a promotion
|
|
263
|
+
verdict returns `INDETERMINATE_LOCAL` with the exact missing statistical inputs
|
|
264
|
+
(`MIN_EPISODES=20`, PBO \u2264 0.30 via combinatorially-symmetric splits, DSR margin with the
|
|
265
|
+
monotonic trials ledger, worst-regime margin across all 5 regimes \u00d7 seeds), plus:
|
|
266
|
+
|
|
267
|
+
- an `audit_request` block \u2014 genome hash + violation summary, **no proprietary payload**;
|
|
268
|
+
- a `cloud_job` spec accepted verbatim by the hosted `POST /tournament/run`.
|
|
269
|
+
|
|
270
|
+
In v1 the handoff is manual via the **Strategy Validation Audit** booking flow at
|
|
271
|
+
[https://1.21initiative.com/](https://1.21initiative.com/) \u2014 no public ingress, no new attack
|
|
272
|
+
surface. Access requests go through the site, which is how contact details are captured and
|
|
273
|
+
how hosted API keys are issued and metered. The human conversation is the product.
|
|
274
|
+
|
|
275
|
+
## Telemetry
|
|
276
|
+
|
|
277
|
+
Off by default, opt-in only (`SWARM_MCP_TELEMETRY_OPT_IN=opt-in`), counters only
|
|
278
|
+
(tool name, success flag, coarse duration). Never symbols, genomes, prices, or
|
|
279
|
+
credentials. Institutional buyers read the source; silent phone-home destroys the wedge.
|
|
280
|
+
|
|
281
|
+
The one exception is by contract: **access-token verification**. When a token is set and
|
|
282
|
+
no local bootstrap token matches, the token is POSTed to the verify endpoint (default
|
|
283
|
+
`https://1.21initiative.com/api/mcp/verify`, override `SWARM_MCP_TOKEN_VERIFY_URL`).
|
|
284
|
+
That call is how usage is metered. Only the token is sent; the gate fails closed if the
|
|
285
|
+
endpoint is unreachable or rejects the token.
|
|
286
|
+
|
|
287
|
+
## Development
|
|
288
|
+
|
|
289
|
+
```powershell
|
|
290
|
+
pip install -e ".[test]"
|
|
291
|
+
py -3.11 -m pytest # 119 tests
|
|
292
|
+
scripts\vendor.ps1 # re-vendor the pinned checker subset
|
|
293
|
+
py -3.11 scripts\check_pin.py # vendored tree == pins.json
|
|
294
|
+
```
|
|
295
|
+
|
|
296
|
+
Vendoring uses the sibling checkouts of the private repos at the pinned SHAs
|
|
297
|
+
(`-FromWorktree` bootstraps before the pin commit exists). CI mirrors the swarm'"'"'s own
|
|
298
|
+
`guardrails-invariants` gate: it checks out the pinned SHAs and verifies the committed
|
|
299
|
+
vendored tree byte-for-byte (and the stripped subsets transform-for-transform), then runs
|
|
300
|
+
the guardrails'"'"' own invariant suite at the pinned SHA.
|
|
301
|
+
|
|
302
|
+
## License
|
|
303
|
+
|
|
304
|
+
Wrapper code: MIT (see `LICENSE`). The vendored guardrails checker subset under
|
|
305
|
+
`swarm_mcp/vendored/guardrails/` is distributed under the source-available terms in
|
|
306
|
+
`swarm_mcp/vendored/guardrails/LICENSE.md`. The excluded selection machinery is not
|
|
307
|
+
licensed.
|
|
308
|
+
|
|
309
|
+
---
|
|
310
|
+
|
|
311
|
+
*The gym is the tier-A price subset. The tape_replay service does not exist publicly.
|
|
312
|
+
Tier-B/C scoring is hosted-only. Anything else would be fabricated evidence \u2014 and this
|
|
313
|
+
repo refuses to fabricate.*
|
|
@@ -0,0 +1,285 @@
|
|
|
1
|
+
# quant-swarm
|
|
2
|
+
|
|
3
|
+
Risk-first pre-trade checks that gate live capital — point-in-time data, invariant and leakage audits, regime probes.
|
|
4
|
+
|
|
5
|
+
<!-- mcp-name: io.github.blink1217/quant-swarm -->
|
|
6
|
+
|
|
7
|
+
## Built by a Principal Quantitative Technologist
|
|
8
|
+
|
|
9
|
+
Authored by the Principal Quantitative Technologist at [The 1.21 Initiative](https://1.21initiative.com) — the same code path that gates live promotion and execution decisions in the trading swarm. Every tool exists because production trading systems fail in two repeatable ways: **lookahead leakage in research** and **an oversized position in production**. `quant-swarm` ships the checkers that prevent both, so you can audit your own work with the exact logic that guards deployed capital.
|
|
10
|
+
|
|
11
|
+
## Why risk-first
|
|
12
|
+
|
|
13
|
+
Risk gates are not post-hoc reports — they are the pre-condition for every action. The package is organized around that constraint:
|
|
14
|
+
|
|
15
|
+
- **Fail-closed by default.** Unknown features map to tier C, missing provenance returns `UNSCORABLE` (never neutral-filled), and unverifiable tokens are refused on the hosted path. See `warden.audit_features` and `features.build` provenance guards.
|
|
16
|
+
- **Pinned, non-drifting invariants.** Order sizing floors (per-name 25%, gross 60%), fill model (spread + slippage + adverse selection, both legs, always against you), and hard-constraint checks are vendored at pinned commit SHAs (`.github/pins.json`, verified byte-for-byte by CI). A parity test pins the three copies of the floors (Python/MCP, C# live engine, Terraform) so they cannot drift.
|
|
17
|
+
- **Point-in-time provenance.** SQLite WAL cache at `%LOCALAPPDATA%\1.21-initiative\swarm-mcp\cache.db` (`$XDG_CACHE_HOME/1.21-initiative/swarm-mcp` on POSIX): finalized sessions are never re-fetched, in-progress sessions refresh at most every 60 s, earnings/news are append-only on `fetched_at`, and `features.build` runs the no-lookahead guard on every row (each feature must equal a fresh causal recomputation at `as_of`).
|
|
18
|
+
- **Pessimistic execution.** `warden.cost_check` and the simulator model the fill that hurts you; there is no optimistic fill path to inflate backtests.
|
|
19
|
+
- **No order-placement code path.** No tool can place, cancel, or route an order — this repository cannot trade, only refuse unsafe trades.
|
|
20
|
+
- **Statistically honest refusals.** Promotion verdicts are **never** issued locally. Statistically undecidable outputs return `INDETERMINATE_LOCAL`/`UNDERPOWERED`/`UNSCORABLE`, name the exact missing inputs (`MIN_EPISODES=20`, PBO, DSR, worst-regime margins), and hand off to the hosted tournament / Strategy Validation Audit.
|
|
21
|
+
|
|
22
|
+
- Local-first, BYO-key: your Alpaca/Finnhub keys are read from env only when operating in BYOK mode; otherwise data flows through the hosted relay.
|
|
23
|
+
- Your symbols, genomes, and alpha never leave your machine except as an `audit_request` (genome hash + violation summary, no proprietary payload) when you explicitly escalate.
|
|
24
|
+
|
|
25
|
+
**One-click install on [Smithery](https://smithery.ai/servers/blink-kt/quant-swarm):**
|
|
26
|
+
the listing is [`blink-kt/quant-swarm`](https://smithery.ai/servers/blink-kt/quant-swarm) (package and Smithery slug are both `quant-swarm`), and it carries all three servers. Configuration is optional — without a token the servers still start and list every tool; the first call points you at the free signup. Add a token any time to unlock the relay-backed tools.
|
|
27
|
+
|
|
28
|
+
---
|
|
29
|
+
|
|
30
|
+
## The servers
|
|
31
|
+
|
|
32
|
+
| Server | Hook | Tools |
|
|
33
|
+
| --- | --- | --- |
|
|
34
|
+
| `swarm-data-mcp` | Derived-only market signals plus point-in-time feature building | `market.pulse`, `market.sentiment`, `features.build`, `cache.warm`, `cache.stats`, `cache.offline` |
|
|
35
|
+
| `swarm-warden-mcp` | Pre-trade invariant + leakage gate — the live-capital floors and the point-in-time guards | `warden.validate_order`, `warden.audit_features`, `warden.cost_check`, `warden.validate_genome`, `warden.explain_sizing`, `warden.promotion_verdict` |
|
|
36
|
+
| `swarm-gym-mcp` | Regime fragility: *which regime kills it, and is your sample even large enough to have an opinion?* | `gym.label_regimes`, `gym.probe_fragility`, `gym.paired_preview`, `gym.estimate_cloud_run` |
|
|
37
|
+
|
|
38
|
+
Raw bar/enrichment access (`get_bars` / `enrich_symbol`) is internal only and no longer
|
|
39
|
+
registered as tools — those paths echo raw provider values, and the data policy is
|
|
40
|
+
derived-only: ratios, percentile ranks, labels, buckets and counts. `market.pulse` and
|
|
41
|
+
`market.sentiment` are the general-purpose replacements; both accept an optional `bars`
|
|
42
|
+
argument so you can supply your own OHLCV rows for symbols we don'"'"'t carry.
|
|
43
|
+
|
|
44
|
+
## Plans
|
|
45
|
+
|
|
46
|
+
Access is tokened through [https://1.21initiative.com/](https://1.21initiative.com/).
|
|
47
|
+
|
|
48
|
+
- **Free** (instant token at signup): all warden checkers (`warden.validate_order`, `warden.cost_check`,
|
|
49
|
+
`warden.explain_sizing`, `warden.validate_genome`, `warden.audit_features`), the derived snapshots
|
|
50
|
+
`market.pulse` / `market.sentiment` / `market.regime` (shared-relay symbols capped at
|
|
51
|
+
10 per call, ~250 relay data calls/month), plus `cache.stats` and `cache.offline`.
|
|
52
|
+
- **Pro** (paid by one-time credit packs, self-serve at the site): everything else — `features.build`,
|
|
53
|
+
`cache.warm` bulk backfill, all gym tools, `warden.promotion_verdict`, and the Pro
|
|
54
|
+
derived tools (`market.microstructure`, `volume.forecast`, `market.screen`,
|
|
55
|
+
`market.rank`), paid by one-time credit packs (10k or 100k relay calls, 90-day validity — no subscription, no unlimited plan) with 50 symbols/call.
|
|
56
|
+
- **Institutional** (custom-quoted): Strategy Validation Audit engagements, custom
|
|
57
|
+
universes, hosted evolution runs, SLA.
|
|
58
|
+
|
|
59
|
+
Plan limits are enforced server-side (the relay, `/api/mcp/verify`, and the hosted
|
|
60
|
+
streamable-HTTP endpoint return structured `402` refusals with an `upgrade_url`). This
|
|
61
|
+
open-source client'"'"'s plan check is **advisory**: a free token calling a Pro tool gets an
|
|
62
|
+
`UPGRADE_REQUIRED` envelope — the tool still lists, and the attempt points at the upgrade
|
|
63
|
+
page. No DRM; the free plan is deliberately the zero-cost surface.
|
|
64
|
+
|
|
65
|
+
### Point-in-time data, for real
|
|
66
|
+
|
|
67
|
+
LLM-driven research re-runs cells constantly; each re-run burns Finnhub (60 req/min) and
|
|
68
|
+
Alpaca (200 req/min) budgets re-pulling identical history — and then silently builds
|
|
69
|
+
features from data that did not exist at decision time. `swarm-data-mcp` fixes both:
|
|
70
|
+
|
|
71
|
+
- SQLite (WAL) cache at `%LOCALAPPDATA%\1.21-initiative\swarm-mcp\cache.db`
|
|
72
|
+
(`$XDG_CACHE_HOME/1.21-initiative/swarm-mcp` on POSIX).
|
|
73
|
+
- **Finalized sessions are never re-fetched** — zero-cost replays forever. The
|
|
74
|
+
in-progress session refreshes at most every 60 s; enrichment every 300 s.
|
|
75
|
+
- Earnings/news are append-only on `fetched_at`: a later fetch can never rewrite an
|
|
76
|
+
earlier `as_of`.
|
|
77
|
+
- Per-provider token buckets + `429` exponential backoff (`1s\u00b72\u207f`).
|
|
78
|
+
- `features.build` runs the no-lookahead guard on every row (each feature must equal a
|
|
79
|
+
fresh causal recomputation at `as_of`) and the provenance guards on every field.
|
|
80
|
+
Tier-B/C fields without recorded point-in-time evidence come back `UNSCORABLE` —
|
|
81
|
+
never neutral-filled with `0.0`.
|
|
82
|
+
|
|
83
|
+
Every response carries `coverage` (cache vs API, oldest/newest session per symbol) and
|
|
84
|
+
`limits` (your local depth in weeks vs the tape-depth gates: 8 weeks for the tier-A
|
|
85
|
+
fast path, 26 weeks for tape eligibility). Below the gates you get an `escalation`
|
|
86
|
+
block naming the hosted `bars_1day` panel that satisfies them. Tape-tier replay is
|
|
87
|
+
**roadmap, not available** — we will not imply otherwise.
|
|
88
|
+
|
|
89
|
+
### The warden
|
|
90
|
+
|
|
91
|
+
`warden.validate_order` is the same function that rejects live orders: per-name 25% of equity,
|
|
92
|
+
gross cap 60%. Per-fund overrides are allowed, but the response always reports your
|
|
93
|
+
deviation from the house floors. `warden.audit_features` flags banned actuals sources
|
|
94
|
+
(`open-meteo.archive` and friends return *actuals*, not what the forecast said on a past
|
|
95
|
+
Friday), features predating tape start, and unknown features fail closed to tier C.
|
|
96
|
+
`warden.cost_check` converts a claimed gross edge into net-of-cost reality under the pessimistic
|
|
97
|
+
fill model (spread + slippage + adverse selection, both legs, always against you).
|
|
98
|
+
`warden.explain_sizing` is a step-by-step mirror of the C# live risk engine, and a parity test
|
|
99
|
+
pins the floors against terraform and guardrails so the three copies cannot drift.
|
|
100
|
+
|
|
101
|
+
### The gym
|
|
102
|
+
|
|
103
|
+
`gym.probe_fragility` replays your genome over the deterministic tier-A simulator and reports
|
|
104
|
+
per-regime net bps, the worst regime, turnover, and hard-constraint violations — never a
|
|
105
|
+
promotion. Seeds are capped at 8 and `per_regime` at 2: **statistical honesty, not
|
|
106
|
+
artificial scarcity**. Tier-B/C mutations against a champion raise the gym'"'"'s
|
|
107
|
+
`TierScoringRefusal` (UNSCORABLE) instead of silently neutral-filling features the price
|
|
108
|
+
panel cannot provide. `gym.paired_preview` compares champion vs challenger on identical
|
|
109
|
+
market paths with the promotion gate bypassed and every statistic labelled
|
|
110
|
+
**UNDERPOWERED**, naming the exact seed count needed to clear `MIN_EPISODES=20`.
|
|
111
|
+
|
|
112
|
+
---
|
|
113
|
+
|
|
114
|
+
## Install
|
|
115
|
+
|
|
116
|
+
Requires Python \u2265 3.11. One kind of credential:
|
|
117
|
+
|
|
118
|
+
- **Access token (all three servers, required).** Every tool call is gated on a token
|
|
119
|
+
issued by [https://1.21initiative.com/](https://1.21initiative.com/) — request access
|
|
120
|
+
there (that'"'"'s also the Strategy Validation Audit booking flow), then set
|
|
121
|
+
`SWARM_MCP_ACCESS_TOKEN` in the server'"'"'s `env`. Clients still list the tools without a
|
|
122
|
+
token; every call returns an `ACCESS_REQUIRED` envelope pointing back to the site.
|
|
123
|
+
The token is verified against the site, and that verification is the usage meter —
|
|
124
|
+
only the token itself is ever sent, never symbols, genomes, prices, or provider keys.
|
|
125
|
+
|
|
126
|
+
The same token also feeds the **hosted data relay**: `swarm-data-mcp` serves bars and
|
|
127
|
+
enrichment through `https://1.21initiative.com/api/mcp/...`, so **no Alpaca or Finnhub
|
|
128
|
+
credentials are required** — the site holds the provider keys behind the relay and caches
|
|
129
|
+
historical bars in GCS. The relay is fail-closed: a rejected or unverifiable token means a
|
|
130
|
+
refused data fetch, never partial rows. The point-in-time cache semantics on the client
|
|
131
|
+
side are unchanged — finalized sessions are immutable in local SQLite regardless of which
|
|
132
|
+
data path filled them.
|
|
133
|
+
|
|
134
|
+
### Smithery
|
|
135
|
+
|
|
136
|
+
Install [`blink-kt/quant-swarm`](https://smithery.ai/servers/blink-kt/quant-swarm) from
|
|
137
|
+
Smithery — one listing, one token, all three servers. Smithery forwards `apiToken` as the
|
|
138
|
+
`SWARM_MCP_ACCESS_TOKEN` env var (stdio) or as `?apiToken=` on the hosted endpoints; the
|
|
139
|
+
token is optional at connect time.
|
|
140
|
+
|
|
141
|
+
### Cursor
|
|
142
|
+
|
|
143
|
+
`Settings \u2192 MCP \u2192 Add server` (or `.cursor/mcp.json` — a checked-in example lives at
|
|
144
|
+
[.cursor/mcp.json](.cursor/mcp.json)):
|
|
145
|
+
|
|
146
|
+
```json
|
|
147
|
+
{
|
|
148
|
+
"mcpServers": {
|
|
149
|
+
"swarm-data": {
|
|
150
|
+
"command": "uvx",
|
|
151
|
+
"args": ["--from", "quant-swarm", "swarm-data-mcp"],
|
|
152
|
+
"env": {
|
|
153
|
+
"SWARM_MCP_ACCESS_TOKEN": "<token from https://1.21initiative.com/>"
|
|
154
|
+
}
|
|
155
|
+
},
|
|
156
|
+
"swarm-warden": {
|
|
157
|
+
"command": "uvx",
|
|
158
|
+
"args": ["--from", "quant-swarm", "swarm-warden-mcp"],
|
|
159
|
+
"env": { "SWARM_MCP_ACCESS_TOKEN": "<token from https://1.21initiative.com/>" }
|
|
160
|
+
},
|
|
161
|
+
"swarm-gym": {
|
|
162
|
+
"command": "uvx",
|
|
163
|
+
"args": ["--from", "quant-swarm", "swarm-gym-mcp"],
|
|
164
|
+
"env": { "SWARM_MCP_ACCESS_TOKEN": "<token from https://1.21initiative.com/>" }
|
|
165
|
+
}
|
|
166
|
+
}
|
|
167
|
+
}
|
|
168
|
+
```
|
|
169
|
+
|
|
170
|
+
Prefer a deeplink? `scripts/make_deeplinks.py` prints `cursor://\u2026/mcp/install` links for
|
|
171
|
+
all three servers (base64 of the stdio config, so they cannot drift from the JSON above);
|
|
172
|
+
the generated list is checked in at [.cursor/DEEPLINKS.md](.cursor/DEEPLINKS.md).
|
|
173
|
+
|
|
174
|
+
### Claude Desktop
|
|
175
|
+
|
|
176
|
+
`claude_desktop_config.json` \u2014 identical `mcpServers` block as above.
|
|
177
|
+
|
|
178
|
+
### Claude Code
|
|
179
|
+
|
|
180
|
+
```bash
|
|
181
|
+
claude mcp add swarm-data --env SWARM_MCP_ACCESS_TOKEN=<token> -- uvx --from quant-swarm swarm-data-mcp
|
|
182
|
+
claude mcp add swarm-warden --env SWARM_MCP_ACCESS_TOKEN=<token> -- uvx --from quant-swarm swarm-warden-mcp
|
|
183
|
+
claude mcp add swarm-gym --env SWARM_MCP_ACCESS_TOKEN=<token> -- uvx --from quant-swarm swarm-gym-mcp
|
|
184
|
+
```
|
|
185
|
+
|
|
186
|
+
### Windsurf
|
|
187
|
+
|
|
188
|
+
`~/.codeium/windsurf/mcp_config.json` \u2014 the same stdio JSON shape as the Cursor block
|
|
189
|
+
above. For the hosted endpoints use the `serverUrl` form instead:
|
|
190
|
+
|
|
191
|
+
```json
|
|
192
|
+
{
|
|
193
|
+
"mcpServers": {
|
|
194
|
+
"swarm-data-remote": {
|
|
195
|
+
"serverUrl": "https://swarm-mcp-503318750546.europe-west1.run.app/mcp/data"
|
|
196
|
+
}
|
|
197
|
+
}
|
|
198
|
+
}
|
|
199
|
+
```
|
|
200
|
+
|
|
201
|
+
(The hosted endpoints accept the token as `Authorization: Bearer <token>` or as
|
|
202
|
+
`?apiToken=<token>`.)
|
|
203
|
+
|
|
204
|
+
The warden and gym are pure checkers and the data server fetches through the hosted
|
|
205
|
+
relay, so **no server needs provider keys** \u2014 only the access token.
|
|
206
|
+
|
|
207
|
+
**Local development:** operators of this repo can bootstrap offline by setting
|
|
208
|
+
`SWARM_MCP_LOCAL_TOKEN` to the same value as `SWARM_MCP_ACCESS_TOKEN` (documented
|
|
209
|
+
bypass; token verification against the site is skipped and the token gets the full
|
|
210
|
+
Pro entitlement \u2014 it is a local override on your own machine).
|
|
211
|
+
|
|
212
|
+
**Swarm operators (internal):** to fetch directly from the providers instead of the
|
|
213
|
+
relay, set `SWARM_MCP_BYOK=1` plus `ALPACA_API_KEY`/`ALPACA_SECRET`/`FINNHUB_API_KEY`
|
|
214
|
+
on `swarm-data-mcp`. Public users should leave `SWARM_MCP_BYOK` unset.
|
|
215
|
+
|
|
216
|
+
**Hosting the remote endpoint yourself:** `swarm-mcp-http` validates the `Host` header
|
|
217
|
+
(DNS-rebinding protection). The defaults allow `1.21initiative.com`, the project'"'"'s Cloud
|
|
218
|
+
Run hostname, the Smithery gateway, and localhost; `SWARM_MCP_ALLOWED_HOSTS`
|
|
219
|
+
(comma-separated) **extends** the defaults \u2014 it never replaces them, so a custom domain
|
|
220
|
+
cannot accidentally lock out the Cloud Run URL. `SWARM_MCP_REMOTE_URL` overrides the
|
|
221
|
+
advertised endpoint base, and `SWARM_MCP_TOKEN_VERIFY_URL` overrides the verify endpoint.
|
|
222
|
+
See the Dockerfile for the container form.
|
|
223
|
+
|
|
224
|
+
---
|
|
225
|
+
|
|
226
|
+
## The IP boundary (what ships, what doesn'"'"'t)
|
|
227
|
+
|
|
228
|
+
This repository ships **checkers only**: order checks, provenance guards, the
|
|
229
|
+
pessimistic fill model, the genome schema, provenance tiers, hard-constraint checking,
|
|
230
|
+
gate thresholds, the tier-A gym simulator, and the regime labeller \u2014 vendored at pinned
|
|
231
|
+
commit SHAs (`.github/pins.json`, verified by CI).
|
|
232
|
+
|
|
233
|
+
The **selection machinery stays server-side** and is not in this repo: objective scoring,
|
|
234
|
+
deflated-Sharpe estimation, and the promotion-gate decision. Any request for a promotion
|
|
235
|
+
verdict returns `INDETERMINATE_LOCAL` with the exact missing statistical inputs
|
|
236
|
+
(`MIN_EPISODES=20`, PBO \u2264 0.30 via combinatorially-symmetric splits, DSR margin with the
|
|
237
|
+
monotonic trials ledger, worst-regime margin across all 5 regimes \u00d7 seeds), plus:
|
|
238
|
+
|
|
239
|
+
- an `audit_request` block \u2014 genome hash + violation summary, **no proprietary payload**;
|
|
240
|
+
- a `cloud_job` spec accepted verbatim by the hosted `POST /tournament/run`.
|
|
241
|
+
|
|
242
|
+
In v1 the handoff is manual via the **Strategy Validation Audit** booking flow at
|
|
243
|
+
[https://1.21initiative.com/](https://1.21initiative.com/) \u2014 no public ingress, no new attack
|
|
244
|
+
surface. Access requests go through the site, which is how contact details are captured and
|
|
245
|
+
how hosted API keys are issued and metered. The human conversation is the product.
|
|
246
|
+
|
|
247
|
+
## Telemetry
|
|
248
|
+
|
|
249
|
+
Off by default, opt-in only (`SWARM_MCP_TELEMETRY_OPT_IN=opt-in`), counters only
|
|
250
|
+
(tool name, success flag, coarse duration). Never symbols, genomes, prices, or
|
|
251
|
+
credentials. Institutional buyers read the source; silent phone-home destroys the wedge.
|
|
252
|
+
|
|
253
|
+
The one exception is by contract: **access-token verification**. When a token is set and
|
|
254
|
+
no local bootstrap token matches, the token is POSTed to the verify endpoint (default
|
|
255
|
+
`https://1.21initiative.com/api/mcp/verify`, override `SWARM_MCP_TOKEN_VERIFY_URL`).
|
|
256
|
+
That call is how usage is metered. Only the token is sent; the gate fails closed if the
|
|
257
|
+
endpoint is unreachable or rejects the token.
|
|
258
|
+
|
|
259
|
+
## Development
|
|
260
|
+
|
|
261
|
+
```powershell
|
|
262
|
+
pip install -e ".[test]"
|
|
263
|
+
py -3.11 -m pytest # 119 tests
|
|
264
|
+
scripts\vendor.ps1 # re-vendor the pinned checker subset
|
|
265
|
+
py -3.11 scripts\check_pin.py # vendored tree == pins.json
|
|
266
|
+
```
|
|
267
|
+
|
|
268
|
+
Vendoring uses the sibling checkouts of the private repos at the pinned SHAs
|
|
269
|
+
(`-FromWorktree` bootstraps before the pin commit exists). CI mirrors the swarm'"'"'s own
|
|
270
|
+
`guardrails-invariants` gate: it checks out the pinned SHAs and verifies the committed
|
|
271
|
+
vendored tree byte-for-byte (and the stripped subsets transform-for-transform), then runs
|
|
272
|
+
the guardrails'"'"' own invariant suite at the pinned SHA.
|
|
273
|
+
|
|
274
|
+
## License
|
|
275
|
+
|
|
276
|
+
Wrapper code: MIT (see `LICENSE`). The vendored guardrails checker subset under
|
|
277
|
+
`swarm_mcp/vendored/guardrails/` is distributed under the source-available terms in
|
|
278
|
+
`swarm_mcp/vendored/guardrails/LICENSE.md`. The excluded selection machinery is not
|
|
279
|
+
licensed.
|
|
280
|
+
|
|
281
|
+
---
|
|
282
|
+
|
|
283
|
+
*The gym is the tier-A price subset. The tape_replay service does not exist publicly.
|
|
284
|
+
Tier-B/C scoring is hosted-only. Anything else would be fabricated evidence \u2014 and this
|
|
285
|
+
repo refuses to fabricate.*
|