Step Plan MCP 通用版 MVP

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

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

• 用户不需要切换 Codex 当前主模型。

• 用户只要配置一次 MCP，就可以在当前对话中调用 Step Plan 生图和语音合成能力。

功能

内部调用的 Step Plan API：

Related MCP server: mcp-media-engine

运行要求

• 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/。

• 主会话返回音频路径和音频内容。

可选环境变量

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

工具参数

step_get_setup_status

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

step_configure_api_key

step_generate_image

常用参数：

支持图片尺寸：

1024x1024
768x1360
896x1184
1360x768
1184x896

step_text_to_speech

常用参数：

安全说明

• 不要把 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