mcp_diagram.txt

+-------------------------------------------------------------------+
|                   AI-Enabled Hardware Control                     |
+-------------------------------------------------------------------+

User Input (Natural Language)
       |
       | "scan for Bluetooth devices"
       v
+--------------------------------------------------------------------+
|                      AI Provider Layer                             |
|  +--------------+  +--------------+  +--------------+              |
|  | Claude Code  |  |Claude Desktop|  |   ChatGPT    |              |
|  |     CLI      |  |              |  |  (with MCP)  |              |
|  +------+-------+  +------+-------+  +------+-------+              |
|         |                 |                 |                      |
|         +----  -----------+--------  -------+                      |
|                           |                                        |
|  All providers use MCP Protocol (JSON-RPC over stdio/SSE)          |
|  stdio = Standard I/O for CLI tools (pipes)                        |
|  SSE = Server-Sent Events for web clients (HTTP streaming)         |
+----------------------------+---------------------------------------+
                             |
                             | MCP Protocol Messages:
                             | - tools/list (discover available tools)
                             | - tools/call (invoke AT command tool)
                             | - Response with parsed results
                             v
+---------------------------------------------------------------------+
|   MCP Server (Python)                                               |
|                                                                     |
|  +--------------------------------------------------------------+   |
|  | MCP Protocol Handler                                         |   |
|  | - Listens for tool requests from AI                          |   |
|  | - Exposes tools: scan_ble, connect_ble, advertise, etc.     |   |
|  | - Returns results in JSON format                             |   |
|  +--------------------------------------------------------------+   |
|                           |                                         |
|  +--------------------------------------------------------------+   |
|  | AT Command Translator                                        |   |
|  | - Converts MCP tool calls to AT commands                     |   |
|  | - Example: scan_ble() -> "AT+SCAN\r\n"                       |   |
|  +--------------------------------------------------------------+   |
|                           |                                         |
|  +--------------------------------------------------------------+   |
|  | Serial Response Parser                                       |   |
|  | - Parses raw serial output from nRF52                        |   |
|  | - Converts to structured JSON for AI                         |   |
|  +--------------------------------------------------------------+   |
+---------------------------------------------------------------------+
       |
       | Serial/USB
       v
+----------------------+
|   nRF52 Hardware     |
|   (Nordic DevKit)    |
|                      |
|  - Zephyr RTOS       |
|  - AT Command Parser |
|  - BLE Stack         |
|    * Scan            |
|    * Advertise       |
|    * Connect         |
|  - Heart Rate Service|
+----------------------+
       |
       | Bluetooth LE
       v
+----------------------+
|  Other BLE Devices   |
|                      |
|  - Heart rate sensor |
|  - Other peripherals |
+----------------------+


Data Flow:
==========

1. User -> AI: Natural language request
   "scan for Bluetooth devices"

2. AI -> MCP Server: MCP Protocol (JSON-RPC)
   Request: {"method": "tools/call", "params": {"name": "scan_ble"}}

3. MCP Server -> MCP Server: Translate to AT command
   scan_ble() -> "AT+SCAN\r\n"

4. MCP Server -> nRF52: Serial command over USB
   Sends: "AT+SCAN\r\n"

5. nRF52 -> BLE Devices: Bluetooth communication
   Performs BLE scan

6. BLE Devices -> nRF52: Response data
   Scan results received

7. nRF52 -> MCP Server: Serial response (raw text)
   Returns: "+SCAN: Device=HeartRate,RSSI=-45\r\nOK\r\n"

8. MCP Server -> MCP Server: Parse serial response
   Converts to JSON: {"device": "HeartRate", "rssi": -45}

9. MCP Server -> AI: MCP Protocol response
   Response: {"result": [{"device": "HeartRate", "rssi": -45}]}

10. AI -> User: Natural language response
    "I found 1 device: Heart Rate Monitor (signal: -45dBm)"


Example Interaction (works with any AI provider):
==================================================

User:     "Find nearby Bluetooth devices"
          |
          v
AI:       Claude Code CLI / Claude Desktop / ChatGPT
          Sends "AT+SCAN" command via MCP
          |
          v
MCP:      Forwards to nRF52 over serial port
          |
          v
nRF52:    Performs BLE scan, returns results:
          "Device: Heart Rate Monitor, RSSI: -45dBm"
          |
          v
MCP:      Parses serial response
          |
          v
AI:       "I found 1 device: Heart Rate Monitor (signal strength: -45dBm)"
          |
          v
User:     Receives natural language response


AI Provider Comparison:
========================

+-----------------+----------------+------------------------------+
|   AI Provider   |  MCP Support   |         Use Case             |
+-----------------+----------------+------------------------------+
| Claude Code CLI |  Native        | Development, automation      |
| Claude Desktop  |  Native        | Desktop app, visual UI       |
| ChatGPT         |  Via plugin    | Web interface, accessibility |
+-----------------+----------------+------------------------------+

Key Benefit: The MCP server acts as a universal bridge, allowing ANY
MCP-compatible AI provider to control the same hardware using the same
natural language interface.