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 仓库地址，然后复制下面整段命令运行：

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 仓库地址：

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

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

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 运行，也可以：

npm run setup:codex

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

检查 Step Plan MCP 配置状态。

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

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

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

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

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

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

手动安装

npm install
npm run build

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

dist/index.js

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

手动配置步骤（Codex）

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

1. 找到项目绝对路径

假设你把项目放在：

<repo_path>

那么 MCP 入口文件就是：

<repo_path>/dist/index.js

Windows 示例：

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

2. 打开 Codex 配置文件

Windows PowerShell：

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

3. 追加 MCP 配置

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

[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 路径示例：

[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 中输入：

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

预期结果：

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

6. 测试语音

在 Codex 中输入：

使用 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

支持图片尺寸：

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 图像模型接入
• Step Plan 语音模型接入
• Model Context Protocol