# 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 }`