prism

Prism

无状态 MCP 网关。位于 AI 客户端与 MCP 服务之间，原样转发 JSON-RPC，并将每次调用转换为 OpenTelemetry span —— 通过 OTLP 发送到你选择的任意端点。无需数据库、账号或 配置。完整规范请参阅 docs/PRISM.md。

**最快启用实时仪表板的方式：**在 telinea.terradev.cloud 免费获取密钥，设置一个目标， 几秒钟内，所有 span 都会显示在 Telinea 中。

运行

pip install -r requirements.txt

# Zero-config dev: spans print to stdout.
PRISM_UPSTREAM_ALLOW='*' \
PRISM_ALLOW_INSECURE_HOSTS='localhost,127.0.0.1' \
uvicorn prism.main:app --port 8080

Span 的去向

一条管道，一种出口机制：PrismSpan → Serializer → Dispatcher。 Prism 只识别四种目标方案，不涉及任何后端：

• https:// / http:// — 将序列化后的 span POST 到任意 OTLP 端点。 Grafana、Honeycomb、collector、Telinea — 查阅后端自己的文档，了解 其端点和身份验证标头，填写两个字段即可。
• file:// — 将 JSONL 追加到本地路径。无需账号，也无需网络。
• stdout:// — 输出便于阅读的行，供开发使用。
• multi://a,b — 扇出到指定名称的目标；各目标的故障互不影响。

在 ~/.prism/config.toml（或 ./prism.toml，或 PRISM_CONFIG）中配置：

[prism]
destination = "telinea"

[destinations.telinea]
endpoint = "https://api.terradev.cloud/telinea/v1/ingest"
format = "telinea"
headers = { "Authorization" = "Bearer tl_your_key" }

格式：otlp_json（默认 — 行业通用的传输标准）、otlp_proto （需要 pip install opentelemetry-proto）、jsonl、telinea（用于 Telinea 接收的原生封装格式）。

每个字段都支持环境变量覆盖 — 密钥无需写入磁盘：

PRISM_DESTINATION=telinea
PRISM_DESTINATION_TELINEA_HEADERS_AUTHORIZATION="Bearer tl_..."

托管模式："Authorization" = "Bearer {token}" 会针对每个 span 将 {token} 解析为调用方的 bearer token — 每位用户的 span 都会写入各自的账号。

传输：缓冲后每 5 秒或每 512 个 span 刷新一次；所有后端遇到 429 时都会遵循 Retry-After；失败批次会进入死信环形缓冲区（10k 个 span），并在退避等待后重试； 关闭时会排空正在传输的 span，并将死信缓冲区写入 ~/.prism/deadletter.jsonl，下次启动时重放。发送后即忘 — Prism 绝不会因刷新操作阻塞聊天会话。

客户端配置

整个集成只需替换 URL 并添加标头：

{
  "mcpServers": {
    "acme-prod": {
      "url": "https://prism-mcp.terradev.cloud/mcp",
      "headers": {
        "Authorization": "Bearer tln_live_…",
        "X-Prism-Upstream": "http://localhost:9000/mcp",
        "X-Prism-Project": "acme-prod",
        "X-Prism-Env": "development"
      }
    }
  }
}

• X-Prism-Upstream — 实际的 MCP 服务。必须与 PRISM_UPSTREAM_ALLOW 匹配。
• X-Prism-Upstream-Authorization — 转发至上游，作为 Authorization。
• X-Prism-Capture — none（默认）| args | args,results。内容会脱敏。
• X-Prism-Sample — 0.0–1.0，每个会话采样一次。

不支持标头的客户端可以在路径中编码上游地址： POST /mcp/u/{base64url(upstream)}。

注册表（Smithery 等）

注册表安装无法设置自定义标头 — 配置通过查询参数传入。 每个 X-Prism-* 选项都有对应的查询参数：

/mcp?upstream=https://mcp.acme.dev/mcp&api_key=tln_live_…&project=acme&env=prod

• upstream → X-Prism-Upstream（或为仅部署单个上游的环境设置 PRISM_DEFAULT_UPSTREAM）
• api_key / token → Authorization / X-Api-Key
• upstream_authorization → X-Prism-Upstream-Authorization
• project、env、role、capture、sample → 对应的 X-Prism-* 选项

此目录中的 smithery.yaml 是可自托管容器部署方式的注册表清单； 托管版列表则指向 https://prism-mcp.terradev.cloud/mcp。

你将获得什么

一个 MCP 会话 = 一个 trace。一个 JSON-RPC 请求 = 一个 span。工具故障 会正确呈现（result.isError → ERROR，而不是绿色的 200）。使用 Telinea 目标时，每个由 Prism 代理的服务也会通过 endpoint 属性显示在 Telinea Gateway 看板上 — p50/p95/p99、req/min、迷你趋势图 — 无需更改 后端。

按设计不包含的功能

• 不提供针对特定后端的序列化。如果后端需要专有格式， 请运行 OpenTelemetry Collector 并将 Prism 指向它 — Collector 就是为此设计的。
• 不提供查询层、存储或界面。Prism 负责发送；Telinea 负责存储和可视化。
• 不支持旧版 HTTP+SSE 传输方式（/sse + /messages，2024-11-05 规范）。
• 不支持传输层的 DNS 重绑定安全 IP 固定（参见 guard.py）。