Clocknext-Inc

@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-Inc/clocknext-mcp --global --agent claude-code
# …or this project only:
npx skills add Clocknext-Inc/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-Inc/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" }
    }
  }
}

命令行 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 是一个数组，env 为 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-Inc/mcp，因此支持注册表的客户端可以直接发现它。 （较早的条目 io.github.Clocknext/mcp 最高只到 0.13.0：GitHub 组织已更名为 Clocknext-Inc，而注册表只允许它以自己的名称发布。）

环境变量

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

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

/plugin marketplace add Clocknext-Inc/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 构建，并使用自带的小型 fetch 客户端访问 Clocknext API（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-Inc/mcp)

参阅 MCP Registry 文档。