┌─────────────────────────────────────────────────────────┐
│  MCP Client  (Claude Desktop / VS Code / Codex)         │
└────────────────────┬────────────────────────────────────┘
                     │ JSON-RPC over stdio
┌────────────────────▼────────────────────────────────────┐
│            MCP Server  (Node.js / TypeScript)            │
│                                                         │
│  ┌──────────────────┐  ┌──────────────────────────────┐ │
│  │ WindowsDesktop   │  │  LocalMailbox Bridge          │ │
│  │ Bridge           │  │                               │ │
│  │ PowerShell COM   │  │  inbox/  ←── requests (.json) │ │
│  │ (fallback only)  │  │  outbox/ ──→ responses (.json)│ │
│  └──────────────────┘  └──────────────┬───────────────┘ │
│  ┌──────────────────────────────────┐  │                 │
│  │ LocalHelper Backend (optional)   │  │                 │
│  │ PowerShell — render / playlist   │  │                 │
│  └──────────────────────────────────┘  │                 │
└────────────────────────────────────────┼────────────────┘
                                         │ file IPC
┌────────────────────────────────────────▼────────────────┐
│         FL Studio  (Python MIDI script companion)        │
│         FLMcpBridge.py — runs inside FL Studio process   │
│         Reads inbox → executes FL API → writes outbox    │
└─────────────────────────────────────────────────────────┘

flowchart TD
    Client([MCP Client]) -->|stdio JSON-RPC| Server[MCP Server]

    Server --> D{FL Studio running?}
    D -- No --> ERR1[Error: FL_NOT_RUNNING]

    D -- Yes --> C{Companion active?\nheartbeat fresh}

    C -- Yes --> MB[LocalMailbox Bridge\ninbox → outbox file IPC]
    MB -->|timeout| CACHE[Return cached state\nfrom last heartbeat]

    C -- "No, desktop-capable cmd" --> DB[WindowsDesktop Bridge\nPowerShell SendKeys]
    DB --> FL[FL Studio process]

    C -- "No, mailbox-only cmd" --> ERR2[Error: COMPANION_NOT_RUNNING]

    MB --> HELPER{Helper configured?}
    HELPER -- Yes --> HP[LocalHelper Backend\nPowerShell render / playlist]
    HELPER -- No --> MB2[Mailbox result only]
    HP --> ENRICH[Enriched response]

sequenceDiagram
    participant S as MCP Server
    participant FS as File System
    participant C as FL Companion

    S->>FS: write inbox/<uuid>.json (atomic)
    loop OnIdle / OnMidiIn callback
        C->>FS: scan inbox/ for .json files
        FS-->>C: inbox/<uuid>.json found
        C->>C: execute FL Studio API
        C->>FS: write outbox/<uuid>.json (atomic)
    end
    loop poll every 150 ms
        S->>FS: check outbox/<uuid>.json
        FS-->>S: response found
    end
    S->>FS: delete outbox/<uuid>.json
    S-->>S: return response to client

git clone https://github.com/your-org/mcp-flstudio
cd mcp-flstudio
npm install
npm run build

node dist/cli/index.js help

mcp-flstudio help

npm run deploy:companion

node dist/cli/index.js deploy-companion

Documents\Image-Line\FL Studio\Settings\Hardware\FLMcpBridge\device_FLMcpBridge.py
Documents\Image-Line\FL Studio\Settings\Hardware\FLMcpBridge\FLMcpBridge.py

Documents\Image-Line\FL Studio\Settings\Hardware\FLMcpBridge\runtime

Documents\Image-Line\FL Studio\Settings\Hardware\FLMcpBridge\runtime\state.json

{
  "mcpServers": {
    "flstudio-local": {
      "command": "node",
      "args": ["C:/path/to/mcp-flstudio/dist/cli/index.js", "serve"]
    }
  }
}

{
  "servers": {
    "flstudio-local": {
      "type": "stdio",
      "command": "node",
      "args": ["${workspaceFolder}/dist/cli/index.js", "serve"]
    }
  }
}

fl_get_status → health field

# Print the resolved configuration
npm run debug:config
# or
node dist/cli/index.js debug-config

# Inspect current bridge state (companion heartbeat, pending requests)
npm run debug:state
# or
node dist/cli/index.js debug-state

# Print canonical catalog coverage vs live registry
npm run catalog:coverage

# Verify the companion end-to-end
npm run verify

# Generate the full tool-by-tool checklist
npm run functional:checklist

# Run the scripted smoke scorecard and publish a Markdown report
npm run evaluate:functional

# Run tests
npm test

# Run tests with coverage
npm run test:coverage

# Tail the live log for the resolved bridgeDir (PowerShell)
$bridgeDir = (node dist/cli/index.js debug-config | ConvertFrom-Json).bridgeDir
Get-Content (Join-Path $bridgeDir 'bridge.log') -Wait -Tail 40

npm run functional:checklist
npm run evaluate:functional
npm run docs:catalog
npm run docs:status

npm run dev           # Run from TypeScript source (tsx, no build needed)
npm run build         # Compile TypeScript → dist/
npm run check         # Type-check only (no emit)
npm run typecheck     # Type-check gate used by CI/prepack
npm run lint          # ESLint
npm run lint:fix      # ESLint with auto-fix
npm run format        # Prettier
npm run functional:checklist
npm run evaluate:functional
npm test              # Vitest
npm run test:coverage # With coverage report
npm run ci:check      # build + typecheck + lint + test + npm pack --dry-run

mcp-flstudio/
├── src/
│   ├── index.ts               # MCP server entry point — tool/resource registration
│   ├── config.ts              # Environment variable parsing
│   ├── configValidation.ts    # Config validation with detailed errors
│   ├── logger.ts              # Structured JSON logger (stderr + file)
│   ├── errors.ts              # BridgeRuntimeError + toBridgeError()
│   ├── types.ts               # Shared TypeScript types
│   ├── env.ts                 # Optional .env loading
│   ├── publicApi.ts           # snake_case public payload normalization
│   ├── server.ts              # MCP bootstrap
│   ├── serverRuntime.ts       # Shared runtime helpers / tool execution
│   ├── bridge/
│   │   ├── flStudioBridge.ts      # Orchestrator — routes across the three tiers
│   │   ├── localMailboxBridge.ts  # File-based IPC (inbox/outbox)
│   │   ├── windowsDesktopBridge.ts # PowerShell COM fallback
│   │   └── helperBackend.ts       # Optional PowerShell helper (render, playlist)
│   ├── catalog/
│   │   └── loadCatalog.ts     # YAML catalog loader + coverage report builder
│   ├── registry/
│   │   ├── definitions.ts     # Canonical tool definitions by domain
│   │   └── register.ts        # MCP registration factory
│   ├── services/
│   │   └── sessionState.ts    # Audit log, checkpoints, transactions
│   ├── cli/
│   │   └── index.ts           # Public CLI: serve / debug / verify / deploy
│   └── __tests__/
│       ├── configValidation.test.ts
│       ├── env.test.ts
│       ├── publicApi.test.ts
│       ├── catalog.test.ts
│       ├── packageManifest.test.ts
│       ├── logger.test.ts
│       └── sessionState.test.ts
├── companion/
│   └── fl_studio/
│       ├── device_FLMcpBridge.py   # Publishable bootstrap, no hardcoded repo path
│       └── FLMcpBridge.py          # FL Studio MIDI script companion runtime
├── config/                    # Client configuration examples
├── .github/workflows/ci.yml   # Required build/test/package gates
├── dist/                      # Compiled output (git-ignored)
└── tools_scoop_mvp_v3         # YAML tool catalog (V3)