segment-mcp

segment-mcp

Twilio Segment 向けの、読み取り優先の MCP サーバーです。 どのイベントがどの宛先に届くのか、使われていないソースはどれか、何のガバナンスも適用されていないソースはどれかを回答します。40 もの画面をクリックして回らなければ誰にも答えられない、そんな疑問に答えます。

デフォルトで読み取り専用

SEGMENT_MCP_MODE のデフォルトは read で、現在このサーバーが提供するすべてのツールは読み取り専用です。書き込みツールを一切含めずにリリースするのは、制限ではなく機能です。BUILD-PLAN.md §2 を参照してください。書き込みがゲート付きで導入されるときに備えて、階層モデル（src/segment_mcp/modes.py）には write モードと admin モードがありますが、現時点ではそれらで有効になる機能はありません。

「今のところ」ではなく、恒久的に実行を拒否する操作

POST /regulations と POST /regulations/sources/{id} は、ワークスペース全体を対象とし、すべてのソースにわたってユーザーデータを復元不能な形で削除または抑制する操作です。すべてのモードで到達不能であり、有効化する設定方法もありません。 これを強制する独立した仕組みが 3 つあります。モード認可レイヤーが現在のモードを確認する前に拒否し、API クライアントがネットワークに到達する前にリクエストの送信を拒否し、さらにこのサーバーが登録するツールは、どのような形でもこれらを参照しません。

これは、適切な権限レベルを待っているゲートではありません。これらのエンドポイントは対象の配列を受け付けるため、形式の誤った呼び出しや幻覚による呼び出しが 1 回あるだけで、取り消しもできず、何千ものプロファイルが恒久的に削除されるおそれがあるからです。詳しい理由は、docs/what-this-refuses-to-do.md を参照してください。

クイックスタート

Team または Business プランの Segment ワークスペースと Public API トークンが必要です（下記の前提条件を参照）。

gh repo clone katekruger/segment-mcp
cd segment-mcp
uv sync
cp .env.example .env      # fill in SEGMENT_API_TOKEN and SEGMENT_REGION
uv run segment-mcp

MCP クライアント（Claude Desktop、Claude Code など）から stdio 経由で接続してください。トークン、リージョン、またはワークスペースのプランが適切でない場合、このサーバーは明確なメッセージを表示して起動を拒否します。起動時のチェックを参照してください。

5 つのツール

各ツールは複数の Public API 呼び出しをまとめ、単なるエンドポイントの生データではなく、構造化された回答を返します。

ツール	回答する質問
audit_event_routing	どのイベントがどの宛先に届きますか？
trace_event	イベント名を指定すると、どこに送られ、何らかのガバナンスが適用されていますか？
find_stale_sources	最近データが届いていないソースはどれですか？ 計測が使われていないのか、単に新しいだけなのかを判別します。
check_delivery_health	この宛先は、気付かれないまま配信に失敗していませんか？
find_ungoverned_sources	何のガバナンスも適用されていないソース、または計画外のイベントを通してしまうソースはどれですか？

前提条件

• Team または Business プラン。 Public API は Free プランや Add-on プランでは利用できません。回避策はありません。ワークスペースが条件を満たさない場合、サーバーの起動時チェックは生の 403 ではなく、明確なメッセージを表示して失敗します。
• Public API トークン。 トークンを作成できるのは Workspace Owner だけです。Segment App → Workspace Settings → Access Management → Tokens → Create Token → Public API（Config API ではありません）の順に進んでください。

リージョンの設定

SEGMENT_REGION=us   # or eu

デフォルト値はありません。必ず明示的に設定してください。EU ワークスペースの API 呼び出し先を米国のエンドポイントにしても、エラーにはならず、何も返さないままになります。これはクラッシュよりもはるかに深刻な失敗です。このサーバーの起動時チェックでは、設定されたリージョンを使って API を 1 回呼び出し、トークンがそのリージョンに実際に属しているかを確認します。異なる場合は、正しいリージョンを示して明確に失敗します。

起動時のチェック

すべて致命的なチェックです。最初のツール呼び出しで分かりにくい形で失敗するのではなく、サーバーは起動を拒否します。

1. SEGMENT_REGION が設定され、us または eu のいずれかであること。
2. SEGMENT_API_TOKEN が設定され、そのリージョンに対する認証に実際に成功すること。
3. ワークスペースのプランが Public API に対応していること。Free プランのワークスペースには、生の 403 ではなく「Team または Business プランが必要です」という明確なメッセージが表示されます。

モード

SEGMENT_MCP_MODE = read (default) | write | admin

• read — 上記のすべてのツールです。どのモードでも、変更を実行できる機能にはアクセスできません。
• write — Tier 3 の置換セマンティクスによる変更を追加する予定です（現時点では未提供）。実行前に、それぞれの内容をユーザーに返して確認を求めます。
• admin — Tier 2 の削除を追加する予定です（現時点では未提供）。confirm=true だけではなく、対象のリソース名を正確に指定する入力確認が必要です。

完全な階層モデルについては src/segment_mcp/modes.py を、モードにかかわらず対象外となる内容については docs/what-this-refuses-to-do.md を参照してください。

プロファイル API — 独立した、より高い信頼レベル

プロファイル API は、名前が特定された個人の個人識別情報（PII）を返します。具体的には、特性、外部 ID、イベント履歴、特定の個人の ID リンクです。このサーバーが提供する機能の中で最もプライバシーに関わる読み取りであるため、ほかの機能から完全に切り離されています。

• 独立した認証情報として SEGMENT_PROFILE_TOKEN を使用します。メインの SEGMENT_API_TOKEN は使用しません。また、SEGMENT_PROFILE_SPACE_ID（ワークスペース ID ではなく、Unify Space ID）も必要です。
• 明示的なオプトインが必要です。 SEGMENT_PROFILE_TOKEN が設定されていない場合、プロファイルツールは登録されません。このサーバーインスタンスでは、その機能自体が利用できません。
• すべての検索が記録されます — リクエストを送信する前に、コレクション、id_type、呼び出し元が、client/profile_api.py の segment_mcp.profile_api ロガーを通じて記録されます。ログに残るのは検索が行われたことと、対象のプロファイルです。検索キーの SHA-256 ダイジェストを一部だけ記録し、生の識別子は決して記録しません。このクライアントは生の識別子を記録せず、構築時に httpx 自身のリクエスト URL ログもプロセス全体で無効にします。Profile API では識別子が URL パスに含まれるため、これによる漏えいも防止します。ダイジェストから識別子を復元することはできませんが、同じプロファイルへの繰り返しの検索は、監査のために複数のログ行間で関連付けられます。
• 検索では大文字と小文字が区別されます。 大文字と小文字が一致しない場合、エラーではなく空の結果が返されます。このクライアントは境界で検索値をすべて小文字に変換し、変換が必要だった場合は警告を記録します。

server.py には、まだプロファイル検索用の MCP ツールは組み込まれていません。これは、BUILD-PLAN.md の v0.2 の範囲に従って、将来ツールを構築するためのクライアントと信頼境界の仕組みです。

開発

uv sync
uv run pre-commit install
uv run ruff check . && uv run ruff format --check . && uv run pyright && uv run pytest

CONTRIBUTING.md と AGENTS.md を参照してください。

関連項目

ここに挙げたプロジェクトはすべて、GTM システムは検証できないデータに基づく処理を拒否すべきだという考えを共有しています。

campaign-preflight — 不足している証拠を合格として扱わないという、同じ方針を採用しています。どちらも insufficient_data を独立した状態として扱います。

pipeline-waterfall — このプロジェクトの下流に位置します。受注とパイプラインのウォーターフォールを照合し、整合性の取れていないブリッジを報告するのではなく、ビルドを失敗させます。

ライセンス

MIT — LICENSE を参照してください。