io.github.Lab94/frenchie-skill

Official7 tools

by Lab94 · TypeScript

Frenchie

OCR, transcription, file extraction, and image generation for AI agents via MCP.

Performs OCR, transcription, file extraction, and image generation for agents.

Captured live from the server via tools/list.

ocr_to_markdown

Convert PDF/image files into Markdown through Frenchie

Parameters (3)

file_pathstring
Absolute local file path. Stdio transport only — over HTTP, upload via upload_file first and pass uploaded_file_reference instead.
uploaded_file_referencestring
Object key returned by upload_file. Required for HTTP transport; ignored when file_path is provided in stdio.
api_keystring
Optional Frenchie API key (fr_...). Falls back to the FRENCHIE_API_KEY env var when omitted.

transcribe_to_markdown

Convert audio/video files into Markdown transcripts through Frenchie. Set language (ISO 639-1 code, e.g. 'th', 'en', 'ja') for better accuracy; omit for auto-detection.

Parameters (4)

file_pathstring
Absolute local file path. Stdio transport only — over HTTP, upload via upload_file first and pass uploaded_file_reference instead.
uploaded_file_referencestring
Object key returned by upload_file. Required for HTTP transport; ignored when file_path is provided in stdio.
api_keystring
Optional Frenchie API key (fr_...). Falls back to the FRENCHIE_API_KEY env var when omitted.
languagestring
Optional ISO 639-1 language code (e.g. 'th', 'en', 'ja') for better accuracy; omit for auto-detection.

generate_image

Generate a single image from a text prompt through Frenchie. Required: prompt. Optional: style (free-text style direction), size, quality, format, background. stdio mode auto-saves the image to .frenchie/<slug>/generated.<ext>; HTTP mode returns a presigned imageUrl that the agent should download for the user.

Parameters (8)

promptstringrequired
Required. Plain-language description of the image to generate (e.g. 'poster of a ramen shop at night').
stylestring
Optional style direction (e.g. 'flat vector, neon palette'). Merged into the generation prompt by Frenchie.
sizestring
Optional output size. Defaults to automatic selection.
qualitystring
Optional output quality.
formatstring
Optional output format. Defaults to png.
backgroundstring
Optional background. transparent is rejected when format is jpeg.
output_dirstring
Stdio mode only: absolute directory under which .frenchie/<slug>/generated.<ext> is saved. Defaults to the MCP server's process cwd. Recommended: pass your workspace root so the image lands next to your work instead of $HOME.
api_keystring
Optional Frenchie API key (fr_...). Falls back to the FRENCHIE_API_KEY env var when omitted.

extract_to_markdown

Extract structured documents (.docx, .xlsx, .csv, .tsv, .pptx) into Markdown through Frenchie. stdio mode auto-saves the result to .frenchie/<name>/result.md; HTTP mode returns inline Markdown.

Parameters (3)

file_pathstring
Absolute local file path. Stdio transport only — over HTTP, upload via upload_file first and pass uploaded_file_reference instead.
uploaded_file_referencestring
Object key returned by upload_file. Required for HTTP transport; ignored when file_path is provided in stdio.
api_keystring
Optional Frenchie API key (fr_...). Falls back to the FRENCHIE_API_KEY env var when omitted.

get_job_result

Fetch the latest async Frenchie job result

Parameters (2)

job_idstringrequired
Job ID returned by ocr_to_markdown, transcribe_to_markdown, or generate_image when status was 'processing'.
api_keystring
Optional Frenchie API key (fr_...). Falls back to the FRENCHIE_API_KEY env var when omitted.

upload_file

Get a presigned upload URL for use with ocr_to_markdown, transcribe_to_markdown, or extract_to_markdown in HTTP mode. After calling this tool, PUT the file to upload_url (with the correct Content-Type header), then pass object_key as uploaded_file_reference to the processing tool.

Parameters (4)

filenamestringrequired
Original filename with extension (e.g. 'report.pdf').
file_sizeintegerrequired
File size in bytes.
mime_typestringrequired
MIME type (e.g. 'application/pdf', 'audio/mpeg').
api_keystring
Optional Frenchie API key (fr_...). Falls back to the FRENCHIE_API_KEY env var when omitted.

fetch_result_file

Get a temporary download URL for a result file from OCR/transcription output. Use this to download images referenced as frenchie-result: in the result markdown.

Parameters (2)

object_keystringrequired
The object key parsed from a frenchie-result:<objectKey> reference in the result markdown.
api_keystring
Optional Frenchie API key (fr_...). Falls back to the FRENCHIE_API_KEY env var when omitted.

README.md10 KBView on GitHub

@lab94/frenchie

Frenchie — your agent's best friend.

Install Frenchie in your coding agent with one command. Frenchie Kit gives agents file and multimodal capabilities: read PDFs and images, transcribe audio and video, extract Office/CSV files to Markdown, and generate images from text prompts. Frenchie Method gives teams a structured workflow from requirement to release.

Upgrading from 0.1.x or 0.2.x? See MIGRATION.md for the breaking changes in 0.3.0 (stdio metadata-only responses, absolute-path MCP configs, new mcp --help / --selftest flags).

This package ships:

Frenchie Kit (/ocr, /transcribe, /extract, /generate-image, /frenchie-status commands + HTTP/stdio MCP guidance)
Frenchie Method (/frenchie-method, /requirement, /qa-analysis, /implement, /run-test, /pr-review, /release-check, and related workflow commands)
The Frenchie stdio MCP server (lab94-frenchie mcp) bundled for npx
An installer that wires skills and MCP config into your agent

Quick start

1. Install the skills

From the root of your project:

bash

npx @lab94/frenchie install

This installs Frenchie Kit and Frenchie Method skills. Method is text-only and works without an API key.

Optional Method config:

bash

npx @lab94/frenchie install --init-method

This creates .frenchie/method.config.json and .frenchie/.gitignore; it does not edit your root .gitignore.

2. Log in for Kit MCP tools when you need file or image capabilities

Create an account at getfrenchie.dev. You get 100 free credits on your first signup, once per email. No card required.

Then connect your local agent:

bash

npx @lab94/frenchie login

The login command opens a browser device-code flow, then writes FRENCHIE_API_KEY into the MCP config the installer created. The full key is never printed.

Fallback if you already have a key from the dashboard:

bash

npx @lab94/frenchie install --api-key fr_your_key_here

To target a specific agent:

bash

npx @lab94/frenchie login --agent claude
npx @lab94/frenchie login --agent cursor
npx @lab94/frenchie login --agent codex
npx @lab94/frenchie login --agent vscode
npx @lab94/frenchie login --agent gemini

User-level installs (Antigravity, Windsurf, Zed, Claude Desktop) need the --global flag — auto-detect never writes under $HOME:

bash

npx @lab94/frenchie login --agent antigravity   --global
npx @lab94/frenchie login --agent windsurf       --global
npx @lab94/frenchie login --agent zed            --global
npx @lab94/frenchie login --agent claude-desktop --global

Fallback with an existing key:

bash

npx @lab94/frenchie install --agent claude        --api-key fr_…
npx @lab94/frenchie install --agent codex         --api-key fr_…
npx @lab94/frenchie install --agent antigravity   --global --api-key fr_…
npx @lab94/frenchie install --agent claude-desktop --global --api-key fr_…

After login, your agent can call ocr_to_markdown, transcribe_to_markdown, extract_to_markdown, or generate_image. OCR/transcription/extraction results are saved to .frenchie/<name>/result.md automatically; generated images are saved to .frenchie/<slug>/generated.<ext>.

Upgrading later

When a new Frenchie version ships, the pinned package spec inside each MCP config (@lab94/frenchie@0.5.0) needs to point at the new version so npx stops serving a cached older bundle. Two upgrade commands cover everything:

bash

# Project-scoped configs in this directory (.mcp.json, .cursor/mcp.json, .codex/config.toml, etc.)
npx @lab94/frenchie@latest install

# Every $HOME config that already has a frenchie entry — Antigravity, Claude Desktop, Windsurf, Zed,
# and any global Claude Code / Cursor / Codex / Gemini configs you set up. cwd doesn't matter.
npx @lab94/frenchie@latest install --global

install --global is upgrade-mode: it only rewrites frenchie entries that already exist. It will not surprise-install anything new under $HOME. First-time global installs still go through install --agent <name> --global.

3. Restart your agent

The installer prints the restart hint for your agent. After that, ask:

code

OCR ./report.pdf with Frenchie

…and Frenchie takes it from there.

For workflow orchestration, ask:

txt

/frenchie-method

/frenchie remains the Kit entrypoint in agents that use a single Frenchie command. It is not an alias for Method.

Hosted agents (Lovable, Manus, Claude.ai, ChatGPT.com, Le Chat)

These agents can't run local npm binaries. Use the hosted MCP endpoint instead:

code

URL:    https://mcp.getfrenchie.dev
Header: Authorization: Bearer fr_your_key_here

The same @lab94/frenchie skill files work in HTTP mode — install them once with install --agent <name> and the included SKILL.md will tell the agent to upload files via upload_file before calling OCR/transcription/extraction. Image generation does not need an upload step in HTTP mode; it returns a short-lived imageUrl that the agent should download for the user.

What you get

Frenchie Kit

Command	What it does
`/ocr <file>`	Parse a PDF or image into Markdown
`/transcribe <file>`	Parse audio or video into a Markdown transcript
`/extract <file>`	Parse DOCX, XLSX, CSV, TSV, or PPTX into Markdown
`/generate-image <prompt>`	Generate a single image from a text prompt
`/frenchie-status`	Check credits and recent jobs

Under the hood, Frenchie exposes these MCP tools:

ocr_to_markdown
transcribe_to_markdown
extract_to_markdown
generate_image
get_job_result
upload_file (HTTP mode only)
fetch_result_file (HTTP mode only)

Frenchie Method

Slash notation is the canonical Method command name. Claude Code reads command files directly. Codex Desktop gets the same entries through wrapper skills such as requirement and qa-analysis; restart Codex after install before trying /requirement. Hosts without slash support can use natural language such as Frenchie Method requirement ....

Command	What it does
`/frenchie-method`	Route a task through Method from requirement to release
`/method-check`	Validate Method config, artifacts, gates, and next action
`/requirement`	Turn a request into scoped requirements
`/qa-analysis` / `/test-case`	Design proof before implementation planning
`/sa-analysis` / `/implementation-plan`	Analyze architecture and implementation approach
`/implement`	Execute from Method artifacts using the current agent
`/run-test`	Run repo-declared verification and write a test report
`/pr-review` / `/review-pr`	Review the result, tests, security, and artifact drift
`/release-check`	Read-only release readiness gate

Method stores optional workflow artifacts under .frenchie/docs/feature/. install --init-method also writes a visible skillTriggers skeleton in .frenchie/method.config.json; command keys are empty slots teams can fill with installed agent skills, for example "requirement": ["brainstorming"]. Teams decide whether to commit or ignore Method config and artifacts.

Invocation — how to call Frenchie in each agent

Every agent handles MCP a little differently. /ocr is a Claude Code-only slash command; Method slash commands are host-dependent and use Codex wrapper skills outside Claude Code. Other agents use natural language, @-mention, or a server-name slash command. All facts below are dogfood-verified.

Agent	Invoke	Full guide
Claude Code	`/ocr TOR.pdf`	docs
Cursor	`Use Frenchie to OCR TOR.pdf`	docs
Codex (Desktop / CLI / IDE)	Kit: `/frenchie TOR.pdf` · `@frenchie ocr TOR.pdf`; Method: `/requirement` after restart, or `Frenchie Method requirement ...`	docs
Antigravity	`/frenchie TOR.pdf` (invokes by server name)	docs
VS Code Copilot	`/frenchie TOR.pdf`	docs
Claude Desktop	`Use Frenchie to OCR TOR.pdf`	docs
Windsurf	`OCR TOR.pdf via Frenchie`	docs
Gemini CLI	`OCR TOR.pdf with Frenchie`	docs
Zed	`OCR TOR.pdf via Frenchie`	docs

Something not working? See the symptom-first troubleshooting guide — every error we've hit in dogfood has a canonical entry.

Pricing

Simple numbers. No subscriptions.

File extraction pricing: DOCX 0.5 credits per page, XLSX 0.5 credits per sheet, CSV/TSV 0.5 credits per file, PPTX 1 credit per slide.

Action	Cost
OCR	1 credit per page
Transcription	2 credits per minute
DOCX extraction	0.5 credits per page
XLSX extraction	0.5 credits per sheet
CSV/TSV extraction	0.5 credits per file
PPTX extraction	1 credit per slide
Image generation	20 credits per image

$1 = 100 credits. Credits don't expire.

Privacy

Files are processed and deleted. Results expire about 30 minutes after first delivery. If you need a durable copy, save the Markdown when it comes back.

Supported formats

OCR: PDF, PNG, JPG, JPEG, WebP

Transcription: MP3, M4A, WAV, MP4, MOV, WebM

File extraction: DOCX, XLSX, CSV, TSV, PPTX

Image generation: PNG, JPEG, WebP output from text prompts

Need help?

Install

Configuration

Environment variables

FRENCHIE_API_KEYrequiredsecret

Your Frenchie API key (starts with fr_). Create one at https://getfrenchie.dev/dashboard/api-keys — first signup comes with 100 free credits.

FRENCHIE_DEFAULT_LANGUAGE

Optional ISO 639-1 language hint (e.g. 'th', 'en', 'ja') applied to transcribe_to_markdown when the tool input does not specify a language. Tool-level language always wins.

claude_desktop_config.json

{
  "mcpServers": {
    "frenchie-skill": {
      "command": "npx",
      "args": [
        "-y",
        "@lab94/frenchie@0.5.0"
      ],
      "env": {
        "FRENCHIE_API_KEY": "<YOUR_FRENCHIE_API_KEY>",
        "FRENCHIE_DEFAULT_LANGUAGE": "<YOUR_FRENCHIE_DEFAULT_LANGUAGE>"
      }
    }
  }
}