@faktry/mcp 0.0.0-stage → 0.1.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/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 faktry
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
package/README.md CHANGED
@@ -1,3 +1,377 @@
1
- # Temporary Holding Version
1
+ <p align="center">
2
+ <a href="https://faktry.ai">
3
+ <picture>
4
+ <source media="(prefers-color-scheme: dark)" srcset="assets/logo_white.png">
5
+ <source media="(prefers-color-scheme: light)" srcset="assets/logo_black.png">
6
+ <img alt="faktry" src="assets/logo_black.png" width="240">
7
+ </picture>
8
+ </a>
9
+ </p>
2
10
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
11
+ <h1 align="center">faktry MCP</h1>
12
+
13
+ <p align="center">
14
+ <strong>Bring the whole faktry media stack into the tools you already use.</strong><br>
15
+ Generate and edit images, video, audio, and PDFs from any MCP-compatible client.
16
+ </p>
17
+
18
+ <p align="center">
19
+ <a href="./LICENSE"><img alt="License: MIT" src="https://img.shields.io/badge/License-MIT-1f9dff.svg"></a>
20
+ <a href="https://faktry.ai/mcp"><img alt="Docs" src="https://img.shields.io/badge/Docs-faktry.ai%2Fmcp-1f9dff"></a>
21
+ </p>
22
+
23
+ <p align="center">
24
+ <a href="#install">Install</a> ·
25
+ <a href="#tools">Tools</a> ·
26
+ <a href="#example-prompts">Examples</a> ·
27
+ <a href="#troubleshooting">Troubleshooting</a>
28
+ </p>
29
+
30
+ <p align="center">
31
+ <img src="assets/platform.png" alt="faktry platform" width="100%">
32
+ </p>
33
+
34
+ ---
35
+
36
+ The **faktry MCP server** exposes the full faktry toolkit — over 70 tools spanning image, video, audio, PDF, and 3D generation and editing — to any client that speaks the [Model Context Protocol](https://modelcontextprotocol.io). Generate a product shot, cut it into a UGC-style video with a voiceover, subtitle it, and export a thumbnail sheet, all without leaving the chat.
37
+
38
+ - <img src="assets/icon_black.png" width="14" align="top"> **Hosted, remote.** Connect to `https://faktry.ai/api/mcp` — no local server to run. stdio-only clients can use the `npx -y @faktry/mcp` bridge.
39
+ - **OAuth or API key, your choice.** One-click connect from Claude.ai, Claude Desktop, Cursor, and Hermes, or drop a static API key into any config-based client.
40
+ - **Async by default.** Long-running jobs (video, some image/audio) return a `job_id` immediately; poll `faktry_job_status` until it's ready.
41
+ - **A library that remembers.** Save any result with `faktry_library_save` and pull it back into a later session with `faktry_library_list`.
42
+ - **You pay through your faktry account.** Usage draws down your existing credit balance — check it anytime with `faktry_credits`.
43
+
44
+ ---
45
+
46
+ ## Install
47
+
48
+ ### One-click / OAuth
49
+
50
+ These clients handle authentication for you — paste the URL, sign in, approve.
51
+
52
+ **MCP Server URL:**
53
+
54
+ ```
55
+ https://faktry.ai/api/mcp
56
+ ```
57
+
58
+ <details open>
59
+ <summary><strong>Claude.ai</strong></summary>
60
+
61
+ 1. Open Claude.ai → **Settings → Integrations**.
62
+ 2. Click **Add MCP Server** and paste the URL above.
63
+ 3. Claude.ai redirects you to faktry — sign in and click **Approve**.
64
+ 4. Done — Claude.ai stores the token automatically.
65
+
66
+ </details>
67
+
68
+ <details>
69
+ <summary><strong>Claude Desktop</strong></summary>
70
+
71
+ 1. Open Claude Desktop → **Settings → Developer → MCP Servers**.
72
+ 2. Click **Add Server** and paste the URL above.
73
+ 3. A browser window opens — sign in to faktry and click **Approve**.
74
+ 4. Restart Claude Desktop if tools don't appear immediately.
75
+
76
+ </details>
77
+
78
+ <details>
79
+ <summary><strong>Cursor</strong></summary>
80
+
81
+ 1. Open Cursor → **Settings → AI → MCP Servers**.
82
+ 2. Click **Add MCP Server** and paste the URL above.
83
+ 3. Cursor detects OAuth and opens a browser login window.
84
+ 4. Sign in to faktry, approve access, and return to Cursor.
85
+
86
+ </details>
87
+
88
+ <details>
89
+ <summary><strong>Hermes Agent</strong></summary>
90
+
91
+ 1. Open Hermes Agent → **Settings → MCP Servers**.
92
+ 2. Click **+** and paste the URL above.
93
+ 3. Hermes opens a browser login — sign in to faktry and approve.
94
+ 4. Toggle the server on — tools appear immediately.
95
+
96
+ </details>
97
+
98
+ <details>
99
+ <summary><strong>ChatGPT Desktop</strong> <sub>(Business / Enterprise / Edu only)</sub></summary>
100
+
101
+ 1. Enable **Developer Mode** in Settings → Beta Features.
102
+ 2. Go to **Settings → MCP Servers → Add Server**.
103
+ 3. Paste the URL above and follow the browser OAuth flow.
104
+
105
+ </details>
106
+
107
+ ### Config file / API key
108
+
109
+ Create an API key at [faktry.ai/api/keys](https://faktry.ai/api/keys) first, then add faktry to your client's config. Replace `YOUR_API_KEY_HERE` with your real key — it's only shown once when created.
110
+
111
+ <details>
112
+ <summary><strong>Claude Code</strong></summary>
113
+
114
+ Add to `.mcp.json` (project) or `~/.claude.json` (user):
115
+
116
+ ```json
117
+ {
118
+ "mcpServers": {
119
+ "faktry": {
120
+ "type": "http",
121
+ "url": "https://faktry.ai/api/mcp",
122
+ "headers": { "Authorization": "Bearer YOUR_API_KEY_HERE" }
123
+ }
124
+ }
125
+ }
126
+ ```
127
+
128
+ Picked up automatically — no restart needed.
129
+
130
+ </details>
131
+
132
+ <details>
133
+ <summary><strong>VS Code (Copilot)</strong></summary>
134
+
135
+ Add to `.vscode/mcp.json` (workspace) or via **Settings → MCP Servers**:
136
+
137
+ ```json
138
+ {
139
+ "servers": {
140
+ "faktry": {
141
+ "type": "http",
142
+ "url": "https://faktry.ai/api/mcp",
143
+ "headers": { "Authorization": "Bearer YOUR_API_KEY_HERE" }
144
+ }
145
+ }
146
+ }
147
+ ```
148
+
149
+ </details>
150
+
151
+ <details>
152
+ <summary><strong>Windsurf</strong></summary>
153
+
154
+ Edit `~/.codeium/windsurf/mcp_config.json` (`%USERPROFILE%\.codeium\windsurf\mcp_config.json` on Windows) — note Windsurf uses `serverUrl`, not `url`:
155
+
156
+ ```json
157
+ {
158
+ "mcpServers": {
159
+ "faktry": {
160
+ "serverUrl": "https://faktry.ai/api/mcp",
161
+ "headers": { "Authorization": "Bearer YOUR_API_KEY_HERE" }
162
+ }
163
+ }
164
+ }
165
+ ```
166
+
167
+ Restart Windsurf to activate the tools.
168
+
169
+ </details>
170
+
171
+ <details>
172
+ <summary><strong>Continue.dev</strong></summary>
173
+
174
+ Add to `~/.continue/config.yaml`:
175
+
176
+ ```yaml
177
+ mcpServers:
178
+ faktry:
179
+ type: http
180
+ url: https://faktry.ai/api/mcp
181
+ requestOptions:
182
+ headers:
183
+ Authorization: "Bearer YOUR_API_KEY_HERE"
184
+ ```
185
+
186
+ Continue.dev reloads automatically.
187
+
188
+ </details>
189
+
190
+ <details>
191
+ <summary><strong>Codex CLI</strong></summary>
192
+
193
+ Add to `~/.codex/config.toml`:
194
+
195
+ ```toml
196
+ [mcp.servers.faktry]
197
+ type = "http"
198
+ url = "https://faktry.ai/api/mcp"
199
+
200
+ [mcp.servers.faktry.headers]
201
+ Authorization = "Bearer YOUR_API_KEY_HERE"
202
+ ```
203
+
204
+ Verify with `codex mcp list`.
205
+
206
+ </details>
207
+
208
+ <details>
209
+ <summary><strong>stdio clients (npx)</strong> <sub>— Zed, older Claude Desktop configs, and anything without remote MCP</sub></summary>
210
+
211
+ The [`@faktry/mcp`](https://www.npmjs.com/package/@faktry/mcp) package is a thin stdio bridge to the hosted server. Requires Node 18+.
212
+
213
+ Generic form:
214
+
215
+ ```bash
216
+ FAKTRY_API_KEY=YOUR_API_KEY_HERE npx -y @faktry/mcp
217
+ ```
218
+
219
+ Claude Desktop (`claude_desktop_config.json`) and most other `mcpServers` clients:
220
+
221
+ ```json
222
+ {
223
+ "mcpServers": {
224
+ "faktry": {
225
+ "command": "npx",
226
+ "args": ["-y", "@faktry/mcp"],
227
+ "env": { "FAKTRY_API_KEY": "YOUR_API_KEY_HERE" }
228
+ }
229
+ }
230
+ }
231
+ ```
232
+
233
+ Zed (`settings.json`, `%APPDATA%\Zed\settings.json` on Windows):
234
+
235
+ ```json
236
+ {
237
+ "context_servers": {
238
+ "faktry": {
239
+ "source": "custom",
240
+ "command": "npx",
241
+ "args": ["-y", "@faktry/mcp"],
242
+ "env": { "FAKTRY_API_KEY": "YOUR_API_KEY_HERE" }
243
+ }
244
+ }
245
+ }
246
+ ```
247
+
248
+ Leave `FAKTRY_API_KEY` out to sign in through the browser (OAuth) instead.
249
+
250
+ </details>
251
+
252
+ <details>
253
+ <summary><strong>Kilo Code</strong></summary>
254
+
255
+ 1. Open the Kilo Code extension settings → **MCP Servers**.
256
+ 2. Add a new server using the same JSON snippet as Claude Code above.
257
+ 3. Replace `YOUR_API_KEY_HERE` with your actual key.
258
+
259
+ </details>
260
+
261
+ <details>
262
+ <summary><strong>Other MCP clients</strong></summary>
263
+
264
+ Add a remote HTTP server pointing at `https://faktry.ai/api/mcp` with header:
265
+
266
+ ```
267
+ Authorization: Bearer YOUR_API_KEY_HERE
268
+ ```
269
+
270
+ Full per-client snippets and paths are also generated at [faktry.ai/mcp](https://faktry.ai/mcp).
271
+
272
+ </details>
273
+
274
+ ---
275
+
276
+ ## Tools
277
+
278
+ Your client picks which tool to call based on your prompt — you don't need to invoke them by name. faktry exposes 70+ tools across five categories:
279
+
280
+ | Category | Examples | What it covers |
281
+ | --- | --- | --- |
282
+ | `faktry_image_*` | `generate`, `edit`, `inpaint`, `outpaint`, `upscale`, `removebackground`, `effects`, `collage`, `watermark`, `smartcrop` | Text-to-image, editing, upscaling, background removal, compositing |
283
+ | `faktry_video_*` | `text2video`, `image2video`, `avatar`, `motioncontrol`, `subtitle`, `reframe`, `stabilize`, `upscale`, `scenedetect` | Generation, editing, avatars, motion control, subtitles, reframing |
284
+ | `faktry_audio_*` | `generatespeech`, `clonevoice`, `generatemusic`, `generatesound`, `mix`, `transcribe`, `trim` | Speech synthesis, voice cloning, music/SFX generation, mixing |
285
+ | `faktry_pdf_*` | `create`, `merge`, `split`, `compress`, `extract`, `mdconvert` | PDF creation and manipulation |
286
+ | `faktry_3d_*` | `image23d`, `text23d` | 3D asset generation from images or text |
287
+
288
+ Plus utility tools:
289
+
290
+ | Tool | What it does |
291
+ | --- | --- |
292
+ | `faktry_job_status` | Poll an async job by `job_id` until it's `completed`, returning `result_url` |
293
+ | `faktry_credits` | Check credit balance and current-month usage |
294
+ | `faktry_library_list` | Browse previously saved media assets |
295
+ | `faktry_library_save` | Save a result URL to the library for reuse across sessions |
296
+
297
+ ### The async job pattern
298
+
299
+ Most generation tools (video, some image/audio) are async:
300
+
301
+ 1. Call the generation tool → receive a `job_id`.
302
+ 2. Poll `faktry_job_status` with that `job_id` every few seconds.
303
+ 3. When status is `completed`, the response contains `result_url`.
304
+ 4. Optionally persist it with `faktry_library_save`.
305
+
306
+ ---
307
+
308
+ ## Example prompts
309
+
310
+ Try these once faktry is connected:
311
+
312
+ ```
313
+ Generate a studio product shot of a matte black wireless speaker on a
314
+ white background, then upscale it to 4K.
315
+ ```
316
+
317
+ ```
318
+ Turn this product image into a 9:16 UGC-style video with a voiceover
319
+ reading the description, and add subtitles.
320
+ ```
321
+
322
+ ```
323
+ Remove the background from this photo, then composite it onto a
324
+ gradient backdrop.
325
+ ```
326
+
327
+ ```
328
+ Clone this voice sample and generate a 30-second narration reading
329
+ this script.
330
+ ```
331
+
332
+ ```
333
+ Check my faktry credits, then show me what's in my library.
334
+ ```
335
+
336
+ ---
337
+
338
+ ## Troubleshooting
339
+
340
+ <details>
341
+ <summary><strong>Tools don't appear after connecting</strong></summary>
342
+
343
+ - **Claude.ai / Desktop:** Settings → Integrations (or Developer → MCP Servers), confirm faktry shows as connected. Remove and re-add if it failed silently — make sure pop-ups aren't blocked so the OAuth window can open.
344
+ - **Claude Code:** `claude mcp list` should show the server.
345
+ - **Codex:** `codex mcp list` should show `faktry`. Start a new session after adding.
346
+ - Quick smoke test: ask your client *"check my faktry credits"*.
347
+
348
+ </details>
349
+
350
+ <details>
351
+ <summary><strong>Authentication or API key errors</strong></summary>
352
+
353
+ - For config-file clients, confirm `YOUR_API_KEY_HERE` was replaced with a real, active key from [faktry.ai/api/keys](https://faktry.ai/api/keys) — keys are shown only once at creation.
354
+ - For OAuth clients, disconnect and reconnect the connector to redo the flow.
355
+
356
+ </details>
357
+
358
+ <details>
359
+ <summary><strong>A generation keeps loading</strong></summary>
360
+
361
+ Video renders and some audio/image jobs take longer than a plain image generation. The tool returns a pending `job_id` immediately — keep polling `faktry_job_status` until it reports `completed`.
362
+
363
+ </details>
364
+
365
+ ---
366
+
367
+ ## Links
368
+
369
+ - **MCP setup UI** — [faktry.ai/mcp](https://faktry.ai/mcp)
370
+ - **API keys** — [faktry.ai/api/keys](https://faktry.ai/api/keys)
371
+ - **faktry** — [faktry.ai](https://faktry.ai)
372
+
373
+ ---
374
+
375
+ ## License
376
+
377
+ [MIT](./LICENSE) © faktry
@@ -0,0 +1,43 @@
1
+ #!/usr/bin/env node
2
+ // stdio bridge to the hosted faktry MCP server (https://faktry.ai/api/mcp).
3
+ //
4
+ // With FAKTRY_API_KEY set, requests are authenticated with that key.
5
+ // Without it, mcp-remote falls back to the browser OAuth flow.
6
+
7
+ import { spawn } from "node:child_process";
8
+ import { createRequire } from "node:module";
9
+ import { dirname, join } from "node:path";
10
+
11
+ const DEFAULT_URL = "https://faktry.ai/api/mcp";
12
+
13
+ const require = createRequire(import.meta.url);
14
+ const proxy = join(dirname(require.resolve("mcp-remote/package.json")), "dist", "proxy.js");
15
+
16
+ const url = process.env.FAKTRY_MCP_URL || DEFAULT_URL;
17
+ const apiKey = process.env.FAKTRY_API_KEY?.trim();
18
+
19
+ const args = [proxy, url];
20
+ const env = { ...process.env };
21
+
22
+ if (apiKey) {
23
+ // mcp-remote expands ${VAR} in header values, so the key never appears in argv
24
+ // (visible in process listings) and the value has no spaces for a shell to split.
25
+ env.FAKTRY_AUTH_HEADER = `Bearer ${apiKey}`;
26
+ args.push("--header", "Authorization:${FAKTRY_AUTH_HEADER}");
27
+ }
28
+
29
+ // stdout is the MCP channel; diagnostics must go to stderr.
30
+ const child = spawn(process.execPath, args, { stdio: "inherit", env });
31
+
32
+ for (const signal of ["SIGINT", "SIGTERM"]) {
33
+ process.on(signal, () => child.kill(signal));
34
+ }
35
+
36
+ child.on("error", (err) => {
37
+ console.error(`faktry-mcp: failed to start bridge: ${err.message}`);
38
+ process.exit(1);
39
+ });
40
+
41
+ child.on("exit", (code, signal) => {
42
+ process.exit(code ?? (signal ? 1 : 0));
43
+ });
package/package.json CHANGED
@@ -1,6 +1,34 @@
1
1
  {
2
2
  "name": "@faktry/mcp",
3
- "version": "0.0.0-stage",
4
- "stub": true,
5
- "description": "Temporary package placeholder for staged publishing"
6
- }
3
+ "version": "0.1.0",
4
+ "mcpName": "io.github.faktry/faktry-mcp",
5
+ "description": "stdio bridge to the hosted faktry MCP server. Generate and edit images, video, audio, and PDFs from any MCP client.",
6
+ "keywords": ["mcp", "model-context-protocol", "faktry", "image-generation", "video-generation", "audio", "pdf"],
7
+ "license": "MIT",
8
+ "homepage": "https://faktry.ai/mcp",
9
+ "repository": {
10
+ "type": "git",
11
+ "url": "git+https://github.com/faktry/faktry-mcp.git"
12
+ },
13
+ "bugs": {
14
+ "url": "https://github.com/faktry/faktry-mcp/issues"
15
+ },
16
+ "type": "module",
17
+ "bin": {
18
+ "faktry-mcp": "bin/faktry-mcp.js"
19
+ },
20
+ "files": [
21
+ "bin",
22
+ "README.md",
23
+ "LICENSE"
24
+ ],
25
+ "dependencies": {
26
+ "mcp-remote": "^0.14.3"
27
+ },
28
+ "engines": {
29
+ "node": ">=18"
30
+ },
31
+ "publishConfig": {
32
+ "access": "public"
33
+ }
34
+ }