164 lines
4.6 KiB
Markdown
164 lines
4.6 KiB
Markdown
# FF Orbit MCP — VSCode / Claude Code Setup
|
|
|
|
How to set up and run the FlutterFlow Orbit MCP server with Claude Code in VSCode.
|
|
|
|
## 1. Install Dependencies
|
|
|
|
```bash
|
|
cd /Users/alainbagmi/flutterflow-mcp
|
|
npm install
|
|
```
|
|
|
|
## 2. Get FlutterFlow API Token
|
|
|
|
1. Open FlutterFlow web app → Settings → API Token
|
|
2. Copy the token
|
|
|
|
## 3. Configure MCP for Claude Code
|
|
|
|
### Option A: Project-Level Config (Recommended)
|
|
|
|
Add to `.mcp.json` in your project root:
|
|
|
|
```json
|
|
{
|
|
"mcpServers": {
|
|
"ff_orbit_mcp": {
|
|
"command": "npm",
|
|
"args": ["start"],
|
|
"cwd": "/Users/alainbagmi/flutterflow-mcp",
|
|
"env": {
|
|
"FLUTTERFLOW_API_TOKEN": "<your-token>",
|
|
"FLUTTERFLOW_API_MIN_INTERVAL_MS": "1000",
|
|
"ORBIT_POLICY_SAFE_MODE": "guidedWrite"
|
|
}
|
|
}
|
|
}
|
|
}
|
|
```
|
|
|
|
### Option B: Claude Code CLI
|
|
|
|
```bash
|
|
claude mcp add -s project \
|
|
-e FLUTTERFLOW_API_TOKEN=<your-token> \
|
|
-e FLUTTERFLOW_API_MIN_INTERVAL_MS=1000 \
|
|
-e ORBIT_POLICY_SAFE_MODE=guidedWrite \
|
|
ff_orbit_mcp -- npm start
|
|
```
|
|
|
|
### Option C: Global Config
|
|
|
|
Add to `~/.claude/settings.json` under `mcpServers` key (same format as `.mcp.json`).
|
|
|
|
## 4. Verify Connection
|
|
|
|
After restarting Claude Code (or the MCP server), run:
|
|
|
|
```
|
|
orbit({ cmd: "help" })
|
|
orbit({ cmd: "projects.list" })
|
|
```
|
|
|
|
If either fails:
|
|
- Check `FLUTTERFLOW_API_TOKEN` is set and valid
|
|
- Check `cwd` points to `/Users/alainbagmi/flutterflow-mcp`
|
|
- Check `npm start` runs without errors in that directory
|
|
- Check network access to `https://api.flutterflow.io/v2`
|
|
|
|
## 5. First-Time Project Setup
|
|
|
|
```
|
|
# List your FlutterFlow projects
|
|
orbit({ cmd: "projects.list" })
|
|
|
|
# Create a snapshot of the target project
|
|
orbit({ cmd: "snapshots.create", args: { projectId: "<project-id>" } })
|
|
|
|
# Verify snapshot
|
|
orbit({ cmd: "snapshots.info" })
|
|
|
|
# List pages
|
|
orbit({ cmd: "pages.list" })
|
|
```
|
|
|
|
## Environment Variables Reference
|
|
|
|
### Required
|
|
|
|
| Variable | Description |
|
|
|----------|-------------|
|
|
| `FLUTTERFLOW_API_TOKEN` | Your FlutterFlow API bearer token |
|
|
|
|
### Server Configuration
|
|
|
|
| Variable | Default | Description |
|
|
|----------|---------|-------------|
|
|
| `PORT` | 8080 | HTTP server port |
|
|
| `ORBIT_HTTP_ENABLED` | 1 | Set to 0 to disable HTTP health endpoint |
|
|
| `ORBIT_DB_PATH` | `.orbit/orbit.sqlite` | SQLite database location |
|
|
| `ORBIT_SNAPSHOT_STALE_MINUTES` | 30 | Snapshot staleness threshold |
|
|
| `ORBIT_POLICY_FILE` | `orbit.policy.json` | Policy file location |
|
|
| `ORBIT_ALLOW_POLICY_WRITE` | 0 | Set to 1 to enable runtime policy updates |
|
|
|
|
### FlutterFlow API
|
|
|
|
| Variable | Default | Description |
|
|
|----------|---------|-------------|
|
|
| `FLUTTERFLOW_API_BASE_URL` | `https://api.flutterflow.io/v2` | API base URL |
|
|
| `FLUTTERFLOW_API_MIN_INTERVAL_MS` | 1000 | Minimum ms between API calls |
|
|
|
|
### Policy Overrides (Environment)
|
|
|
|
| Variable | Values | Description |
|
|
|----------|--------|-------------|
|
|
| `ORBIT_POLICY_SAFE_MODE` | `readOnly`, `guidedWrite`, `fullWrite` | Write permission level |
|
|
| `ORBIT_POLICY_REQUIRE_MANUAL_APPROVAL` | `true`/`false` | Require manual approval for writes |
|
|
| `ORBIT_POLICY_MAX_FILES_PER_APPLY` | number | Max files in a single apply |
|
|
| `ORBIT_POLICY_MAX_LINES_CHANGED` | number | Max line changes per apply |
|
|
| `ORBIT_POLICY_ALLOW_PROJECTS` | comma-separated | Restrict to specific projects |
|
|
| `ORBIT_POLICY_DENY_FILE_PREFIXES` | comma-separated | Block file paths from edits |
|
|
|
|
## Policy Configuration
|
|
|
|
Default policy in `orbit.policy.json`:
|
|
|
|
```json
|
|
{
|
|
"allowProjects": ["*"],
|
|
"allowFileKeyPrefixes": [],
|
|
"denyFileKeyPrefixes": ["lib/custom_code/", "lib/custom_functions/", "lib/main.dart"],
|
|
"maxFilesPerApply": 200,
|
|
"maxLinesChanged": 10000,
|
|
"requireManualApproval": false,
|
|
"allowPlatformConfigEdits": false,
|
|
"safeMode": "fullWrite"
|
|
}
|
|
```
|
|
|
|
**Safe mode levels:**
|
|
- `readOnly` — No writes allowed, read-only queries only
|
|
- `guidedWrite` — Writes require changeset preview + validate + confirm
|
|
- `fullWrite` — Direct writes with `apply: true` allowed
|
|
|
|
## Troubleshooting
|
|
|
|
### "MCP server not responding"
|
|
- Restart Claude Code / VSCode
|
|
- Check if `npm start` works in `/Users/alainbagmi/flutterflow-mcp`
|
|
- Look for errors in the terminal output
|
|
|
|
### "Invalid token" or authentication errors
|
|
- Regenerate token in FlutterFlow Settings
|
|
- Update `FLUTTERFLOW_API_TOKEN` in `.mcp.json`
|
|
|
|
### Rate limiting (429 errors)
|
|
- Increase `FLUTTERFLOW_API_MIN_INTERVAL_MS` to 2000 or higher
|
|
- Use `snapshots.refreshSlow` instead of `snapshots.refresh`
|
|
- Use `changeset.applySafe` instead of `changeset.apply`
|
|
|
|
### Snapshot data looks incomplete
|
|
- Run `snapshots.refresh` with `mode: "full"`
|
|
- Check `snapshots.info` for `authoritative` status
|
|
- If 429s during refresh, use chunked: `{ mode: "full", fetchStrategy: "file", maxFetch: 5 }`
|