TypeSafe MCP

什么是 Arbitype？

Arbitype 是一个面向 AI Agent 的 MCP 原生类型化决策层，由 TypeSafe Jev 提供支持。它将概率性判断转化为 Agent 或程序可以直接使用的结构化决策原语。

Arbitype 已发布到 PyPI 和官方 MCP Registry。

说明

Arbitype 是一个独立的开源项目。它不是 TypeSafe AI 的官方产品， 也不是针对任何特定 Agent 宿主的官方集成。

快速开始

连接 MCP 宿主最快的方式，是通过 uvx 启动本地 STDIO 服务：

export TYPESAFE_API_KEY="your-key"
uvx arbitype

如需固定版本以确保可复现启动：

uvx --from 'arbitype==0.7.0' arbitype

或者将软件包安装到当前环境：

python -m pip install arbitype
arbitype

API 密钥保存在进程环境中。它不是 MCP 参数，也绝不会输出到标准输出。

宿主配置

在写入任何内容之前，先检查检测到的宿主：

arbitype setup --detect --dry-run

然后应用经过审查的计划：

arbitype setup codex
arbitype doctor --json

配置流程为：计划 → 统一差异 → 确认 → 备份 → 应用。 可用 claude、cursor 或 vscode 替代 codex。有关宿主格式、 密钥转发、--yes、--remove、所有权和非交互行为的详细说明，请参阅 docs/HOST_SETUP.md。

配置

至少需要设置 TYPESAFE_API_KEY。若要明确选择模型：

export TYPESAFE_API_KEY="your-key"
export TYPESAFE_MODEL="jev-latest"

有关端点、超时、重试以及请求/响应限制，请参阅完整配置参考。

兼容性

arbitype 是规范的发行版、Python 包和 CLI。现有 TypeSafe MCP 用户应 迁移到 Arbitype；请参阅 docs/REGISTRY_MIGRATION.md。

从历史发行版安全迁移的方式：

python -m pip uninstall typesafe-mcp
python -m pip install arbitype

接口	规范名称	旧版兼容名称
PyPI / CLI	arbitype	typesafe-mcp, typesafe-codex-mcp
Python 导入	arbitype	typesafe_mcp, typesafe_codex_mcp
MCP 工具	route, review	codex_route, codex_review

为什么选择 Arbitype？

Arbitype 围绕契约和有界决策设计，而非自由形式的文本：

原则	含义
契约优先	请求和提供方响应会先经过验证，再传递给 Agent。
默认安全	凭据不会出现在 MCP 工具参数和生成的宿主配置中。
面向 Agent	专为分类、验证、设门、路由、审查和评分打造的基本工具。
可移植	零第三方运行时依赖，并采用标准 MCP STDIO。
可衡量	公开的工具选择和决策稳定性评估资源。

决策流程如下：

free-form state
      ↓
  TypeSafe Jev
      ↓
probabilistic judgment
      ↓
    Arbitype
      ↓
typed decision + probability
      ↓
agent / code branch

实际用例

从以下小型可运行示例开始：

场景	工具	展示内容
支持请求路由	route	选择一个后续操作，但不执行它。
PR 验证	verify	独立检查多项声明。
发布审查	review / gate	将整体审查与设有阈值的检查区分开来。
Agent 后续步骤	route	限定后续工作流操作的范围。

示例输出仅为说明性示例，并非实时模型结果、准确率声明或授权决策。

工具

Arbitype 提供九个只读、幂等的 MCP 工具：

工具	适用场景	结果
evaluate	需要自定义的类型化 Jev 问题集时。	原始类型化 Jev 响应。
classify	需要从无序标签中选择一项时。	选项和概率分布。
score	需要一个有序评分或等级时。	加权分数和分布。
check	需要某个有界标准的概率时。	Noul 是／否概率。
verify	需要独立检查多项命名声明时。	每项声明对应一个 Noul 答案。
gate	需要将检查项和阈值转换为信号时。	通过、审查或失败。
route	需要一个建议的后续操作时。	一个操作；不执行操作。
review	需要整体质量或风险评估时。	审查决策和证据。
health	需要本地诊断或明确执行实时检查时。	配置和可选的提供方健康状态。

工具选择指南

需求	使用	不要替代为
一个无序标签	classify	route，它会选择一个操作
一个有序评分	score	classify，它不涉及顺序
一个有界命题	check	verify，它处理多项声明
多项命名声明	verify	review，它评估整个对象
检查项加阈值	gate	review，它用于整体评估
一个后续操作	route	classify，它返回一个类别
整个差异、计划、发布或报告	review	verify，它逐项回答声明

工具说明还会标明适用和不适用边界，帮助宿主在没有隐藏提示词约定的情况下选择基本工具。

概率和置信度是模型信号，并非证明。gate 和 review 是用于转换决策的辅助工具，并非授权系统、安全边界或审批引擎。

架构

flowchart LR
    host["AI Agent / MCP Host<br/>Codex · Claude · Cursor · VS Code"]
    arbitype["Arbitype<br/>Typed decision tools"]
    jev["TypeSafe Jev<br/>System One Model"]
    env["TYPESAFE_API_KEY<br/>process environment"]

    host -->|MCP| arbitype
    arbitype -->|validated HTTPS| jev
    jev -->|typed probabilistic judgment| arbitype
    arbitype -->|structured decision| host
    env -. credential .-> arbitype

公开产品是 Arbitype；当前提供方是 TypeSafe Jev。提供方配置刻意保留 TYPESAFE_* 名称，因为凭据和端点属于 TypeSafe。

基准测试概览

在公开的、由 Jev 处理的 120 个案例工具选择评估中记录：

指标	结果
工具选择准确率	96.67%
无效工具率	0%
架构验证通过率	100%

这是一项针对 Arbitype 所提供 MCP 工具目录、由 Jev 处理的评估。它不是 Codex、Claude 或 Cursor 宿主基准测试，也不代表对模型整体性能的保证。

详情和可复现资源：

• 基准测试方法
• 工具选择数据集
• 已记录的报告

安全边界

Arbitype 是一个本地 MCP 适配器和类型化决策层。它不是：

• 不可信代码的沙箱；
• 授权或身份系统；
• 提示词注入防火墙；
• 安全审批边界；或
• TypeSafe AI 的官方产品。

它不会执行路由建议的操作、编辑文件、运行 shell 命令，也不会将模型概率视为证据。使用真实凭据前，请阅读 SECURITY.md。

文档

• 宿主配置
• 配置参考
• MCP Registry 迁移
• 供应链安全态势
• 可观测性提案
• 测试
• 基准测试
• 贡献指南
• 安全
• 官方 MCP Registry 条目
• Glama 列表（索引和元数据刷新可能晚于发布）

开发

测试套件使用本地模拟对象，无需 API 密钥：

python3 -m unittest discover -s tests -v
python3 -m compileall -q .
make check
make release-check

官方 MCP Python SDK 互操作性冒烟测试位于 scripts/official_sdk_smoke.py。实时 Jev 检查为可选项，且需要付费：

TYPESAFE_API_KEY="your-key" arbitype doctor --live

常规 CI 不会调用服务提供方，也不会运行付费基准测试。