Jev MCP

Jev MCP

一个小巧且依赖精简的 MCP 服务，可通过 OpenRouter 或直接通过 TypeSafe，让任何 MCP 客户端获得来自 Jev（TypeSafe 的 System One 模型）的类型化概率决策。

Jev 不会编写文本。你向它发送数据和类型化问题，它会针对每个问题返回一个经过校准的答案：从你提供的选项中作出选择，为是/否问题给出概率，或在你定义的量表上给出位置；每个答案都附带置信度和完整的概率分布。它会在一次并行处理中快速作答，成本仅为聊天模型的一小部分，并且不会返回你未提供的选项。

此服务将其封装为五种 MCP 工具，会验证提供方返回的每个答案，绝不泄露你的凭据，也绝不重试收费调用。

为什么使用它

• 让你的 Agent 作出决策，而不是猜测。 路由、分流、分类、声明核验和排序都能变成明确的类型化调用，并返回带概率的结果，供工作流执行或升级处理。
• 成本低、速度快。 每次工具调用只进行一次付费推理，无论其中包含多少条目或问题。
• 不依赖特定提供方。 使用你已有的 OpenRouter 密钥或 TypeSafe 密钥。只需更改一个环境变量即可切换。
• 输出诚实可靠。 答案会根据你提出的问题进行验证；答案不一致或不完整时，调用会失败，而不会擅自修补。始终返回未经更改的提供方响应，包括 usage.cost。
• 设计上安全。 凭据仅保存在服务环境中；强制使用 HTTPS、拒绝重定向，并限制请求与响应的大小和耗时。

快速开始

1. 获取 API 密钥

• OpenRouter（默认）：在 openrouter.ai 创建密钥，并设置 OPENROUTER_API_KEY。Jev 在 OpenRouter 上的名称是 typesafe/jev-latest；也可以使用简写 ID jev-latest。
• TypeSafe：在 typesafe.ai 创建密钥，并设置 TYPESAFE_API_KEY，同时设置 JEV_PROVIDER=typesafe。

2. 安装服务

选择一种方式：

二进制文件。 从 Releases 下载适用于你平台的压缩包（Linux、macOS 和 Windows，amd64 和 arm64），根据 checksums.txt 验证，并将 jev-mcp 放入 PATH。

容器。 每个已标记的发布版本都会发布对应镜像：

docker pull ghcr.io/freepik-company/jev-mcp:latest

Go 工具链。

go install github.com/freepik-company/jev-mcp/cmd/jev-mcp@latest

3. 在 MCP 客户端中注册

此服务通过 stdio 使用 MCP 协议，并从其环境中读取凭据。切勿将密钥放在工具参数中。

Claude Code

claude mcp add jev -e OPENROUTER_API_KEY="$OPENROUTER_API_KEY" -- jev-mcp

Claude Desktop、Cursor 和其他使用 JSON 配置的客户端

{
  "mcpServers": {
    "jev": {
      "command": "jev-mcp",
      "env": { "OPENROUTER_API_KEY": "sk-or-..." }
    }
  }
}

使用容器而非二进制文件（使用 -i，不要使用 -t；密钥会从客户端环境继承）：

{
  "mcpServers": {
    "jev": {
      "command": "docker",
      "args": ["run", "--rm", "-i", "-e", "OPENROUTER_API_KEY", "ghcr.io/freepik-company/jev-mcp:latest"]
    }
  }
}

若要直接使用 TypeSafe，请添加 "JEV_PROVIDER": "typesafe" 和 TYPESAFE_API_KEY，而不是 OpenRouter 密钥。

此服务也已列入 MCP Registry，名称为 io.github.freepik-company/jev-mcp，因此可以浏览该注册表的客户端可直接从中安装。

配置

变量	默认值 / 用途
JEV_PROVIDER	openrouter 或 typesafe（默认：openrouter）
OPENROUTER_API_KEY	OpenRouter 凭据
TYPESAFE_API_KEY	TypeSafe 凭据
API_KEY	覆盖所选提供方的凭据
JEV_MODEL	jev-latest；可通过工具调用中的 model 覆盖
BASE_URL	提供方 API 根地址；后面会追加 /v1/systemone

默认根地址：https://openrouter.ai/api 和 https://api.typesafe.ai。 BASE_URL 必须使用 HTTPS；仅允许在回环地址上使用普通 HTTP，以供本地 代理和测试使用。凭据应放在服务环境中，绝不能放在工具参数里。

工具

工具	输入	结果
decide	共享的 state 和命名的 questions	原始类型化答案和提供方元数据
classify	items、categories、instructions	每个条目的类别、置信度和概率
verify	claims、evidence	每项声明对应 supported、contradicted 或 insufficient_evidence
rerank	query、candidates、可选的 top_k	按 0–4 评分标准给出的降序相关性分数
list_models	无参数	兼容的模型 ID 和配置的默认模型

Items、claims、evidence 和 candidates 均为 { "id": "unique-id", "text": "..." } 数组，包含 1–64 个条目。Categories 将类别 ID 映射到描述。三个任务工具 均接受可选的 model，进行一次推理调用，并返回 results 以及未更改的提供方 response（包括提供的 response.usage.cost）。 分类和验证会保留输入顺序；排序会在分数相同时保留输入顺序。 top_k 会在评估所有候选项后筛选结果。输入绝不会被截断。

验证仅使用提供的证据；其判定是模型判断，并非证明或认可。不会强制执行 自动接受阈值。模型发现会使用 OpenRouter 的 decisions 目录或 TypeSafe 的原生目录，不进行推理。

示例：decide

{
  "state": {"ticket": "Please refund the duplicate charge."},
  "questions": {
    "department": {
      "type": "choice",
      "instructions": "Which team should handle this ticket?",
      "criteria": {"billing": "Payments and refunds", "technical": "Software defects"}
    },
    "refund": {"type": "noul", "instructions": "Is a refund requested?"},
    "urgency": {
      "type": "score",
      "instructions": "How urgent is this ticket?",
      "criteria": ["Routine", "Service blocked", "Active financial harm"]
    }
  }
}

choice 会选择一个提供的选项；noul 会返回 P(true)；score 会返回 按概率加权的评分指标。完整的提供方输出都会保留，包括评分图例和可用时的 usage.cost。

示例：classify

{
  "instructions": "Route each support message to the right queue.",
  "categories": {
    "billing": "Charges, invoices and refunds",
    "technical": "Bugs, errors and outages",
    "other": "Anything else"
  },
  "items": [
    {"id": "m1", "text": "I was charged twice this month."},
    {"id": "m2", "text": "The export button does nothing."}
  ]
}

每个条目会按输入顺序返回一个 { "id", "category", "confidence", "probabilities" }， 并附上完整的提供方 response。

限制和故障模式

未知输入字段以及不完整或不一致的答案都会导致调用失败。 请求超时时间为 30 秒，输入限制为 1 MiB，响应限制为 2 MiB。 付费调用不会自动重试。提供方错误只会显示 HTTP 状态码，不会显示响应正文，因此提供方回显的凭据不会传递给模型。完整约定请参阅 input 和 output 架构。

开发

只需要 Docker：

make test       # formatting, vet, race-enabled unit and integration tests
make image      # runtime image, tagged jev-mcp:local
make release    # archives and checksums for every platform in dist/

cmd/jev-mcp 包含入口点。internal/ 将配置、System One 客户端和答案验证、 任务层以及 MCP 协议分开。 CI 会在每次推送和拉取请求时验证构建和测试；版本标签会发布 发行版归档文件、GHCR 上的容器映像以及 MCP Registry 中的条目。

有关工作流和设计原则，请参阅 CONTRIBUTING.md； 有关漏洞报告，请参阅 SECURITY.md；有关发行说明，请参阅 CHANGELOG.md。

许可证

Apache License 2.0。Jev 和 System One 是 TypeSafe AI 的产品；本项目是一个独立客户端， 与 TypeSafe 或 OpenRouter 均无关联。