segment-mcp

segment-mcp

面向 Twilio Segment 的只读优先 MCP 服务。 它会回答哪些目标接收哪些事件、哪些来源已失效，以及哪些来源不受任何治理——这些问题没人能回答，除非点开四十个页面逐一查看。

默认只读

SEGMENT_MCP_MODE 默认为 read，而此服务目前提供的所有工具都只读。提供零个写入工具是一项特性，而非限制——请参阅 BUILD-PLAN.md §2。层级模型中已有 write 和 admin 模式（src/segment_mcp/modes.py），以便在受控写入功能上线后使用；目前没有任何功能需要它们解锁。

此服务永久拒绝执行的操作，而非“暂时不支持”

POST /regulations 和 POST /regulations/sources/{id}——作用于整个工作区、不可逆地删除或抑制所有来源中的用户数据——在任何模式下都无法访问，也没有任何配置可以启用它们。 三项相互独立的措施确保了这一点：模式授权层会在检查当前模式之前就拒绝此操作；API 客户端会在请求到达网络之前拒绝发送；此服务注册的工具也不会以任何形式引用这些端点。

这不是一道等待合适权限级别才能通过的门槛，而是一条明确的界线，因为这些端点接受一组主题，一次格式错误或幻觉产生的调用就可能永久删除数千个用户档案，且无法撤销。完整说明：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

通过 stdio 将 MCP 客户端（Claude Desktop、Claude Code 等）连接到此服务。如果令牌、区域或工作区套餐不正确，服务会拒绝启动，并清楚地说明原因；请参阅启动检查。

五种工具

每种工具都会组合多个 Public API 调用，给出一个结构化答案，而不是原始端点数据：

工具	回答的问题
audit_event_routing	哪些目标接收哪些事件？
trace_event	给定一个事件名称：它会发送到哪里？是否受任何规则治理？
find_stale_sources	哪些来源没有近期数据——是埋点已失效，还是只是刚刚创建？
check_delivery_health	此目标是否在悄无声息地发生故障？
find_ungoverned_sources	哪些来源不受任何规则治理，或允许未计划的事件通过？

先决条件

• Team 或 Business 套餐。 Free 或 Add-on 套餐无法使用 Public API。没有变通办法；如果你的工作区不符合要求，服务的启动检查会给出清楚的提示，而不是原始的 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 调用指向 US 端点不会报错，只会悄无声息地返回空结果，这种故障模式远比崩溃糟糕。此服务的启动检查会使用已配置的区域调用一次 API；如果令牌实际上不属于该区域，就会明确报错并指出其所属区域。

启动检查

以下情况都会导致启动失败——服务会拒绝启动，而不是等到首次调用工具时才令人困惑地失败：

1. 已设置 SEGMENT_REGION，且其值为 us 或 eu。
2. 已提供 SEGMENT_API_TOKEN，且该令牌确实能通过对应区域的身份验证。
3. 工作区套餐支持 Public API——Free 套餐工作区会收到清楚的“需要 Team 或 Business 套餐”提示，而不是原始的 403 错误。

模式

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。

Profile API — 独立的更高信任级别

Profile API 会返回具名个人的 PII，包括特征、外部 ID、事件历史记录以及特定个人的身份关联信息。这是此服务所有功能中隐私敏感度最高的读取操作，因此与其他所有功能隔离：

• 使用独立凭证 SEGMENT_PROFILE_TOKEN — 绝不使用主凭证 SEGMENT_API_TOKEN。还需要 SEGMENT_PROFILE_SPACE_ID（你的 Unify Space ID，而非你的工作区 ID）。
• 明确选择启用。 如果未设置 SEGMENT_PROFILE_TOKEN，则不会注册任何个人资料工具 — 该服务实例不具备此功能。
• 每次查询都会记录日志 — 在发送请求之前，通过 client/profile_api.py 的 segment_mcp.profile_api 日志记录器记录集合、id_type 和调用方。日志会记录发生了查询以及查询了哪个个人资料，但个人资料仅以截断的 SHA-256 摘要表示，绝不会记录原始标识符 — 此客户端自身绝不记录原始标识符；此外，由于 Profile API 会将标识符放在 URL 路径中，此客户端在构造时会在整个进程范围内关闭 httpx 自带的请求 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。