TypeSafe

TypeSafe MCP 服务

让 TypeSafe 的 Jev 为你的 AI 助手提供类型化、经过校准的判断：某个是/否陈述成立的可能性有多大、哪些选项最符合，或者某项内容在你自定义的量表上处于什么位置。你可以针对单条状态提出这些问题，也可以一次处理最多 1000 行数据，让助手筛选招聘信息、交易记录或电子邮件，而无需逐条阅读。所有工具都只读：不会对任何内容进行更改，而且没有工具涉及 money。

你需要一个 TypeSafe 账户，以及从其控制台获取的 API 密钥。调用按输入 Token 计费，每个 Token 只需几分之一美分；Jev 大约半秒就会给出答复。

你可以询问

• “检查 postings.jsonl 中的 300 条招聘信息，列出远程高级职位，并说明 Jev 对每条信息有多大把握。”
• “这封客服邮件是否紧急？应该由哪个团队处理：账单、技术还是销售？”
• “将上个月的 600 笔银行卡交易分类为杂货、交通、软件或其他，并统计每类的数量。”
• “评估这 40 条评论中的客户流失可能性，并列出风险最高的十条。”
• “这些段落中，哪些回答了‘如何重置密码’？标出 Jev 不确定的内容，供我阅读。”

安装

使用 Claude Code：

claude mcp add typesafe -e TYPESAFE_API_KEY_FILE="<path to API key file>" -- npx -y @foreverworks/mcp-typesafe

Claude Desktop（Settings、Developer、Edit Config）和大多数其他客户端都通过 JSON 读取相同的命令：

{
  "mcpServers": {
    "typesafe": {
      "command": "npx",
      "args": ["-y", "@foreverworks/mcp-typesafe"],
      "env": {
        "TYPESAFE_API_KEY_FILE": "<path to API key file>"
      }
    }
  }
}

每种方式都会在 Node 22.19 或更高版本上运行已发布的软件包。VS Code 和 Claude Desktop 安装包在添加服务时会提示输入 TYPESAFE_API_KEY_FILE。Cursor 则从你的环境中读取该值（${env:TYPESAFE_API_KEY_FILE}），因此请在启动 Cursor 前设置好它。配置 中说明了该变量的内容。

从克隆版本安装

git clone https://github.com/foreverworks/mcps.git && cd mcps
npm ci && npm run build
claude mcp add typesafe -e TYPESAFE_API_KEY_FILE="<path to API key file>" -- node "$PWD/servers/typesafe/dist/index.js"

在 JSON 配置中，命令为 node，唯一的参数是 servers/typesafe/dist/index.js 的完整路径。如需通过 HTTP 在多个客户端之间共享同一个运行实例，请参阅 docs/deploying.md。

配置

变量	必需	含义
TYPESAFE_API_KEY_FILE	是	存放 API 密钥的文件。本地运行时，也可以直接用 TYPESAFE_API_KEY 存放密钥。
TYPESAFE_MODEL	否	调用未指定模型时使用的模型。默认为 jev-latest，它会跟随最新的 Jev。
TYPESAFE_BASE_URL	否	默认值为 https://api.typesafe.ai。
TYPESAFE_OUTBOX_DIR	否	ask_batch 搭配 save 时写入 JSONL 的位置。默认为状态文件夹中的 outbox/。文件权限为 0640，因此部署可以与用户组共享此文件夹。
TYPESAFE_STATE_DIR	否	状态文件夹；默认值见 docs/configuration.md。

没有密钥时，服务仍会启动并列出其工具，每次调用都会返回一条指出相应变量的 config 错误。ask_batch 会从 MCP_FILE_ROOTS 读取 items_file；该变量及其他各服务共用的变量见 docs/configuration.md。

获取 API 密钥

1. 在 https://console.typesafe.ai 登录并打开 Keys。
2. 创建密钥，并将其写入只有你（或服务用户）能够读取的文件。
3. 将 TYPESAFE_API_KEY_FILE 指向该文件。

为每个部署使用单独的密钥，这样你就可以单独撤销密钥，并在控制台的用量页面区分它们。只有 TypeSafe 自有控制台颁发的密钥才可用；经销商的密钥只能通过该经销商的网关使用。

首次运行

请助手运行 TypeSafe 的 health 检查。它会返回所连接的 API、默认模型，以及你的密钥可访问的模型。缺少密钥时，这里会显示 config；密钥被拒绝时则显示 auth，且都发生在任何批次开始之前。

工具

read 不会更改任何内容；这里的每个工具都是只读工具（按输入令牌计费属于计量，不是付款）。

工具	访问权限	功能
health	只读	密钥是否存在且有效，以及它可以访问哪些模型。
ask	只读	一次往返中询问关于单个状态的所有问题；返回 TypeSafe 给出的答案，但会省略 Score 的 legend。
ask_batch	只读	对最多 1000 个状态提出相同的问题，可直接输入或从文件读取，默认同时处理 8 项：每个问题给出摘要和精简行；使用 save 时，将完整行作为 JSONL 保存到发件箱。还可根据你的阈值返回可选的 act、review 或 abstain 判定，并使用 where、top 和 counts 仅列出重要行。

问题类型可以是 noul（某个是／否陈述成立的概率）、choice（2 到 255 个选项之一，每个选项都有对应概率），或 score（将状态放在 2 到 10 个由低到高排序的等级上）。

故障排除

config。 缺少密钥：将 TYPESAFE_API_KEY_FILE 设为存放 console.typesafe.ai/keys 中密钥的文件；本地运行时，也可设置 TYPESAFE_API_KEY。

auth。 TypeSafe 拒绝了密钥。检查它是否仍存在于 console.typesafe.ai/keys；如果已撤销，请更换文件。

input。 无法按要求回答该问题；消息会指出相应字段（choice 至少需要两个选项，score 需要 2 到 10 个等级）。超过 20 行时，每行都必须包含 id。

rate_limited。 服务自行重试后，TypeSafe 仍在限流或过载。请等待一分钟，或降低 concurrency 后发送批次。

api。 其他任何拒绝、重试后仍未恢复的 5xx，或无连接（状态码 0）。重试一次；如果问题仍然存在，请运行 health 并查看服务日志。

drift。 TypeSafe 返回了服务无法识别的格式（其 SDK 的类型可能已有更新）。请报告此问题。

工作原理

网络。 评估不会产生副作用，因此每个请求（ POST /v1/systemone、GET /v1/models）都可以重复发送：遇到 5xx 或连接断开时会重试；遇到 429 或 529（“过载”）时则会像 TypeSafe 的 SDK 那样等待，以遵守速率限制。调用会在一分钟后超时。每个答案都会根据 SDK 的类型进行检查（@typesafe-ai/sdk，仅类型定义，位于 src/domain/schema.ts）。

批次。 批次会跳过失败的行并报告错误，但遇到会导致所有行都失败的问题（没有密钥、密钥被拒绝）时就会停止，这样一千行不会各自都收到一个 401。答案通过 id 与对应行匹配；行数超过 20 时必须提供 id：只有在你能逐行目视核对时，才适合按位置匹配。

从文件读取行。 不必将行输入到 items 中，可以传入 items_file：文件可以是每行一个 {"id", "state"} 对象的 JSONL，也可以是这类对象组成的 JSON 数组；文件路径必须位于 MCP_FILE_ROOTS 指定的目录中（也可以由脚本以 content_base64 和对应的 sha256 传入）。这些行不会经过模型，因此途中不会发生变化；如果某行格式错误，调用会在发送任何内容之前失败并指出行号。响应会列出文件的 sha256 和大小。

判定结果。 如果某个问题设置了 thresholds，每行的答案都会根据其确定性获得 act（足够确定，可以采取行动）、review（应由人工查看）或 abstain（不要使用）判定：对于二元问题，确定性为 |p - 0.5| x 2（p 为 0.95 和 0.05 时均为 0.9）；对于选项题或评分题，则使用 TypeSafe 返回的置信度。确定性会向下取整到三位小数，这是该行显示的数值；只有严格高于 act_above 才能采取行动，高于 review_above 才需要审核。调整好阈值后，将 model 固定到一个有版本号的 Jev：jev-latest 可能会发生变化。

选择行。 where 只列出已回答且满足你为每个问题给出的所有条件的行：二元问题可用 true 或 false（摘要统计中的“是”表示 p >= 0.7，“否”表示 p <= 0.3），选项题可用标签，评分题可对行显示的值指定 min 和 max，还可指定 verdict。top 会保留某个问题中 p 值或分数最高的 k 行；counts 会统计 where 保留的行的答案；摘要仍涵盖所有行。每个条件都会在发送请求前检查，因此如果标签不是可选项，调用会直接失败，而不是让一千行逐个失败。

npx tsx scripts/smoke.ts 会用几千个输入 token 通过真实 API 测试构建好的服务：执行 health、每种问题类型各执行一次 ask、将一个五行批次保存到发件箱，并触发一次不会到达 TypeSafe 的输入错误。

限制

• 仅作判断。 Jev 不会编写文本，也不会进行多步推理。请将规则、查询和算术运算留在代码中，并通过阈值处理概率（thresholds 会按问题设置阈值）。
• where 只能用“与”连接条件。 如需“或”，请读取已保存的 JSONL 行，或提出一个明确列出不同选项的问题。
• 每次调用最多 1000 行；更大的数据集需要拆分。
• 除非另行指定 list，否则批次响应会列出每一行。 对于较大的批次，请搭配 save 传入 list: "none" 或 "failed"，然后读取 JSONL。

其他 TypeSafe 服务

搜索日期：2026-10-15。TypeSafe 没有发布 MCP 服务：其 GitHub 组织提供 SDK、Agent 技能和一个 n8n 节点。npm 上有两个社区服务：

• typesafe-mcp：通过 Bun 使用 stdio，从环境变量读取密钥；支持对通过 glob 匹配的文件进行批量处理，并为每个答案提供 act、review 或 abstain 判定。
• @y0usaf/typesafe-mcp：使用 stdio，提供一个 evaluate 工具。

这个项目的用途是提供其他项目都没有的功能：它也能通过 HTTP 作为独立服务运行，密钥保存在调用它的客户端不会读取的文件中；它会将批次的完整答案以 JSONL 格格式保存到发件箱，并列出文件的 SHA-256；同时遵循本仓库中所有服务共享的约定。它的判定结果以及 where、top 和 counts 均遵循 typesafe-mcp 的规则，但阈值按问题设置，而不是按调用设置。