ClockNext

@clocknext/mcp

ClockNext MCP 服务 — 可直接通过 AI 编码工具（Claude Code、Cursor、Codex、 Antigravity，……）和其他任何 Model Context Protocol 客户端计量用量、验证信号并管理按用量计费。

它通过 本地 stdio 运行：AI 工具将其作为子进程启动，而组织的 cnk_… API 密钥保存在服务的环境变量中，绝不会进入模型的上下文。

此仓库提供 两 项内容：

• MCP 服务（@clocknext/mcp）——Agent 调用的工具。
• clocknext-onboarding 技能——逐步引导手册，通过这些工具完成完整设置（人在回路中，优先使用沙盒）。

可以一起安装（Claude Code 插件），也可以分别安装。根据你的需求和所用的 Agent 选择：

技能与 MCP 服务协同工作——技能会 驱动 工具——因此，要获得完整的引导式体验，请同时安装 两者（或直接使用包含它们的插件）。插件是一条命令即可完成安装的选项，但仅适用于 Claude Code。

使用这些工具需要 ClockNext API 密钥：Settings → API Keys → cnk_…。这是服务端机密——请将其保存在环境变量/机密配置中，切勿放入 客户端代码或代码库。

1 — 技能（适用于所有 AI 编码 Agent）

clocknext-onboarding 技能是一份引导式手册（检测模型 → 权限 → 套餐 → 计量代码库 → 使用虚拟客户测试）。它会 驱动 MCP 工具，因此也要安装 MCP 服务（见下方 §2）——仅安装技能 本身没有可调用的内容。

使用 npx skills 安装——只需一条命令，即可用于 Claude Code、Cursor、Codex、Windsurf、Gemini、Antigravity、VS Code，以及 另外约 20 种 Agent。使用 --agent 指定你的 Agent，确保技能安装到该 Agent 实际查找的位置：

# user-wide (all projects), for a specific agent:
npx skills add ClockNext/clocknext-mcp --global --agent claude-code
# …or this project only:
npx skills add ClockNext/clocknext-mcp --agent claude-code

将 claude-code 换成 cursor、codex、windsurf 等（或使用 * 为 所有检测到的 Agent 安装）。npx skills list 可查看已安装的技能； npx skills remove clocknext-onboarding 可将其移除。安装后，重启 Agent——大多数 Agent 会在启动时加载技能。

Claude Code 用户请注意。 Claude Code 只会从 ~/.claude/skills/、.claude/skills/ 或插件加载技能——不会从 CLI 默认 的通用 .agents/skills/ 文件夹加载。因此，必须传入 --agent claude-code （如上所示），这样技能才会安装到 ~/.claude/skills/（使用 --global 时）或 .claude/skills/。直接运行 npx skills add … 会将技能放入 .agents/skills/， Claude Code 永远无法在这里找到它。对于 Claude Code，最简单的方式是使用 插件——它会原生注册技能，并一步 配置好 MCP。

git clone https://github.com/ClockNext/clocknext-mcp
# Claude Code — all projects:
mkdir -p ~/.claude/skills && cp -r clocknext-mcp/skills/clocknext-onboarding ~/.claude/skills/
# …or this project only: .claude/skills/

2 — MCP 服务（适用于所有 AI 编码 Agent）

提供技能（以及你）要调用的 工具——一个 stdio 服务， npx -y @clocknext/mcp，并在其环境变量中设置 CLOCKNEXT_API_KEY。

大多数客户端都使用下方的 标准配置块——JSON 相同，只是写入的文件不同：

{
  "mcpServers": {
    "clocknext": {
      "command": "npx",
      "args": ["-y", "@clocknext/mcp"],
      "env": { "CLOCKNEXT_API_KEY": "cnk_your_key" }
    }
  }
}

CLI Agent

Claude Code —— 一条命令：

claude mcp add clocknext --env CLOCKNEXT_API_KEY=cnk_your_key -- npx -y @clocknext/mcp

Gemini CLI —— ~/.gemini/settings.json → 标准配置块。

Codex —— ~/.codex/config.toml：

[mcp_servers.clocknext]
command = "npx"
args = ["-y", "@clocknext/mcp"]
env = { CLOCKNEXT_API_KEY = "cnk_your_key" }

GitHub Copilot CLI —— copilot mcp add，或编辑 ~/.copilot/mcp-config.json：

{
  "mcpServers": {
    "clocknext": {
      "type": "local",
      "command": "npx",
      "args": ["-y", "@clocknext/mcp"],
      "env": { "CLOCKNEXT_API_KEY": "cnk_your_key" },
      "tools": ["*"]
    }
  }
}

OpenCode —— ~/.config/opencode/opencode.json（注意：根键为 mcp，command 是一个数组，环境变量字段为 environment）：

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "clocknext": {
      "type": "local",
      "command": ["npx", "-y", "@clocknext/mcp"],
      "environment": { "CLOCKNEXT_API_KEY": "cnk_your_key" },
      "enabled": true
    }
  }
}

Factory (Droid) —— droid mcp add，或在其配置文件中使用标准配置块， 并在服务中添加 "type": "stdio"：

droid mcp add --type stdio clocknext "npx -y @clocknext/mcp"

Kimi Code —— kimi mcp add clocknext -- npx -y @clocknext/mcp（在环境中设置 CLOCKNEXT_API_KEY；配置文件位于 ~/.kimi/config.toml）。

IDE

Cursor —— .cursor/mcp.json（项目级）或 ~/.cursor/mcp.json（全局）→ 标准配置块。

Windsurf —— ~/.codeium/windsurf/mcp_config.json → 标准配置块。

Antigravity —— 其 MCP 设置 JSON → 标准配置块。

Kiro —— .kiro/settings/mcp.json（项目级）或 ~/.kiro/settings/mcp.json （用户级）→ 标准配置块。Kiro 不会继承 shell 的 PATH，因此如果找不到 npx，请使用其完整路径（which npx）。

VS Code（原生 MCP / Copilot）—— .vscode/mcp.json（使用 servers，而不是 mcpServers）：

{
  "servers": {
    "clocknext": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@clocknext/mcp"],
      "env": { "CLOCKNEXT_API_KEY": "cnk_your_key" }
    }
  }
}

任何其他 MCP 客户端 —— 将其指向 stdio 命令 npx -y @clocknext/mcp， 并在 env 中设置 CLOCKNEXT_API_KEY。@clocknext/mcp 也已列入官方 MCP Registry，标识为 io.github.ClockNext/mcp，因此支持注册表发现的客户端可以直接发现它。

环境变量

3 — Claude Code 插件（仅限 Claude Code）

一条命令即可安装 MCP 服务和 clocknext-onboarding 技能，并为你配置 API 密钥。仅限 Claude Code（该插件格式属于 Claude Code；其他 Agent 请使用上文 §1 + §2）。

/plugin marketplace add ClockNext/clocknext-mcp
/plugin install clocknext@clocknext

Claude Code 会在安装时提示你输入 ClockNext API 密钥（并安全存储），运行随附的服务， 并自动从插件的 skills/ 文件夹发现技能。验证方法：

• /mcp → 查看列出的 clocknext 工具。
• 开始任何 ClockNext 相关工作时，技能都会自动触发（也可以检查 已安装的技能）。

无需手动配置，无需环境变量，也无需构建。

工具

此外还有目录 CRUD 工具（create_plan / create_credit / create_outcome / create_unit …）、客户工具（create_customer、create_purchase、 bulk_import_customers）和文档工具（search_docs、get_doc）。运行 /mcp 可查看完整列表。

典型的 Agent 工作流：whoami → list_models → get_customer_plan（确认方案，以及代码将发送的每个模型和 Agent 密钥都能解析）→ 运行产品自身的代码，使其通过 @clocknext/sdk 发送真实信号 → 调用 SDK 的 signals.usageLog({ customerId })（确认信号已送达）。clocknext-onboarding 技能会统筹这一切。

MCP 配置计费，但绝不进行计量。 根据设计，没有记录/跟踪工具，也没有预览功能：真实信号由产品代码通过 SDK（signals.credit / .wallet / .outcome）发送；这也是唯一能端到端验证集成的方式。SDK 的 signals.usageLog() 用于证明信号已送达；MCP 没有读取用量的工具。

开发

npm install
npm run build        # tsup → dist/index.js (executable bin)
npm run dev          # run from source via tsx
CLOCKNEXT_API_KEY=cnk_... npm start

基于官方的 @modelcontextprotocol/sdk 构建，并为 ClockNext API 配备了专用的小型 fetch 客户端（src/api.ts），所有内容均由 tsup 打包到 dist/ 中。目前使用 stdio；计划推出托管式 Streamable‑HTTP 版本。 日志写入 stderr（stdout 是协议通道）。已提交的 dist/ 是插件实际运行的内容——任何代码变更后都要重新构建并提交。

发布（维护者）— 自动化

推送标签后，会通过 .github/workflows/publish-mcp.yml 发布 npm 包和官方 MCP Registry 条目：

# 1. bump the version in package.json, server.json (both "version" fields),
#    src/index.ts and .claude-plugin/plugin.json; rebuild + commit:
npm run build && git commit -am "release: vX.Y.Z"

# 2. tag and push — CI does the rest:
git tag vX.Y.Z && git push origin main --tags

工作流会检查标签是否与 package.json 一致，进行构建，通过 npm publish 发布（附带来源证明），然后使用 GitHub OIDC（无需密钥）向 Registry 进行身份验证并发布 server.json。它只托管指向 npm 包的元数据，因此会先发布 npm 包。

**一次性设置：**添加一个 NPM_TOKEN 密钥（仓库 → Settings → Secrets → Actions）。 若要彻底移除该令牌，请在 npmjs.com 为 @clocknext/mcp 配置 npm 可信发布（OIDC），并删除 NODE_AUTH_TOKEN 这一行。

npm publish --access public                 # npm first — the registry validates against it
# get the publisher CLI (Linux/macOS, no brew needed):
curl -L "https://github.com/modelcontextprotocol/registry/releases/latest/download/mcp-publisher_$(uname -s | tr '[:upper:]' '[:lower:]')_$(uname -m | sed 's/x86_64/amd64/;s/aarch64/arm64/').tar.gz" | tar xz mcp-publisher
./mcp-publisher login github                # device flow — must be a ClockNext org member
./mcp-publisher publish                     # reads server.json (name io.github.ClockNext/mcp)

参阅 MCP Registry 文档。