Frenchie
MCP onlineLog in

docs → migrating

Migrating Frenchie

One command per version gap. Every upgrade picks up where the previous one left off — run the section that matches your current Frenchie release.

Already on 0.4.0?

You're on the latest. If something still feels off, jump to troubleshooting — the pages there lead with verbatim error text so Cmd-F lands on the fix.

0.3.2 → 0.4.0 image generation

0.4.0 adds image generation and moves every tool onto the same result envelope.

  1. generate_image MCP tool and /generate-image command. Agents can generate PNG/JPEG/WebP images from a prompt. Stdio saves the image locally under .frenchie/<slug>/generated.<ext>; HTTP returns a temporary download URL.
  2. Shared result envelope. OCR, transcription, and image generation now return { status, jobId, creditsUsed, resultExpiresAt, result }. Code that read top-level markdown, savedTo, or imageUrl should branch on result.kind instead.
  3. Registry metadata is current. The npm package, server.json, static MCP server card, and Smithery metadata now advertise OCR, transcription, and image generation together.

Upgrade

cd <your project>
npx @lab94/frenchie@latest install

Restart your agent afterwards. If you hand-wrote or pinned your MCP config, update the package spec to @lab94/frenchie@0.4.0 or re-run install and let the installer write it.

0.3.1 → 0.3.2

0.3.2 ships two unrelated improvements. Both land on the next install.

  1. install reuses your existing API key. Re-runs no longer require --api-key — the installer reads FRENCHIE_API_KEY from your current MCP config and rewrites the file with the same key. Matters because Frenchie keys are shown only once at creation, so "paste it again" was a dead end if you lost the plaintext. Pass --api-key fr_new_key to rotate.
  2. npm metadata no longer leaks private repo links. repository is dropped from package.json and bugs now points to getfrenchie.dev/contact. No behavior change — just a cleaner npmjs.com/package/@lab94/frenchie page.

Upgrade

cd <your project>
npx @lab94/frenchie@latest install

No --api-key needed if you already have Frenchie configured. Restart your agent afterwards.

0.3.0 → 0.3.1 critical fix

0.3.0 moved stdio tool responses to metadata-only so agents read .frenchie/<name>/result.md instead of burning context on inline markdown. The contract was silently broken for any user whose npx cache held an older @lab94/frenchie bundle — install ran 0.3.0, but the MCP config's unpinned "args": ["-y", "@lab94/frenchie", "mcp"] let npx keep spawning the cached 0.2.x server. Agents saw the full 25k-token markdown dump, not the promised ~200-token response.

0.3.1 pins the package spec in every MCP config the installer writes: ["-y", "@lab94/frenchie@0.3.1", "mcp"]. The spawned server version is locked to whatever the installer shipped with.

Upgrade

cd <your project>
npx @lab94/frenchie@latest install --api-key fr_your_key_here

Pass --api-key again on 0.3.1 — the installer doesn't yet reuse the key from your existing MCP config (that's in 0.3.2). If you're upgrading past 0.3.1 straight to 0.3.2, the 0.3.1 → 0.3.2 steps apply and you don't need the flag.

If you hand-wrote your MCP config

Change "args": ["-y", "@lab94/frenchie", "mcp"] to "args": ["-y", "@lab94/frenchie@0.3.1", "mcp"] — or re-run install and let it do it.

Verifying the fix

Call /ocr or /transcribe on a small file. A correct stdio response looks like:

{
  "status": "done",
  "savedTo": ".frenchie/<name>/result.md",
  "wordCount": 1234,
  "imageCount": 0,
  "creditsUsed": 2,
  "resultExpiresAt": "..."
}

No markdown field. If you still see "markdown": "..." in the response, your agent is spawning a cached 0.2.x bundle — see http-shadow troubleshooting or clear the npx cache with rm -rf ~/.npm/_npx and re-run install.

0.2.x → 0.3.0

Frenchie 0.3.0 ships three changes that may affect existing installs:

  1. Stdio tool responses return metadata only, not full markdown. The server still writes .frenchie/<name>/result.md to disk as before — the response just stops re-sending the markdown inline. Your agent reads the file if it needs the content. Cuts responses from ~25k tokens to ~200 tokens on a 17-page PDF.
  2. MCP configs now bake in absolute paths. install writes the absolute path to npx into command, plus a scoped PATH into env. Makes stdio MCP spawn correctly under GUI-launched agents (Antigravity, Claude Desktop, Windsurf, Zed) that don't inherit shell PATH.
  3. mcp --help / --version / --selftest short-circuit. The bundled stdio server no longer hangs when an agent preflights it. Good news for VS Code Copilot and any future agent that validates before wiring up MCP.

Upgrade

cd <your project>
npx @lab94/frenchie@latest install --api-key fr_your_key_here

The installer detects your agent markers and overwrites the stale command: "npx" entries with the new absolute-path form. Restart your agent afterwards.

If you pinned the version

If you have @lab94/frenchie@0.2.x hard-coded anywhere (CI, Dockerfile, other repos), bump to ^0.4.0 so the new stdio behavior and image generation support take effect. We recommend jumping straight to 0.4.0 since that also includes the 0.3.1 critical fix.

0.1.x → 0.2.0+

Frenchie 0.2.0 made stdio the primary integration path. Local coding agents now spawn a local stdio MCP server via npx @lab94/frenchie mcp instead of connecting to mcp.getfrenchie.dev over HTTP. HTTP remains available for hosted/web agents.

You need to remove the old HTTP entry first — an old HTTP Frenchie entry at user or local scope will shadow the new project stdio entry. See also http-shadow troubleshooting.

1. Remove the old HTTP entry

Claude Code

claude mcp list                      # check scope — likely "local" or "user"
claude mcp remove frenchie -s local  # or -s user / -s project as needed

Cursor

Edit ~/.cursor/mcp.json and remove the frenchie block with "url": "https://mcp.getfrenchie.dev".

Codex

Edit ~/.codex/config.toml and remove any [mcp_servers.frenchie] block that uses url = "..." rather than command = "npx".

2. Re-install with --api-key

cd <your project>
npx @lab94/frenchie@latest install --api-key fr_your_key_here

This writes project-scoped stdio MCP configs for every agent marker found in the project (Claude Code / Cursor / Codex / VS Code / Gemini CLI / Windsurf / Zed). For user-level installs (Windsurf, Zed, Claude Desktop), add --global.

We recommend pinning to @latest — that lands 0.4.0 with image generation, the API key reuse, the 0.3.1 critical pin, and every intermediate fix.

3. Restart your agent

Fully quit and reopen. A reload-window is not always enough — MCP subprocesses persist across soft reloads.

4. Verify

Claude Code

claude mcp list

Should show:

frenchie: /usr/local/bin/npx -y @lab94/frenchie@0.4.0 mcp (stdio)

Not:

frenchie: https://mcp.getfrenchie.dev (HTTP)

After every upgrade

Restart your agent fully — a reload-window often isn't enough because MCP subprocesses persist across soft reloads. Then send a small file through /ocr or /transcribe to confirm the new behavior is live.

Seeing an error? Start at symptom-first troubleshooting — every entry leads with verbatim error text so Cmd-F lands on the fix.

Still stuck? Email support@getfrenchie.dev with the exact command and full error output.

More