famistudio-mcp

English | 简体中文

面向 FamiStudio 的 Model Context Protocol 服务器。 用纯 JSON 生成、检查、校验并渲染 NES .fms 工程 —— 无需 GUI，无需手工处理二进制格式。

compile_song_spec  ──▶  create_fms  ──▶  validate_fms  ──▶  verify_roundtrip  ──▶  export_audio
   JSON 音符            .fms 文件         不变量校验        FamiStudio 认可         .wav

FamiStudio 的命令行可以读取 .fms、.txt、.ftm 和 .nsf，但没有 fms-export 命令 —— 直接用脚本产出 .fms，写二进制格式是唯一可行的方法。famistudio-mcp 按照与 FamiStudio 4.5.x 完全相同的方式写出这些字节，在写盘前校验每一条加载不变量， 并把结果送回 FamiStudio 来证明它确实可用。

快速开始

无需安装 —— 让 MCP 宿主指向已发布的包即可：

// Claude Desktop / Cursor / 任何通过命令启动 MCP 服务器的客户端
{
  "mcpServers": {
    "famistudio": {
      "command": "npx",
      "args": ["-y", "famistudio-mcp"],
      // 可选的兜底配置，详见 docs/USAGE.zh-CN.md 的“生成文件写到哪里”。
      // 如果你的客户端支持弹窗，则会被询问一次，并可针对每个工程单独指定目录。
      "env": { "FAMISTUDIO_MCP_OUTDIR": "/absolute/path/to/your/audio-work" }
    }
  }
}

使用 bun 的话可以换成：

{ "command": "bunx", "args": ["famistudio-mcp"] }

然后直接向你的 agent 提要求：

帮我做一个 2 秒的贪吃蛇移动音效：明亮的 Square1 琶音，下面垫一条低音 Triangle 脉冲， 再加一个噪声短音。写到 D:/Game Assets/snake_move.fms，验证 FamiStudio 能加载， 并在旁边渲染一个 44100 Hz 的 WAV。

不使用 MCP 宿主

同一套引擎也以 CLI 形式发布，适合脚本与 CI：

npx -y famistudio-mcp-cli info
npx -y famistudio-mcp-cli compile examples/snake-move.json -o out/snake.fms
npx -y famistudio-mcp-cli verify out/snake.fms
npx -y famistudio-mcp-cli export out/snake.fms out/snake.wav --rate 44100
npx -y famistudio-mcp-cli analyze out/snake.wav --pitch

作为库

npm install famistudio-mcp

import { compileSongSpec, writeFms, readProject } from 'famistudio-mcp/core';
import { writeFile } from 'node:fs/promises';

const { project } = compileSongSpec({
  name: 'Blip',
  patternLength: 16,
  channels: [
    { channel: 'Square1', notes: [{ time: 0, note: 'C4', duration: 8 }, { time: 8, note: 'stop' }] },
    { channel: 'Triangle', notes: [{ time: 0, note: 'C1', duration: 16 }] },
  ],
});

await writeFile('blip.fms', writeFms(project));
console.log(readProject(writeFms(project)).songs[0].name); // "Blip"

只有渲染、文本导出和回环验证才需要 FamiStudio 本体。生成、读取、校验和对比工程都不需要它。

工具

| 工具 | 用途 | |---|---| | famistudio_info | 定位 FamiStudio 可执行文件，报告版本以及允许的读/写根目录 | | compute_ticks | 在秒、tick 与速度之间换算 | | compile_song_spec | 把 JSON 歌曲 spec 编译成完整工程对象，可选择写成 .fms | | create_fms | 同上，但总是写出文件 | | validate_fms | 检查每一条 FamiStudio 加载不变量并列出问题 | | read_fms | 把 .fms 解码为结构化 JSON（歌曲、声道、pattern、音符、包络） | | summarize_fms | 可读的工程清单，含每个 pattern 的音符转储 | | diff_fms | 两个工程的结构化对比 | | verify_roundtrip | 经 FamiStudio 回环：文本导出 + WAV 渲染，检查失同步与静音 | | export_audio | 通过 FamiStudio CLI 渲染 WAV / MP3 / OGG | | export_text | FamiStudio 文本、FamiTracker 文本，或声音引擎汇编 | | analyze_audio | WAV 时长、峰值/RMS、静音与音高检测 | | run_famistudio | 其它 FamiStudio CLI 命令（NSF、ROM 等）的逃生通道 |

推荐流程

1. compute_ticks —— 确定你想要的音效需要多少 tick。
2. compile_song_spec —— 构建音符。
3. create_fms —— 写出文件（或把返回的 project 直接传给下一步）。
4. verify_roundtrip —— 证明 FamiStudio 能加载并产出音频。
5. export_audio —— 为你的游戏渲染 .wav。
6. analyze_audio —— 确认时长与音高，例如配合 separateChannels。

动手写音符前只需知道一件事：一个 tick 就是主机的一帧，所以一首曲子的长度是 ticks / 60.0988 秒（NTSC），速度完全由你写下的 tick 网格决定 —— bpm = 60 * 帧率 / beatLength。groove 和 noteLength 不会缩放播放速度。 spec 的其余内容（完整语法、效果表等）都在 docs/USAGE.zh-CN.md。

文档

| 文档 | 内容 | |---|---| | README.zh-CN.md（本文件） | 项目是什么、安装、快速上手、工具清单 | | docs/USAGE.zh-CN.md | 完整的歌曲 spec 参考：音符写法、效果、速度、输出位置、配置、编辑器/CLI 选项 | | docs/DEVELOPMENT.zh-CN.md | 构建/测试/验证命令及其坑点、新增工具、代码风格、路径策略、失同步排查、已知局限 | | docs/FMS_FORMAT.zh-CN.md | 按实现描述的 .fms 容器与 payload 布局，以及定时模型 | | AGENTS.md | 面向编码 agent 的精简入口：仓库地图、格式不变量、变更清单（仅英文，agent 都读得懂英文，不值得再维护一份译文） | | CONTRIBUTING.zh-CN.md | 如何贡献 | | CHANGELOG.zh-CN.md | 版本历史 |

每份文档都有英文与简体中文两个版本（X.md / X.zh-CN.md），标题下方的语言切换链接指向另一版； 唯一的例外是 AGENTS.md —— 它面向 agent，刻意只保留英文。

兼容性

• 读写 FamiStudio 4.5.x 工程文件：序列化版本 19。
• 不支持读取更早的版本（10–18）；请在 FamiStudio 中打开并重新保存以升级。生成功能不受影响。
• 仅支持纯 2A03（不支持扩展音源：VRC6、FDS、N163、S5B、VRC7、EPSM）。已有工程中的 DPCM 采样会被逐字节保留，但无法通过本工具创作。
• 容器按设计使用 zlib 原始 deflate，重新编码后的容器可能与原始文件逐字节不同，而解压后的 payload 完全一致。

许可

MIT —— 见 LICENSE。

FamiStudio 本身是 Mathieu Gauthier-Pilote 的独立项目，同样以 MIT 许可发布；本服务器只读写它的 文件格式并驱动它的命令行。