# yf-decide-mcp

一个通用的 MCP 服务，对接 **System One 类型化决策端点**（`POST {BASE_URL}/v1/systemone`）。

它只做一件事：让你能从任何 MCP 客户端使用**任意** System One 提供方，包括那些
`jev-decision-mcp` 用不了的。

那个服务把 `usage.output_tokens` 当作必填字段，缺失就返回 `INVALID_RESPONSE`；
百炼的 `decision-model-preview` 只返回 `input_tokens`，所以在那边根本跑不起来。
本服务对 `usage` 做宽松归一化（缺的字段补 `null`），其余原样透传。

**不内置任何分类体系或业务判据——问题由调用方每次请求时传入。**

## 安装运行

```bash
npx -y yf-decide-mcp
```

## 配置

| 变量 | 必填 | 说明 |
|---|---|---|
| `BASE_URL` | 是 | 端点根地址。**不要带 `/v1`**，服务端会自己拼 `/v1/systemone`。 |
| `MODEL` | 是 | 默认模型名，可被单次调用覆盖。 |
| `API_KEY` | 否 | Bearer 凭据。不设时请求里完全不带这个头。 |
| `TIMEOUT_MS` | 否 | 单次请求超时，默认 `30000`。 |

MCP 客户端配置：

```json
{
  "mcpServers": {
    "systemone": {
      "command": "npx",
      "args": ["-y", "yf-decide-mcp"],
      "env": {
        "BASE_URL": "http://127.0.0.1:3425",
        "API_KEY": "your-key",
        "MODEL": "your-model"
      }
    }
  }
}
```

要同时对接两个提供方，就把这个服务注册两次、起不同名字、给不同的 `BASE_URL` / `MODEL`——
每个进程固定一个端点。

## `decide` 工具

只有一个工具，四种问题类型：

| `type` | 回答什么 | 返回字段 |
|---|---|---|
| `choice` | 从 `criteria` 里选一个标签 | `choice`、`probabilities`、`confidence` |
| `score` | 落在 2–10 个有序档位上的位置，0 起 | `score`、`legend`、`probabilities`、`confidence` |
| `noul` | yes 的概率（0–1） | `noul` |
| `box` | 感兴趣区域，归一化 0–1 | `box`、`confidence` |

### 示例

```json
{
  "name": "decide",
  "arguments": {
    "state": { "message": "我的订单一直没到，帮我退款" },
    "questions": {
      "team": {
        "type": "choice",
        "instructions": "这条消息该由哪个团队处理？",
        "criteria": {
          "billing": "付款与退款",
          "shipping": "配送",
          "other": "其他"
        }
      },
      "urgency": {
        "type": "score",
        "instructions": "这件事有多紧急？",
        "criteria": ["可以等", "本周内", "今天", "立刻"]
      }
    }
  }
}
```

返回：

```json
{
  "model": "typesafe/jev-1.14-20261014",
  "answers": {
    "team": {
      "type": "choice",
      "choice": "billing",
      "probabilities": { "billing": 0.87, "shipping": 0.12, "other": 0.01 },
      "confidence": 0.8
    },
    "urgency": {
      "type": "score",
      "score": 1.64,
      "legend": { "0": "可以等", "1": "本周内", "2": "今天", "3": "立刻" },
      "probabilities": { "0": 0.02, "1": 0.4, "2": 0.5, "3": 0.08 },
      "confidence": 0.48
    }
  },
  "usage": { "input_tokens": 398, "output_tokens": 53 },
  "provider": "TypeSafe",
  "id": "gen-dec-..."
}
```

### 怎么把问题写好

- **把模型需要的事实全放进 `state`**。它看不到你的对话，也读不到本地文件。
- **完整的判断写在 `instructions` 里**。问题 ID 只是返回时的键名，模型不认它。
- **`criteria` 的描述要具体**。写成「敏感 / 不敏感」这种，概率会糊在 0.5 附近。
- 需要时给一个「都不匹配 / 其他」选项。
- **做阈值判断时看概率，别看 `choice`**。0.55 和 0.98 在业务上完全不是一回事。
- **`score` 是期望档位**，即 $\sum_i i \cdot p_i$，不是强度大小。要结合 `legend` 读。
- **`noul` 接近 0.5 表示对 yes/no 不确定**，不是「中等强度」。

## 错误处理

失败一律返回 `isError: true` 加一段 JSON，绝不编造答案：

| 错误码 | 含义 |
|---|---|
| `CONNECTION_ERROR` | 端点连不上 |
| `TIMEOUT` | 超过 `TIMEOUT_MS` |
| `INVALID_RESPONSE` | 返回不是 JSON，或没有 `answers` 对象 |
| `API_ERROR` | 上游返回非 2xx（错误信息会带出来） |
| `UNKNOWN_TOOL` | 工具名不对 |

注意：部分提供方自带输入审核，可能在模型看到请求之前就用 4xx 拒掉。这会被归为
`API_ERROR`——请把它当作提供方的策略结果，而不是传输故障。

## 与 `jev-decision-mcp` 的差异

| | jev-decision-mcp | systemone-mcp |
|---|---|---|
| `usage.output_tokens` | 必填 | 可选，缺了补 `null` |
| 不返回该字段的端点（如百炼） | `INVALID_RESPONSE` | 正常可用 |
| 内置分类体系 | 无 | 无 |
| 运行时依赖 | MCP SDK + zod + TypeSafe SDK | 仅 MCP SDK |
| 问题类型 | choice / score / noul | choice / score / noul / box |

## 许可

MIT