# cn-free-ai-mcp

> 国内直连的**免费 AI 能力** MCP 服务器：文本对话、图片生成、语音识别、语音合成——四合一、零成本、clone 即用。
> Zero-cost, China-accessible AI MCP server: chat, image generation, speech-to-text & text-to-speech — four free AI capabilities in one, works out of the box.

[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
[![Node](https://img.shields.io/badge/node-%3E%3D18-brightgreen)](package.json)

---

# 中文文档

## ✨ 功能特性

| 能力 | 工具 | 默认服务 | 费用 |
|---|---|---|---|
| 📝 文本对话 / 写作 / 翻译 / 代码 | `chat` | 智谱 `glm-4.7-flash` | **免费** |
| 🖼️ 图片生成 | `generate_image` | 智谱 `cogview-3-flash` | **免费** |
| 🎙️ 语音转文字（ASR） | `transcribe_audio` | 智谱 `glm-asr-2512` | 免费额度 |
| 🔊 文字转语音（TTS） | `text_to_speech` | **微软 Edge TTS**（默认，免费） | **免费** |

全部能力实测可用：`npm test` 13/13 通过（含真实端到端调用）。

## 🧠 API 选型（为什么这样选）

本项目调用两个**国内直连、无需科学上网**的免费服务：

### 1. 智谱开放平台（bigmodel.cn）— 文本 / 图片 / 语音识别

- **选型理由**：一个平台同时提供文本、图像、语音三类免费模型，API 统一（OpenAI 兼容、Bearer 认证），国内直连速度快。
- **Base URL**：`https://open.bigmodel.cn/api`
- **免费模型**（本项目默认值）：

| 能力 | 模型编码 | 说明 |
|---|---|---|
| 文本对话 | `glm-4.7-flash` | 200K 上下文，免费 |
| 图片生成 | `cogview-3-flash` | 图片 URL 30 天有效，免费 |
| 语音识别 | `glm-asr-2512` | `.wav/.mp3` ≤25MB ≤30s，中英文精准 |

- **认证**：`Authorization: Bearer <API_KEY>`，Key 在 [bigmodel.cn 控制台](https://bigmodel.cn/usercenter/proj-mgmt/apikeys) 免费创建。
- **接口**（本项目内部调用）：`POST /paas/v4/chat/completions`、`POST /paas/v4/images/generations`、`POST /paas/v4/audio/transcriptions`

### 2. 微软 Edge TTS — 语音合成

- **选型理由**：智谱 `glm-tts` 收费；Edge TTS 完全免费、无需 API Key、中文音色丰富（晓晓/云希等），适合开源项目零成本落地。
- **调用方式**：npm 包 `node-edge-tts`（微软 Edge 在线 TTS），输出 `mp3`。
- **切换收费后端**：`text_to_speech` 支持 `provider: "zhipu"` 切换回智谱 `glm-tts`（输出 wav）。

## 🚀 快速开始（下载即可用）

**环境要求**：Node.js ≥ 18 + 一个 MCP 客户端（Claude Code / Reasonix 等）。

```bash
git clone https://github.com/<你的用户名>/cn-free-ai-mcp.git
cd cn-free-ai-mcp
npm install
cp .env.example .env    # Windows: copy .env.example .env
```

编辑 `.env` 填入智谱 Key（[免费获取](https://bigmodel.cn/usercenter/proj-mgmt/apikeys)）：

```
ZHIPU_API_KEY=你的key
```

> 没有 Key 也能跑：`text_to_speech` 默认走免费的 Edge TTS；配置 Key 后 4 个能力全部可用。

**注册 MCP**（自带 `.mcp.json`，Claude Code 规范，Reasonix 兼容，相对路径通用）：

```jsonc
{
  "mcpServers": {
    "zhipu-ai": {
      "command": "node",
      "args": ["./src/index.js"],
      "cwd": ".",
      "env": { "ZHIPU_API_KEY": "${ZHIPU_API_KEY}" }
    }
  }
}
```

> `${ZHIPU_API_KEY}` 运行时从环境变量 / 项目 `.env` 展开，**密钥不写入配置文件**。重启客户端后工具以 `mcp__zhipu-ai__<tool>` 暴露。

## 🔧 工具与调用示例

| 工具 | 参数 | 示例 |
|---|---|---|
| `chat` | `prompt`（必填）、`system`、`temperature`、`max_tokens` | "帮我写一首关于秋天的诗" |
| `generate_image` | `prompt`（必填）、`size`、`quality` | "生成一张赛博朋克风格的猫" |
| `transcribe_audio` | `audio`（本地路径或 https URL）、`prompt`、`hotwords` | "把 D:/录音.wav 转成文字" |
| `text_to_speech` | `text`、`provider`（`edge`/`zhipu`）、`voice`、`output_path`、`speed`、`volume` | "把'你好世界'念出来，保存到 D:/out.mp3" |

**音色参考**：Edge TTS（默认）`zh-CN-XiaoxiaoNeural`（晓晓）、`zh-CN-YunxiNeural`（云希）、`en-US-AriaNeural` 等；智谱（`provider:"zhipu"`）`tongtong`/`chuichui`/`xiaochen`/`jam`/`kazi`/`douji`/`luodo`。

## 📦 项目结构

```
cn-free-ai-mcp/
├── .mcp.json           # MCP 注册声明（相对路径，通用）
├── .env.example        # 环境变量模板（复制为 .env 使用）
├── package.json
├── src/index.js        # MCP server（4 个工具）
└── test/               # 测试（离线 + 真实端到端）
```

## 🔒 安全设计

- **密钥不入库**：`.env` 已被 `.gitignore` 忽略，配置只用 `${VAR}` 占位展开
- **SSRF 防护**：音频 URL 仅允许 https、拒绝重定向与内网/回环/链路本地地址
- **输入校验**：本地音频限 `.wav/.mp3` 且 ≤25MB；TTS 写盘前校验音频文件头
- **错误净化**：上游错误信息截断、折叠空白，避免回显敏感内容
- **无注入面**：无 shell 调用、无动态执行

## 🧪 测试

```bash
npm test
```

离线用例（握手、防护）无需任何 Key / 网络；检测到 `.env` 有真实 Key 时自动执行**真实端到端**用例（对话、图片生成、语音识别、Edge TTS 合成→ASR 识别闭环）。当前基线：13/13 通过，0 skip。

## 🤝 贡献

欢迎 Issue / PR。开发前请确保 `npm test` 全绿。

## 📄 许可证

[MIT](LICENSE)

---

# English

## ✨ Features

| Capability | Tool | Default service | Cost |
|---|---|---|---|
| 📝 Chat / writing / translation / code | `chat` | Zhipu `glm-4.7-flash` | **Free** |
| 🖼️ Image generation | `generate_image` | Zhipu `cogview-3-flash` | **Free** |
| 🎙️ Speech-to-text (ASR) | `transcribe_audio` | Zhipu `glm-asr-2512` | Free quota |
| 🔊 Text-to-speech (TTS) | `text_to_speech` | **Microsoft Edge TTS** (default, free) | **Free** |

All capabilities verified end-to-end: `npm test` 13/13 passing (including real API calls).

## 🧠 Why these APIs

Two **China-direct, no-VPN** free services:

1. **Zhipu AI** (`open.bigmodel.cn`) — chat / image / ASR in one platform, OpenAI-compatible, Bearer auth. Free models: `glm-4.7-flash` (chat), `cogview-3-flash` (image), `glm-asr-2512` (ASR). Base URL: `https://open.bigmodel.cn/api`.
2. **Microsoft Edge TTS** — free, no API key, rich Chinese voices (Xiaoxiao/Yunxi...), via npm `node-edge-tts`. Optional paid fallback: `provider: "zhipu"` (Zhipu `glm-tts`).

## 🚀 Quick Start

```bash
git clone https://github.com/<you>/cn-free-ai-mcp.git
cd cn-free-ai-mcp
npm install
cp .env.example .env    # fill ZHIPU_API_KEY (optional but recommended)
```

Register the bundled `.mcp.json` in your MCP client (Claude Code / Reasonix), restart, and tools are exposed as `mcp__zhipu-ai__<tool>`. Works without a key too — TTS defaults to free Edge TTS.

## 🔧 Tools

`chat` (prompt/system/temperature/max_tokens), `generate_image` (prompt/size/quality), `transcribe_audio` (audio path or https URL), `text_to_speech` (text/provider/voice/output_path/speed/volume).

## 🔒 Security

`.env` git-ignored (keys never committed, `${VAR}` placeholders only); SSRF-guarded (https-only, no redirects/internal IPs); input validation (`.wav/.mp3` ≤25MB, TTS file-header checks); error sanitization; no shell injection surface.

## 🧪 Testing

`npm test` — offline cases need no key/network; with a real key in `.env`, end-to-end cases run automatically (chat, image, ASR, Edge-TTS→ASR loop). Baseline: 13/13, 0 skipped.

## 📄 License

[MIT](LICENSE)