# Step Plan MCP 通用版 MVP

这是一个本地 `stdio` 形态的 MCP Server MVP，用于让 Codex、Cursor、Claude Desktop 等支持 MCP 的客户端，通过一个 Step Plan API Key 调用 Step Plan 的多模态能力。

当前版本重点验证两件事：

- 用户不需要切换 Codex 当前主模型。
- 用户只要配置一次 MCP，就可以在当前对话中调用 Step Plan 生图和语音合成能力。

## 功能

| 工具 | 作用 | 默认模型 | 默认输出 |
| --- | --- | --- | --- |
| `step_get_setup_status` | 检查 MCP 是否安装、Key 是否已配置、当前支持哪些能力 | 无 | JSON 状态 |
| `step_configure_api_key` | 在 Agent 对话里保存 Step Plan API Key 到本机配置 | 无 | JSON 状态 |
| `step_generate_image` | 根据文本生成图片、海报、汇报图、信息图等视觉内容 | `step-image-edit-2` | `outputs/images/*.png` |
| `step_text_to_speech` | 将文本、脚本、广告词、旁白生成语音文件 | `stepaudio-2.5-tts` | `outputs/audio/*.mp3` |

内部调用的 Step Plan API：

| 能力 | 接口 |
| --- | --- |
| 生图 | `POST https://api.stepfun.com/step_plan/v1/images/generations` |
| 语音合成 | `POST https://api.stepfun.com/step_plan/v1/audio/speech` |

## 运行要求

- Node.js 20 或更高版本
- npm
- 一个可用的 Step Plan API Key
- 一个支持 MCP 的客户端，例如 Codex

## 一键安装到 Codex（推荐）

这里的“克隆项目”指的是：把 GitHub 上的这个项目下载到你自己的电脑里。

“项目目录”指的是：下载完成后生成的那个项目文件夹，例如 `step-plan-mcp-mvp`。

### Windows PowerShell 一次性安装

1. 打开 Windows PowerShell。
2. 选择一个你想存放项目的位置，例如桌面。
3. 把 `<repo_url>` 替换成你的 GitHub 仓库地址，然后复制下面整段命令运行：

```powershell
cd "$env:USERPROFILE\Desktop"
git clone <repo_url>
cd step-plan-mcp-mvp
node scripts/install-codex.mjs
```

如果你的 GitHub 仓库名不是 `step-plan-mcp-mvp`，第三行的 `cd step-plan-mcp-mvp` 要改成实际下载出来的文件夹名。

### macOS / Linux 一次性安装

把 `<repo_url>` 替换成你的 GitHub 仓库地址：

```bash
cd ~/Desktop
git clone <repo_url>
cd step-plan-mcp-mvp
node scripts/install-codex.mjs
```

如果你已经克隆过项目，只需要进入项目文件夹后运行：

```bash
node scripts/install-codex.mjs
```

这个脚本会自动完成：

1. 安装依赖：`npm install`
2. 构建项目：`npm run build`
3. 写入 Codex MCP 配置：`~/.codex/config.toml`
4. 提示你重启 Codex
5. 重启后由 Agent 在对话里完成 Step Plan API Key 配置

如果你想通过 npm script 运行，也可以：

```bash
npm run setup:codex
```

默认安装命令不会询问或保存 Key。重启 Codex 后，在新会话里输入：

```text
检查 Step Plan MCP 配置状态。
```

如果提示还没有配置 Key，再输入：

```text
配置 Step Plan MCP，我的 Step Plan API Key 是 <你的 key>
```

Agent 会调用 `step_configure_api_key`，把 Key 保存到你本机的 `~/.step-plan-mcp/config.json`。后续生图和语音工具会自动读取它。

如果你更希望在命令行里一次性配置 Key，可以运行：

```bash
node scripts/install-codex.mjs --with-key
```

> 注意：无论用哪种方式，Key 都只保存在你的本机配置里，不会写入项目代码。不要把 `~/.codex/config.toml` 或 `~/.step-plan-mcp/config.json` 提交到 GitHub。

## 手动安装

```bash
npm install
npm run build
```

构建成功后，入口文件位于：

```text
dist/index.js
```

如果你使用上面的一键安装脚本，可以跳过下面的手动配置。

## 手动配置步骤（Codex）

如果你已经使用 `node scripts/install-codex.mjs`，可以跳过本节，直接重启 Codex 后测试。

### 1. 找到项目绝对路径

假设你把项目放在：

```text
<repo_path>
```

那么 MCP 入口文件就是：

```text
<repo_path>/dist/index.js
```

Windows 示例：

```text
C:\path\to\step-plan-mcp-mvp\dist\index.js
```

### 2. 打开 Codex 配置文件

Windows PowerShell：

```powershell
notepad "$env:USERPROFILE\.codex\config.toml"
```

### 3. 追加 MCP 配置

把 `<repo_path>` 替换成你的项目绝对路径，把 `YOUR_STEP_API_KEY` 替换成你的 Step Plan API Key。

```toml
[mcp_servers.step_plan_mcp_generic_mvp]
command = "node"
args = ["<repo_path>/dist/index.js"]
startup_timeout_sec = 60

[mcp_servers.step_plan_mcp_generic_mvp.env]
STEP_API_KEY = "YOUR_STEP_API_KEY"
```

Windows 路径示例：

```toml
[mcp_servers.step_plan_mcp_generic_mvp]
command = "node"
args = ["C:\\path\\to\\step-plan-mcp-mvp\\dist\\index.js"]
startup_timeout_sec = 60

[mcp_servers.step_plan_mcp_generic_mvp.env]
STEP_API_KEY = "YOUR_STEP_API_KEY"
```

### 4. 重启 Codex

保存配置后，完全退出并重新打开 Codex，让 MCP 配置重新加载。

### 5. 测试生图

在 Codex 中输入：

```text
使用 Step Plan 生图能力，给我生成一张牛奶的海报。画面干净明亮，有中文标题“每日鲜牛奶”，适合电商详情页首屏。
```

预期结果：

- Codex 主模型识别到这是生图任务。
- Agent 调用 `step_generate_image`。
- MCP 调用 Step Plan 生图接口。
- 图片保存到 `outputs/images/`。
- 主会话返回图片路径和图片内容。

### 6. 测试语音

在 Codex 中输入：

```text
使用 Step Plan 语音能力，把这句话生成一段温柔自然的女声语音：“每日鲜牛奶，来自清晨牧场的新鲜味道。”
```

预期结果：

- Codex 主模型识别到这是文本转语音任务。
- Agent 调用 `step_text_to_speech`。
- MCP 调用 Step Plan TTS 接口。
- 音频保存到 `outputs/audio/`。
- 主会话返回音频路径和音频内容。

## 可选环境变量

| 环境变量 | 默认值 | 说明 |
| --- | --- | --- |
| `STEP_API_KEY` | 无 | Step Plan API Key。优先级高于本地配置文件 |
| `STEP_MCP_CONFIG_PATH` | `~/.step-plan-mcp/config.json` | Agent 内配置 Key 时写入和读取的本地配置文件 |
| `STEP_API_BASE_URL` | `https://api.stepfun.com` | Step API 基础地址 |
| `STEP_IMAGE_GENERATIONS_PATH` | `/step_plan/v1/images/generations` | 生图接口路径 |
| `STEP_AUDIO_SPEECH_PATH` | `/step_plan/v1/audio/speech` | TTS 接口路径 |
| `STEP_OUTPUT_DIR` | `outputs/` | 统一输出目录 |
| `STEP_IMAGE_OUTPUT_DIR` | `outputs/images/` | 图片输出目录 |
| `STEP_AUDIO_OUTPUT_DIR` | `outputs/audio/` | 音频输出目录 |

如果自定义输出目录，建议使用 ASCII-only 路径，避免部分 MCP 客户端或终端把中文路径显示成乱码。

## 工具参数

### `step_get_setup_status`

无需参数。用于检查当前 MCP 是否可用、Key 是否已配置、支持哪些 Step Plan 能力。

### `step_configure_api_key`

| 参数 | 说明 |
| --- | --- |
| `api_key` | 用户明确提供的 Step Plan API Key。工具返回时只展示脱敏后的 Key |

### `step_generate_image`

常用参数：

| 参数 | 说明 |
| --- | --- |
| `prompt` | 完整生图提示词，最长 512 字符 |
| `size` | 图片尺寸，默认 `1024x1024` |
| `style_hint` | 可选风格：`business_report`、`infographic`、`poster`、`illustration`、`realistic` |
| `seed` | 可选随机种子 |
| `steps` | 生成步数，默认 `8` |
| `cfg_scale` | 引导强度，默认 `1.0` |
| `text_mode` | 是否开启文字优化，默认 `true` |

支持图片尺寸：

```text
1024x1024
768x1360
896x1184
1360x768
1184x896
```

### `step_text_to_speech`

常用参数：

| 参数 | 说明 |
| --- | --- |
| `text` | 要合成的完整文本，最长 1000 字符 |
| `voice` | 音色 ID，默认 `linjiajiejie` |
| `instruction` | 可选语气、情绪、节奏说明，最长 200 字符 |
| `response_format` | 输出格式，默认 `mp3`，可选 `mp3` 或 `wav` |
| `speed` | 实验参数，语速倍率 |
| `volume` | 实验参数，音量倍率 |

## 安全说明

- 不要把 Step Plan API Key 写进代码。
- 不要把 Step Plan API Key 提交到 GitHub。
- 如果使用 Agent 内配置，Key 会保存到本机 `~/.step-plan-mcp/config.json`。
- 如果不希望在对话里输入 Key，可以用 `node scripts/install-codex.mjs --with-key`，或手动通过 MCP 客户端环境变量传入 `STEP_API_KEY`。
- `.env`、`.env.*`、`outputs/`、`node_modules/`、`dist/` 已在 `.gitignore` 中忽略。
- 真实调用会消耗 Step Plan 额度。

## 当前限制

- 当前是本地 `stdio` MCP，不是远程 Hosted MCP。
- 当前支持文生图和文本转语音，不支持图像编辑、ASR、实时语音。
- 媒体文件保存到本地目录，不提供临时 URL。
- TTS 的 `speed`、`volume` 是实验参数，建议正式发布前进一步验证。
- 当前版本只做 MVP 验证，不包含用量查询、成本预估和调用审计。

## Roadmap

- 增加图像编辑工具 `step_edit_image`。
- 增加语音识别工具 `step_transcribe_audio`。
- 增加媒体有效性校验，避免无效图片或音频被误判为成功。
- 提供 Hosted MCP 版本，降低用户本地配置成本。
- 发布 npm 包，支持无需 clone 仓库的 `npx` 一行安装。

## 参考文档

- [Step Plan 图像模型接入](https://platform.stepfun.com/docs/zh/step-plan/integrations/image-api)
- [Step Plan 语音模型接入](https://platform.stepfun.com/docs/zh/step-plan/integrations/audio-api)
- [Model Context Protocol](https://modelcontextprotocol.io/)