# TypeSafe MCP Server

一个基于 [Model Context Protocol (MCP)](https://modelcontextprotocol.io) 的
TypeSafe System One 服务，让 MCP 客户端可以调用 Jev 模型完成结构化判断。

## 工具

### `typesafe_classify`

通用结构化判断，支持 TypeSafe 的三种问题类型：

- `choice`：从一组候选项中选择并返回概率分布
- `score`：根据有序标准评分
- `noul`：返回“是”的概率

`content` 可以是字符串、JSON 对象或数组，并可在一次请求中提交多个问题。

### `typesafe_ticket_classify`

分析工单类型、优先级、负责部门、用户情绪和影响范围。

### `typesafe_content_moderate`

检测暴力、色情、仇恨言论和垃圾信息，并给出风险评分与处理建议。

## 要求

- Python 3.10+
- TypeSafe API Key，可从 [TypeSafe Console](https://console.typesafe.ai/keys) 获取

## 安装与运行

推荐使用 [uv](https://docs.astral.sh/uv/)：

```bash
git clone https://github.com/wangBoYi972/typesafe-mcp.git
cd typesafe-mcp
uv sync
TYPESAFE_API_KEY=your-api-key uv run typesafe-mcp
```

也可以使用 pip：

```bash
python -m venv .venv
source .venv/bin/activate
pip install .
TYPESAFE_API_KEY=your-api-key typesafe-mcp
```

服务使用 stdio 传输，正常启动后不会输出提示信息。

## MCP 客户端配置

以 Claude Code 为例，在 MCP 配置中添加：

```json
{
  "mcpServers": {
    "typesafe": {
      "command": "uv",
      "args": [
        "--directory",
        "/absolute/path/to/typesafe-mcp",
        "run",
        "typesafe-mcp"
      ],
      "env": {
        "TYPESAFE_API_KEY": "your-api-key"
      }
    }
  }
}
```

将仓库路径替换为本机绝对路径，然后重新加载 MCP 客户端。

## 通用分类示例

下面是传给 `typesafe_classify` 的参数：

```json
{
  "content": "这个产品太棒了！",
  "questions": {
    "sentiment": {
      "type": "choice",
      "instructions": "判断文本表达的主要情感。",
      "criteria": {
        "positive": "积极正面",
        "neutral": "中性客观",
        "negative": "消极负面"
      }
    },
    "intensity": {
      "type": "score",
      "instructions": "评估情感表达强度。",
      "criteria": ["几乎没有情感", "轻微", "明显", "强烈"]
    },
    "is_recommendation": {
      "type": "noul",
      "instructions": "这段文本是否在推荐该产品？"
    }
  },
  "model": "jev-latest"
}
```

Score 的结果按 `criteria` 的零基索引计算。例如四个等级对应 0 到 3，而不是任意的
`min`/`max` 区间。

## 配置

| 环境变量 | 必需 | 默认值 | 说明 |
| --- | --- | --- | --- |
| `TYPESAFE_API_KEY` | 是 | - | TypeSafe API 密钥 |
| `TYPESAFE_BASE_URL` | 否 | SDK 默认值 | 自定义 API 根地址 |
| `TYPESAFE_TIMEOUT` | 否 | `30` | 单次 HTTP 操作超时秒数 |
| `TYPESAFE_MAX_RETRIES` | 否 | `2` | 连接失败、超时、429 和 5xx 的最大重试次数 |

支持 `jev-latest`、`jev-preview` 和版本化模型 ID，例如 `jev-1.13.0`。完整模型列表见
[TypeSafe Models](https://docs.typesafe.ai/models)。

## 开发

安装开发依赖并运行全部检查：

```bash
uv sync --extra dev
uv run pytest
uv run ruff check .
uv run pyright
```

测试不会调用真实 TypeSafe API。GitHub Actions 会在 Python 3.10、3.11、3.12 和 3.13
上运行相同检查。

## 错误处理

服务使用官方 `typesafe-sdk`：

- API 请求全程异步
- 默认对连接错误、超时、429 和 5xx 自动重试
- 认证、权限、限流和连接错误会转换成可读的 MCP 工具错误
- API 密钥不会包含在工具错误或日志中

## 许可证

[MIT](LICENSE)

## 相关链接

- [TypeSafe API 文档](https://docs.typesafe.ai/api)
- [TypeSafe Python SDK](https://docs.typesafe.ai/sdk/python)
- [Model Context Protocol](https://modelcontextprotocol.io)