Clocknext-Inc

@clocknext/mcp

Clocknext MCP サーバー — Claude Code、Cursor、Codex、 Antigravity などの AI コーディングツールや、その他の 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-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 などに置き換えてください（または * を指定すると、検出されたすべてのエージェントが対象になります）。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-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 コーディングエージェント）

スキル（およびユーザー）が呼び出すツールを提供します。stdio サーバー npx -y @clocknext/mcp を 1 つ起動し、環境変数に CLOCKNEXT_API_KEY を設定します。

ほとんどのクライアントでは、以下の標準ブロックを使用できます。JSON は同じで、書き込むファイルがクライアントごとに異なるだけです。

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

CLI エージェント

Claude Code — コマンドを 1 つ実行します。

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 Registry に io.github.Clocknext-Inc/mcp としても登録されているため、レジストリ対応クライアントから直接検出できます。 （古いエントリー io.github.Clocknext/mcp は 0.13.0 で更新が止まっています。GitHub 組織名が Clocknext-Inc に変更され、レジストリでは組織自身の名前でしか公開できないためです。）

環境変数

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

コマンド 1 つで設定する方法です。MCP サーバーと clocknext-onboarding スキルをまとめてインストールし、API キーも設定します。Claude Code 専用です（プラグイン形式は Claude Code のもので、ほかのエージェントでは上記の §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 を実行してください。

一般的なエージェントのフロー：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 と一致することを確認してビルドし、（ provenance 付きで）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-Inc/mcp)

MCP Registry のドキュメントを参照してください。