jev-decision-mcp

Jev Decision MCP

一个本地 stdio MCP 服务，通过任何兼容 SDK 的决策 API 端点提供一个工具 jev_decide，用于执行类型化决策。将其指向配置了 BASE_URL 和 MODEL 的端点即可；没有预设提供商、主机允许列表或模型允许列表。使用 TypeScript、官方 MCP SDK 和类型化决策 SDK @typesafe-ai/sdk 编写。

独立社区项目；与 SDK 供应商无关。基于 MIT 许可协议授权。

问题	用途	结果
choice	选择标签或候选项	选择结果、概率、置信度
score	按 2–10 个有序等级对单个维度评分	从 0 开始的分数、概率、图例、置信度
noul	判断某个条件是否成立	是的概率，范围为 0 到 1

一次调用中，可基于同一上下文批量处理相互独立的问题。答案会保留其问题 ID。MCP 返回判断结果和 token 用量；阈值设定、升级处理和操作执行由调用方负责。

要求

• Node.js 22 或更高版本，并且 PATH 中可用 npm。
• 支持本地 stdio 服务的 MCP 客户端。
• 所配置决策端点的 API 密钥（API_KEY）。仅决策调用需要该密钥——无需密钥即可发现此工具。

此处的“兼容 SDK”是什么意思。 兼容性指 @typesafe-ai/sdk 的类型化决策契约：端点必须实现 SystemOne 请求（POST {BASE_URL}/v1/systemone），并返回包含概率分布和用量计数的类型化 choice/score/noul 答案。

从 npm 安装

npm 包包含构建好的服务。npx 会在首次使用时下载该包并运行，无需克隆或构建：

npx -y [email protected]

将以下内容添加到 MCP 客户端的配置中，并将占位符替换为端点的值。对于使用 mcpServers JSON 的客户端：

{
  "mcpServers": {
    "jev": {
      "command": "npx",
      "args": ["-y", "[email protected]"],
      "env": {
        "API_KEY": "YOUR_API_KEY",
        "BASE_URL": "https://api.example.com/decisions",
        "MODEL": "your-model-name"
      }
    }
  }
}

也可以在启动客户端的环境中设置 API_KEY、BASE_URL 和 MODEL，如果客户端会转发这些变量，则省略 env。保存配置后，重启或重新加载客户端的 MCP 服务；届时会显示 jev_decide 工具。

如果主机无法解析 npx，请使用该主机文档中介绍的平台专用启动器或绝对路径。GUI 应用的 PATH 可能与终端中的不同。

该服务通过 stdio 通信；在终端中启动时，它会等待 MCP 客户端，而不会打开网页。npm 安装不会读取调用方工作目录中的 .env。

若要改为全局安装可执行文件：

npm install -g [email protected]

然后在 MCP 客户端中使用不带参数的 "command": "jev-decision-mcp"，并提供相同的 API_KEY、BASE_URL 和 MODEL 值。

通过 Glama 安装

打开 Glama 上的 Jev Decision MCP，查看其 README、工具架构和源代码。若要本地安装，请使用上方的 npm 配置，或点击列表中的 GitHub Repository 链接下载或克隆源代码，然后按下文所述进行构建。Glama 将其列为本地 stdio 服务；列表 URL 不是 MCP 连接端点。

端点配置

启动时必须设置 BASE_URL 和 MODEL，且它们在进程运行期间固定不变；工具调用只能覆盖模型名称。没有运行时预设选择器：服务不会针对每次调用切换端点或凭据，除了 URL 验证外，也不会应用主机或模型允许列表。BASE_URL 是一个前缀 — SDK 会在其后追加 /v1/systemone — 因此支持带自定义路径前缀的 HTTP(S) URL。

参考端点（仅为示例；不代表暗示或认可任何提供商）。 以下是已知兼容 SDK 的端点，你可以将其复制到 BASE_URL/MODEL，并使用自己的 API_KEY：

示例	BASE_URL	MODEL
TypeSafe	https://api.typesafe.ai	jev-latest
Liquid	https://api.liquid.ai/decisions	d1-ultra

使用两个实例比较端点。 为每个端点配置一个实例，并向每个实例的 jev_decide 发送相同的请求：

{
  "mcpServers": {
    "jev-a": {
      "command": "npx",
      "args": ["-y", "[email protected]"],
      "env": {
        "API_KEY": "YOUR_FIRST_API_KEY",
        "BASE_URL": "https://api.typesafe.ai",
        "MODEL": "jev-latest"
      }
    },
    "jev-b": {
      "command": "npx",
      "args": ["-y", "[email protected]"],
      "env": {
        "API_KEY": "YOUR_SECOND_API_KEY",
        "BASE_URL": "https://api.liquid.ai/decisions",
        "MODEL": "d1-ultra"
      }
    }
  }
}

每个实例都会固定使用自己的端点，因此每次调用的比较结果始终只对应一个端点。

连接到 Codex

对于 npm 包，将以下内容合并到 Codex 的 config.toml 中：

[mcp_servers.jev]
command = "npx"
args = ["-y", "[email protected]"]
env_vars = ["API_KEY", "BASE_URL", "MODEL"]
tool_timeout_sec = 45

在启动 Codex 的环境中设置 API_KEY、BASE_URL 和 MODEL；env_vars 会将它们现有的值转发给服务。将主机工具超时时间设置为高于 JEV_TIMEOUT_MS / 1000。请参阅官方 Codex MCP 配置。

从源代码构建

克隆仓库、安装其依赖项并编译服务：

git clone https://github.com/amidabuddha/jev-decision-mcp.git
cd jev-decision-mcp
npm ci
npm run build

你也可以在 GitHub 上通过 Code → Download ZIP 下载仓库，解压后在解压目录中运行 npm ci 和 npm run build。

将 .env.example 复制为该目录中的 .env，并设置 API_KEY、BASE_URL 和 MODEL，或者通过 MCP 客户端的环境提供这些值。无论当前工作目录是什么，源码构建都会读取此 .env；现有环境变量优先级更高。更改后请重启服务。.env 已从 Git 中排除。

配置 MCP 客户端以运行构建后的入口文件：

{
  "mcpServers": {
    "jev": {
      "command": "node",
      "args": ["/absolute/path/to/jev-decision-mcp/dist/index.js"]
    }
  }
}

将占位符替换为检出目录的绝对路径。Windows 路径可以使用正斜杠，例如 C:/projects/jev-decision-mcp/dist/index.js。如果客户端的 PATH 中没有 node，请使用 Node 可执行文件的绝对路径。

对于 Codex，请使用上方 TOML 示例中的相同 command 和 args。只有在通过 Codex 的环境而非 .env 提供配置时，才保留 env_vars。

要验证构建，请运行 npm run check（使用模拟 API 响应进行类型检查和测试；不发起网络调用）。本地开发时使用 npm run dev；修改源码后，在重启 MCP 客户端前运行 npm run build 重新构建。

配置

在 MCP 客户端的服务环境中设置这些变量；如果是从源码构建，则在 .env 中设置。只会读取以下四个变量：

变量	默认值	用途
API_KEY	无	配置端点的 Bearer 凭据；决策调用必需，工具发现时启动可选
BASE_URL	无	绝对 http(s) API 根路径前缀（SDK 会追加 /v1/systemone）；启动时必需
MODEL	无	决策调用的默认模型名称；启动时必需
JEV_TIMEOUT_MS	30000	每次调用的总时限，包括 SDK 重试；1–120000 ms

必需与可选。 启动时必须显式设置 BASE_URL 和 MODEL；否则服务会因配置错误退出，且不会回退到 SDK 或供应商默认值。启动时 API_KEY 为可选，因此客户端可以在没有密钥的情况下发现 jev_decide；没有密钥时进行决策调用会返回 MISSING_API_KEY。仅包含空白字符的值会被视为未设置。

模型优先级（从高到低）：单次调用的 model 参数，其次是 MODEL。单次调用的 model 为空或仅包含空白字符时会被拒绝，并返回 INVALID_INPUT；它绝不会回退到空白或隐藏的默认值。单次调用指定的模型只会更改请求中的模型名称；凭据和目标地址保持不变。

端点由运维人员固定，而非由工具决定。 进程会将每个请求发送到配置的 BASE_URL；工具输入无法更改目标地址，并且没有供应商主机或模型允许列表——BASE_URL 可接受任何主机和任何路径前缀（包括用于自托管的 localhost）。BASE_URL 必须是绝对 http:/https: URL，且不能包含凭据、查询或片段；启动时会拒绝包含 ? 或 # 的值，因此不会追加空的查询或片段分隔符。状态和问题会发送到配置的端点，并可能产生 API 费用。服务不会持久化输入或决策，也不会暴露上游错误响应正文。

超时。 JEV_TIMEOUT_MS 是单次决策调用的总时限，包括 SDK 自动重试（单次尝试的时限上限为 10 秒）。请将客户端的工具超时设置为高于 JEV_TIMEOUT_MS / 1000 秒。

从 0.1.3 迁移。 0.1.3 读取 TYPESAFE_API_KEY 和 TYPESAFE_DEFAULT_MODEL（默认值为 jev-latest），并始终将请求发送到 https://api.typesafe.ai。请将 TYPESAFE_API_KEY 改为 API_KEY，将 TYPESAFE_DEFAULT_MODEL 改为 MODEL；如果依赖旧的默认模型，请显式设置 MODEL=jev-latest。添加 BASE_URL=https://api.typesafe.ai，以继续使用 0.1.3 的端点。最后，将固定的程序包配置更新为 [email protected]，并重启或重新加载宿主，使新进程读取重命名后的变量。

调用工具

使用 examples/decision.json 中的 JSON 调用 jev_decide。它会结合团队选择、退款是/否判断和紧急程度评分。较小的示例如下：

{
  "state": { "request": "Please refund the duplicate charge." },
  "questions": {
    "route": {
      "type": "choice",
      "instructions": "Which team should handle `request`?",
      "criteria": {
        "billing": "Charges, invoices, refunds",
        "technical": "Broken software or integrations",
        "other": "Neither billing nor technical"
      }
    }
  }
}

响应包含 model、answers 和 usage，既以 MCP 结构化内容形式提供，也以 JSON 文本形式提供。Jev 可能会将概率四舍五入到小数点后两位，因此概率之和可能与 1 略有差异。服务端允许相应的舍入误差（每个选项最多 0.005），且绝不会修正返回值：所有内容都会严格按 API 发送的原样传递，概率绝不会重新归一化，也绝不会凭空生成 token 数量。usage 计数为 null 的响应属于不兼容响应，会被拒绝并返回 INVALID_RESPONSE，而不是报告编造的零值。Choice 支持 1–255 个命名选项。

接受的输入形态保持不变：instructions 和 descriptions 可以是字符串、JSON 对象或数组；choice descriptions 可以为 null；noul 接受可选的 criteria.true 和 criteria.false descriptions，这些 descriptions 可以为 null。在请求传输过程中，服务端只进行一次规范化：当 noul 的 criterion description 为 null 时，会从发出的请求中省略；如果 criteria 对象中没有剩余的 description，则会将整个对象省略。这是与提供方无关的规范性省略，用于处理未设置的可选 description——部分端点会因收到 null 的 noul description 而返回 HTTP 422，但会将省略的 description 视为未描述（在 Liquid 参考端点上观察到此情况；省略后问题得到解决）。其余内容都会严格按提供的原样传递：非 null 的 noul descriptions（包括包含嵌套 null 的结构化对象和数组），以及所有 choice 和 score 值（包括为 null 的 choice descriptions）。

请明确提供相关事实、源文本和策略：Jev 无法查看调用方的对话或本地文件。在 instructions 中写出完整判断；ID 仅作为响应键。适当时加入无匹配选项。一次批处理中的问题无法看到彼此的答案。接近 0.5 的 noul 表示对是/否判断不确定，而非中等强度。置信度不能授权执行操作，也不保证正确；请在有代表性的数据上评估阈值。

故障排查

如果更新后工具没有显示，请重启服务端并开启新的客户端会话。已配置的服务端名为 jev；其工具为 jev_decide。在双实例对比设置中，两个服务端都提供 jev_decide；它们的服务端名称（jev-a、jev-b）可用于区分实例。

服务或配置故障会作为 MCP 工具错误返回（isError: true），绝不会生成虚构的判断。错误代码包括 MISSING_API_KEY、INVALID_INPUT、INVALID_RESPONSE、API_ERROR、CONNECTION_ERROR、TIMEOUT 和 CANCELLED。MCP SDK 也可能直接拒绝无效参数。如果缺少或格式错误的 BASE_URL 或 MODEL，启动会因配置错误而失败；错误会指出变量名称，但绝不会回显其值。

参考资料

• TypeSafe JavaScript SDK — 此服务端使用的 @typesafe-ai/sdk
• TypeSafe HTTP API — 此服务端执行的类型化决策（SystemOne）请求
• 决策原语和问题设计
• 函数调用指南