time

Clockchain 开发者工具

一个 CLI 和一个 MCP 服务，将 Clockchain 的工具——共识时间、 公证、智能合约调度、审计轨迹和 Agent 身份验证——接入任何 MCP 客户端（Claude Code、Cursor、Claude Desktop、Codex、 Hermes、OpenClaw、……）以及你的终端。它封装了运行中的 D4 节点网关 node.clockchain.network；不会改变区块链协议。

最快上手方式——经过验证的时间闹钟，无需账户，只需一条命令（适用于 Agent 和普通用户）：

curl -fsSL https://raw.githubusercontent.com/thetangstr/clockchain-developer-tools/main/packages/clock-sdk/examples/try-alarm-mcp.sh | bash

（需要 jq；会铸造一个免费演示令牌，无需注册——在托管 MCP 服务中锚定一个闹钟，并以无密钥方式验证。） **可安全地在无人值守时运行：**无需账户、API 密钥或机密——只会在共享演示账户上消耗一条日志额度（与你的账户无关）。Agent 无需审批即可直接运行。典型运行时间约 30 秒（闹钟等待时间）；设置 CC_WAIT_S=5 可缩短等待时间。

在你的 MCP 客户端中安装：INSTALL.md——托管端点（适用于任何客户端，推荐）或自行托管（本地 stdio）。 非工程师？约 10 分钟即可试用：TRY-IT.md · 工程师：QUICKSTART.md Agent？加载操作手册：skills/clockchain-verified-alarm/SKILL.md——了解已验证时间的不变条件，以便首次使用工具时就操作正确。 路线图及当前限制：roadmap.md

快速安装——托管端点（适用于任何 MCP 客户端）

适用于任何 MCP 客户端——Claude Code、Cursor、Claude Desktop、Codex、Hermes、 OpenClaw。立即获取测试网 令牌（x-api-key）——运行 curl -X POST https://mcp.clockchain.network/token（无需注册）——然后将以下内容添加到你的 客户端 MCP 配置中：

{
  "mcpServers": {
    "clockchain": {
      "type": "http",
      "url": "https://mcp.clockchain.network/mcp",
      "headers": { "x-api-key": "<YOUR_TOKEN>" }
    }
  }
}

零凭据闹钟演示（无需账户、无需构建——需要 jq）：curl -fsSL https://raw.githubusercontent.com/thetangstr/clockchain-developer-tools/main/packages/clock-sdk/examples/try-alarm-mcp.sh | bash

使用 mcp add 命令的 CLI（以 Claude Code 为例）：

claude mcp add clockchain --transport http https://mcp.clockchain.network/mcp \
  --header "x-api-key: <YOUR_TOKEN>"

然后运行 /mcp（或客户端中的对应命令），确认 clockchain（50 个工具），并 询问：*“使用 clockchain 获取当前共识时间。”*自行托管（本地 stdio）、 使用自有密钥以及聊天连接器的配置方法见 INSTALL.md。

让 Agent 连接它——无需安装

不方便设置机器？将下面的提示词交给任何支持 MCP 的 Agent（Claude Code、Cursor、Codex、 Hermes、OpenClaw、Claude Desktop）——服务已托管，无需克隆或构建任何内容：

我想使用 Clockchain MCP 服务。它已经托管，因此不要克隆或 构建任何仓库——只需通过 HTTP 连接到远程服务。添加一个名为 clockchain 的 MCP 服务， 使用以下配置（替换为我的令牌）：

{ "mcpServers": { "clockchain": { "type": "http", "url": "https://mcp.clockchain.network/mcp", "headers": { "x-api-key": "<YOUR_TOKEN>" } } } }

然后列出你的 MCP 服务，确认 clockchain 已连接，并调用它的 get_time 工具，向我展示当前的 Clockchain 共识时间。

向团队申请每位用户专用的令牌——Clockchain 密钥保留在服务端。 同一个托管端点（https://mcp.clockchain.network/mcp）适用于任何 MCP 客户端。聊天连接器客户端（claude.ai chat、Cowork）有所不同——请参阅 INSTALL.md。

你将获得什么

七个模块中的 50 个工具：

• 时间： get_time、get_timestamp、get_block、get_validation。
• 日志记录（公证）： log_action、get_log_entry、search_actions、 verify_asset。
• 已验证的时间工具（60 秒内即可试用，无需注册：curl -fsSL https://raw.githubusercontent.com/thetangstr/clockchain-developer-tools/main/packages/clock-sdk/examples/try-clock-tools-mcp.sh | bash）：stopwatch_start、stopwatch_stop、stopwatch_verify — 通过两个锚定标记记录防篡改的经过时间；stopwatch_verify 无需密钥，即可根据两个不可变区块时间重新计算时长。 timer_set、alarm_set、timer_status、timer_cancel、timer_list — 基于共识时间托管 单次定时任务（以及重复闹钟），即使客户端离线也会触发；轮询 timer_status 获取触发状态及其回执，或在允许列表中的主机上提供 webhook_url，以接收经过签名且 DNS 固定的 POST 请求（注册时会返回每位所有者专属的验证密钥）。 回执会注明锚点所在位置（attestation.substrate）。 同样的基础功能也可通过 @clockchain/clock-sdk 在客户端运行。
• 调度器（智能合约）： get_contract_types、estimate_schedule、 create_schedule、list_schedules。类型、估算和列表功能已上线； create_schedule 是预览功能 — 后端签名消息规范尚未完成，因此该功能暂不可用。调度为非托管式：调用者使用自己的 EVM 钱包签名，服务端不会伪造签名。
• 审计（衍生功能 — 组合时间 + 日志记录 + 身份，无新增基础功能）： generate_audit_trail、generate_compliance_report（EU AI Act Art. 12 / SEC 17a-4 / ISO 27001 预设）、build_evidence_package、verify_package。
• Agent 身份（验证，在 T 时刻有效 — 非身份认证）： resolve_agent、attest_action、complete_attestation、verify_receipt、 mint_identity、revoke_identity、delegate_authority、 get_identity_history、verify_identity_at、verify_cross_party。 使用 wait=false 调用 attest_action 时会提交请求而不阻塞；complete_attestation 用于轮询，在区块写入后返回已确认的回执。
• 承诺（TSA）： tsa_issue、tsa_checkpoint、tsa_attest、 tsa_settle、tsa_status。基于锚点基础功能的承诺生命周期 — 签发 → 检查点 → 证明（履约/违约）→ 结算，以及状态查询。tsa_attest 会根据链上锚点时间与截止时间进行核对，并给出履约/broken-late/ broken 判定；后果仅记录，不执行（MVP）。

跨方验证已上线，且无需密钥： GET /searchAssetFromChain?blockHeight={h} 可在无需 API 密钥的情况下读取不可变的链上区块。该区块 — 而非可变的 /ledger/{id} 缓存 — 才是权威记录；验证结果以链上记录为准。

软件包（此单体仓库）：

软件包	说明
@clockchain/mcp-server	MCP 服务 — clockchain-mcp（dist/stdio.js），支持 stdio 和 HTTP 传输。
@clockchain/core	共享客户端、类型、哈希/回执及 ERC-8004 辅助工具（仅限 Node，无额外依赖）。
@clockchain/web-demo	浏览器聊天演示 — 通过 MCP 驱动这些工具的大模型 Agent。
@clockchain/clock-sdk	客户端已验证时间基础功能 — 校准时钟 + 闹钟/定时任务调度器 + 秒表。运行闹钟/定时任务必需（见下方说明框）。

⏰ 闹钟和计时器在客户端组件中运行——这是有意设计

MCP 服务提供信任基础功能——共识时间、防篡改公证、attest_action 和无需密钥的链上验证。秒表（可证明的经过时间）可直接通过这些工具运行。闹钟和计时器——任何在未来某个时间自动触发的功能——还需要客户端配套组件 @clockchain/clock-sdk。

这种拆分是有意为之，体现的是信任属性，而非限制：你的计划和触发的操作都留在你自己的环境中。Clockchain 从不保存你的计划或密钥，也不会代表你采取行动——它只提供中立、可验证的时间，以及每次触发的不可变且可独立验证的记录。区块链无法（而且为了保持中立，也不应该）主动唤醒你的系统；配套组件会将本地时钟校准到 Clockchain（类似 NTP），并在你的信任边界内触发，同时为回执锚定记录，以便无需密钥即可验证。

不需要 SDK 和凭据，只想看看效果？运行闹钟流程演示：bash packages/clock-sdk/examples/try-alarm-mcp.sh（或使用顶部的 curl 单行命令）。它会生成一个免费的演示令牌，并运行完整的锚定 + 无需密钥验证流程（轮询托管 MCP 上的 log_action，无需构建 SDK）。这展示了信任基础功能的触发过程，但不是客户端调度器。要真正运行真实的客户端闹钟，请使用下面的 SDK 方案，它会添加校准时钟同步和 ClockScheduler 类——这才是在你的信任边界内自动触发的真正闹钟。简而言之：MCP 流程是无需凭据即可查看锚定触发效果的方式；SDK 则是运行真实闹钟的方式。

安装并运行：packages/clock-sdk——快速入门、信任与安全模型，以及生产环境守护进程配置示例（通过 pm2 运行）。

**托管方案（路线图）：**可选的托管 keeper 将通过 MCP schedule_trigger 工具提供服务，为不想运行配套组件的团队在服务器端触发，同时提供相同的可验证回执。请参阅 roadmap.md。

面向终端的 @clockchain/cli 正在规划中——请参阅 roadmap.md。

已验证时间闹钟（clock-sdk）

根据 Clockchain 中立、可验证的时钟触发，并证明每次触发。 @clockchain/clock-sdk 是客户端的校准时钟 + 调度器：闹钟、计时器、秒表。链上部分保持为纯粹的时钟 + 公证服务；调度在你的进程中运行，每次触发都会锚定为可无需密钥验证的回执。

**工作原理：**以类似 NTP 的方式同步到 Clockchain（偏移量 + 不确定性——不是轮询，也不是信标）→ 当 clockchain_now ≥ T 时在本地触发 → 锚定此次触发（attest_action）→ 根据不可变的链上区块进行无需密钥验证。无论是否有未来签名时间信标，均可运行（时间源可插拔）。触发时间 T 时必须有进程在运行，因此调度器位于客户端（例如始终在线的主机）——区块链无法唤醒你的客户端。

状态——概念验证，已实测验证。已构建并合并（35 项单元测试；2026-06 修复了 4 个调度器 Bug）。端到端实测：读取时钟约 0.12 秒，触发到链上锚定约 1.4 秒（远低于 3 秒的预算），随后 verify_cross_party 返回 verifiedAgainst: "on-chain block", keyless: true。（这 1.4 秒指的是触发到锚定；触发前的等待时间就是你设定的延迟——也就是你的 fireAt / CC_WAIT_S，并非 SDK 开销，因此总耗时 = 你的等待时间 + 约 1.4 秒。）适用于审计、SLA 和 Agent 截止时间场景——不适用于微秒级 / 高频交易。当前为单验证者测试网，因此“法庭级”是目标，并非现阶段的承诺。

试用：

# Zero creds (MCP flow, self-serve demo token; needs jq) — start here, no account:
curl -fsSL https://raw.githubusercontent.com/thetangstr/clockchain-developer-tools/main/packages/clock-sdk/examples/try-alarm-mcp.sh | bash

# Full SDK (disciplined-clock loop) — once you have testnet gateway creds:
export CLOCKCHAIN_API_KEY=… CLOCKCHAIN_CLIENT_ID=… CLOCKCHAIN_WALLET_ID=…
curl -fsSL https://raw.githubusercontent.com/thetangstr/clockchain-developer-tools/main/packages/clock-sdk/examples/try-alarm.sh | bash

请参阅 packages/clock-sdk，了解 API、信任与安全模型，以及 Clark Slack 机器人守护进程配置示例。

在你的应用中使用（无需 npm）

@clockchain/* 包尚未发布到 npm——因此，npm install @clockchain/clock-sdk 无法正常运行。现在可以通过以下两种方式之一使用：

A — 零依赖、托管 MCP（Node 18+ 内置的 fetch，自助演示令牌）。 将以下内容粘贴到编码 Agent 中：

Add a verified-time alarm to my project — NO npm packages, Node 18+ only (built-in fetch),
against Clockchain's hosted MCP (https://mcp.clockchain.network/mcp — JSON-RPC over HTTP, SSE replies).

1. Key:  curl -X POST https://mcp.clockchain.network/token  -> demo token (no signup); use as
   header x-api-key. Mint ONCE and cache — it's IP-rate-limited.
2. call(name,args) helper: POST {jsonrpc:"2.0",id:1,method:"tools/call",params:{name,arguments:args}}
   with headers x-api-key + accept "application/json, text/event-stream". Reply is SSE — take the
   last `data:` line, JSON-parse, read result.content[0].text (itself a JSON string).
3. Alarm: poll get_timestamp (madMarzulloTime, ISO 8601 since 2026-09; older gateways used
   DD-MM-YYYY_HH:MM:SS:mmm — parse both) until consensus
   time >= your target T (never fire early), then log_action {action, asset_reference_id, content,
   wait:true, wait_ms:30000} to fire + anchor. Content is SHA-256-hashed, never stored.
4. Assert it anchored: if blockHeight is null the validator pool was degraded — treat as FAILURE,
   don't claim success.
5. Verify keylessly: verify_cross_party {ledger_id, block_height:<number>} — result nests under
   .onChain; expect verifiedAgainst "on-chain block", keyless true.

Report the fired time, blockHeight, and verify result.

B — SDK 类（纪律时钟 + 调度器）——克隆 monorepo 并构建，然后 导入工作区包（npm 链接，无需注册表）：

git clone --depth 1 https://github.com/thetangstr/clockchain-developer-tools.git
cd clockchain-developer-tools && npm install && npm run build
# then import @clockchain/clock-sdk / @clockchain/core from within the workspace,
# or copy packages/clock-sdk/examples/alarm-live.mjs as a starting point.

等到包发布后，npm install @clockchain/clock-sdk @clockchain/core 就可以正常运行——请参阅 roadmap.md。

路线图

阶段	范围	状态
0 · 重新标注 + 文档	明确 create_schedule 是合约部署，而不是闹钟；发布文档	✅ 已完成
1 · 客户端 SDK	纪律时钟 + 调度器（Alarm / Timer / Stopwatch）+ 示例	✅ 已构建并合并；PoC 已通过实时验证
2 · 托管 keeper	通过 MCP schedule_trigger 工具进行链下调度——零安装、离线时也能触发；可靠交付（重试 / 幂等性 / DLQ）	◻ 下一步（按需）
3 · 多验证器	实现可用于法庭级别的主张	◻ 尚未开放（受协议路线图限制）

**可靠性门槛：**触发必须实际锚定——验证器池降级可能导致回执仅缓存在缓存中（blockHeight 为 null）。此问题已跟踪为 P0（锚定前不要报告成功）；多验证器（第 3 阶段）将解决验证器池参与度问题。try-alarm-mcp.sh 脚本会自动检测并处理此情况——无需手动操作。

状态

正在对接实时网关。MCP 服务已验证可用—— initialize + tools/list 返回 50 个工具，实时调用也能成功。已验证的功能（更新于 2026-06-11）：

• 时间：通过公开的 /getTime 读取共识时间（无需密钥权限范围）。使用日志权限范围的密钥调用 /api/time/* 系列接口会返回 401。
• **公证：**已确认 /log、/ledger/{id}、/searchAsset、 /getValidationBlock 均可正常工作——记录、链上确认、检索、验证。
• **跨方验证：**实时可用且无需密钥—— GET /searchAssetFromChain?blockHeight={h} 无需 API 密钥即可读取不可变的链上区块， 该区块是权威记录。
• **智能合约调度：**合约类型、估算和列表接口均已上线； create_schedule 仅提供预览，因后端签名消息规范尚未完成而受阻。 基于签名且非托管（由调用方的 EVM 钱包签名）。
• **Agent 身份：**验证（在时间 T 有效），而非身份认证。ERC-8004 注册表已上线并可解析；身份图谱写入操作（mint/revoke/delegate） 会对接到仍处于预览阶段的目录。

**为可用于法庭级别的证据而设计。**单验证器测试网；速率限制严格。

当前的完整限制 + 路线图：roadmap.md。

托管、CI/CD 与运维

托管在 GCP Cloud Run 上，地址为 https://mcp.clockchain.network/mcp（受令牌保护 + 自带密钥），推送到 main 后会在通过测试门禁后自动部署。

文件	内容
CLOUD-RUN.md	部署与运维手册：无密钥 WIF CI/CD、Cloud Armor、监控、密钥/令牌轮换、回滚。托管文档的权威版本。
cicd-plan.md	CI/CD 流水线、不可妥协的规则及后续计划。
AGENTS.md	贡献者/Agent 指南——推送前运行测试，绝不绕过部署门禁，每个工作树仅运行一个 Agent。
auth-and-traffic-decision.md	单一 ID 入口、委派访问与自带密钥、Cowork 与 Claude Code、渠道/流量及成本模型。
agentdash-mcp-integration-brief.md	提供给 AgentDash 团队的交接简报，用于集成托管的 MCP。
eval/	按执行结果评分的评估工具：Layer-A 性能测试 + Layer-B Agent 任务套件（链上检查，不使用 LLM 评审）。
RETRO-2026-06-13.md	06-11 → 06-13 构建复盘（Cloud Run、CI/CD、TSA、评估）。

下方的 DELEGATED-ACCESS.md 描述的是已弃用的 Mac-mini 方案，现已由 CLOUD-RUN.md 取代。

规格说明与规划文档

背景、设计决策和发布计划（本仓库最初是这项工作的规划场所，这些文档目前仍保存在这里）：

文件	内容	适用对象
mcp-deployment-brief.md	审批请从此处开始。 一页简报：需求、部署依赖项及网络暴露模型，并附有面向利益相关方、网络团队和后端团队的签批栏。	利益相关方 / 网络 / 后端
DELEGATED-ACCESS.md	无需 API 密钥或 VPN，即可让测试人员获得访问权限：在 Web 演示和 MCP 端点前设置 Cloudflare Access，并限制令牌、速率和预算。	工程 / 运维
implementation-plan.md	完整技术规格与构建计划。权威信息来源。	工程
implementation-plan-technical.html	规格的幻灯片版本，包含设计细节。	工程评审
implementation-plan.html	简短的高层概览演示文稿。	业务 / 利益相关方
product-findings.md	基于实时网络和控制面板的实测发现。	产品 / 工程
industry-landscape.md	关于领先的时间戳/溯源平台如何运作，以及 Clockchain 可以在哪些方面实现差异化的证据。	产品 / 战略
mcp-readiness.md	基于实时测试，对哪些 API 已具备条件成为 Products A & B 的 MCP 工具进行逐项评估。	工程 / 产品
journeys.md	开发者和 Agent 的端到端使用旅程，标明当前 API 流程支持或阻碍自主 Agent 使用的环节。	工程 / 产品
product-a-identity-decision.md	决策备忘录：Agent 身份采用专有 DID 还是 ERC-8004 + SIWA。建议采用混合方案——遵循标准，并在时间/验证方面实现差异化。	产品 / 领导层
deployment.md	托管计划：本地 stdio（开发者）、Mac mini 测试主机（业务用户 + AgentDash）以及 AWS 生产计划和信息清单。	工程 / 运维
poc-build-plan.md	在 Mac mini 上运行 MCP 服务的目标与分步计划，以及它如何连接到 Clockchain。	工程 / 领导层
roadmap.md	当前路线图、已实现功能及已知限制。	产品 / 工程

在浏览器中打开任一 .html 文件即可进行演示（使用方向键导航， 按 Esc 查看幻灯片概览）。