@obrahaus/fileforge-mcp 2.2.0
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +71 -0
- package/dist/index.js +1380 -0
- package/package.json +40 -0
package/README.md
ADDED
|
@@ -0,0 +1,71 @@
|
|
|
1
|
+
# @obrahaus/fileforge-mcp
|
|
2
|
+
|
|
3
|
+
A [Model Context Protocol](https://modelcontextprotocol.io) server that lets AI
|
|
4
|
+
agents convert files with [FileForge](https://fileforge.obrahaus.com) —
|
|
5
|
+
images, audio, video, documents, and archives — without learning the REST API.
|
|
6
|
+
It's a thin client of the FileForge Public API (`/v1`): same `ff_live_…` keys,
|
|
7
|
+
tiers, and limits. No native dependencies.
|
|
8
|
+
|
|
9
|
+
## Install
|
|
10
|
+
|
|
11
|
+
Add to your MCP client config and set your API key:
|
|
12
|
+
|
|
13
|
+
```json
|
|
14
|
+
{
|
|
15
|
+
"mcpServers": {
|
|
16
|
+
"fileforge": {
|
|
17
|
+
"command": "npx",
|
|
18
|
+
"args": ["-y", "@obrahaus/fileforge-mcp"],
|
|
19
|
+
"env": { "FILEFORGE_API_KEY": "ff_live_…" }
|
|
20
|
+
}
|
|
21
|
+
}
|
|
22
|
+
}
|
|
23
|
+
```
|
|
24
|
+
|
|
25
|
+
- **Claude Code**: `claude mcp add fileforge -e FILEFORGE_API_KEY=ff_live_… -- npx -y @obrahaus/fileforge-mcp`
|
|
26
|
+
- **Claude Desktop / Cursor / Windsurf**: paste the block above into the app's MCP config.
|
|
27
|
+
|
|
28
|
+
Get an API key from your FileForge account → Settings → API keys (Forge Pro).
|
|
29
|
+
|
|
30
|
+
## Tools
|
|
31
|
+
|
|
32
|
+
- **`convert_file`** — one call: give it a file (`source.path` local file,
|
|
33
|
+
`source.url`, or base64 `source.bytes`) + `target_format` (+ optional
|
|
34
|
+
`preset`, `options`, `output`); it uploads, converts, polls, and downloads.
|
|
35
|
+
- **`list_formats`** — the tier-filtered formats + options matrix.
|
|
36
|
+
- **`get_conversion_status`** — poll/resume a conversion and download its result.
|
|
37
|
+
- **`convert_files`** — bulk conversion (Forge Pro).
|
|
38
|
+
|
|
39
|
+
Example: *"Convert ./logo.png to a favicon with sizes 16,32,48"* →
|
|
40
|
+
`convert_file({ source: { path: "./logo.png" }, target_format: "ico", options: { sizes: "16,32,48" } })`
|
|
41
|
+
→ writes `./logo.ico`.
|
|
42
|
+
|
|
43
|
+
## Configuration
|
|
44
|
+
|
|
45
|
+
| Env var | Default | Purpose |
|
|
46
|
+
|---------|---------|---------|
|
|
47
|
+
| `FILEFORGE_API_KEY` | — (required) | Your `ff_live_…` key. |
|
|
48
|
+
| `FILEFORGE_API_BASE_URL` | `https://fileforge-api.obrahaus.com/v1` | Override for self-host / dev. |
|
|
49
|
+
| `FF_MCP_MAX_POLL_SECONDS` | `300` | Ceiling on any tool's wait loop. |
|
|
50
|
+
| `FF_MCP_MAX_INLINE_BYTES` | `5242880` | Max size for base64-inlined results. |
|
|
51
|
+
| `FF_MCP_OUTPUT_DIR` | — | Default output directory. |
|
|
52
|
+
| `FF_MCP_LOG_LEVEL` | `info` | Log verbosity. |
|
|
53
|
+
|
|
54
|
+
## Troubleshooting
|
|
55
|
+
|
|
56
|
+
- **Logs go to stderr, never stdout** — stdout is reserved for the JSON-RPC
|
|
57
|
+
protocol. Check your MCP client's server logs for `[fileforge-mcp]` lines.
|
|
58
|
+
- **`config error: FILEFORGE_API_KEY …`** — the key is missing/malformed; it
|
|
59
|
+
must look like `ff_live_…`.
|
|
60
|
+
- **Self-host / develop** — set `FILEFORGE_API_BASE_URL` to your API's `/v1` base.
|
|
61
|
+
- **First run** — use `npx -y` so npm installs without an interactive prompt.
|
|
62
|
+
|
|
63
|
+
## Develop (from a checkout)
|
|
64
|
+
|
|
65
|
+
```bash
|
|
66
|
+
pnpm --filter @obrahaus/fileforge-mcp build # bundles dist/index.js
|
|
67
|
+
FILEFORGE_API_KEY=ff_live_… node apps/mcp/dist/index.js
|
|
68
|
+
# or, without building: pnpm --filter @obrahaus/fileforge-mcp dev
|
|
69
|
+
```
|
|
70
|
+
|
|
71
|
+
Full docs: https://fileforge-docs.obrahaus.com/api/mcp
|