Ribox MCP
by AlgoWolfx
README.md
# Ribox MCP
Exact, file-based tools for AI assistants: the work a language model **cannot** do reliably by itself. Compress, resize and convert images, read or strip hidden metadata, make and read QR codes, count text exactly, diff text and validate JSON.
**Files never leave your computer.** Everything runs locally with WebAssembly codecs. No uploads, no network requests, no telemetry (the test suite checks this).
The same tools run in your browser at **[ribox.app](https://ribox.app)**.
## Tools
| Tool | What it does |
|---|---|
| `compress_image` | Make JPEG, PNG, WebP or AVIF files smaller (HEIC/BMP input accepted); target size such as "under 200 KB", max side length, format change |
| `resize_image` | Exact pixel sizes, fit/cover/stretch, crop, rotate 90/180/270, flip |
| `convert_image` | HEIC, JPEG, PNG, WebP, AVIF, BMP, ICO (favicon) |
| `file_metadata` | Read EXIF / GPS / XMP / IPTC / PNG text / PDF info, or remove it without re-encoding (verified afterwards) |
| `generate_qr` | Standards-compliant QR codes (link, text, Wi-Fi, vCard, email, SMS, WhatsApp, phone, location) as PNG or SVG |
| `read_qr` | Decode every QR code in photos or screenshots |
| `count_text` | Exact characters, words, sentences, lines, bytes; reading and speaking time |
| `diff_text` | Line, word or character diff with counts and a unified diff |
| `check_json` | Strict validation with the exact line and column of the first error; format, minify, sort keys |
Not included on purpose: changing letter case, rewriting text and similar work an assistant already does well.
## Install
Requires [Node.js](https://nodejs.org) 22.12 or newer.
The npm package will be `ribox-mcp`. Until then, run it straight from this repository with `npx github:AlgoWolfx/ribox-mcp`. The first start downloads and builds it, which takes a minute; later starts are fast.
### Claude Code
```sh
claude mcp add ribox -- npx -y github:AlgoWolfx/ribox-mcp
```
### Claude Desktop
Open *Settings > Developer > Edit Config* and add this to `claude_desktop_config.json`, then restart Claude Desktop:
```json
{
"mcpServers": {
"ribox": {
"command": "npx",
"args": ["-y", "github:AlgoWolfx/ribox-mcp", "/path/to/allowed/folder"]
}
}
}
```
On Windows, write the folder as `"C:\\Users\\you\\Pictures"`.
### Cursor
Add the same block to `.cursor/mcp.json` in your project (or `~/.cursor/mcp.json` for all projects).
### Other clients
Any MCP client that can start a stdio server works with the command `npx -y github:AlgoWolfx/ribox-mcp [allowed-folder ...]`.
### No local install? Use the remote endpoint
Assistants that cannot run local servers can connect to the remote endpoint **`https://ribox.app/api/mcp`** (Streamable HTTP). It offers only the four text tools (`generate_qr`, `count_text`, `diff_text`, `check_json`) and never accepts files. For anything that touches files, use the local server above.
## Which files can it touch?
Only files inside the allowed folders:
1. folders given as arguments (as in the examples above), otherwise
2. the folders your client shares as MCP *roots*, otherwise
3. the working directory the client starts the server in.
Paths outside these folders, including `../` tricks and symbolic links that point outside, are refused.
Results are written as **new files** next to the input (`photo.min.jpg`, `photo.resized.png`, `photo.clean.jpg`) or into `output_dir`. An original is replaced only when you pass `overwrite: true`. Up to 500 files per call; folders are processed non-recursively; each file up to 200 MB.
## Privacy
- Your files are read and written only on your machine.
- The server makes no network requests and sends no telemetry. The test suite blocks `fetch`, `http` and `https` and fails if any of them is called.
- The only usage signal is the public npm download count (once published).
## Development
```sh
git clone https://github.com/AlgoWolfx/ribox-mcp.git
cd ribox-mcp
npm install # also builds dist/
npm test # core tests + in-memory MCP client tests
npm run build
node dist/index.js --help
```
Layout:
- `src/`: the MCP server (stdio transport, file sandbox, tool handlers)
- `packages/core/`: the environment-independent tool core shared with [ribox.app](https://ribox.app); bundled into `dist/index.js` at build time
- `test/`: end-to-end tests with an in-memory MCP client
Issues and pull requests are welcome.
## License
MIT, see [`LICENSE`](LICENSE). Third-party components and their licenses (including the LGPL-3.0 HEIC decoder, used as a separate, unmodified module) are listed in [`THIRD_PARTY_NOTICES.md`](THIRD_PARTY_NOTICES.md).