@floopfloop/mcp

Model Context Protocol server for the FloopFloop API — lets Claude Desktop, Cursor, Zed, and any other MCP-aware LLM host build, poll, and refine FloopFloop projects on the user's behalf.

Wraps the official @floopfloop/sdk and exposes a curated subset of its surface as MCP tools.

Tools

| Tool | What it does | |----------------------|---------------------------------------------------| | list_projects | List every project you have access to | | get_project | Fetch a project by id or subdomain | | project_status | Cheap status snapshot — safe to poll | | create_project | Kick off a new build from a natural-language prompt | | refine_project | Send a refinement message to an existing project | | wait_for_live | Block until the project reaches a terminal state | | cancel_project | Stop a queued or in-progress build | | reactivate_project | Resume a cancelled / archived project | | get_conversations | Read a project's message timeline (prompts + replies + deploy markers) | | check_subdomain | Is a given slug available? | | suggest_subdomain | Generate a friendly slug from a prompt | | list_secrets | List secret keys on a project (names only) | | set_secret | Create/overwrite a project secret | | remove_secret | Delete a project secret | | list_library_projects| Browse the public project library | | clone_library_project| Duplicate a library project into the user's account | | usage_summary | Plan limits + current-period credit / build / storage usage | | list_api_keys | List the user's API keys (never returns the raw secret) | | create_api_key | Mint a new API key — raw secret returned ONCE | | remove_api_key | Revoke an API key by id or name | | upload_from_path | Read a local file, presign + upload to S3, return an attachment ref | | whoami | Show the authenticated user | | current_subscription | Plan tier + credit balance (price, billing period, current/rolled-over credits) |

Configuration

Grab an API key: floop keys create mcp-host (via the floop CLI) or the dashboard → Account → API Keys. Business plan required to mint new keys.

The server reads FLOOP_API_KEY from the environment. Optionally override FLOOP_API_URL to point at staging.

Claude Desktop

~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %AppData%\Claude\claude_desktop_config.json (Windows):

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

Restart Claude Desktop; the tools show up under the 🔌 icon.

Cursor

~/.cursor/mcp.json (or Cursor Settings → Tools & Integrations → MCP):

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

Generic MCP host

Any host that speaks the MCP stdio transport can run the server:

FLOOP_API_KEY=flp_... npx -y @floopfloop/mcp

Install

The package is pulled in automatically via npx -y @floopfloop/mcp in the config snippets above. If you prefer a pinned install:

npm install -g @floopfloop/mcp
which floop-mcp

Usage notes

• create_project starts a build right away. Follow up with wait_for_live (blocks) or project_status (poll) to know when it's up.
• wait_for_live defaults to a 10-minute ceiling (bounded by timeoutMs, capped at 30 min). Most builds finish in under two minutes.
• upload_from_path → refine_project is the canonical attachment flow: call upload_from_path with a local file, get back an UploadedAttachment ({key, fileName, fileType, fileSize}), then pass it as attachments: [<that object>] on refine_project. The LLM host's process needs read access to the file path; max 5 MB.
• refine_project codeEditOnly: true runs a 3-step in-place patch instead of a full 6-step rebuild and charges roughly half the credits — use it for copy edits, colour swaps, or typo fixes on a project that's already live. The backend won't promote a code-edit to a full refinement automatically, so prefer plain refine_project when the change actually needs redesign.
• cancel_project → reactivate_project is the abort/redo pattern. cancel_project is destructiveHint: true; hosts should confirm before calling it. reactivate_project triggers a fresh build at the project's most recent prompt.
• set_secret / remove_secret are marked destructiveHint: true — hosts may ask the user to confirm before they run.
• list_secrets only returns names, never values. Secret values cannot be retrieved once written; rotate them by re-setting.
• On failure, tools return an MCP isError content result rather than tearing down the session, so the host displays the error to the user.

Development

git clone https://github.com/FloopFloopAI/floop-mcp.git
cd floop-mcp
npm install
npm run typecheck
npm run build

FLOOP_API_KEY=flp_... node dist/index.js

To smoke-test the stdio handshake without an LLM host:

printf '%s\n' \
  '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2024-11-05","capabilities":{},"clientInfo":{"name":"smoke","version":"0"}}}' \
  '{"jsonrpc":"2.0","method":"notifications/initialized"}' \
  '{"jsonrpc":"2.0","id":2,"method":"tools/list"}' \
  | FLOOP_API_KEY=flp_dummy node dist/index.js 2>/dev/null

Releasing

.github/workflows/release.yml publishes to npm with provenance whenever a tag matching mcp-v* is pushed. One-time setup before the first release:

1. Create an automation npm token on the @floopfloop scope (publishes bypass 2FA by design when tokens are marked automation).
2. Add it as the repo secret NPM_TOKEN:

   gh secret set NPM_TOKEN --repo FloopFloopAI/floop-mcp
   # paste token when prompted — do NOT use --body, which can leak it to
   # shell history.

3. Tag + push:

   npm version 0.1.0-alpha.1 --no-git-tag-version  # if needed
   git tag mcp-v$(node -p "require('./package.json').version")
   git push --follow-tags

The workflow typechecks, builds, runs the stdio smoke test, verifies the tag matches package.json, then publishes and cuts a GitHub Release (prerelease, auto-generated notes).

License

MIT