Agents (MCP)
Formercial is an MCP server, so an agent can start a commercial from a preset, edit it, voice it and render it. Tool calls run through the same checks as the editor.
Connect
Agents working in this repository
The repository has a .mcp.json, so clients that read it, like Claude Code, offer the formercial server when started here. Approve it when asked. The client starts the server itself, and the first start takes a minute to build the app.
While the app is running
Start the app with pnpm dev, then point your client at its MCP endpoint:
claude mcp add --transport http formercial http://localhost:3000/_mcp/messagesOther clients take the same address. Use whatever port pnpm dev printed.
Let the client start it (stdio)
claude mcp add formercial -- pnpm --dir /path/to/formercial exec kick formercial mcpOr in a client's JSON config:
{
"mcpServers": {
"formercial": {
"command": "pnpm",
"args": ["--dir", "/path/to/formercial", "exec", "kick", "formercial", "mcp"]
}
}
}This runs the built app, building it first if there's no dist/. Run pnpm build again after you update Formercial, or the client keeps serving the old build.
Tools
| Tool | What it does |
|---|---|
list_presets | The commercials a project can start from |
list_projects | Every commercial in the workspace |
project_schema | The JSON Schema of project.json, so an agent can write a valid one |
create_project | A new commercial: name, and optionally a preset |
get_project | Its project.json, the version to send back, its voice clips, and whether it's trusted |
update_project | Replace project.json: project and baseVersion |
voice_project | Generate missing or changed lines. They're sent to Microsoft's speech service. |
list_drivers | Render drivers, and what each one needs |
list_history | The steps a project has been through |
restore_revision | Put a project back to one of those steps; the rest are kept |
render_project | Queue a render: format (16:9, 9:16, 1:1 or all), optional driver and fps. Returns job ids at once. |
get_renders | Job progress, finished files, and the folder they're in |
A typical run:
list_presets, thencreate_projectwith one.get_project, change the text and code, thenupdate_projectwith theversionyou read. If someone else changed it first, the update is refused and returns thecurrentversion: read again and redo the edit.render_project, then pollget_rendersuntil the job isdone. Rendering takes about 2–3 times the length of the spot.
What agents can't do
- Trust code. There's no tool for it. If an agent writes a custom scene,
update_projectanswerstrusted: false, andrender_projectis refused until you read the code and press Trust and run them in the editor. An agent's edit to a project you already trusted also needs trusting again if it changes custom scene code. - Delete anything, or upload files. Recordings, music, logos and fonts are added in the editor.
The agent can still spend your time and disk: it can queue renders, overwrite project.json and send lines to the speech service. Connect agents you'd trust with those.
Security
The MCP endpoint follows the app's own rules: it answers only this machine, addressed as localhost or 127.x, and refuses other sites. Requests that send no Origin header, which is what MCP clients do, aren't browser requests and are let through. There are no accounts, so any program running on your machine can call it.