ttctl

TTCtl

ご自身のToptal Talentプロフィール向けの、個人生産性向上CLIおよびMCPサーバーです。

⚠️ 非公式 — 個人利用のみ

TTCtlはToptal LLCと提携しておらず、同社の推奨やサポートを受けていません。 本ツールは個人生産性向上ツールであり、ご自身のセッションを使用してToptal Talentのウェブ／モバイルインターフェイスとやり取りし、ご自身のプロフィールのデータだけを扱います。

本ツールはフェアユースを目的に開発され、ご自身のプロフィールで同様のツールを利用したい他のToptal人材にも役立つ場合に備えて公開されています。次の用途には使用しないでください。

• リクルーター／クライアントへのスパムや、依頼されていない営業連絡
• 求人への応募、プロフィールの更新、メッセージ送信の大規模な自動化
• エンゲージメントシグナルの操作、応募の大量送信、リクルーター情報のスクレイピング
• ご自身以外のプロフィールに対する操作
• Toptalの利用規約に違反する、またはプラットフォームに負荷をかける行為

TTCtlの不正利用を見かけた場合は、SECURITY.mdの不正利用の報告をご覧ください。

コードベースにおけるアーキテクチャ上の制約（順次適用されるレート制限、単一認証情報の設計、自動化されやすいエンドポイントでのバッチ並列処理の禁止）は意図的なものです。取り除かないでください。

「Toptal」はToptal LLCの商標です。本プロジェクトの説明での名称の使用は、指示的フェアユースに限られます。TTCtlはToptalブランドではありません。

できること

TTCtl を使うと、自分の Toptal Talent プロフィールにプログラムからアクセスできます（MCP 経由で AI アシスタントからもアクセスできます）。

• プロフィール — タレントプロフィール（基本情報、スキル、職歴、学歴、資格、業界、ポートフォリオ、ビザ、履歴書、外部リンク、レビュー、写真）の表示と更新
• 応募 — アクティビティ項目（応募、稼働状況のリクエスト、面接、エンゲージメントのシグナル）の確認、applications stats によるステータスグループ別件数の取得、applications confirm / applications reject による未対応の Interest Request の承諾／拒否、applications interview show <id> による面接詳細（面接官と TopChat スレッドのハンドル、クライアント側の連絡先、予定日時、アジェンダリンク、準備ガイドの参照情報）の取得、applications interview notes show <jobId> による面接準備メモの閲覧、applications availability-request show <id> による稼働状況リクエストの詳細（ステータス、種類、リクルーターの固定報酬、コメント、ライフサイクルのタイムスタンプ、仕事）の取得
• エンゲージメント — 現在および過去のエンゲージメントの表示、エンゲージメントの休止期間の管理、engagements stats によるステータス別件数の取得
• 仕事 — 案件の閲覧（アルゴリズムによる jobs recommended フィード、案件ごとの jobs match-quality によるマッチスコアの内訳、案件ごとの jobs rate-insight による報酬情報パネルを含む）、保存済み／閲覧済み／興味なしのシグナルの管理、検索サブスクリプションの設定、jobs apply <id> --consent による直接応募（法令遵守のためのゲートは必須）。--suggest-answers を追加すると、過去に回答した類似の質問への自分の回答を取得し、参考用のオートコンプリート候補として提示できます（オプトイン方式で、応募のクリティカルパス外にあり、失敗しても正常に処理を続行します）。MCP ツール ttctl_jobs_apply_similar_answers からも、エージェントが同じ機能を利用できます。
• タイムシート — タイムシートの請求サイクルの一覧表示、閲覧、更新、提出
• 稼働状況 — 勤務時間と週あたりの割り当て時間の表示と更新
• 契約 — タレントレベルの契約（Toptal Direct、MSA など）の閲覧
• 支払い — 支払い履歴、支払い合計額（payments summary）、支払い方法の閲覧、payments rate current（軽量）または統合された payments rate show による現在の時間単価の表示、単価変更リクエストの提出
• アンケート — 未回答のアンケートの一覧表示、構造化された回答の提出、面接後／NPS プロンプトへの自由記述フィードバックの追加。回答とフィードバックは取り消せず、同意が必要です
• 認証 — 設定の初期化、サインイン、ステータス確認、サインアウト

利用可能な機能は、読み取り中心の個人利用に限定されています。プラットフォームに対する大規模な自動化を可能にする操作は、意図的に公開していません。

対象外

以下の Toptal Talent の機能は、設計上対象外です。悪用（大量自動化やスパムにつながる要因）を可能にする、TTCtl が依存しないサードパーティー SDK が必要になる、タレント側のワークフローではなくクライアントのオンボーディングを対象とする、スタッフ側またはソーシング側のワークフローに属する、あるいは一度限り／モバイル専用の UI 機能で CLI で繰り返し利用する価値がないためです。

• 通知設定 — UpdateJobAlertSettings、UpdateSmsNotificationsSettings、UpdateTimesheetReminderSettings、UpdateNotificationSetting（悪用防止 — アラートの停止は、別の悪用につながる前兆となるため）
• コミュニティ／Slack でのやり取り — イベント、チャンネル、メッセージ、出欠確認（サードパーティー SDK — コミュニティへの参加は人間向けであり、CLI 向けではないため）
• 紹介のフロー — 紹介の送信、報酬の受け取り、紹介者の追跡（悪用防止 — 紹介をプログラムで生成することはスパムにつながるため）
• クライアントになる／相談／コーチング／ギグ — 購入者側のワークフロー（クライアントのオンボーディング — タレント側のプロフィール管理ではないため）
• Hire-me ページの公開 — 公開用のマーケティングページ（一度限りの操作 — 繰り返し更新するプロフィールの状態ではないため）
• ビデオピッチ／Zendesk 連携 — Ziggeo／CameraTag および Zendesk を利用する機能（サードパーティー SDK — TTCtl が対象とする GraphQL の機能ではないため）
• TopChat のメッセージ機能 — メッセージとファイルのダウンロードは引き続き対象外です。applications interview show では、面接官ごとの検索用ハンドルのみを公開します（機能全体の追跡先は #23）
• モバイル専用ウィジェット — Story、MobileTopTip、MarketCondition（モバイル専用 UI — CLI で同等の価値を提供できないため）
• クイズ／質問票 — オンボーディング時の最終フォーム（一度限りの操作 — 繰り返し更新するプロフィールの状態ではないため）
• スタッフ側のワークフロー — SEND_CONTRACTS、推薦文の公開、スナップショット履歴（スタッフ側 — Toptal スタッフ向けの機能であり、タレント向けではないため）
• タレントのソーシング用シグナル — CreateTalentSignal、GetTalentSignalSetup（ソーシング側 — リクルーター／スタッフがタレントを特定するためのものであり、タレント側の機能ではないため）

注：scheduler.toptal.com の機能（面接のスケジュール設定）は、設計上対象外なのではなく、現在まだ実装されていません。リバースエンジニアリングの調査が完了するまで延期されています。

対象範囲に含まれる機能については、上記の機能をご覧ください。

前提条件

• Node.js >= 22.19.0
• Toptal Talent のプロフィール（これを使用するには Toptal のタレントである必要があります。ほかのユーザーには価値がありません）
• 推奨：認証情報の解決に使用する 1Password CLI（op）

対応プラットフォーム

TTCtl は、Cloudflare で保護された機能（プロフィール編集）で Chrome の TLS フィンガープリントを偽装するために node-wreq を使用します。このトランスポートはビルド済みのネイティブバイナリとして提供され、次の環境で利用できます。

未対応のプラットフォームでも、npm install -g ttctl は成功します（ネイティブバイナリはオプションの依存関係です）。モバイルゲートウェイのコマンドも引き続き動作します。ただし、Cloudflare で保護されたコマンド（プロフィールを編集するコマンド）はすべて、プラットフォーム名と対応環境の一覧を示す NATIVE_MODULE_UNAVAILABLE エラーを出して失敗します。未対応の 2 つの環境への対応が必要な場合は、issue を作成してください。

インストール

npm install -g ttctl

または、npx を使って直接実行します。

npx ttctl --help

セキュリティを強化したインストール（推奨）

サプライチェーンの安全性を最大限に高めるには、postinstall フックを無効にしてインストールします。

npm install -g --ignore-scripts ttctl

--ignore-scripts は、インストール時に依存関係ツリー全体の preinstall／postinstall／prepare フックをブロックします。これにより、侵害された推移的依存関係（PhantomRaven、Shai-Hulud など）がインストール中にマシン上でコードを実行するのを防ぎ、パッケージマネージャーのユーザーを標的とする、最も悪用されているサプライチェーン攻撃の経路を遮断します。

TTCtl 自体には、インストール時のフックは含まれていません。これらを無効にするのは、直接管理していない依存関係の悪意ある動作を防ぐためだけです。SECURITY § ユーザーインストール時のサプライチェーン強化を参照してください。

クイックスタート

# 1. Install
npm install -g ttctl

# 2. Bootstrap a config interactively (recommended)
#    Walks you through Form A (1Password reference; vault + item picker
#    when the `op` CLI is installed) or Form B (literal credentials,
#    explicit warning). Output: ~/.ttctl.yaml at mode 0600.
ttctl auth init

# 3. Sign in (captures the bearer back into ~/.ttctl.yaml under auth.token)
ttctl auth signin

# 4. Verify
ttctl auth status

# 5. View your profile
ttctl profile show

ttctl auth init は、対話形式で新しい ~/.ttctl.yaml を生成します。フォーム A（1Password の参照、推奨）またはフォーム B（認証情報を直接記述、非推奨。明示的な警告で保護されています）を選択します。フォーム A で op CLI がインストールされている場合は、ボールト選択と LOGIN カテゴリーのアイテム選択が実行されます。op がない場合、または JSON の形式に問題がある場合は、プロンプトが自由形式の op://VAULT/ITEM 参照に切り替わります。出力ファイルはモード 0600 でアトミックに書き込まれ、--force が指定されない限り、既存のファイルを上書きしません。このコマンドは対話形式でのみ実行できます。stdin がパイプされている場合、または TTY 以外の環境では、明確なメッセージを表示してゼロ以外の終了コードで終了します。

ttctl auth signin は EmailPasswordSignIn GraphQL ミューテーションを実行してセッションベアラーを取得し、同じ ~/.ttctl.yaml ファイルの auth.token に書き戻します（アトミック書き込み、コメントを保持、モード 0600）。以降のすべてのコマンドでは、各 GraphQL リクエストに Authorization: Token token=<X> として再送信されます。op CLI が呼び出されるのは、サインイン時に認証情報を解決するときだけです。別のトークンファイルはありません。設定と有効なセッションは、1 つの YAML ファイルに保存されます。

設定ファイルを手動で作成する方法も利用できます（YAML ファイルを ~/.ttctl.yaml に置き、chmod 600 を実行してください）。有効な auth の形式は 4 種類あり、詳細は以下の設定セクションを参照してください。推奨される開始方法は ttctl auth init です。

設定

TTCtl で使用する設定ファイルは 1 つだけです。プロファイルには対応していません。設定ファイルのパスは、優先順位の高いものから決定されます。

1. --config <path> フラグ — 明示的な上書き（呼び出しごと）。
2. TTCTL_CONFIG_FILE 環境変数 — プロセス単位（CI、direnv）。
3. ~/.ttctl.yaml — POSIX のホームディレクトリにあるドットファイル（最後のフォールバックのみ）。

XDG パス（$XDG_CONFIG_HOME/ttctl/config.yaml、~/.config/ttctl/config.yaml）と、カレントワーキングディレクトリの ./.ttctl.yaml は自動検出されません。プロジェクトローカルの設定を使うには、direnv 経由で TTCTL_CONFIG_FILE をそのファイルに設定します。

# .envrc in your project root (requires `direnv` installed and `direnv allow` run)
export TTCTL_CONFIG_FILE="$PWD/.ttctl.yaml"

同期ルートからの除外

TTCtl は、既知のクラウド同期対象のプレフィックス配下に設定ファイルがある場合、取得したベアラーの保存を拒否します。

これらの場所にベアラーを保存すると、ホスト外に気づかれずに複製されてしまいます。プロジェクトローカルの設定が必要な場合は、これらのディレクトリの外に置き、TTCTL_CONFIG_FILE 経由で指定してください（上記の direnv の例を参照）。誤検出を防ぐため、同じ名前で始まるだけのディレクトリは対象外です。たとえば ~/DropboxOther/ は問題ありません。

auth — 有効な 4 つのライフサイクル状態

auth ブロックは、オプションの credentials フィールドと token フィールドを持つ構造化されたブロックです。有効な形式は 4 種類あり、それぞれライフサイクルの状態に対応しています。

Form A — 1Password リファレンス経由の認証情報（推奨。signin により auth.token が設定されます）

# Single 1Password account (or relying on `OP_ACCOUNT` env / op default)
auth:
  credentials: "op://Personal/ttctl"

# Multiple 1Password accounts — pin one explicitly
auth:
  credentials: "op://my-account/Personal/ttctl"

TTCtl は op://[ACCOUNT/]VAULT/ITEM を解析し、op item get ITEM --vault VAULT [--account ACCOUNT] --format json を実行します。その後、purpose: USERNAME と purpose: PASSWORD を持つフィールドと照合して認証情報を解決します。これらは、LOGIN カテゴリのアイテム（フィールドラベルが user[email] のような HTML フォームの入力名になっている、ブラウザーが自動保存したログイン情報も含む）に対して 1Password が自動設定する、標準的な意味識別子です。

省略可能な ACCOUNT セグメントが必要なのは、複数の op アカウントを設定している場合のみです（op account list）。アカウントが 1 つだけの構成では省略できます。ACCOUNT には、アカウント UUID、op account add で設定した略称、またはサインイン用メールアドレスを指定できます。TTCtl は検証のため、その値をそのまま op に渡します。

Form A2 — フィールドごとの 1Password リファレンス（signin により auth.token が設定されます）

# username and password each resolve from their own field-level op:// ref
auth:
  credentials:
    username: "op://Personal/ttctl/username"
    password: "op://Personal/ttctl/password"

# account prefix works on field refs too (parity with Form A)
auth:
  credentials:
    username: "op://my-account/Personal/ttctl/username"
    password: "op://my-account/Personal/ttctl/password"

credentials が 2 つの op:// フィールドリファレンスを持つオブジェクトの場合、TTCtl は各フィールドについて 1 回ずつ op read --no-newline [--account ACCOUNT] op://VAULT/ITEM/FIELD を実行します。op read は ID またはラベルでフィールドを解決するため、ブラウザーが自動保存した LOGIN アイテムでも、標準の username／password フィールド ID を使用できます。先頭の ACCOUNT は省略可能で、Form A と同様に切り分けられて --account として渡されます。

4 セグメントのフィールドリファレンスは、常にアカウント指定付き（op://account/vault/item/field）として読み取られます。そのため、1Password のセクション付きリファレンス（op://vault/item/section/field。こちらも 4 セグメント）はサポートされません。セクションがアカウントとして誤認されます。認証情報フィールドはアイテムのトップレベルに保存してください（LOGIN アイテムではデフォルトでそのように保存されます）。

ルーティングはコンテナーの形式によって決まり、セグメント数では決まりません（op://a/b/c は単独の文字列では account/vault/item ですが、オブジェクトの値では vault/item/field です）。単独の文字列の credentials 値は常に単一アイテム（Form A）として扱われ、アイテムレベルの参照のみが有効です。オブジェクトの値は、値が op:// リファレンスならフィールドごと（この形式）、メールアドレスとパスワードの組み合わせならリテラル（Form B）として扱われます。

Form B — リテラルの認証情報（開発／テスト専用）

auth:
  credentials:
    username: "[email protected]" # value is your Toptal email; field name matches 1P USERNAME purpose
    password: "hunter2"

日常的な使用は推奨されません。設定ファイル内の平文の認証情報は、バックアップ、同期クライアント、誤ったコミットなどを通じて漏えいする可能性があります。通常は Form A を使用してください。

アイテムレベル（Form A）とフィールドごと（Form A2）。 Form A は 1 つの LOGIN アイテムから USERNAME と PASSWORD の両方を読み取ります。Form A2 は各認証情報をそれぞれ独自のフィールドに指定します。/field サフィックス付きの単独文字列リファレンスは拒否されます。フィールドごとの指定にはオブジェクト形式が必要です（1 つの文字列では 2 つのリファレンスを指定できません）。

Form C — トークンのみ（帯域外ブートストラップ）

auth:
  token: "user_<24hex>_<20alnum>"

ベアラートークンを直接指定します。ttctl auth signin は適用されません（NO_CREDENTIALS で拒否されます）。E2E サンドボックスや、サイドチャネル経由でトークンをブートストラップするデプロイで役立ちます。

Form D — 認証情報とトークン（Form A または B でのサインイン後）

auth:
  credentials: "op://Personal/ttctl"
  token: "user_<24hex>_<20alnum>"

Form A または B の設定で ttctl auth signin が成功した後の、ディスク上の形式です。両方のフィールドが共存します。サインアウトすると token フィールドが削除され（Form A または B に戻り）、credentials は変更されません。

ページネーション

TTCtl は、サービスごとのワイヤーで実際に使われるページネーションモデルを公開します。Toptal Talent プラットフォームでは、複数のページネーション方式が共存しており、統一された単一の形式はありません。また、ワイヤーは異なる方式を混在させたリクエストを拒否します（PR #383 で実証済みです。limit のみを使うフィールドに offset を追加しようとした結果、8 件の E2E テストが失敗し、すべて HTTP 400 で拒否されました）。

ワイヤーが受け付ける形式を偽って伝える統一変換レイヤーを作るのではなく、ttctl のフラグ名はワイヤー引数の名前に合わせ、その型もワイヤー引数が受け付ける型に合わせています。これにより、AI やスクリプトの呼び出し元は、フラグ名とワイヤー引数が 1 対 1 で対応することを前提にできます（文書化された変換は1 つのみです。2 行目を参照してください）。

異種性を維持するのが、意図的な Sage の方針です。統一された --cursor <token> レイヤーでは、オフセット方式のサービスでスクリプトから扱いやすい整数ページが失われます。また、動詞を分けて（show-all と list）も、フラグの型ですでに判別できるため、明確さは増さずコマンドツリーが二重になるだけです。サービスごとの --help が、各サービスで使える具体的なフラグ形式を確認するための標準的な手段です。

この 5 行の文法は、ADR-007 — ページネーションのフラグ文法 で確定しています。

求人への応募

TTCtl では、ttctl jobs apply <job-id> を使って求人に直接応募できます。これは破壊的なワイヤー操作です。Toptal 側に JobApplication レコードを作成しますが、TTCtl には withdraw 操作がありません（ADR-008 § 対象外とする項目を参照してください）。まず --dry-run を使って、ワイヤーペイロードを確認することをおすすめします。

同意のゲート

--consent は必須です。これは、Toptal の応募条件に明示的に同意したことを示すものです（法令遵守に関する証明）。このフラグにデフォルト値はありません。ADR-008 § 決定事項 パート 4 に基づき、ユーザーに代わって自動入力することは禁止されています。指定しない場合は CONSENT_REQUIRED が発生し、ワイヤー呼び出しは行われません。

ttctl jobs apply <job-id> --consent

質問一覧のプレビュー

多くの求人では、apply ミューテーションがリクエストを受け付ける前に、マッチング／専門知識に関する質問への回答が必要です。--show-questions は、apply ミューテーションを発行せずに質問一覧を取得します（読み取り専用の経路であり、--consent は不要です）。

ttctl jobs apply <job-id> --show-questions

出力には、各質問の識別子、プロンプトのテキスト、適用前のコンテキスト（canApply、suggestedRate、rateValidation）が一覧表示されます。復元された SDL（#438）によると、識別子は2つの回答配列で異なる形で対応付けられます。マッチングの回答では id として使い、専門知識の回答では questionId として使います（JSON の形式は以下を参照）。ttctl jobs show <job-id> --with-questions は、求人の詳細全体に同じ質問一覧を含める関連する読み取りコマンドです。

--answers-file で回答を渡す

質問ごとの回答を含む JSON ファイルを渡します。ファイルの形式は ADR-008 § Decision Part 2 の文法に従います（Interest Request に対して applications confirm が使用する形式と同じです）。復元された SDL（#438）に従い、マッチングと専門知識の回答ではキーの形式が異なります。マッチングの回答では質問の識別子を id に指定し、専門知識の回答では questionId に指定します。また、other と subjectId（どちらも nullable）も指定できます。

{
  "matcherAnswers": [
    { "id": "<matcher-question-id>", "answer": "<your-answer>" },
    { "id": "<matcher-question-id>", "answer": "<your-answer>" }
  ],
  "expertiseAnswers": [
    { "questionId": "<expertise-question-id>", "other": null, "subjectId": null },
    { "questionId": "<expertise-question-id>", "other": "free-text-context", "subjectId": "<subject-id>" }
  ]
}

続いて、次を実行します。

ttctl jobs apply <job-id> --consent --answers-file ./apply.json

パスの代わりに - を渡すと、標準入力から JSON を読み取ります。ラッパーの形式と内側の各項目は、ワイヤー呼び出しの前に復元された Zod スキーマ（#438 に基づく）で検証されます。JSON が不正な場合や不明なキーがある場合は、VALIDATION_ERROR エンベロープを返して拒否し、ミューテーションは発行されません。

--pitch-file <path>（または標準入力の場合は -）を使うと、回答とともに PitchInput ペイロードを添付できます。1回の実行で標準入力を使用できるフラグは1つだけです。

ドライランでのプレビュー

--dry-run は、ワイヤーのミューテーションを発行せずに、完全な適用プレビューエンベロープ（オペレーション名、サーフェス、トランスポート、GraphQL 変数）を出力します。破壊的な呼び出しを確定する前に、ペイロードの形式を確認するために使用してください。

ttctl jobs apply <job-id> --consent --dry-run

--dry-run でも --consent のゲートは適用されます。プレビューであっても、法令遵守の証明が必要です（このゲートはワイヤーレベルではなく、CLI レベルで拒否します）。

Interest Request

リクルーターが Toptal の Availability Request（AR）フローを通じてあなたのプロフィールに関心を示した場合は、applications confirm／applications reject で応答します。AR の確認は破壊的な操作です。AR の状態を AVAILABILITY_REQUEST_CONFIRMED に変更し、JobApplication を作成します。取り消し操作はありません。まず --dry-run でワイヤーのペイロードをプレビューすることをおすすめします。

AR id を確認する

<id> 引数はAvailabilityRequest idであり、アクティビティ項目の id ではありません。アクティビティ行を調べて確認します。

ttctl applications show <activityId>

出力内の Availability request: <id> の行を探します。

Interest Request を確認する

ttctl applications confirm <ar-id>

--rate と --kind の両方を省略すると、サービスが AR メタデータを事前取得して、次の値を自動入力します。

• metadata.__typename から kind
• metadata.offeredHourlyRate から rate（Fixed-kind の場合のみ）

Flexible-kind の AR にはリクルーターが指定したレートがありません。FLEXIBLE／MARKETPLACE_FLEXIBLE の AR では、呼び出し側が --rate <decimal> を渡す必要があります。

任意の --answers-file／--pitch-file

AR にマッチング／専門知識の質問やピッチのプロンプトが含まれている場合は、jobs apply と同じ JSON ファイルの文法を使って回答を渡します。

ttctl applications confirm <ar-id> \
  --answers-file ./answers.json \
  --pitch-file ./pitch.json

どちらのフラグも - を指定すると標準入力から読み取ります（1回の実行で標準入力を使用できるのは1つまでです）。回答ファイルの形式は、上記の求人への応募で示したものと同じです。ピッチのペイロードは復元された PitchInput Zod スキーマ（#438 に基づく）で検証されます。不明なキーが余分にある場合は、フィールドパスのエラーが返されます。

Interest Request を拒否する

ttctl applications reject <ar-id> --reason <key>

<key> は、サーバーのロケールに応じた一覧 ttctl applications reject-reasons から取得します。キーによっては --comment <text> も必要です。必要なキーは拒否理由の一覧に記載されています。

MCP の統合

TTCtl は Model Context Protocol（MCP）を実装しており、AI アシスタントが自然言語を使って Toptal Talent プロフィールを操作できます。ttctl mcp を実行して、stdio 上で MCP サーバーを起動します。

MCP クライアントの設定

{
  "mcpServers": {
    "ttctl": {
      "command": "npx",
      "args": ["ttctl", "mcp"]
    }
  }
}

claude mcp add ttctl -- npx ttctl mcp

{
  "mcpServers": {
    "ttctl": {
      "command": "npx",
      "args": ["ttctl", "mcp"]
    }
  }
}

信頼モデル：ttctl mcp を起動できるすべてのプロセスは、保存済みの認証トークンを通じて Toptal Talent プロフィールに完全にアクセスできます。信頼できない AI エージェントに MCP へのアクセスを許可しないでください。SECURITY.md を参照してください。

データの取り扱い — MCP ツールがアシスタントのコンテキストに返す内容

AI アシスタントが TTCtl MCP ツールを呼び出すと、プロフィール、契約関係、支払い、契約書などを含むツールの応答ペイロードが、アシスタントのコンテキストウィンドウに入ります。その時点から、そのデータをどう扱うかは AI アシスタントのホストが決定します。チャット履歴に保存するか、ベクターデータベースにインデックス化するか、同じセッションで読み込まれた他のツールに表示するか、テレメトリーの一部としてアップロードするかは、ホスト次第です。

TTCtl はホストの動作を制御できません。防御策は、利用者自身の選択にかかっています。具体的な推奨事項は次の 3 つです。

1. プライバシーに関する方針に合ったホストを選びます。 現在のホストのデフォルト設定（2026-05 時点。今後変更される可能性があります）：Claude Code：セッション単位で、セッション間の永続化はオプトイン。Claude Desktop：ローカルのチャット履歴への永続化がデフォルトで有効。Cursor：ローカルへの永続化とツール出力のベクターデータベースへのインデックス化がデフォルトで有効。Windsurf：Cursor と同様。ChatGPT デスクトップ：ベンダー管理のため、永続化されるものと想定してください。ベクターインデックスを作成するホスト（Cursor／Windsurf）では、意味的なクエリが一致すると、将来の無関係な会話に Toptal のデータが再表示されることがあります。これは、永続化先として最も扱いに注意が必要な特性です。
2. TTCtl のツールが第三者作成の自由記述テキストを返すセッションでは、プライベートモードまたは一時的なチャットモードを使用します。 対象となるのは、契約関係のコメント、応募メッセージ、求人情報、契約条項、レビューコメントです。アシスタント経由で日常的に求人を閲覧したり契約関係のメモを読んだりする利用者は、TTCtl タスク専用のホスト側ワークスペースを検討してください（Cursor：別のワークスペース、Claude Code：プロジェクトごとのスコープ設定）。
3. 管理していない外部送信ツールと TTCtl を同時に読み込まないでください。 ウェブ取得ツール、任意のファイルシステム書き込みツール、または独自の適用経路を持つ別の MCP サーバーがあると、ツール間の情報流出が現実的な脅威になります。Toptal の契約関係メモに埋め込まれた敵対的な指示が、dryRun による制限なしに、別のツールの適用経路へ連鎖する可能性があります。対策はセッション単位で講じます。読み込むツールを利用者が信頼できるものに限ったセッションで TTCtl を使用してください。

ツールごとの監査、重大度の評価基準、対策のトレードオフ分析、残存リスクの一覧を含む脅威モデルの全文は、docs/security/mcp-leakage-threat-model.md にあります。SECURITY.md § MCP Trust Model の関連セクションでは、入力側の防御策（dryRun による状態変更の軽減、ファイルアップロードのサンドボックス）を説明しています。

トラブルシューティング

auth signin ／ auth signout のデバッグログ

サインイン後に ~/.ttctl.yaml へ書き戻す際に予期しない動作が発生した場合（通知のない上書き、mtime のずれによる拒否、ロックの競合、原因不明の「Refusing to write」メッセージなど）は、構造化デバッグログを有効にすると、どの不変条件に抵触したか、各段階でファイルがどのような状態だったかを正確に確認できます。

TTCTL_DEBUG_CONFIG=1 ttctl auth signin

出力は 1 行につき 1 つの JSON オブジェクトで、stderr に出力されます（そのため、-o json モードの stdout はクリーンなままです）。ベアラートークンがログに記録されることは決してありません。jq に渡して確認できます。

TTCTL_DEBUG_CONFIG=1 ttctl auth signin 2> debug.log
jq -c '.' debug.log

各レコードには ts（ISO-8601）、op（persist または clear）、path、event が含まれます。イベント固有のフィールドから、何が起きたかを確認できます。

lock_released が続かない error イベントが見つかった場合は、ロックが解放されずに残っています。イシューを報告してください。エラー発生時の処理では必ず lock_released が出力されます（解放処理は finally 内にあるため、どの不変条件に抵触した場合でも実行されます）。

TTCTL_DEBUG_CONFIG が未設定の場合（またはリテラルの 1 以外に設定されている場合。0、true、空文字列はいずれも「オフ」です）、ロガーは何も出力せず、呼び出しごとのオーバーヘッドも発生しません。

リモートキルスイッチ（ワイヤーブレーク対策）

TTCtl は Toptal の APK をリバースエンジニアリングして作られているため、ワイヤーフォーマットは予告なく変更される可能性があります。多層防御のシグナルとして、CLI は起動時に https://raw.githubusercontent.com/alexey-pelykh/ttctl/main/status/known-broken.json から小さな JSON マニフェストを取得し、実行中のバージョンが既知の問題ありとして登録されている場合は警告を表示するか、実行を拒否します。MCP サーバーも buildServer の実行時に同じ確認を行い、さらに約24時間ごとに再取得します。ただし、警告のみを表示し、実行を拒否することはありません（長時間稼働するサーバーの実行を拒否すると、進行中のツール呼び出しが中断されるためです）。

• レイテンシーへの影響：タイムアウトを3秒に設定した同期フェッチです。raw.githubusercontent.com への一般的なレイテンシーは50～200ミリ秒ですが、最悪の場合、アクションの実行前に3秒かかります。

• プライバシー：フェッチで送信されるのは、Node のデフォルトの fetch ヘッダーのみです。バージョン、アカウント識別子、テレメトリーは送信されません。インストール数の追跡は意図的に見送っています。

• フェイルサイレント：ネットワーク、タイムアウト、404、マニフェストの形式不正など、すべてのエラーは無視されます。メンテナーのリポジトリに一時的に接続できない場合でも、このキルスイッチがそれ自体でサービス拒否を引き起こすことは決してありません。

• オーバーライド — 次の設定でチェックを完全に無効にできます。

  export TTCTL_DISABLE_KILL_SWITCH=1
  

  モジュールの読み込み時に取得されます（TTCTL_DEBUG_CONFIG／TTCTL_DEBUG_MCP／TTCTL_MCP_FILE_UPLOAD_ALLOW_ANY の規則と同じです）。その他の値（空文字列、0、true）では、チェックは有効のままです。

検出元、重大度の段階、対応の頻度、C&D および法的対応方針については、docs/operations/wire-breakage-runbook.md に記載されています。マニフェストのスキーマと更新手順は、status/README.md にあります。

TTCtl の内部動作

Toptal Talent プラットフォームは、次の3つの GraphQL エンドポイントを公開しています。

• https://www.toptal.com/gateway/graphql/talent/graphql — モバイルアプリで使用されます。通常の HTTPS とセッション Cookie を受け付けます。
• https://www.toptal.com/api/talent_profile/graphql — Web プロフィールエディターで使用されます。Cloudflare で保護されています（ブラウザーの TLS フィンガープリントの偽装が必要です）。
• https://scheduler.toptal.com/api/graphql — スケジューラーで使用されます。Cloudflare のゾーンは別です。

TTCtl は、次の2つのトランスポートを使用します。

• 標準（undici）：モバイルゲートウェイのエンドポイント用
• TLS 偽装（node-wreq、chrome_147 プロファイル使用）：Cloudflare で保護されたエンドポイント用

認証はベアラートークン方式です（非公開の ttctl/research リポジトリにある ADR-005 に基づきます）。TTCtl は、永続クエリモードで EmailPasswordSignIn を POST します（取得済みのオペレーションカタログにある SHA-256 ハッシュを使用）。返されたセッショントークンを取得し、同じ ~/.ttctl.yaml 設定ファイルの auth.token に永続化します（アトミック書き込み、モード 0600）。以降の GraphQL リクエストでは、Authorization: Token token=<X> としてトークンを再送します。Cookie は使用しません。Chrome の TLS 偽装だけで、保護されたエンドポイントの Cloudflare を通過できます。

リバースエンジニアリングの成果物（デコード済み APK、GraphQL オペレーションカタログ、スキーマの合成、ADR）は、別の非公開リポジトリ（ttctl/research）にあります。これらを再配布することはできません。

免責事項

TTCtl は、個人の生産性向上を目的とした独立プロジェクトであり、Toptal、Toptal LLC、またはいかなる Toptal 関連組織とも提携、承認、公式な関係はありません。

このソフトウェアは、Toptal のタレントである皆さんが、ご自身のプロフィールデータをより効率的に管理するためのツールとして提供されています。ご自身以外のプロフィールとのやり取り、人間が手動で行える範囲を超えるアウトリーチの拡大、プラットフォーム側の指標の操作、または他者に関するデータの抽出に使用することは、公正利用の精神および Toptal の利用規約に反します。

メンテナーは一切の保証を否認し、プラットフォームの規約に違反する使用について責任を負いません。Toptal LLC が TTCtl の存在に異議を唱え、誠意をもって連絡をした場合、メンテナーは懸念に対処するため協力します。

「Toptal」は Toptal LLC の商標です。このプロジェクトの説明で名称を使用するのは、TTCtl がやり取りするサードパーティのプラットフォームを特定するための指示的公正使用に限られます。

商標の使用、利用規約、AGPL の選択、そしてこの種のツールが位置づけられる公正利用の慣行に関する、プロジェクトの姿勢についての詳細は、docs/legitimacy.md をご覧ください。

サポート

TTCtl は Toptal の APK をリバースエンジニアリングして作られているため、通信形式は予告なく変更される可能性があります。変更があったことをメンテナーが知る唯一の手段は、皆さんからの報告です。テレメトリ、エラー報告用エンドポイント、インストール数の追跡はありません。以下の窓口が唯一のフィードバック経路です。

通信が動作しない — ttctl <command> が失敗する

TTCtl のコマンドでエラーが発生したり、予期しない応答（404、不可解な GraphQL エラー、WIRE_SHAPE_ERROR エンベロープなど）が返されたりする場合は、通信が動作しないイシューを作成してください。テンプレートでは、ttctl --version、失敗したコマンド、エラーのテキスト、および ttctl auth status が引き続き成功するかどうかを報告できます。これらの情報があれば、メンテナーは停止スイッチマニフェスト status/known-broken.json と通信障害対応手順に照らして優先度を判断できます。

報告を作成する前に、停止スイッチマニフェスト https://raw.githubusercontent.com/alexey-pelykh/ttctl/main/status/known-broken.json を確認してください。ご使用のバージョンが掲載されている場合、メンテナーはすでに問題を把握しています。

MCP ホストがツールの呼び出しに失敗する

MCP ホスト（Claude Desktop、Claude Code、Cursor、Windsurf など）が TTCtl のツールを表示できない、または呼び出せない場合、問題は Toptal の通信ではなく、ホスト ↔ サーバー間の境界にあります。MCP ホストがツールの呼び出しに失敗するイシューを作成してください。テンプレートでは、ホスト製品とバージョン、失敗したツール名、ホスト上でエラーがどのように表示されたか、および任意の TTCTL_DEBUG_MCP=1 サーバー側トレースを報告できます。

質問、アイデア、「これは想定どおりですか？」

質問、使い方のサポート、アイデア、「ほかにも同じ現象を見た人はいますか？」といった内容には、ディスカッションをご利用ください。イシュートラッカーは、確認済みの不具合と機能リクエスト専用です。

セキュリティ脆弱性

セキュリティ脆弱性について、公開イシューを作成しないでください。調整された情報開示の窓口については、SECURITY.md § 脆弱性の報告をご覧ください。

不正利用の報告

TTCtl が Toptal の利用規約に違反する方法（大規模な自動化、リクルーターによるスクレイピング、エンゲージメントシグナルの操作など）で使用されていることを確認した場合は、SECURITY.md § 不正利用の報告をご覧ください。

報告時のプライバシー

~/.ttctl.yaml には、取得したベアラートークン（auth.token、形式 user_<24hex>_<20alnum>）が含まれています。**公開イシューやディスカッションスレッドに絶対に貼り付けないでください。**TTCtl のデバッグ出力機能（TTCTL_DEBUG_CONFIG、TTCTL_DEBUG_MCP）は、ベアラー値を決して出力しないよう設計されていますが、シェルの記録には含まれる可能性があります。貼り付ける前に確認し、<REDACTED> に置き換えてください。

行動規範

このプロジェクトでは、Contributor Covenant Code of Conduct（バージョン 3.0）を採用しています。この規範は、プロジェクトのすべての場と、課題トラッカー、プルリクエスト、MCP サーバーとのやり取り、その他あらゆるチャネルを通じてプロジェクトに関わるすべての人に適用されます。

懸念事項を報告するには、[email protected] までメールでご連絡ください。仮名での報告を受け付けていますが、完全に匿名での報告には対応できません（メンテナーが受信トレイを直接確認するためです）。可能な限り、7 日以内に対応します。

ライセンス

AGPL-3.0-only

AGPL が意味すること

• ttctl を CLI ツールまたは MCP サーバーとして使用する場合、あなたのコードが AGPL ライセンスになることはありません。このツールの実行、スクリプトによる連携、アプリケーションへの接続は通常の使用であり、ライセンス上の義務は生じません。
• @ttctl/core をライブラリとして使用する場合（コードにインポートする場合）、結合作品は AGPL-3.0 の適用対象になります。その結合作品を配布する場合は、AGPL と互換性のある条件のもとでソースを公開する必要があります。
• TTCtl 自体を改変して配布する場合、変更内容を AGPL-3.0 のもとで共有する必要があります。
• 商用ライセンスは現在提供していません。TTCtl は個人の生産性向上を目的としたプロジェクトであり、製品ではありません。