内容
# predmarket-mcp
一个**可变现的远程MCP服务器**，销售预测市场情报（Polymarket，Kalshi）作为其他AI代理调用并付费的工具。
不是另一个机器人：**rails**。标准化数据、价格异常检测和诚实的**可实现优势**（扣除费用/燃料/滑点后），打包成工具，代理可以依赖这些工具，而不是自己构建。
服务器是**核心引擎的薄封装**（匹配器、信号、可实现优势、存储）。它只返回**情报** - 它从不执行交易或持有资金。
> **引擎状态.** 两个可互换的引擎共享一个接口，由 `CORE_ENGINE` 选择（MCP层无论如何都不会改变）：
> - **`mock`** （默认）- 现实的，具有相同签名的存根（`core/mock.py`），以便服务器离线工作。
> - **`live`** - 真实的Polymarket + Kalshi适配器（`core/adapters/`）供给实时引擎（`core/live.py`）。需要访问场馆API的网络；如果场馆无法访问，则会优雅地回退（空结果）。
## 工具目录（12种工具，6种资源，1种提示）
描述是代理的唯一文档，因此它们被写成副本。
每个响应都带有新鲜度（`as_of` / `data_age_seconds`）和成本（`tier` / `price_usd`）。
### 免费层级（发现 + 信任 - 通道）
| 工具 | 回答内容 |
|---|---|
| `search_markets(query, category?, venue?)` | 通过关键词发现市场。 |
| `list_venues()` | 存在哪些场馆，它们的状况和覆盖范围。 |
| `track_record()` | **可验证的性能** - 标记的机会在解决时实际表现如何（命中率，优势滑点，Brier）。信任付费工具的原因。 |
| `evaluate_market(venue, market_id)` | 价格，隐含概率，深度为一个市场。**数据延迟~60s** 在免费层级。 |
### 付费层级（每次调用收入 - 实时）
| 工具 | 回答内容 | 价格/调用 |
|---|---|---|
| `find_mispricing(min_edge, kind?, category?)` | 旗舰。实时**跨场地 / 捆绑 / 荷兰书**机会在**可实现**优势阈值以上；每个风险调整（年化优势，持有天数）。签名。 | $0.05 |
| `compare_across_venues(event)` | 相同事件在不同场地：价差，方向，匹配信心。 | $0.02 |
| `estimate_execution(legs, size_usd)` | 当前深度下**您规模的**可实现优势，场地成本明细。 | $0.01 |
| `get_market_history(venue, market_id, from_ts, to_ts)` | 历史价格/价差系列。 | $0.01 |
| `watch(min_edge, kind?, category?, event?)` | **订阅**机会而不是轮询 - 注册一次，接收提醒。 | $0.02 |
| `poll_alerts()` | 检索已触发您关注的机会（一次性交付）。 | $0.005 |
价格存活在[`pricing.yaml`](./pricing.yaml)中，绝不硬编码。
- **资源：** `market://{venue}/{market_id}` - 市场快照供代理更喜欢资源而不是工具调用。
- **提示：** `arbitrage_scan_workflow(min_edge)` - 引导代理扫描→确认→估计执行→排名。
## 快速开始
```bash
uv sync # Python 3.12, 依赖项
uv run pytest # 22个测试，全部通过
uv run python -m predmarket_mcp.server # 流式HTTP在http://0.0.0.0:8000/mcp
curl -s http://127.0.0.1:8000/health # {"status":"ok",...}
# 来自Polymarket + Kalshi的实时数据（需要前往场馆API的网络出口）：
CORE_ENGINE=live uv run python -m predmarket_mcp.server
```
使用官方MCP检查器（参见[`tests/test_inspector.md`](./tests/test_inspector.md)）进行验证：
```bash
npx @modelcontextprotocol/inspector # UI → 流式HTTP → http://127.0.0.1:8000/mcp
```
## 从客户端连接
**直接HTTP代理** （Cursor，LangGraph，任何支持流式HTTP的MCP客户端）：
```json
{
"mcpServers": {
"predmarket": { "url": "https://your-host/mcp", "transport": "streamable-http" }
}
}
```
**仅stdio的主机（Claude Desktop / Claude Code）** - 使用`mcp-remote`桥接到远程服务器：
```json
{
"mcpServers": {
"predmarket": {
"command": "npx",
"args": ["-y", "mcp-remote", "https://your-host/mcp"]
}
}
}
```
## 变现
两种方式；**x402是主要的**，API密钥/计量是备用方案。两者都是惰性的，直到您翻转开关 - 服务器可以赚钱，但启动时不限制（**先使用，后计费**）。
```bash
PAID_ENABLED=false # 默认：付费工具免费，计量仍然记录使用情况
PAID_ENABLED=true # 强制对付费工具进行限制
PAYMENT_RAIL=x402 # 或 "apikey" 用于OAuth/计量的备用方案
```
### x402（代理原生，稳定币微支付）
没有签名的`X-PAYMENT`头的付费工具调用会得到一个真正的**HTTP 402**，带有x402挑战（方案，网络，金额，支付至）。重试带有有效的base64-JSON `X-PAYMENT`头→`Facilitator`验证它，记录**收据**，转发调用。结算以USDC进行。
> 默认的`MockFacilitator`进行结构验证并存根结算（`# TODO: 真实的促进者/结算`）。402流程，限制和收据日志都是真实的。
### 计量（备用）
每个付费调用通过可插拔的`MeteringBackend`写入**恰好一条使用记录**。默认是本地**SQLite**（零基础设施）；`StripeBackend` / `MoesifBackend`是具有相同接口的已键入存根。
### 配置（全部通过环境变量 - 代码中没有秘密）
| 变量 | 默认值 | 目的 |
|---|---|---|
| `CORE_ENGINE` | `mock` | `mock`（离线存根）或 `live`（Polymarket/Kalshi适配器）。实时模式需要到场馆主机的出站出口（`gamma-api.polymarket.com`，`clob.polymarket.com`，`api.elections.kalshi.com`）；如果网络策略阻止它们，实时引擎会优雅地降级为空结果，并且场馆断路器打开（已验证）。 |
| `PAID_ENABLED` | `false` | 主开关。 |
| `PAYMENT_RAIL` | `x402` | `x402` 或 `apikey`. |
| `FREE_TIER_DELAY_SECONDS` | `60` | 免费层级数据延迟。 |
| `METERING_BACKEND` | `local` | `local` \| `stripe` \| `moesif`. |
| `METERING_DB_URL` | `sqlite:///metering.db` | 使用/收据存储。 |
| `HISTORY_DB_URL` | `sqlite:///history.db` | 价格历史存储。`postgresql://` DSN启动真正的asyncpg **Timescale/Postgres**路径（如果驱动程序/数据库不可用，则降级为SQLite）。 |
| `MATCHER` | `lexical` | 跨场地匹配器层级：`lexical`（离线），`semantic`（嵌入），`hybrid`. |
| `MATCH_MIN_CONFIDENCE` | `0.45` | 匹配阈值 - 调整使用`semantic`/`hybrid`（余弦在不同尺度上）。 |
| `EMBED_BACKEND` / `EMBED_MODEL` | `fastembed` / `BAAI/bge-small-en-v1.5` | 语义层级的嵌入器。`EMBED_BACKEND=voyage`使用托管的嵌入器（镜像中没有模型 - 无服务器友好）。 |
| `VOYAGE_API_KEY` | - | `EMBED_BACKEND=voyage`所需（Voyage AI - Claude没有嵌入端点）。 |
| `RECON_DB_URL` | `sqlite:///reconciliation.db` | 跟踪记录存储（标记→解决→实现）。 |
| `WATCH_DB_URL` | `sqlite:///watches.db` | 监视/提醒订阅存储。 |
| `SIGNING_KEY` | - | 操作员秘密；当设置时，响应带有HMAC-SHA256 `provenance`签名。 |
| `SIGNING_KEY_ED25519` | - | 32字节Ed25519种子（十六进制/ base64）。优于HMAC - 对方可以使用公钥在`GET /pubkey`进行验证。 |
| `X402_OPERATOR_WALLET` | - | x402的付款地址。 |
| `X402_NETWORK` | `base-sepolia` | 结算网络。 |
| `X402_FACILITATOR_URL` | - | **设置以启用真实结算**：一个Coinbase/自行托管的x402促进者（`/verify` + `/settle`）。未设置→结构化MockFacilitator。 |
| `KALSHI_API_KEY_ID` / `KALSHI_PRIVATE_KEY`（或 `_PATH`） | - | Live Kalshi私有端点（订单簿）- RSA-PSS请求签名。 |
| `AUTH_JWKS_URI` / `AUTH_ISSUER` / `AUTH_AUDIENCE` | - | OAuth 2.1备用。 |
| `HOST` / `PORT` | `0.0.0.0` / `8000` | 绑定地址。 |
| **v2 - Provable Alpha Rail** | | *(默认全部关闭/降级)* |
| `STREAMING` | `off` | 场馆价格ticks的实时WSS摄取到历史存储。如果未设置/无`websockets`/连接断开，则降级到TTL-fetch路径。 |
| `ALERT_ENGINE` / `ALERT_ENGINE_INTERVAL` | `off` / `30` | 背景线程根据热路径触发监视；`poll_alerts`仅变为排空。关闭→触发内联（同步，服务器无害）。 |
| `ALERT_WEBHOOK_URL` / `ALERT_WEBHOOK_SECRET` | - | 将触发的提醒推送到Webhook（尽力而为；提醒在失败时仍排队`poll_alerts`）。 |
| `WATCH_MAX_PER_CLIENT` | `50` | 每个客户端的活动监视上限。 |
| `ANALYST_ENABLED` / `ANTHROPIC_API_KEY` | `off` / - | LLM解决风险分析师（Claude `claude-opus-4-8`，结构化工具输出，自适应思考）。关闭/无密钥→离线启发式。`ANALYST_MODEL`，`ANALYST_MAX_ENRICH`（`3`）调整它。 |
| `KELLY_FRACTION` | `0.5` | `estimate_execution`大小的分数Kelly乘数（半Kelly）。 |
| `FAIRVALUE_MIN_LIQUIDITY_USD` | `1.0` | 跨场地共识加权流动性下限。 |
| `MANIFOLD_ENABLED` | `off` | 添加Manifold作为第三个市场/共识场地（实时引擎）。 |
| `RATE_LIMIT_RPM` / `RATE_LIMIT_BURST` | `0` / `=RPM` | 每个客户端的令牌桶速率限制（超过时429）。`0` = 禁用。 |
| `CIRCUIT_FAIL_MAX` / `CIRCUIT_RESET_TIMEOUT` | `5` / `30` | 场馆断路器：连续失败N次后打开，冷却后半开放探测。 |
| `HISTORY_RETENTION_DAYS` | `90` | 剪枝历史记录旧于此（限流）。`0` = 保留所有。 |
| `LOG_FORMAT` / `LOG_LEVEL` | `text` / `INFO` | `LOG_FORMAT=json`用于结构化日志。 |
| **v3 - Provable Alpha（护城河）** | | *(在此构建的智能**
| `CALIBRATION_MIN_SAMPLES` / `CALIBRATION_BINS` | `30` / `10` | 来自解决历史的在线概率校准（直到有足够的结果）。 |
| `ANALYST_ENABLED` / `ANTHROPIC_API_KEY` | `off` / - | 还为结算**基础** LLM差异（结算规则比较）；否则为启发式。 |
| `RESOLUTION_ENGINE` / `RESOLUTION_INTERVAL` | `off` / `3600` | 自主解析器：结算待定标记的机会对抗场地解析API，以便跟踪记录/校准/Merkle锚点增长而无需操作员（需要`CORE_ENGINE=live`）。 |
| `OPTIONS_ENABLED` / `DERIBIT_API_URL` | `off` / deribit.com | `evaluate_market`中的期权隐含概率交叉检查（Breeden–Litzenberger）。 |
| `MICROSTRUCTURE_WINDOW` | `20` | 受限流的知情流/动量读取。 |
| `ANCHOR_ENABLED` / `ANCHOR_RPC_URL` / `ANCHOR_NETWORK` / `ANCHOR_MIN_INTERVAL` | `off` / - / `base-sepolia` / `3600` | 链上锚定跟踪记录Merkle根（mock链直到设置RPC）。 |
| `KELLY_FRACTION`（重复使用） | `0.5` | Kelly可以喂养**校准**概率，而不是原始价格。 |
**包含&期限结构套利**（C1）和`get_market_history`的**价值定价**（按范围缩放，封顶）无需标志 - 始终开启。
| **v4 - 自主性和产品深度** | | |
| `PERSISTENCE_MIN_SAMPLES` / `EXEC_HORIZON_SECONDS` | `20` / `60` | 边缘生存模型：按预期价值（边缘×存活概率）对`find_mispricing`进行排名，从机会寿命学习。 |
| `QUALITY_GATE` / `QUALITY_MIN` | `off` / `0.5` | 报价质量保护：跳过扫描过时/薄/交叉报价。建议性（在`evaluate_market`中显示）除非开启。 |
| `ADMIN_TOKEN` | - | 启用仅限操作员的`GET /revenue`（收费-vs-结算对账）；发送为`X-Admin-Token`。 |
| `ALERT_WEBHOOK_SECRET`（重复使用） | - | 现在使用Webhook正文的HMAC-SIGNATURE（`X-Signature: sha256=…）。 |
新表面：免费`event://{entity}`资源（主题的整个市场结构：相关市场，隐含/相同事件/邻居关系，传输违规，期限结构）；付费`assess_portfolio`工具（净暴露，相关性，投资组合Kelly，套期）；`simulate_strategy`现在包括样本外滚动检查。
**质量&可证明证据**（J）：每个`find_mispricing`机会带有`adverse`块 - 陷阱得分（知情流对立面+历史边缘种类+报价质量）和`trust_adjusted_edge`.传递`audit=true`为签名**audit bundle`机会：输入，价格，账本深度和时间戳，Ed25519签名，可在公共`GET /audit/{id}` - 买家独立验证边缘存在，不信任我们的说法（最深的，复制性最低的信任基元）。
**资本速度策略**（I）：`find_mispricing`价格TIME，不只是边缘 - 每个机会带有`velocity`指标（资本效率= EV per locked day，复利年增长率，book depth中的早期退出流动性），`rank="velocity"`将最快的资本周转率放在首位，并且传递`bankroll_usd`）, `rank="velocity"`把最快的资本周转率放在首位，并且传递`bankroll_usd` + `horizon_days`返回一个**rotation_plan**：分配短期机会的资本在回收时发生变化（`VELOCITY_DEFAULT_DAYS`，`ROTATION_MAX_POSITIONS`）。
**隐含分布&依赖图**（H/J）：免费`distribution://{entity}`资源重建市场的整个隐含分布，从一个阈值梯度（生存曲线，百分位数，隐含均值，任何给定区间内的概率 - 预测市场波动率表面）以及一个**连续对数正态拟合**（J2：P(X在[a,b]）用于任何范围，矩，quantiles）；免费`conditional://{event}`资源返回市场隐含P(A|B)（高斯copula从共变+确切逻辑覆盖）以及**贝叶斯信念更新**（J3：多跳P(A | B,C…)通过朴素贝叶斯对数比）。`compare_across_venues`添加一个**校准加权meta_consensus**（J4）：最佳估计+可信区间，根据每个场馆历史准确性（Brier）加权 - 随着市场解决而学习，而不是流动性。 跨场馆匹配器**从解决真相中学习** - `compare_across_venues`报告校准的匹配信心，由哪些过去的匹配实际解决相同的方式调整。
**原生多结果市场**（G）：免费`outcomes://{event}`资源从其二进制市场重建N结果事件（选举，支架编号）- **去偏见**的公平概率（移除保证金使其总和为1），超额，青睐，以及**完整感知**的完整荷兰式报价（超额设定始终是套利；如果结果集不完整，则下注是免费送的钱 - 否则会错误标记为套利路径）。适配器从场馆分组填充`event_group`（Polymarket negRisk，Kalshi事件票）。
| **水平扩展** | | *(单实例默认值不需要任何设置)* |
| `REDIS_URL` | - | x402重放保护（原子`SET NX`）和速率限制器（全局固定窗口）的共享后端。**负载均衡器后面需要正确性** - 没有它，每个实例都有自己的重放集，因此一个签名的付款可以购买每个实例的调用。 如果未设置或`redis`不可用，则降级为本地SQLite/内存。 |
| `NONCE_TTL_SECONDS` | `2592000` | Redis中已使用的付款指纹的TTL（30天）。 |
| `PG_POOL_MIN` / `PG_POOL_MAX` | `1` / `10` | asyncpg池边界，用于Postgres历史路径。 |
多实例部署：每个实例指向相同的`REDIS_URL`（重放+速率限制）和`postgresql://` `HISTORY_DB_URL`（共享时间序列）。 异步asyncpg路径在专用循环线程上运行，因此同步存储保持不变。 安装额外的功能：`--extra redis --extra postgres`。
## 部署
```bash
docker build -t predmarket-mcp .
docker run -p 8000:8000 -e PAID_ENABLED=false predmarket-mcp
# 带有可选功能的有额外功能（依赖项 + 预下载的嵌入权重）：
docker build -t predmarket-mcp \
--build-arg EXTRAS="--extra semantic --extra kalshi --extra postgres" \
--build-arg WITH_SEMANTIC=true .
```
## 布局
```
src/predmarket_mcp/
server.py FastMCP 应用；/health, /metrics, /pubkey, /track-record; HTTP 应用 + 中间件
tools.py 11 种工具（调用 core/，为代理格式化 - 无逻辑）
resources.py 市场:// · 警报:// · 事件:// · 结果:// · 分布:// · 条件:// 资源
multioutcome.py 原生 N 结果市场：de-vig + 完整集荷兰书（G）
distribution.py 从阈值梯度推断的分布 — 波动率表面（H1）
conditional.py 市场推断的 P(A|B)：高斯 copula + 逻辑覆盖（H2）
matchlearn.py 从分辨率真实性校准的匹配器（H5）
prompts.py 套利扫描工作流
config.py 环境驱动的设置（PAID_ENABLED 标志）
deps.py 核心的唯一接口
provenance.py 签名来源（首选 Ed25519，HMAC 备用）
ops.py 指标注册表，令牌桶速率限制，结构化日志
auth.py OAuth 2.1 备用线路
billing/ tiers.py · metering.py · x402.py · middleware.py
core/
models.py 规范的 pydantic 模型
algorithms.py 共享匹配器 / 信号 / 可实现边缘 + 风险终结（模拟 + 现场重用）
entailment.py 逻辑蕴涵 + 概率期限结构套利（C1）
basis.py 分辨率标准差异 / 结算基础风险（C2）
calibration.py 从历史记录的等渗在线概率校准（C3）
backtest.py 在记录的历史上进行均值回归测试（C4）
options.py 布里登-利岑伯格期权隐含概率，Deribit（C7）
microstructure.py 从磁带读取知情流 / 动量（C8）
anchor.py 跟踪记录 Merkle 根的链上锚定（C6）
fairvalue.py 流动性加权跨站点共识 + 偏差（B3）
sizing.py 分数凯利权益 + 市场影响曲线（B4）
analyst.py LLM 分辨率风险 + 基础分析师 + 离线启发式（B5/C2）
merkle.py 跟踪记录的 Merkle 承诺/证明（B6）
circuit.py 每站点电路中断器（B7）
streaming.py WSS 价格摄入（B1）· notifier.py 网络钩子警报推送（B2）
embeddings.py 语义匹配器层的嵌入后端（默认 fastembed）
mock.py 现实离线引擎（默认）
live.py 现场引擎：适配器 + 算法，TTL 缓存，历史记录摄入
storage.py 价格历史记录存储（默认 SQLite；异步 PG via DSN）
pg.py 异步 PG 循环线程桥用于同步存储（D2）
reconciliation.py 标记 → 解析 → 实现边缘 / 命中率 / Brier + Merkle 根
watches.py 监视/警报存储 + 后台 AlertEngine（推送计算，拉取排空）
adapters/ base.py · polymarket.py · kalshi.py · manifold.py （仅获取 + 标准化）
tests/ 40+ 离线测试：工具 · 计费 · 适配器 · 存储 · 匹配器 · 硬化 · 流媒体 · 推送 · 公平价值 · 尺寸 · 分析师 · 信任 · 操作 · manifold
```
## 设计原则
- **≤ 15 种工具**（此处为 7 种）— 代理工具选择在 ~25–30 后降低。
- 工具围绕 **代理问题** 构建，而非 1:1 API 端点。
- **可实现** 边缘，而非总边缘。每个响应都标记数据陈旧性。
- **无托管，无自动执行** — 仅智能。
- `core/` 逻辑 **不重复** — 工具调用引擎。
- 机密信息仅通过 **环境变量**。
## FastMCP 版本说明
规格中引用了“FastMCP 3.x”；此版本基于当前的
[`fastmcp`](https://pypi.org/project/fastmcp/) **3.x**（装饰器 API，可流式 HTTP，OAuth 帮助程序）。SSE 被故意弃用（已废弃）。
MCP 配置
以下是此 MCP Server 的配置信息，可直接复制到 Cursor 或其他 MCP 客户端中使用。
mcp.json
连接信息
猜你喜欢
暂无推荐服务器