flowchart TD
    subgraph CLIENTS["AI Engineering Clients (FastMCP stdio)"]
        direction LR
        C1["Google Antigravity CLI / IDE"]
        C2["Claude Desktop"]
        C3["Cursor / VS Code MCP"]
    end

    subgraph PROTOCOL["Protocol & Security Boundary"]
        MCP["FastMCP JSON-RPC 2.0 Server<br/>(scripts/run_mcp_server.py)"]
        SEC{"SecurityGuard<br/>(Fail-Closed)"}
    end

    subgraph ENGINE["Core Industrial Engines (src/)"]
        AST["IEC 61131-3 Pure-Python AST<br/>Lexer, Parser & Anti-Ladder Guard"]
        CFBF["CFBF / OLE2 Engine<br/>.csp / .cpj Binary Containers"]
        SIM["In-Memory OCS Scan Engine<br/>%R, %AI, %AQ, %I, %Q, %M, %S"]
        MODBUS["Modbus Telemetry Bridge<br/>Scaling & Scan List Reconciler"]
        HMI["Native HMI Engine<br/>Screen Bindings & Widget Auditing"]
    end

    subgraph TARGETS["Execution Environments"]
        WIN["Cscape 10.2 GUI Supervisor<br/>(winsta0\\Default | ListBox 372 | Ctrl+F7)"]
        MEM["Deterministic Memory Sandbox<br/>(Cycle Snapshot & Waveforms)"]
        HARDWARE["Physical Hardware: Horner OCS XL4<br/>(Fase P7 Manual Commissioning ONLY)"]
    end

    CLIENTS <==>|"JSON-RPC 2.0 (stdio)"| MCP
    MCP --> SEC
    SEC -->|"Validated Request"| AST
    SEC -->|"Container Synthesis"| CFBF
    SEC -->|"Scan Stepping"| SIM
    SEC -->|"Modbus Scaling"| MODBUS
    SEC -->|"HMI Screen Ops"| HMI

    MCP -.->|"Win32 / UIAutomation"| WIN
    SIM -.->|"Register Memory"| MEM
    SEC x-.-x|"HARDWARE LOCKOUT (COM / USB Blocked)"| HARDWARE

    classDef safe fill:#1e3a5f,stroke:#3b82f6,stroke-width:2px,color:#ffffff;
    classDef warn fill:#4a154b,stroke:#a855f7,stroke-width:2px,color:#ffffff;
    classDef blocked fill:#5c1d1d,stroke:#ef4444,stroke-width:2px,color:#ffffff;
    class CLIENTS,PROTOCOL,ENGINE safe;
    class WIN,MEM warn;
    class HARDWARE blocked;

sequenceDiagram
    autonumber
    participant Agent as AI Coding Assistant (Antigravity / Claude)
    participant Stdio as FastMCP stdio Transport
    participant Server as Horner Cscape MCP Server
    participant Sec as SecurityGuard
    participant AST as Pure-Python ST Validator
    participant CFBF as CFBF OLE2 Inspector (.csp / .cpj)
    participant Win as Live Cscape 10.2 (winsta0\Default)
    participant Sim as In-Memory Scan Runner

    Note over Agent,Server: 1. Code Synthesis & Static Verification
    Agent->>Stdio: cscape_validate_st(code)
    Stdio->>Server: JSON-RPC tools/call
    Server->>AST: Lex, parse & inspect syntax
    AST-->>Server: AST Validated (Zero ladder tokens)
    Server-->>Stdio: {"status": "success", "valid": true}
    Stdio-->>Agent: Verification Passed

    Note over Agent,Server: 2. Binary Container Mutation
    Agent->>Stdio: cscape_new_iec_project(path="TankLevel.csp")
    Stdio->>Server: JSON-RPC tools/call
    Server->>CFBF: Allocate OLE2 sectors, SAT, SSAT & Logic Streams
    CFBF-->>Server: Container Written & Verified
    Server-->>Stdio: {"status": "success", "format": "CFBF_OLE2"}
    Stdio-->>Agent: Project Created

    Note over Agent,Win: 3. In-GUI Compiler Verification
    Agent->>Stdio: cscape_compile(timeout_seconds=60)
    Stdio->>Server: JSON-RPC tools/call
    Server->>Win: Dispatch ID_PROGRAM_ERRORCHECK (Ctrl+F7)
    Win-->>Server: Scrape ListBox 372 output (0 errors, 0 warnings)
    Server-->>Stdio: {"status": "success", "errors": 0, "warnings": 0}
    Stdio-->>Agent: Clean Build Confirmed

    Note over Agent,Sim: 4. Discrete Scan Simulation
    Agent->>Stdio: cscape_simulate_pou(code, inputs, steps=10)
    Stdio->>Server: JSON-RPC tools/call
    Server->>Sim: Execute cyclic scan steps with %S clock pulses
    Sim-->>Server: Register snapshots (%R, %AI, %AQ, %M)
    Server-->>Stdio: {"status": "success", "cycles_executed": 10}
    Stdio-->>Agent: Deterministic Simulation Verified

    Note over Agent,Sec: 5. Physical Download Attempt (Intercepted)
    Agent->>Stdio: cscape_download_firmware(port="COM1")
    Stdio->>Server: JSON-RPC tools/call
    Server->>Sec: Intercept download attempt
    Sec-->>Server: HardwareLockoutError: Physical port access prohibited
    Server-->>Stdio: {"status": "blocked", "error_code": "HARDWARE_PORT_BLOCKED"}
    Stdio-->>Agent: Action Refused Fail-Closed

# 1. Clone repository
git clone https://github.com/armando-token/horner-cscape-mcp.git C:\HornerAI\horner-cscape-mcp
cd C:\HornerAI\horner-cscape-mcp

# 2. Create and activate virtual environment
python -m venv .venv
.\.venv\Scripts\Activate.ps1

# 3. Install package in editable development mode
pip install -e .
pip install pytest pydantic fastmcp psutil

# Run the FastMCP server over stdio transport
.\.venv\Scripts\python.exe scripts\run_mcp_server.py

# Inspect server version
.\.venv\Scripts\python.exe scripts\run_mcp_server.py --version

# Execute security lockout and fail-closed test suite
.\.venv\Scripts\python.exe -m pytest tests/test_security.py -v

# Run complete regression test suite
.\.venv\Scripts\pytest.exe -q

{
  "mcpServers": {
    "horner-cscape": {
      "command": "C:/HornerAI/horner-cscape-mcp/.venv/Scripts/python.exe",
      "args": [
        "C:/HornerAI/horner-cscape-mcp/scripts/run_mcp_server.py"
      ],
      "env": {
        "PYTHONUNBUFFERED": "1"
      }
    }
  }
}

{
  "mcpServers": {
    "horner-cscape": {
      "command": "C:\\HornerAI\\horner-cscape-mcp\\.venv\\Scripts\\python.exe",
      "args": [
        "C:\\HornerAI\\horner-cscape-mcp\\scripts\\run_mcp_server.py"
      ],
      "env": {
        "PYTHONUNBUFFERED": "1",
        "CSCAPE_BIN_PATH": "C:\\Program Files (x86)\\Horner APG\\Cscape\\Cscape.exe"
      }
    }
  }
}

{
  "mcpServers": {
    "horner-cscape": {
      "command": "C:\\HornerAI\\horner-cscape-mcp\\.venv\\Scripts\\python.exe",
      "args": [
        "C:\\HornerAI\\horner-cscape-mcp\\scripts\\run_mcp_server.py"
      ],
      "env": {
        "PYTHONUNBUFFERED": "1"
      }
    }
  }
}

horner-cscape-mcp/
├── MANUAL_DE_INGENIERIA_Y_HANDOFF_PROYECTO.md # Master engineering manual & technical handoff
├── README.md                            # Primary project presentation & architecture guide
├── CONTRIBUTING.md                      # Contribution guidelines & safety rules
├── CODE_OF_CONDUCT.md                   # Industrial engineering code of conduct
├── LICENSE                              # MIT License
├── pyproject.toml                       # Python package configuration & dependencies
│
├── src/                                 # CORE SOURCE CODE
│   ├── automation/                      # Win32 / UIAutomation Cscape 10.2 driver
│   │   ├── cscape_win32.py              # Win32 messaging, HWND control & pane scraping
│   │   └── supervisor.py                # Desktop watchdog & modal dialog sweeper
│   ├── cscape/                          # Cscape internal state & Modbus bridging
│   ├── iec/ & iec61131/                 # IEC 61131-3 pure-Python AST lexer & parser
│   ├── mcp/                             # FastMCP JSON-RPC 2.0 server implementation
│   │   ├── server.py                    # 43 registered MCP tools & resource routes
│   │   └── schemas.py                   # Pydantic input/output schemas (39+ models)
│   ├── parser/                          # CFBF / OLE2 binary engine (.csp / .cpj)
│   ├── security/                        # Fail-closed security guard & port interceptor
│   │   └── guard.py                     # Physical COM/USB port and flash blockers
│   └── simulation/                      # Deterministic in-memory OCS scan engine
│
├── tests/                               # AUTOMATED TEST SUITE (227+ passing)
│   ├── test_security.py                 # Fail-closed hardware ban & port isolation
│   ├── test_ast.py                      # Pure Structured Text AST verification
│   ├── test_cfbf.py                     # CFBF OLE2 stream read/write verification
│   └── ...                              # Integration, stress & closed-loop tests
│
├── scripts/                             # ENTRYPOINT & SUPERVISION SCRIPTS
│   ├── run_mcp_server.py                # FastMCP stdio server entrypoint
│   └── cscape_supervisor.py             # Dedicated Win32 GUI watchdog launcher
│
├── docs/                                # DETAILED TECHNICAL SPECIFICATIONS
│   ├── MANUAL_DE_INGENIERIA_Y_HANDOFF_PROYECTO.md # Engineering manual mirror
│   ├── mcp_server_reference.md          # Complete API tool reference & schemas
│   ├── HOW_TO_TEST_MCP.md               # Local verification instructions
│   ├── safety_and_security.md           # Security architecture specification
│   ├── cscape_save_failed_diagnosis.md  # Sharing violation forensic analysis
│   ├── st_to_ld_conversion_blocked.md   # Architectural boundary documentation
│   ├── HOW_TO_TEST_PHYSICAL_PLC.md      # Phase P7 manual hardware loading guide
│   └── CORE_08_09_10_RUNTIME_GAPS_AND_ROADMAP.md # Hardware commissioning roadmap
│
└── quarantine/                          # ISOLATED LEGACY ARTIFACTS
    └── straton_k5_legacy/               # Quarantined Copa-Data Straton K5 files