docs(mcp): client setup for Codex and others, plus troubleshooting

[rohanpoudel2]

The MCP README covered Claude only. The npm page for that package is where people decide whether to use it, so it needed to cover more than one client.

Client setup

• Codex CLI — both codex mcp add and the raw ~/.codex/config.toml block
• Claude Code and Claude Desktop
• A generic stdio block for anything else (Cursor, VS Code, Windsurf, Zed)

The Codex syntax is verified locally against codex-cli 0.137.0, not copied from a blog post: codex mcp add <NAME> -- <COMMAND>..., with the TOML shape ([mcp_servers.<name>] + command + args) confirmed against a real installed server entry.

Also added

• "What you can ask for" — the requests a person actually makes. Tool names mean nothing to someone reading an npm page cold.
• Troubleshooting for the four real failure modes: server won't start, ffmpeg missing from a GUI-launched client's PATH, a format rejected as unsupported, and files reported as skipped when nothing is wrong.
• Badges, and every parameter of every tool documented.

Verified against the published package

Not the local workspace build — the actual thing users get:

$ npx -y image-and-video-compressor-mcp
tools: compress_media, discover_media, list_capabilities, plan_video_conversion, probe_media
image formats: .jpg .png .webp .avif .tif .gif
video available: true

The troubleshooting section tells people the server should print nothing on stdout, so I checked that too — 0 bytes, exit 0 on stdin close. A stray byte there would corrupt JSON-RPC.

One packaging note

mcp/README.md deliberately uses absolute GitHub URLs, no relative links. That package sets repository.directory to mcp, which makes npm's relative-link rewriting fragile. The main README keeps its relative links, which resolve correctly from the repo root.