{
  "markdown": "# @reelsfarm/mcp-client\n\nTyped TypeScript SDK and CLI for the ReelsFarm MCP server.\n\n## Version 3.0\n\nSDK `3.0.0` matches ReelsFarm MCP server `3.0.0` and contract\n`2026-08-22.1`. It tracks all 107 public tools. It adds publishing preflight,\nthe complete per-platform publishing contract, and canonical slideshow and\nautomation types.\n\nPublishing aliases from MCP 2.x are removed. Read [MIGRATION.md](./MIGRATION.md)\nbefore you update a publishing integration.\n\n    npm install @reelsfarm/mcp-client\n\n    import { ReelsFarmClient } from '@reelsfarm/mcp-client';\n\n    const rf = new ReelsFarmClient({\n      apiKey: process.env.REELSFARM_API_KEY,\n      validateToolSurface: 'throw',\n    });\n\n    await rf.ready();\n\n    const avatar = await rf.avatars.generate({\n      prompt: 'Woman in her 30s, casual outfit, smartphone selfie style',\n      model: 'nano-banana-pro',\n    });\n\n    if ('confirmationId' in avatar) {\n      console.log('Review mode requires confirmation:', avatar);\n    } else if ('wait' in avatar) {\n      const result = await avatar.wait();\n    }\n\nReview mode returns a `PreparedAction` by default. Trusted applications can set\n`autoConfirm: true` to confirm Review actions automatically. Creator and\nAutopilot connections execute the capabilities enabled by their server-owned\nconnection policy without an extra SDK approval step.\n\n## Conversational generation\n\nAvatar and product-scene jobs return `conversationId`, `parentGenerationId`,\nand `jobId`. Pass the conversation and parent IDs into the next generation to\ncontinue the same branch. Read the complete branch through\n`rf.imageGenerations.getConversation(conversationId)`.\n\n    const nextAvatar = await rf.avatars.generate({\n      prompt: 'Keep the same person and use a tighter crop',\n      sourceImageUrl: previousImageUrl,\n      conversationId,\n      parentGenerationId: previousJobId,\n    });\n\nHook generation accepts `customPrompt`, all current Veo and Seedance models,\nduration, and optional spoken script settings. Slideshow generation accepts\nMax mode visual context. Use `rf.slideshows.reviseText(...)` to apply a natural\nlanguage instruction to the complete current slide text state.\n\nSDK 3.0.0 also maps the web content library workflows directly:\n\n    const gallery = await rf.mediaCollections.listGallery({ kinds: ['COLLECTION', 'AVATAR'] });\n    const collections = await rf.mediaCollections.list();\n    const communityImages = await rf.community.listImages(collectionId, { random: true });\n    const voices = await rf.aiClones.listVoices({ search: 'warm' });\n    const importJob = await rf.hooks.importClips({\n      items: [{ url: youtubeUrl, start: \"0\", length: \"5\" }],\n    });\n\nThe same MCP contracts now cover the unified gallery, personal media\ncollections, community images, hook import health and jobs, AI Clone voice\nsearch, product-context URL suggestions, saved character identity extraction,\nand all four web trash item types.\n\n## Protocol and OAuth\n\nThe SDK uses the stable MCP TypeScript SDK v2. It probes for the 2026-07-28\nprotocol and falls back to the legacy 2025 handshake when required.\n\nOAuth clients should request only the capabilities they need. The default\nremains `mcp:full` for compatibility:\n\n    const rf = new ReelsFarmClient({\n      oauth: {\n        redirectUri: 'http://127.0.0.1:3456/callback',\n        scopes: ['content:read', 'content:generate'],\n        onAuthorizationUrl: openInBrowser,\n      },\n    });\n\n    await rf.raw.listTools();\n    await rf.completeOAuthCallback(callbackUrl);\n\nPass the complete callback URL to `completeOAuthCallback`. The SDK validates\nthe redirect URL, OAuth state, and authorization-server issuer before it\nredeems the code. The SDK does not expose a raw authorization-code completion\nmethod because that form cannot validate state by itself.\n\n## CLI\n\n    npm install -g @reelsfarm/mcp-client\n    reelsfarm login --api-key rfmcp_xxx\n    reelsfarm whoami\n    reelsfarm avatars list\n    reelsfarm avatars generate --prompt \"Creator selfie style\" --wait\n    reelsfarm media-collections gallery --kinds COLLECTION,AVATAR\n    reelsfarm ai-clones voices --search warm\n    reelsfarm hooks import-capabilities\n    reelsfarm posts preflight --content-type SLIDESHOW --content-id 11111111-1111-4111-8111-111111111111 --publish-format VIDEO --connection-ids 22222222-2222-4222-8222-222222222222 --agent\n    reelsfarm posts list --json\n\nCredentials are resolved in this order: constructor options, environment\nvariables, then the CLI config file at ~/.reelsfarm/config.json. Set\nREELSFARM_CONFIG_DIR to use a different config directory.\n\n## Using ReelsFarm with AI Agents\n\nReelsFarm is safe for shell-capable agents when invoked in agent mode:\n\n    reelsfarm agent status\n    reelsfarm agent commands\n    reelsfarm social connected --agent\n    reelsfarm posts schedule --content-type SLIDESHOW --content-id 11111111-1111-4111-8111-111111111111 --when 2026-09-01T15:00:00Z --platforms tiktok:22222222-2222-4222-8222-222222222222 --publish-format VIDEO --agent\n    reelsfarm confirm conf_123 --agent\n\nUse `--agent` or set `REELSFARM_AGENT_MODE=1` to receive strict JSON envelopes\non stdout. Agent mode never mixes tables or human narration into command output.\nErrors are also JSON on stdout and use a non-zero exit code.\n\nPrepared actions such as generation, scheduling, publishing, updating, and\ndeleting return a confirmation payload by default in agent mode. Review the\nsummary, then run `reelsfarm confirm <confirmationId> --agent`. Pass `--yes` only\nwhen the application should automatically confirm Review-mode actions.\n`--dry-run` is sent to the server and cannot mutate in Review, Creator, or\nAutopilot, even when combined with `--yes`.\n\nThe server connection policy is authoritative for direct writes. Creator may\ncreate and edit content but cannot publish or activate automations. Autopilot\nmay publish and manage automations subject to account limits. Credential,\nconnection-mode, webhook-security, and permanent-delete actions are\ndashboard-only and are not exposed by this package.\n\n## Idempotency and operation recovery\n\nSDK 3.0.0 generates one UUID for every logical mutation and reuses it if the\ntransport response is ambiguous. Supply `idempotencyKey` on a mutation input,\nor `--idempotency-key <key>` in the CLI, when retries must also survive process\nrestarts. Never reuse a key with different arguments.\n\nThe SDK never automatically re-prepares an action after confirmation. It safely\nreplays the same request once after an ambiguous transport failure and polls the\noriginal durable operation when the server returns one:\n\n    reelsfarm operations get --id op_123 --agent\n    reelsfarm operations wait --id op_123 --timeout 30000 --agent\n\nStructured errors distinguish authentication, insufficient scope, policy\ndenial, rate limiting, idempotency conflict, operation-in-progress, and plan\nlimits. OAuth profiles retain rotating refresh tokens in the existing protected\nprofile token store until revoked or a security event requires authorization.\n\n## Endpoint\n\nThe default MCP endpoint is https://mcp.reelsfarm.com/mcp. Pass `serverUrl` in\nthe SDK or `--server-url` in the CLI to target another deployment. The SDK\nrejects non-loopback plaintext HTTP by default. Set `allowInsecureHttp: true`\nor `REELSFARM_ALLOW_INSECURE_HTTP=1` only for a trusted private development\nendpoint. The CLI also accepts `--allow-insecure-http`.\n\n## Development\n\n    npm install\n    npm run typecheck\n    npm test\n    npm run check:manifest\n    npm run build\n\nThe checked-in tool manifest reflects the current discoverable ReelsFarm MCP\nsurface. Dashboard-only credential, webhook, and permanent-delete tools stay\nout of the public SDK catalog. The manifest check compares the 107 public SDK\ntools, release version, and contract version with the local app MCP catalog\nwhen both repositories are adjacent. Use\nnpm run generate:tools against an authenticated MCP endpoint when the server\nadds or removes tools.\n\n## Publishing preflight and platform settings\n\nRun preflight before a schedule or publish call. The server repeats preflight\nbefore it creates or executes the action.\n\n    const readiness = await rf.posts.preflight({\n      contentType: 'SLIDESHOW',\n      contentId: slideshowId,\n      publishFormat: 'VIDEO',\n      connectionIds: [tiktokConnectionId, youtubeConnectionId],\n    });\n\n    const scheduled = await rf.posts.schedule({\n      contentType: 'SLIDESHOW',\n      contentId: slideshowId,\n      publishFormat: 'VIDEO',\n      scheduledFor: '2026-09-01T15:00:00.000Z',\n      platforms: [{\n        platform: 'TIKTOK',\n        connectionId: tiktokConnectionId,\n        captionOverride: 'TikTok caption',\n        tiktokPublishMode: 'DIRECT',\n        tiktokPrivacyLevel: 'PUBLIC_TO_EVERYONE',\n        tiktokAllowComment: true,\n        tiktokCommercialContentEnabled: false,\n      }, {\n        platform: 'YOUTUBE',\n        connectionId: youtubeConnectionId,\n        youtubeTitle: 'Launch Short',\n        youtubePrivacyStatus: 'UNLISTED',\n        youtubeMadeForKids: false,\n        youtubeContainsSyntheticMedia: true,\n      }],\n    });\n\nThe CLI accepts simple `platform:connectionId` pairs. Use `--platforms-json`\nwhen you need captions or platform settings.\n",
  "bytes": 9202,
  "sha": "c494c61e7d29c60e128bc2b9530010d08df8b3db9cc401a9631638faca546142",
  "repo_slug": "mateohysa/reelsfarm-mcp",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_mateohysa_reelsfarm_4ea28735/readme"
}