Hive Cdn

hive-mcp-cdn

A2A 能力的边缘缓存——Hive Civilization

一个轻量级、仅入站的 MCP 服务，用于缓存任意对象（Agent 卡片、能力清单、签名信封，以及 A2A 流水线会重复读取的任何内容）。采用两层存储，包括内存 LRU 和 SQLite 热备层，并支持 ETag 和 If-None-Match、清除端点，以及通过 x402 按请求和每 GB 计量。

Council 来源：临时创建，由用户于 2026-04-27 推广。

---

这是什么

大多数 A2A 流量都是读取操作——同一张 Agent 卡片、同一份能力列表、同一份签名证明，被分发到没有共享缓存的整个集群。hive-mcp-cdn 正是缺失的边缘缓存。Agent 将对象存入键名下，再通过低成本、支持 ETag 的 GET 请求将其取回。

• **协议：**通过 Streamable-HTTP / JSON-RPC 2.0 传输的 MCP 2024-11-05
• 传输：POST /mcp
• 发现：GET /.well-known/mcp.json
• 运行状况：GET /health
• **结算：**Base L2 上的 USDC
• **品牌金色：**Pantone 1245 C / #C08D23
• **模式：**仅入站。默认 ENABLE=true。

定价

项目	价格	计费方式
每次请求	$0.0002 USDC	每次 /v1/cdn/get 请求，无论命中还是未命中。
每 GB 出站流量	$0.05 USDC	200 响应返回的正文字节数。304 响应不计出站流量费用。
预付套餐	$1.00 USDC	购买访问令牌；读取操作从预付余额中扣款，直至余额耗尽。

使用 Base L2 上的 USDC 结算。收款方为 WALLET_ADDRESS 环境变量指定的地址。

工具

工具	级别	描述
cdn_cache_get	2（$0.0002/次请求 + $0.05/GB）	按键读取缓存对象。遵循 if_none_match。
cdn_cache_put	0（免费）	在键下存储对象，可选设置 Cache-Control: max-age=...。
cdn_purge	0（免费）	清除单个键。可重复调用且结果一致。

REST 端点

方法	路径	用途
GET	/v1/cdn/get?key=...	读取。发送 ETag、Cache-Control、X-Cache、Age。遵循 If-None-Match。
POST	/v1/cdn/put	写入 { key, body, content_type?, cache_control? }。
POST	/v1/cdn/purge	清除 { key }。
GET	/v1/cdn/today	每日计数器：请求数、命中数、未命中数、已提供字节数、收入。
POST	/v1/x402/proof/submit	提交链上证明，铸造访问令牌。
GET	/v1/x402/pricing	定价计划。
GET	/v1/x402/stats	未使用的 nonce 和有效令牌。
GET	/health	服务运行状况和缓存统计信息。
GET	/.well-known/mcp.json	MCP 发现描述符。
GET	/	落地页。

存储模型

两层存储，均由 shim 管理：

• **热层（LRU）：**进程内的 Map，按插入顺序记录最近使用情况。由 CDN_LRU_MAX_ENTRIES 和 CDN_LRU_MAX_BYTES 限制容量。未命中时回退至热备层，并在读取时提升到热层。
• **热备层（SQLite）：**位于 CDN_DB_PATH 的 better-sqlite3（默认路径为 /tmp/cdn.db）。包含一个 cache 表，存储正文、ETag、内容类型、字节大小、创建时间戳和过期时间戳；另有一个 egress 表，用于汇总每日计数器。

每行都会记录 size_bytes，并以此为依据计量出站流量。ETag 在写入时计算一次，取正文的 SHA-256 十六进制值，截取前 32 个字符并加上双引号。

x402 流程

首次在没有令牌的情况下调用 /v1/cdn/get 时，会返回：

{
  "error": "payment_required",
  "payment": {
    "nonce": "<uuid>",
    "amount_usd": 1.0,
    "pricing": {
      "per_request_usd": 0.0002,
      "per_gb_egress_usd": 0.05
    },
    "accepts": [{ "chain": "base", "asset": "USDC", "recipient": "0x15184b..." }],
    "expires_at": 1777220000,
    "tier": 2,
    "product": "cdn_prepaid_bundle"
  }
}

向 /v1/x402/proof/submit 提交证明：

{ "nonce": "...", "payer": "0x...", "chain": "base", "tx_hash": "0x..." }

……然后携带 X-Hive-Access: hive_<token> 调用 /v1/cdn/get。每次请求都会按 per_request + (bytes / 1GB) * per_gb_egress 扣减预付余额。剩余余额通过响应头 X-Hive-Balance-USD 返回。

缓存语义

• PUT 请求中的 Cache-Control: max-age=<s> 用于设置 TTL。默认值为 300 秒，最长为 7 天。
• ETag 是强验证器（引号内的 SHA-256 前缀）。
• GET 请求中的 If-None-Match: <etag> 会返回 304 Not Modified，不含响应正文，也不收取出站流量费用。
• 过期条目会在读取时以及每 60 秒执行一次的扫描中延迟清除。
• 对现有键执行 PUT 会替换正文、ETag、内容类型和 TTL，并重置命中计数器。

环境变量

变量	默认值	用途
PORT	3000	HTTP 端口。
ENABLE	true	总开关。设为 false 时，仅运行 /health。
WALLET_ADDRESS	0x15184bf50b3d3f52b60434f8942b7d52f2eb436e	x402 费用的收款方。
CDN_PRICE_PER_REQUEST_USD	0.0002	每次请求的费用。
CDN_PRICE_PER_GB_EGRESS_USD	0.05	每 GB 出站流量的费用。
CDN_PREPAY_BUNDLE_USD	1.0	默认预付套餐金额。
CDN_DEFAULT_TTL_S	300	未显式指定 max-age 时对象的默认 TTL。
CDN_LRU_MAX_ENTRIES	1024	热层条目上限。
CDN_LRU_MAX_BYTES	67108864	热层字节数上限（64 MiB）。
CDN_MAX_OBJECT_BYTES	4194304	单个对象的大小上限（4 MiB）。
CDN_DB_PATH	/tmp/cdn.db	SQLite 温层路径。

此服务不会执行的操作

• 不会发出任何类型的出站请求。缓存中仅包含写入其中的内容。
• 不会解析 URL、获取源站内容，也不会针对后端存储重新验证。
• 不会强制执行按键访问控制。请将键视为不透明的命名空间；如需隐私保护，请在上游进行限制。
• 不会在 SQLite 文件之外持久化数据。在使用新的 /tmp 的全新容器中，缓存为空。

许可证

MIT。

Hive 游戏化

此 MCP 服务属于 Hive Civilization 游戏化体系（10 种机制的能力分类）。

• 能力分类：https://hive-gamification.onrender.com/.well-known/hive-gamification.json
• Centrifuge 仪表板：https://hive-gamification.onrender.com/.well-known/hive-centrifuge.json
• 汇总版 OpenAPI：https://hive-gamification.onrender.com/.well-known/openapi.json

表层标签： gamification.spec.v1 · gamification.surface.public · gamification.signal.read-only · gamification.settlement.real-rails

在 Base L2 上使用真实支付通道（USDC 0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913）。只读信号层。品牌金色 #C08D23。

Hive Civilization 目录

隶属于 Hive Civilization——面向 Agent 的金融基础设施。

• 端点目录：https://thehiveryiq.com
• 实时排行榜：https://hive-a2amev.onrender.com/leaderboard
• 收入仪表板：https://hivemine-dashboard.onrender.com
• 其他 MCP 服务：https://github.com/srotzin?tab=repositories&q=hive-mcp

品牌色：#C08D23