ClockNext

@clocknext/mcp

ClockNext MCP サーバー — AI コーディングツール（Claude Code、Cursor、Codex、 Antigravity、…）やその他の Model Context Protocol クライアントから、使用量を計測し、シグナルを検証し、従量課金を管理できます。

stdio 経由でローカル実行されます。AI ツールがサブプロセスとして起動し、組織の cnk_… API キーはサーバーの環境変数に保持されます。モデルのコンテキストに渡されることはありません。

このリポジトリには2 つのものが含まれています。

• MCP サーバー（@clocknext/mcp） — エージェントが呼び出すツールです。
• clocknext-onboarding スキル — これらのツールを使ってセットアップ全体を進める手順書です（人間が介在し、サンドボックスを優先します）。

一緒に（Claude Code プラグインとして）、または別々にインストールできます。目的と使用しているエージェントに応じて選んでください。

スキルと MCP サーバーは連携します。スキルがツールを操作するため、ガイド付きのエクスペリエンスをすべて利用するには両方をインストールしてください（または、両方が含まれるプラグインを使用してください）。プラグインはコマンド 1 つで済みますが、Claude Code 専用です。

ツールを利用するには ClockNext API キーが必要です。Settings → API Keys → cnk_…。これはサーバー側のシークレットです。環境変数またはシークレット設定に保存し、クライアントコードやリポジトリには決して含めないでください。

1 — スキル（すべての AI コーディングエージェント）

clocknext-onboarding スキルは、ガイド付きの手順書です（モデルの検出 → エンタイトルメント → プラン → コードベースの使用量計測 → ダミー顧客でのテスト）。MCP ツールを操作するため、MCP サーバーもインストールしてください（§2 を参照）。スキル単体では呼び出すツールがありません。

npx skills を使えば、1 つのコマンドでインストールできます。Claude Code、Cursor、Codex、Windsurf、Gemini、Antigravity、VS Code など、約 20 種類のエージェントに対応しています。--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、…に置き換えてください（または * を指定すると、検出されたすべてのエージェントが対象になります）。npx skills list でインストール済みのスキルを確認できます。npx skills remove clocknext-onboarding で削除できます。インストール後はエージェントを再起動してください。ほとんどのエージェントは起動時にスキルを読み込みます。

Claude Code をお使いの方へ。 Claude Code がスキルを読み込むのは ~/.claude/skills/、.claude/skills/、またはプラグインからのみです。CLI のデフォルトのユニバーサルな .agents/skills/ フォルダーからは読み込みません。そのため、上記のように --agent claude-code を指定する必要があります。これにより、--global を付けた場合は ~/.claude/skills/ に、付けない場合は .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 コーディングエージェント）

スキル（およびユーザー）が呼び出すツールを提供します。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 エージェント

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 はシェルの PATH を引き継がないため、 npx が見つからない場合は、フルパスを使用してください（which npx）。

VS Code（ネイティブ MCP／Copilot）— .vscode/mcp.json（mcpServers ではなく servers を使用します）：

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

その他の MCP クライアント — stdio コマンド npx -y @clocknext/mcp を指定し、 環境変数に CLOCKNEXT_API_KEY を設定します。@clocknext/mcp は公式の MCP レジストリにも io.github.ClockNext/mcp として登録されているため、レジストリ対応クライアントから直接検出できます。

環境変数

3 — Claude Code プラグイン（Claude Code 専用）

ワンコマンドでの方法です。MCP サーバーと clocknext-onboarding スキルを一緒にインストールし、API キーも自動設定します。Claude Code 専用です （プラグイン形式は Claude Code のもので、その他のエージェントでは上記の §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を実行して確認してください。

一般的なエージェントのフロー：whoami → list_models → get_customer_plan（プランと、コードが送信するすべてのモデルキーおよびエージェントキーが解決されることを確認）→ 製品独自のコードを実行し、@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（シークレット不要）でレジストリに認証し、server.jsonを公開します。ホストするのはnpmパッケージを参照するメタデータのみなので、先にnpmへの公開が実行されます。

初回のみの設定： NPM_TOKENシークレットを追加します（リポジトリ → Settings → Secrets → Actions）。 トークンを完全になくすには、npmjs.comで@clocknext/mcpのnpm trusted publishing（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のドキュメントを参照してください。