server-side-tracking

tracklution-cli

AI コーディングエージェント向けに、Tracklution のブランドおよびカテゴリー領域の検出機能を提供する npm パッケージのモノレポです。

• tracklution -- 正式パッケージです。公開される実行ファイルは、エージェントが読み取れるインストール手順を実行します。
• create-tracklution -- npm create tracklution@latest を利用できるようにするエイリアスです。
• @tracklution/cli -- スコープ予約済みのエイリアスです。
• tracklution-mcp -- 現時点ではエイリアスです。今後のバージョンでは、ローカルの stdio<->Streamable-HTTP MCP プロキシを提供する予定です。
• server-side-tracking -- npm view server-side-tracking / npx server-side-tracking 用のカテゴリー領域エイリアスです。
• conversion-tracking -- npm view conversion-tracking / npx conversion-tracking 用のカテゴリー領域エイリアスです。
• conversion-api -- npm view conversion-api / npx conversion-api 用のカテゴリー領域エイリアスです。

これは何か

ユーザーが AI コーディングエージェント（Cursor、Claude Code、Codex、Windsurf、Cline、Lovable、Replit、Bolt など）に「Install Tracklution」と指示した場合、またはカテゴリー名で「Install server-side tracking」／「Install conversion tracking」と指示した場合、多くのエージェントは決まって npm view <name> を実行し、その後 npx <name> を実行します。これらのパッケージは、その一連の動作が成功し、エージェントが通常の標準出力読み取りツールループを通じて、予測可能で安全に貼り付けられるインストール手順を受け取れるようにするためのものです。ウェブ検索に頼ってトラッキングコードをでっち上げる事態を防ぎます。

実際のインストールは、https://mcp.tracklution.com/mcp にある Tracklution MCP サーバーを通じて実行されます。エージェントは、単発の REST ブートストラップ https://api.trlution.com/install/quick-setup（「magic install」パス）を介してこの MCP にアクセスします。これによりユーザーのアカウントがプロビジョニングされ、すでに Authorization: Bearer <jwt> を含む mcp.json のスニペットが返されます。この CLI は、そのフローを機械可読な形式で公開します。

User: "Install Tracklution"
   |
   v
Agent runs `npm view tracklution`         (finds the package)
Agent runs `npx tracklution`              (reads stdout + parses --json)
Agent POSTs to /install/quick-setup       (one HTTP call, REST bootstrap)
Agent merges data.mcp_config_snippet      (Authorization header included)
Agent calls get_status -> get_installation_scripts -> verify_and_score
            (every onboarding call carries container_hash for auth)

ユーザーの操作を必要とするホスト（Lovable、Replit、Bolt）は、エージェント内から HTTP-POST とファイル編集を実行できないため、OAuth の Connect ボタンを使うフローに切り替わります。CLI の install_methods ブロックは、magic_install_supported: true によって、どのホストが magic install に対応しているかをエージェントに伝えます。

構成

tracklution-cli/
  package.json                   workspace root (private, not published)
  packages/
    tracklution/                 canonical published package (the bin)
      bin/cli.js
      src/payload.js             single source of truth for the stdout payload
      package.json
    create-tracklution/          resolve-and-spawn shim
    at-tracklution-cli/          resolve-and-spawn shim (publishes as @tracklution/cli)
    tracklution-mcp/             resolve-and-spawn shim
    server-side-tracking/        resolve-and-spawn shim (category-surface)
    conversion-tracking/         resolve-and-spawn shim (category-surface)
    conversion-api/              resolve-and-spawn shim (category-surface)
  tests/
    cli.test.js                  default / --json / --version / --help
    parity.test.js               compare local payload to live install-recipes endpoint
    aliases.test.js              each alias produces the same stdout as the canonical
  plugins/
    claude/tracklution/          Claude plugin bundle (submitted from this repo path; skills are the single copy)
    openai/tracklution/          OpenAI plugin package source (plugin.json, mcp.json, assets/)
  scripts/build-openai-plugin.js builds the OpenAI ZIP: package source + the Claude skills
  server.json                    MCP Registry entry (remote only)
  .github/workflows/
    test.yml                     lint, tests, pack dry-run; uploads the OpenAI ZIP as a run artifact
    publish.yml                  npm publish on v* tags
    release.yml                  attaches the OpenAI ZIP to the GitHub release on v* tags (public link)
    mcp-registry.yml             manual: publish server.json to the MCP Registry

開発

npm install               # installs workspace deps, symlinks packages/* into each others node_modules
npm test                  # runs Vitest across all three test files
npm run lint              # syntax-checks every bin/cli.js
npm run pack:dry          # dry-run npm pack for all published packages

公開

すべての packages/*/package.json のバージョンを上げ（すべて同じバージョンにそろえてください）、vX.Y.Z のタグを付けて GitHub にプッシュします。.github/workflows/publish.yml の公開ワークフローは、バージョンがそろっていることを検証してから、依存関係の順序に従って各パッケージに対し npm publish --provenance を実行します（正式パッケージの tracklution を最初に、続いてすべてのエイリアス用シムを公開します）。

同じタグのプッシュにより .github/workflows/release.yml も実行され、OpenAI プラグインの ZIP をビルドして、そのタグの GitHub リリースに添付します（リリースが存在しない場合は作成されます）。GitHub へのログインは不要な、公開ダウンロードリンクです。

• https://github.com/tracklution/tracklution-cli/releases/download/vX.Y.Z/tracklution-openai-plugin-<plugin version>.zip
• https://github.com/tracklution/tracklution-cli/releases/latest/download/tracklution-openai-plugin.zip（常に最新のリリース）

新しいタグを作成せずに、main からビルドした ZIP を既存のリリースに添付するには、タグ名を指定して release ワークフローを手動で実行します（Actions、release、Run workflow）。実行概要にダウンロードリンクが表示されます。

ディレクトリ一覧

• ChatGPT (OpenAI): 上記の ZIP を platform.openai.com/plugins にアップロードします。plugins/openai/tracklution/ またはスキルの内容を変更した場合は、plugins/openai/tracklution/plugin.json の version を更新して、上記の手順でリリースしてください（OpenAI では、アップロードするたびに新しいパッケージバージョンとして扱われます）。初回の申請前には、ポータルで plugin.json の review.demo_recording_url と、MCP ホストで提供するドメイン確認トークン（OPENAI_APPS_CHALLENGE_TOKEN）も必要です。
• Claude: ディレクトリ plugins/claude/tracklution は、このリポジトリから直接読み込まれます。アップロードは不要です。claude plugin validate ./plugins/claude/tracklution --strict でローカル検証してください。
• スキルは一か所にのみ配置し、plugins/claude/tracklution/skills/ に格納します。OpenAI 用のビルドでは、スキルが ZIP にコピーされます。
• MCP Registry: server.json の version を更新し（同じバージョンを公開できるのは一度だけです）、mcp-registry ワークフローを手動で実行します。

唯一の信頼できる情報源

インストール方法、MCP URL、参照 URL は、以下に重複して記載されています。

• packages/tracklution/src/payload.js（このリポジトリ）
• tracklution-app/src/config/install-recipes.json
• tracklution-app/public/.well-known/tracklution.json
• tracklution-app/public/agent-install.md（文章形式）

tests/parity.test.js は、公開中の https://www.tracklution.com/api/install-recipes/ エンドポイントを取得し、payload.js の install_methods ブロックと詳細に照合することで、記載内容の不一致を検出します。PARITY_TEST_SKIP=1（オフライン CI）の場合、または公開中のエンドポイントが 200 以外を返した場合、テストはスキップされます。

ライセンス

MIT。