Metadata-Version: 2.4
Name: wb-cn-model-gateway-mcp
Version: 1.2.0
Summary: 国产大模型网关 MCP 连接器（15 个工具，12 家模型，合并路由/成本/硬件能力）
Requires-Python: >=3.10
Description-Content-Type: text/markdown

# 国产大模型统一调用网关（cn-model-gateway）

**开发者：牛魔科技工作室**

把 12 家国产大模型统一封装成一个常驻 MCP 服务，对外暴露 15 个标准 MCP 工具。
**纯 Python 标准库，零第三方依赖**（讯飞星火可选 `websocket-client`），填好 `config.json` 的 `api_key` 即可运行。

> 本连接器已合并原 `cn-llm-router` 的路由决策 / 模型竞技场 / 成本可观测 / 硬件画像能力，
> 两者不再分装，统一为单一连接器提交平台。

## 支持的模型厂商（12 家）

| 厂商 | provider 标识 | 环境变量 |
|---|---|---|
| DeepSeek | `deepseek` | `DEEPSEEK_API_KEY` |
| 阿里通义千问 | `tongyi` | `DASHSCOPE_API_KEY` |
| 智谱 GLM | `zhipu` | `ZHIPU_API_KEY` |
| Moonshot Kimi | `kimi` | `KIMI_API_KEY` |
| 腾讯混元 | `hunyuan` | `HUNYUAN_API_KEY` |
| 火山豆包 | `doubao` | `DOUBAO_API_KEY` |
| MiniMax | `minimax` | `MINIMAX_API_KEY` |
| 零一万物 Yi | `lingyi` | `LINGYI_API_KEY` |
| 百川智能 | `baichuan` | `BAICHUAN_API_KEY` |
| 阶跃星辰 Step | `stepfun` | `STEPFUN_API_KEY` |
| 百度文心 | `ernie` | `ERNIE_OPENAI_KEY`（或 `ERNIE_API_KEY`+`ERNIE_SECRET_KEY`） |
| 讯飞星火 | `spark` | `SPARK_API_KEY` + `SPARK_APP_ID` + `SPARK_API_SECRET` |

> 环境变量优先级高于 `config.json`，两者都没有则视为未配置。

## 提供的 15 个 MCP 工具

| 工具 | 说明 | 需要 API Key |
|---|---|---|
| `ask_model` | 文本问答；`providers` 传 2 家以上返回对比结果；支持 Function Calling | 是 |
| `describe_image` | 图片理解（Qwen-VL / GLM-4V / 豆包视觉） | 是 |
| `embed_text` | 文本向量嵌入 | 是 |
| `rerank` | 文档按相关性重排序 | 是 |
| `audio_transcribe` | 语音转文字 | 是 |
| `video_understand` | 视频理解（关键帧 + 视觉描述） | 是 |
| `list_providers` | 列出已配置且可用的提供商 | **否** |
| `health_check` | 检查所有提供商连通性 | **否** |
| `route_decision` | 路由决策：按任务类型推荐最优厂商/模型（不调 API） | **否** |
| `arena` | 模型竞技场：多模型并排对比（支持盲选 / mock 演示） | 是 / mock 否 |
| `cost_report` | 跨厂商 token 成本与用量报表（日/周/月） | **否** |
| `budget` | 本月预算使用与告警（阈值在 config.json 的 `budget_monthly`） | **否** |
| `cache` | 语义缓存管理（stats 查看 / clear 清空，省 token） | **否** |
| `hardware` | 硬件画像与并发建议（CPU / 内存 / 最大并发 / 单批大小） | **否** |
| `version` | 查看连接器版本 | **否** |

## 配置方法

编辑连接器目录下的 `config.json`，把要用到的厂商 `api_key` 填进去即可：

```json
{
  "deepseek": { "api_key": "sk-你的密钥" },
  "zhipu":    { "api_key": "你的密钥" },
  "budget_monthly": 50
}
```

不填的厂商保持空字符串会自动跳过，不影响其他厂商使用。
未配置任何 Key 时连接器仍可正常启动，`list_providers` / `health_check` / `route_decision` 等免密钥工具可用，
调用类工具会返回中文配置引导，不会崩溃。

## 能力特性

- **能力画像自动选路**：`ask_model` 不指定 provider 时，按任务类型与能力评分自动挑最优模型
- **自动故障转移**：超时或失败自动切换备用模型
- **统一中文错误映射**：不暴露原始英文 API 报错
- **使用量统计**：内置 SQLite（WAL 模式）记录调用量、token 消耗与各模型占比
- **硬件感知并发控制**：自动采集 CPU / 内存，动态限制并发，不拖慢本机
- **跨厂商成本可观测**：`cost_report` / `budget` 基于本地 SQLite 聚合花费、成功率、P95 延迟
- **路由决策与竞技场**：`route_decision` 按任务分类推荐模型；`arena` 多模型并排对比选型
- **流式 SSE 输出**：支持 `stream_chat` 逐字返回

## 目录结构

```
cn-model-gateway-connector/
├── mcp_server.py         入口：加载配置 → 注册适配器 → 启动 MCP stdio 服务
├── mcp.json              MCP 服务器声明
├── connector-meta.json   连接器元信息（source / 版本 / 示例）
├── config.json           API Key 配置（默认全空，开箱即用）
├── src/                  核心实现
│   ├── mcp_server.py     JSON-RPC 2.0 服务与 15 个工具
│   ├── router.py         路由（转发到 llm_core）
│   ├── llm_core/         适配器内核、错误映射、能力评分
│   ├── adapters/         12 家厂商适配器
│   ├── frameworks/       LangChain / AutoGPT / CrewAI / Coze / Dify 适配
│   ├── monitor.py        使用量统计
│   ├── benchmark.py      性能基准测试套件
│   ├── price_tracker.py  价格追踪
│   ├── hardware.py       硬件画像
│   ├── classifier.py     任务分类器
│   ├── cache.py          语义缓存
│   ├── cost_tracker.py   成本聚合
│   └── report.py         成本报表
└── icon.svg
```

## 注意事项

- 本连接器只做协议网关：不做本地推理、不做微调、不做私有部署
- 所有日志输出到 stderr，stdout 专用于 MCP 协议通信
- 需要 Python 3.9+

有更好建议：njskills@agent.qq.com
