formae MCP Release Notes

Releases of the formae-mcp plugin — the MCP server and skills that integrate formae with AI coding assistants like Claude Code, Codex, and OpenCode. Install via the platform-engineering-labs/formae-marketplace; see the setup guide for the full install + configuration walk-through.

One-time catch-up update (May 2026). The marketplace catalog previously pinned formae-mcp to version 0.2.0, which silently prevented /plugin marketplace update from delivering newer releases. The pin has been removed, so users on 0.2.0 will jump directly to 0.3.2 on their next update — receiving all the changes in 0.3.0, 0.3.1, and 0.3.2 at once. Subsequent updates will land normally.

To pull the catch-up, run these three commands in Claude Code (no uninstall/reinstall needed):

/plugin marketplace update formae-marketplace
/plugin update formae-mcp@formae-marketplace
/reload-plugins

The first refreshes the catalog, the second installs 0.3.2, and the third applies it to your current session. The MCP binary rebuilds automatically on the next session start (thanks to the 0.3.2 fix).

0.6.0

New features and improvements

Manage named formae environments from your assistant. If you work across several formae environments — local-dev, load-test, prod — your assistant can now list them, show which one is active, switch between them, snapshot the current one under a new name, create new ones from a starter template, delete them, compare two of them, and view or replace a profile's contents. This brings the full set of profile operations to the assistant; previously they lived only in a separate fcfg command-line tool, which formae 0.87.0 has folded into formae profile.

Target a specific environment for a single command. Every tool that talks to a formae agent — apply, destroy, status, inventory, the various list and force commands, cancel, and extract — now accepts an optional environment to run that one command against, without changing which environment is active. Your assistant prefers this per-command targeting over switching the active environment, because the active selection is shared with your formae command line and with any other assistant sessions you have open: switching it to "set up" one session would quietly redirect the others. Switching your default environment now happens only when you explicitly ask for it (for example, "make prod my default"), and takes effect immediately for later commands without restarting anything.

Requires formae 0.87.0. Profile management and per-command environment targeting are available only when the connected formae is version 0.87.0 or newer. On an older formae, these tools return a clear "requires formae >= 0.87.0" message instead of failing in a confusing way — the first step toward the assistant understanding which capabilities your formae version provides.

0.5.0

Released June 22, 2026

New features and improvements

Author new infrastructure by describing it. Ask your assistant something like "deploy a service on AWS with formae" or "set up a Kubernetes app," and it now has a guided path from that request to working, idiomatic forma code. It works out where the code should live (a brand-new project or one you already have), determines which formae plugins you need and adds them as schema dependencies, helps you decide how to group resources into stacks and where lifecycle policies belong, and walks you through simulating before applying. If no plugin exists yet for what you want to manage, it guides you through building one. New focused workflows cover starting a project from scratch, adding or removing plugin dependencies, and stack design.

Examples and plugin discovery, straight from the source. When your assistant writes forma code it can now search the live formae plugin catalog and pull real examples directly from each plugin's repository — matched to the plugin version your project pins — so what it produces reflects what the plugins actually support today instead of guesswork. It tells you when an example may not match your pinned version, and it won't quietly treat examples from unverified third-party plugins as authoritative.

Better built-in authoring guidance. The reference material your assistant consults while writing forma files has been corrected and expanded: accurate forma-file structure, how to think about stacks as the unit of reconciliation, where to find examples, and a growing list of common pitfalls to avoid.

Reusable policies. You can now have your assistant declare a TTL or auto-reconcile policy once and attach it to several stacks, alongside the existing inline policies — with help choosing which approach fits.

Rename a resource without recreating it. Ask your assistant to rename a managed resource (or give a readable name to one that discovery labelled with a raw cloud identifier) and it renames it in place via an alias — the resource keeps its identity and the underlying cloud object is untouched, with no destroy-and-recreate. If a rename is combined with a change to an immutable field, the assistant flags the resulting replace as destructive and asks you to confirm rather than treating it as a routine rename.

Consistent across assistants. The skills now behave the same whether you drive formae from Claude Code, Codex, or OpenCode.

Command-line flags. The formae-mcp binary now supports --version (and -V) and --help, and reports one consistent version across the command line and the MCP handshake.

0.4.0

Released June 14, 2026

Fix: Documentation links your assistant shares while helping with plugin development now open the right pages. Several plugin SDK tutorial and reference links it pointed to previously led to "page not found" errors; those links are now correct.

New: When your assistant refers you to formae documentation, it now draws from a built-in index of canonical links instead of assembling URLs on its own — so the pages it sends you to actually open, rather than landing on a mistyped or guessed address. The index spans core concepts, the PKL cheatsheet, the AI-assistant setup guide, and the plugin SDK tutorial and reference.

0.3.2

Released May 28, 2026

Fix: Updates pulled with /plugin marketplace update now take effect on the next session start. Previously the start-mcp.sh wrapper only built the Go binary on first install, so marketplace updates kept serving the stale cached binary until you deleted bin/formae-mcp by hand. The wrapper now detects when source has changed and rebuilds automatically.

0.3.1

Released May 21, 2026

New: Your AI assistant now understands PKL syntax, forma file structure, schema annotations, and common error messages out of the box. Practical effect: fewer wrong PKL snippets in suggested code, faster grounded answers to "why is this resource being replaced?" or "how do I reference one resource's output from another?", and clearer diagnoses when something goes wrong. The server exposes four new on-demand reference resources (formae://docs/pkl-primer, formae://docs/forma-anatomy, formae://docs/annotations, formae://docs/troubleshooting) that the assistant reads when it needs the depth.

New: When your assistant explains a concept (stacks, targets, drift, apply modes, the .res accessor), it now cites the canonical docs.formae.io page for follow-up reading.

Improved: When you ask your assistant to build a new resource plugin (e.g., "build a Cloudflare plugin for formae"), the generated scaffold and CRUD implementation are more likely to be correct on the first pass. The formae-plugin-new skill now guides assistants through advanced patterns (polymorphic resources, cross-plugin Target references, computed Resolvable outputs, synthetic identifiers, external-binary integrations like helm or atlas) that previously needed multiple correction rounds.

Docs: Install/update instructions now point you at /reload-plugins (Claude Code v2.1.116+) to apply changes without restarting your session.

0.3.0

Released May 19, 2026

New: Manage formae stack policies in natural language. Ask your assistant to "expire lifeline in 20 minutes" or "reject out-of-band changes on production" and it edits the right PKL file through the existing simulate/confirm/apply discipline — no hand-rolled policy syntax needed. Adds the create_inline_policy MCP tool and the formae-stack-policy skill.

New: Switch between formae config profiles (different agents, environments, auth setups) by asking your assistant. The new formae-config skill drives the fcfg companion command to list, switch, save, edit, and delete profiles without leaving the conversation.

Fix: Drift-detection workflows (/formae-fix-code-drift and the list_changes_since_last_reconcile MCP tool) now return results correctly. Earlier versions called the wrong agent endpoint and silently returned empty results.

Improved: /formae-apply now suggests clearer recovery options when a deploy fails mid-way (which resources to retry, which to roll back, which to inspect first).

0.2.0

Released February 12, 2026 — initial public release

The first marketplace release of the formae-mcp plugin. With it installed, your AI assistant can:

  • Inspect your infrastructure. Ask "what's running in production?", "any failed commands today?", "show me unmanaged resources in us-west-2", or "which plugins are loaded?" — the assistant answers from the live formae agent rather than guessing.

  • Deploy and update infrastructure safely. "Apply my VPC forma" runs through a strict simulate → confirm → apply loop so you always see the planned change before it touches cloud resources.

  • Hot-fix during incidents. "Patch the API gateway timeout to 60s without reconciling the rest of the stack" — applies targeted changes via patch mode without forcing a full reconcile of unrelated resources.

  • Absorb out-of-band changes into your IaC codebase. "Has anything changed in production since the last reconcile? Pull it into the PKL files." The assistant extracts current state, edits your PKL to match, and verifies with a dry-run.

  • Discover and import resources you didn't manage with formae yet. "What's in this AWS account that formae doesn't know about? Bring the RDS clusters under management." The assistant runs discovery, then imports the resources into your forma files.

  • Build new resource plugins. "Build a Cloudflare plugin for formae." The assistant researches the provider API, proposes resource types in implementation waves, scaffolds the plugin, and TDDs through each CRUD operation against the plugin SDK tutorial.

Ships with 15 MCP tools and 13 skills covering these workflows. Install via the platform-engineering-labs/formae-marketplace. Multi-platform install documentation covers Claude Code (marketplace + manual), Codex, and OpenCode.

License: FSL-1.1-ALv2.