# yasu89/switch-bot-mcp-server architecture

> Architecture diagram of the GitHub repository yasu89/switch-bot-mcp-server, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-01). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/yasu89/switch-bot-mcp-server
- Repository: https://github.com/yasu89/switch-bot-mcp-server

## Overview

##### Project type and purpose
- This is a standalone microservice (Model Context Protocol or MCP server) written in Go.
- It exposes a set of “tools” over MCP so that an MCP-aware client (e.g., Claude Desktop) can drive SwitchBot devices interactively.

##### File structure
- Top level:
- cmd/switch-bot-mcp-server/main.go → entry point for the MCP server binary
- tools/device_control.go, tools/devices.go → implement individual MCP “tools,” each encapsulating one kind of SwitchBot operation
- Config and dependency files: go.mod, go.sum, .gitignore, editorconfig
- No persistent database—state is fetched on demand from the SwitchBot-provided REST API.

##### README for additional insights
- The server acts as an MCP endpoint that:
- Retrieves device lists (`get_switch_bot_devices`)
- Retrieves device status (`get_switch_bot_device_status`)
- Sends turn-on/turn-off commands (`turn_on_off_device`)
- Requires environment-injected secrets: SWITCH_BOT_TOKEN and SWITCH_BOT_SECRET
- Integrates directly with SwitchBot’s REST API (via SwitchBotAPI library).

##### Components
a. Main components:
- MCP Client (e.g., Claude Desktop)
- SwitchBot MCP Server (the Go binary)
- Tools layer (device discovery, status query, on/off control modules)
- External SwitchBotAPI REST endpoint
- SwitchBot physical devices
b. Relationships and interactions:
1. Client sends an MCP request (e.g., “get devices”).
2. MCP Server routes to the corresponding tool.
3. Tool calls the SwitchBotAPI (HTTP + authentication).
4. API returns JSON response.
5. Tool transforms and returns it via MCP.
c. Architectural patterns and design principles:
- Modular “tools” plugin pattern: each operation is a separate Go module under /tools
- Single‐binary microservice: no database, stateless, relies on environment variables for config
- External integration via HTTP REST
d. Key technologies/libraries:
- Go (golang) for core server and tools
- Model Context Protocol (MCP) for RPC abstraction
- OpenWonderLabs/SwitchBotAPI Go client library
- JSON over HTTP

##### Detailed breakdown to capture all essential elements
- If desired, show the SwitchBotAPI Go library as a sub‐component within the server or tools.
- Error paths (e.g., authentication failures from API).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Client
    Client["MCP-Aware Client\n(e.g., Claude Desktop)"]:::client

    %% Server Core
    ServerCore["MCP Server Core\nenv: SWITCH_BOT_TOKEN, SECRET"]:::server

    %% Tools Layer
    subgraph "Tools Layer"
        direction TB
        Discovery["Device Discovery & Status Tool"]:::tool
        Control["On/Off Control Tool"]:::tool
    end

    %% External Services
    SwitchBotAPI["SwitchBotAPI REST Endpoint"]:::external
    Devices["SwitchBot Physical Devices"]:::device

    %% Project File References
    subgraph "Project Files"
        direction TB
        Modules["go.mod, go.sum"]:::docs
        Readme["README.md"]:::docs
        Gitignore[".gitignore"]:::docs
        Editorconfig[".editorconfig"]:::docs
    end

    %% Flow
    Client -->|"MCP/JSON"| ServerCore
    ServerCore -->|"invoke Discovery"| Discovery
    ServerCore -->|"invoke Control"| Control
    Discovery -->|"HTTP/JSON + token"| SwitchBotAPI
    Control -->|"HTTP/JSON + token"| SwitchBotAPI
    SwitchBotAPI -->|"REST response JSON"| Discovery
    SwitchBotAPI -->|"REST response JSON"| Control
    Discovery -->|"MCP/JSON"| ServerCore
    Control -->|"MCP/JSON"| ServerCore
    ServerCore -->|"MCP/JSON"| Client

    %% External Integration to Devices
    SwitchBotAPI -->|"Wireless Protocol"| Devices
    Devices -->|"Status/ACK"| SwitchBotAPI

    %% Click Events
    click ServerCore "https://github.com/yasu89/switch-bot-mcp-server/blob/main/cmd/switch-bot-mcp-server/main.go"
    click Discovery "https://github.com/yasu89/switch-bot-mcp-server/blob/main/tools/devices.go"
    click Control "https://github.com/yasu89/switch-bot-mcp-server/blob/main/tools/device_control.go"
    click Modules "https://github.com/yasu89/switch-bot-mcp-server/blob/main/go.mod"
    click Modules "https://github.com/yasu89/switch-bot-mcp-server/blob/main/go.sum"
    click Readme "https://github.com/yasu89/switch-bot-mcp-server/blob/main/README.md"
    click Gitignore "https://github.com/yasu89/switch-bot-mcp-server/blob/main/.gitignore"
    click Editorconfig "https://github.com/yasu89/switch-bot-mcp-server/blob/main/.editorconfig"

    %% Styles
    classDef client fill:#AED6F1,stroke:#1F618D,color:#1F618D;
    classDef server fill:#ABEBC6,stroke:#196F3D,color:#196F3D;
    classDef tool fill:#D5F5E3,stroke:#27AE60,color:#27AE60;
    classDef external fill:#FAD7A0,stroke:#D35400,color:#D35400;
    classDef device fill:#D5D8DC,stroke:#566573,color:#566573;
    classDef docs fill:#F2F3F4,stroke:#A6ACAF,color:#566573;
```
