cp0x public data

cp0x MCP

由 cp0x 拥有的只读 MCP 服务，提供 cp0x 公开数据。

工具

工具	返回内容	参数
list_deals	符合条件的优惠，包括奖金、推荐链接和代码、比赛摘要，以及匹配总数。	可选 query：场馆标题或 slug 中不区分大小写的子字符串（最多 100 个字符）；可选 limit：1–100；省略时返回所有匹配项。
get_deal	完整的优惠记录，包括其描述和比赛；如果优惠不存在，则返回已知 slug。	必填 slug：优惠 slug（最多 100 个字符）。
get_referral_code	匹配场馆的优惠、推荐代码和链接；如果有多个匹配项，则返回候选名称和 slug。	必填 venue：场馆名称或 slug（最多 100 个字符）；精确匹配优先于子字符串匹配。
list_races	比赛代码、标题、状态、日期，以及每场比赛对应的优惠 slug。	可选 status：active 或 completed；省略时返回两种状态；可选 slug：优惠 slug（最多 100 个字符）。
get_leaderboard	比赛详情、列定义、领先条目，以及条目总数。	必填 slug（最多 100 个字符）；可选 race_code（默认为 leaderboard）；可选 top：1–100（默认为 20）。
check_interface_restrictions	接口声明的限制、观测到的探测结果、替代方案、图例、快照版本和 country_match；如果没有精确匹配项，则返回候选接口。	必填 protocol：接口名称或 ID（最多 100 个字符）；可选 country：ISO 3166 alpha-2 代码；省略时返回所有观测到的国家。
list_restricted_interfaces	存在国家级、仅限平仓、区域性或观测到的限制的接口，包括 scope、declared_layers、close_only_layers、regions 和 observed_block。	必填 country：ISO 3166 alpha-2 代码。
list_x402_facilitators	公开的 facilitator 目录，包括名称和 URL。	无。
list_cp0x_x402_resources	cp0x 资源目录条目，包括价格、标签和目标 URL。	可选 tag：不区分大小写的标签匹配。
about_cp0x	以 distributed_to_users 开头：按今日代币价格计算的用户所得总额、每笔代币数量或现金奖励分配，以及分配时的价值。包含已发布的 cp0x 概况表：使命、价值观、活动、站点、渠道、资助和 2025 年数据。	无。
list_cp0x_open_source	公开的 cp0x 仓库，包括描述、URL、主页、类型、星标数、主题、推送日期、分支标记和数量，并按最近推送时间排序。排除已归档和私有仓库，以及 pi- 接口以外的分支。	可选 kind：interface 或 project；省略时返回两种类型。

结果包含来源归属和 stale 标记；失败时可能包含 error 字段。推荐代码按发布内容返回，不会虚构缺失的代码。

上游数据的新鲜度和重试字段（about_cp0x 将这些字段保留在 distributed_to_users.prices 中；其顶层 stale 始终为 false）。缺失代币价格时会返回部分总额，并在摘要中列出缺价的代币；如果没有任何代币有价格，摘要将使用分配时的价值。价格错误保留在 distributed_to_users.prices 中：

• stale：由于刷新失败或请求暂停而返回过期缓存数据时为 true。
• fetched_at：所用最早上游响应的 UTC 时间戳；如果没有可用响应，则为 null。
• age_s：最早响应的秒数；如果没有可用响应，则为 null。
• stale_since：结果为陈旧数据时，最早响应的缓存 TTL 过期时间的 UTC 时间戳；否则为 null。
• retry_after_s：发生上游错误时包含；当预算、退避或负缓存阻止请求时，表示重试前等待的整数秒数；如果是首次普通失败，则为 null。 对于 check_interface_restrictions，country_match 包含 national 和 close_only 标志、与 regions 中区域代码匹配的结果，以及 status（产生该匹配的声明状态；若没有声明匹配，则为 null）；未提供国家/地区时，country_match 为 null。对于 list_restricted_interfaces 中的每个条目，scope 按优先级顺序取值 national、close_only、regional 或 observed。declared_status 字段记录 national、close-only 和 regional 匹配对应层级的状态；对于仅 observed 的匹配，该字段为 null。当多个声明匹配时，两个状态字段都采用该范围优先级顺序中第一个层级的状态。close_only_layers 字段列出仅允许平仓的层级；regions 列出匹配的细分区域，例如 CA-ON。

示例问题：“Extended 有哪些推荐交易优惠？”“目前有哪些赛事正在进行？”以及“监控报告显示 Aave 在美国有哪些界面限制？”

连接

公开的 Streamable HTTP URL：https://mcp.cp0x.com/mcp

无需身份验证。

Claude（连接器 / Desktop）

在 Claude 连接器或 Claude Desktop 中，使用 https://mcp.cp0x.com/mcp 按 URL 添加远程 MCP 服务，无需身份验证。

ChatGPT

使用 https://mcp.cp0x.com/mcp 作为自定义 MCP 连接器，按 URL 添加远程 MCP 服务，无需身份验证。

Cursor

在 mcp.json 中按 URL 添加远程 MCP 服务：

{
  "mcpServers": {
    "cp0x": {
      "url": "https://mcp.cp0x.com/mcp"
    }
  }
}

Perplexity

使用 https://mcp.cp0x.com/mcp 按 URL 添加远程 MCP 服务；将身份验证选为 None。

数据来源与时效性

来源	公开端点	缓存 TTL
cp0x 优惠与赛事	优惠 API；排行榜位于 https://cp0x.com/api/v1/deals/{slug}/races/{race_code}。	优惠和排行榜为 60 秒。
DeFi 界面限制监控	来自公开监控仓库的界面目录和观测记录。	600 秒。
cp0x x402 目录	Facilitators 和 cp0x resources。	300 秒。
cp0x 开源仓库	cp0x-org 的 api.github.com 公开仓库 API；无需 API 密钥。	10 分钟（600 秒）。
代币价格	用于一次请求获取 HYPE、LIT、DRV、RESOLV 和 DIME 的美元价格的 CoinGecko 公开端点；无需 API 密钥。供 distributed_to_users 使用。	60 秒。
cp0x 静态信息表	cp0x_mcp/data/about.json，随服务一同提供；数据来自 cp0x 2025 年度报告。	加载到内存一次；不会发起网络请求，也不会定时刷新。

监控数据是已发布的仓库快照，而非实时探测。其版本来自目录的 meta.generated 字段，并由 check_interface_restrictions 作为 data_version 返回。观测记录描述已记录的检查；缺少探测记录并不能证明服务可用。

缓存由各服务实例本地维护，过期后按需刷新。如果上游请求失败，可返回现有缓存响应，并将 stale 设为 true；若没有缓存数据，结果中会包含 error。缓存 TTL 不保证上游数据已发生变化。

速率限制

HTTP 服务默认将每个调用方 IP 的请求数限制为 60 次/分钟，可通过 --per-ip-per-minute 配置。超过限制的请求会收到 HTTP 429，并附带以秒为单位的 Retry-After 标头。

上游 cp0x.com API 也将每个 IP 的请求数限制为 60 次/分钟。该服务的所有上游请求共用同一个出口 IP；缓存读取可减少上游流量。

每个服务实例的所有工具共用每个主机 45 次上游请求/分钟的额度，按主机和端口计数，并在滚动的 60 秒时间窗口内统计。只有实际的上游调用会消耗额度；缓存命中不会消耗额度。额度耗尽时，会返回已过期的缓存数据，并将 stale 设为 true；如果没有缓存数据，结果中会包含 error 和 retry_after_s。上游 HTTP 429 会根据 Retry-After 触发主机级退避（缺少该标头或其值不是数字时为 60 秒），并采用相同的过期缓存回退策略。没有缓存数据时，普通故障会按 URL 负缓存 30 秒；重复请求会返回错误和剩余的 retry_after_s，但不会再次调用上游。首次普通故障会将 retry_after_s 设为 null。

本地运行

使用 Python 3.10 或更高版本从仓库安装：

pip install -e .

通过 stdio 运行：

cp0x-mcp --transport stdio

通过 HTTP 运行：

cp0x-mcp --transport http --host 127.0.0.1 --port 8000 --allowed-host localhost:8000 --allowed-host 127.0.0.1:8000

HTTP 路由为 /mcp 和 /health。配置 --allowed-host，使其与客户端的 Host 标头匹配；必要时需包含端口。未提供允许列表时，会允许带端口或不带端口的 localhost 和 127.0.0.1。

在反向代理后部署

Uvicorn 会读取 FORWARDED_ALLOW_IPS，以决定哪些代理可以提供转发的客户端 IP。将其设为反向代理的 IP 地址，这样调用方速率限制就会使用 X-Forwarded-For 中的原始客户端 IP。如果未设置受信任代理，所有经由不受信任代理的调用方都会共用一个以代理 IP 为键的速率限制额度。

Docker 镜像将 FORWARDED_ALLOW_IPS="*" 设为默认值。使用此设置时，端口 8000 必须只能由反向代理访问。否则，请通过环境变量覆盖将 * 替换为代理 IP。对于运行在 Docker 主机上的代理，请将发布端口绑定到 loopback：

构建并运行 Docker 镜像：

docker build -t cp0x-mcp .
docker run -p 127.0.0.1:8000:8000 cp0x-mcp

将 /mcp 和 /health 转发到端口 8000，并保留公开的 Host 标头。镜像会绑定到所有接口，并允许 Host 标头为 mcp.cp0x.com 和 mcp.cp0x.com:*。向容器发送本地请求时，必须使用允许的 Host 标头。容器的健康检查会向 loopback 上的 /health 发送请求，并使用 Host: mcp.cp0x.com；此路由也会检查主机允许列表和调用方速率限制。

发布

将 server.json 保留在仓库根目录。该文件声明了 com.cp0x/public-data、版本 0.1.0 和公开的 Streamable HTTP 端点；发布此远程服务无需提供包。

发布到 MCP Registry 前，请通过域名顶点处的 DNS TXT 记录或在 https://cp0x.com/.well-known/mcp-registry-auth 上提供 HTTP 验证来证明你拥有 cp0x.com。使用相应的域名验证方式通过 mcp-publisher 进行身份验证，然后在仓库根目录运行：

mcp-publisher validate
mcp-publisher publish

Glama 在为 GitHub 仓库编制索引时，会读取根目录中的 glama.json 获取维护者元数据。

披露说明

交易链接包含 cp0x 推荐码。该服务仅读取公开数据；不会下单交易，也不会执行付费的 x402 请求。采用 MIT 许可证，详见 LICENSE。隐私政策：详见 PRIVACY.md。