IVR Flow Linter

Deterministic IVR Flow Linter via MCP + ChatGPT Skybridge Widget

A Model Context Protocol (MCP) server that validates IVR flows (JSON) providing a score, error detection (unreachable nodes, dead ends), and suggested fixes. Includes a Skybridge-pattern HTML widget for visualizing results directly in ChatGPT.

Demo Video

Features

• Strict Validations: Unreachable nodes, dead ends, missing fallbacks, undefined variables.

• Best Practices: Warning on long prompts, multiple questions, and irreversible actions without confirmation.

• Idempotency: Consistent results via flow hashing.

• Skybridge Widget: Interactive HTML/JS visualization with zero external dependencies.

• MCP Compatible: Works with both ChatGPT Actions and Claude Desktop.

Architecture

• Server: FastAPI with JSON-RPC 2.0 (/mcp)

• Linter: Pure Python deterministic engine

• Widget: Inline HTML injection (text/html+skybridge)

Local Development

Prerequisites

• Python 3.9+

• git

Setup

# Clone
git clone https://github.com/arebury/ivr-flow-linter.git
cd ivr-flow-linter

# Virtual Environment
python -m venv venv
source venv/bin/activate

# Install
pip install -r requirements.txt

# Run Server
uvicorn src.main:app --host 0.0.0.0 --port 8000 --reload

Visit http://localhost:8000/demo for an interactive simulator.

Validating the Demo

1. Run server: uvicorn src.main:app --host 0.0.0.0 --port 8000 --reload

2. Open http://localhost:8000/demo

3. Select "Invalid: Dead End" from the dropdown.

4. Click Lint & Render.

5. Verify:

   • "Parsed Result" tab shows errors.

   • Widget renders the flow with error indicators.

Deployment (Render)

This project includes a render.yaml for 1-click deployment on Render.

1. Create a new Web Service on Render.

2. Connect your GitHub repository: https://github.com/arebury/ivr-flow-linter.

3. Select "Python 3" runtime.

4. Build Command: pip install -r requirements.txt

5. Start Command: uvicorn src.main:app --host 0.0.0.0 --port $PORT

Connecting to ChatGPT (Apps SDK / MCP)

This server acts as an MCP Server that exposes the lint_flow tool. The tool returns a Skybridge-compatible widget (text/html+skybridge) for rich visualization.

1. Deploy the service to a public URL (e.g., https://your-app.onrender.com).

2. Register the app in the OpenAI Developer Portal (for Apps SDK) using the manifest at /.well-known/ai-plugin.json.

3. Alternatively, for Custom Actions (GPTs):

   • Import configuration from https://your-app.onrender.com/openapi.yaml.

   • Ensure the model knows how to interpret the ui field in the response (Skybridge pattern).

Connecting to Claude (Desktop)

Add the server to your Claude Desktop configuration (claude_desktop_config.json):

Local:

{
  "mcpServers": {
    "ivr-linter": {
      "command": "uvicorn",
      "args": ["src.main:app", "--port", "8000"],
      "cwd": "/absolute/path/to/ivr-flow-linter"
    }
  }
}

Remote (via Stdio Wrapper - Advanced): (Typically Claude Desktop connects to local processes. For remote MCP, use a local bridge or simple local-proxy).

Examples

See /examples directory for 10 sample flows (5 valid, 5 invalid) including:

• valid_basic.json: Simple greeting

• valid_payment.json: Transaction flow

• invalid_unreachable.json: Disconnected nodes

• invalid_dead_end.json: Stuck user path