Frenchie
MCP loadingLog inDashboardInstall

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.6?

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.4.5 → 0.4.6 global upgrade-mode

0.4.6 fixes the long-standing bug where install from a project never refreshed user-level MCP configs (Antigravity, Claude Desktop, Windsurf and Zed global variants). The pinned @lab94/frenchie@<version> inside ~/.gemini/antigravity/mcp_config.json and friends would stay locked at whatever version you originally installed, even after running install repeatedly.

install --global (no --agent, no --all) is now upgrade-mode: it scans every $HOME MCP config, finds entries with an existing frenchie server, and rewrites them with the current pinned spec while preserving each file's own API key. Paths without a frenchie entry are left untouched — first-time global installs still go through install --agent <name> --global.

Upgrade

# Project-scoped configs in this directory
cd <your project>
npx @lab94/frenchie@latest install

# Every $HOME config that already has frenchie — run once from anywhere
npx @lab94/frenchie@latest install --global

If you only have project-scoped configs, the second command will print "No existing Frenchie entries found in global MCP configs" and exit cleanly. Restart each affected agent afterwards so it re-reads the pinned @lab94/frenchie@0.4.6 spec.

Behaviour change to be aware of

In 0.4.5 and earlier, install --global (with project markers present in cwd) wrote to mcp.global paths even if no frenchie entry existed there. That undocumented edge case is gone — install --global now only updates pre-existing entries. If you were relying on it for first-time global install, switch to install --agent <name> --global (one agent) or install --all --global (every Tier A agent).

0.4.4 → 0.4.5 file extraction

0.4.5 adds file extraction to the published skill package. Agents now get the extract_to_markdown MCP tool, /extract <file> slash command, and extraction-aware HTTP upload instructions for DOCX, XLSX, CSV, TSV, and PPTX.

Upgrade

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

Restart your agent afterwards. If you hand-pinned the version, update to @lab94/frenchie@0.4.5 or re-run install.

0.4.3 → 0.4.4 async image fixes

0.4.4 fixes async image-generation result handling. Failed image jobs now surface as errors from get_job_result, and generated-image retention starts when the result is first delivered instead of when the worker finishes.

Upgrade

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

Restart your agent afterwards. If you hand-pinned the version, update to @lab94/frenchie@0.4.4 or re-run install.

0.4.2 → 0.4.3 default language

0.4.3 adds an optional default-language hint for transcribe_to_markdown. Tool-level language always wins; the hint only kicks in when the tool input doesn't specify one. Skip this entirely if you're happy with auto-detection.

Stdio

Add FRENCHIE_DEFAULT_LANGUAGE to the env block in your MCP config:

{
  "command": "npx",
  "args": ["-y", "@lab94/frenchie@0.4.3", "mcp"],
  "env": {
    "FRENCHIE_API_KEY": "fr_...",
    "FRENCHIE_DEFAULT_LANGUAGE": "th"
  }
}

HTTP

Send X-Frenchie-Default-Language alongside Authorization:

Authorization: Bearer fr_...
X-Frenchie-Default-Language: th

Upgrade

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

Restart your agent afterwards. If you hand-pinned the version, update to @lab94/frenchie@0.4.3 or re-run install.

0.4.1 → 0.4.2 registry metadata

0.4.2 is a metadata-only release that fixes the Official MCP Registry namespace to io.github.Lab94/frenchie-skill. Tool semantics, response shapes, and installer behaviour are unchanged.

Upgrade

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

Restart your agent afterwards so it re-reads the pinned @lab94/frenchie@0.4.2 spec. If you hand-pinned the version, update to @lab94/frenchie@0.4.2 or re-run install.

0.4.0 → 0.4.1 metadata polish

0.4.1 is a metadata-only release. Tool semantics, response shapes, and installer behaviour are unchanged — the upgrade tightens MCP listing quality so agents pick up better tool hints on first call.

  1. Per-parameter descriptions on every input field of every tool, so agents understand what to pass without trial and error.
  2. MCP tool annotations (readOnlyHint, idempotentHint, openWorldHint, plus a human-readable title) on all six tools — useful for agent UIs that surface tool intent before invoking.
  3. Optional FRENCHIE_OUTPUT_DIR exposed in the Smithery config schema. Existing installs already read this env var; it's now discoverable in the listing.

Upgrade

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

Restart your agent afterwards so it re-reads the pinned @lab94/frenchie@0.4.1 spec. If you hand-pinned the version, update to @lab94/frenchie@0.4.1 or re-run install and let the installer rewrite the config.

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 points at the public skill mirror. repository now points to Lab94/frenchie-skill, the public mirror synced from the private monorepo, and bugs points to getfrenchie.dev/docs/troubleshooting. No behavior change — just a cleaner npmjs.com/package/@lab94/frenchie page with a real source link for directory reviewers.

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