SDK e MCP

FloopFloop SDKs & MCP

FloopFloop include otto SDK ufficiali per diversi linguaggi più un server MCP per agenti AI. Ogni interfaccia punta allo stesso backend /api/v1/*— quindi un progetto creato tramite il Node SDK è lo stesso progetto che un LLM che gira attraverso l'MCP vedrà, byte per byte.

Scegli l'interfaccia giusta per il tuo stack:

• Stai costruendo un'app o un backend? Usa l'SDK per il tuo linguaggio.
• Stai costruendo un agente AI / chatbot? Usa il server @floopfloop/mcp con Claude Desktop, Cursor, Zed, Copilot CLI, o qualsiasi host compatibile con MCP.
• Stai operando dal terminale? Usa il FloopFloop CLI.

Server MCP — per agenti AI

@floopfloop/mcp— server Model Context Protocol. Espone le API FloopFloop come 23 strumenti che qualsiasi host LLM compatibile con MCP può richiamare.

Gli strumenti coprono l'intero ciclo di vita del progetto: create_project, refine_project, upload_from_path(allegati), cancel_project, reactivate_project, wait_for_live, list_secrets / set_secret / remove_secret, list_library_projects / clone_library_project, current_subscription, usage_summary, oltre a controlli di sottodominio e gestione delle chiavi API. Ogni strumento è in sola lettura o contrassegnato con destructiveHintin modo che l'host possa chiedere conferma all'utente prima di modificare lo stato.

Snippet di configurazione per Claude Desktop

{
  "mcpServers": {
    "floopfloop": {
      "command": "npx",
      "args": ["-y", "@floopfloop/mcp"],
      "env": { "FLOOP_API_KEY": "flp_..." }
    }
  }
}

Aggiungi a ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) o %APPDATA%\Claude\claude_desktop_config.json(Windows), riavvia Claude Desktop e chiedi “costruisci un sito FloopFloop per <X>”.

Abbina floop-skills per il playbook

L'MCP espone le capacità; floop-skills include skill markdown in stile Anthropic che spiegano i flussi di lavoro — quando richiamare quale strumento, in quale ordine, con quali argomenti. Installa entrambi per la migliore esperienza con gli agenti:

mkdir -p ~/.claude/skills
git clone https://github.com/FloopFloopAI/floop-skills.git /tmp/floop-skills
cp -r /tmp/floop-skills/skills/* ~/.claude/skills/

Link: npm · GitHub · floop-skills

SDK per linguaggi

Stessa interfaccia su tutti gli otto: client.projects.create(), refine, waitForLive / streaming, secrets, uploads, library, apiKeys, subscriptions.current, usage.summary, subdomains, user.me. Ogni SDK si adatta all'idioma nativo del suo linguaggio (sync + async su Python, Flow su Kotlin, AsyncThrowingStreamsu Swift, ecc.) ma il contratto wire — codici di errore, envelope di risposta, semantica degli stati terminali — è identico.

Node / TypeScript — @floopfloop/sdk

Node 20+. fetch nativo, tipi TypeScript completi,AsyncIteratorper lo streaming. L'SDK canonico; il server MCP lo usa direttamente.

npm install @floopfloop/sdk

import { FloopClient } from "@floopfloop/sdk";

const floop = new FloopClient({ apiKey: process.env.FLOOP_API_KEY! });
const { project } = await floop.projects.create({
  prompt: "a cat-cafe blog with three sample posts",
});
const live = await floop.projects.waitForLive(project.id);
console.log(live.url);

Link: npm · GitHub · cookbook

Python — floopfloop

Python 3.10+. FloopClient sincrono su httpx.Client più AsyncFloopClient asincrono su httpx.AsyncClient — stessi nove accessor di risorse, async for su projects.stream.

pip install floopfloop

from floopfloop import FloopClient

floop = FloopClient(api_key=os.environ["FLOOP_API_KEY"])
created = floop.projects.create(prompt="a cat cafe landing page")
live = floop.projects.wait_for_live(created["project"]["id"])
print(live["url"])

Link: PyPI · GitHub · cookbook

Go — github.com/FloopFloopAI/floop-go-sdk

Go 1.22+. Primo argomento idiomatico context.Context, *Error con campo codice tipizzato, streaming compatibile con i canali.

go get github.com/FloopFloopAI/floop-go-sdk@latest

client := floop.NewClient(os.Getenv("FLOOP_API_KEY"))
res, err := client.Projects.Create(ctx, floop.CreateProjectInput{
    Prompt: "a cat cafe landing page",
})
if err != nil { log.Fatal(err) }
live, err := client.Projects.WaitForLive(ctx, res.Project.ID, nil)
fmt.Println(live.URL)

Link: pkg.go.dev · GitHub · cookbook

Rust — floopfloop

Rust 2021 / 1.75+. Asincrono basato su tokio, pattern builder sul client, enum FloopErrorCode tipizzato, Result<T, FloopError> su ogni metodo.

# Cargo.toml
floopfloop = "0.1.0-alpha.4"

use floopfloop::{Client, CreateProjectInput};

let client = Client::new(std::env::var("FLOOP_API_KEY")?)?;
let res = client.projects().create(CreateProjectInput {
    prompt: "a cat cafe landing page".into(),
    ..Default::default()
}).await?;
let live = client.projects().wait_for_live(&res.project.id, None).await?;
println!("{}", live.url.unwrap_or_default());

Link: crates.io · docs.rs · GitHub · cookbook

Ruby — floopfloop

Ruby 3.0+. Trasporto Net::HTTP, risposte basate su hash (senza wrapper tipizzati opinionati), passaggio di blocchi per lo streaming.

gem install floopfloop

require "floopfloop"

client = FloopFloop::Client.new(api_key: ENV.fetch("FLOOP_API_KEY"))
res = client.projects.create(prompt: "a cat cafe landing page")
live = client.projects.wait_for_live(res["project"]["id"])
puts live["url"]

Link: RubyGems · GitHub · cookbook

PHP — floopfloop/sdk

PHP 8.1+. Trasporto stdlib puro (non serve ext-curl), costruttore compatibile con argomenti nominati, classe eccezione FloopFloop\Error con codice tipizzato.

composer require floopfloop/sdk

$client = new FloopFloop\Client(apiKey: getenv('FLOOP_API_KEY'));
$res = $client->projects()->create(prompt: 'a cat cafe landing page');
$live = $client->projects()->waitForLive($res['project']['id']);
echo $live['url'];

Link: Packagist · GitHub · cookbook

Swift — FloopFloop (SPM)

Swift 5.9+. async/await ovunque, tipi Codable, AsyncThrowingStream per lo streaming. iOS 17+ / macOS 14+ / tvOS 17+ / watchOS 10+ / visionOS 1+. Lato server / desktop oggi; la distribuzione su app mobile richiede un flusso di autenticazione diverso nel backend (roadmap).

// Package.swift
.package(url: "https://github.com/FloopFloopAI/floop-swift-sdk.git", from: "0.1.0-alpha.2")

import FloopFloop

let client = FloopFloop(apiKey: ProcessInfo.processInfo.environment["FLOOP_API_KEY"]!)
let res = try await client.projects.create(.init(prompt: "a cat cafe landing page"))
let live = try await client.projects.waitForLive(res.project.id)
print(live.url ?? "")

Link: Tag SPM · GitHub · cookbook

Kotlin / JVM — floop-kotlin-sdk

Kotlin 2.0+ / JVM 11+. OkHttp + kotlinx-serialization + kotlinx-coroutines. Funzioni suspend ovunque; streaming tramite Flow<StatusEvent> freddo. Distribuzione JitPack (Maven Central in programma).

// build.gradle.kts
repositories {
    maven("https://jitpack.io")
}
dependencies {
    implementation("com.github.FloopFloopAI:floop-kotlin-sdk:0.1.0-alpha.3")
}

import com.floopfloop.sdk.FloopFloop
import com.floopfloop.sdk.resources.CreateProjectInput

val client = FloopFloop(apiKey = System.getenv("FLOOP_API_KEY"))
val res = client.projects.create(CreateProjectInput(prompt = "a cat cafe landing page"))
val live = client.projects.waitForLive(res.project.id)
println(live.url)

Link: JitPack · GitHub · cookbook

Chiavi API

Ogni SDK usa chiavi API programmatiche flp_…per l'autenticazione, distinte dai token di dispositivo che la CLI usa per i login interattivi. L'emissione delle chiavi API richiede il piano Business. Crea una chiave da Account → Chiavi API, salvala nel tuo gestore di segreti / ambiente e passala al costruttore dell'SDK.

Vedi Autenticazione API per il modello completo delle chiavi (scope, limiti di frequenza, pattern di rotazione).

Sorgente & release

Tutti gli otto repo SDK più l'MCP e le skills sono open-source sotto licenza MIT su github.com/FloopFloopAI. Ogni release viene pubblicata nel registro standard del suo linguaggio al push del tag (npm, PyPI, crates.io, RubyGems, Packagist, Go modules, JitPack, tag SPM). CHANGELOG per SDK in ogni repo; il coordinamento delle release cross-SDK è tracciato nel monorepo.