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

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

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

把 10 家国产大模型统一封装成一个常驻 MCP 服务，对外暴露 8 个标准 MCP 工具。
**纯 Python 标准库，零第三方依赖**，填好 `config.json` 的 `api_key` 即可运行。

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

| 厂商 | 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` |

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

## 提供的 8 个 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` | 检查所有提供商连通性 | **否** |

## 配置方法

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

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

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

## 能力特性

- **能力画像自动选路**：`ask_model` 不指定 provider 时，按任务类型与能力评分自动挑最优模型
- **自动故障转移**：超时或失败自动切换备用模型
- **统一中文错误映射**：不暴露原始英文 API 报错
- **使用量统计**：内置 SQLite（WAL 模式）记录调用量、token 消耗与各模型占比
- **硬件感知并发控制**：自动采集 CPU / 内存，动态限制并发，不拖慢本机
- **流式 SSE 输出**：支持 `stream_chat` 逐字返回

## 与 cn-llm-router 的分工

两者是上下两层，不是重复，建议同时安装：

| | 本连接器（gateway） | cn-llm-router |
|---|---|---|
| 层次 | 协议网关层 | 路由决策层 |
| 形态 | 常驻 MCP stdio 服务 | CLI 单次调用 |
| 解决什么 | 让 Agent 框架**调用**国产模型 | 帮用户**挑模型、算成本、限流** |
| 厂商数 | 10 家 | 12 家（多文心、讯飞星火） |

## 目录结构

```
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 服务与 8 个工具
│   ├── router.py         路由（转发到 llm_core）
│   ├── llm_core/         适配器内核、错误映射、能力评分
│   ├── adapters/         10 家厂商适配器
│   ├── frameworks/       LangChain / AutoGPT / CrewAI / Coze / Dify 适配
│   ├── monitor.py        使用量统计
│   ├── benchmark.py      性能基准测试套件
│   └── price_tracker.py  价格追踪
└── icon.svg
```

## 注意事项

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

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