# noboru-i/nature-remo-mcp-server architecture

> Architecture diagram of the GitHub repository noboru-i/nature-remo-mcp-server, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-04-11). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/noboru-i/nature-remo-mcp-server
- Repository: https://github.com/noboru-i/nature-remo-mcp-server

## Overview

##### Main Components
- Entry Point (index.ts): Acts as the central server interface that receives MCP requests and routes them to the appropriate modules.
- Operations Modules (located in the "operations" folder): These files (appliances.ts, appliances_aircon_settings.ts, appliances_tv.ts, devices.ts) encapsulate distinct functionalities for interacting with Nature Remo devices. For example, listing devices or operating specific appliances.
- Common Utilities (inside the "common" folder): Contains shared code for handling errors, making HTTP requests, and managing versioning. These modules support the operations and central server functionality.
- External Dependency – Nature Remo API: This is an external system with which the MCP server communicates. It requires an ACCESS_TOKEN, which is provided via environment variables as seen in the README configuration.

##### Out the Relationships and Data Flow
- Optionally, show the configuration/environment (like the ACCESS_TOKEN) as a configuration block that feeds into the MCP server and operations.

##### Architectural Patterns and Design Principles
- Separation of Concerns/Modularity: Emphasize the clear separation between the central server (index.ts), operations that encapsulate discrete commands, and common utilities. This modular design simplifies maintenance and testing.
- External Integration: Clearly indicate the integration with Nature Remo’s external API.
- Scalability: By structuring operations as separate modules, additional features can be added with minimal changes to the core architecture.
- Use of Environment Variables: Document the injection of the ACCESS_TOKEN which is critical for authentication with the external API.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% MCP Clients and Configuration
    client["MCP Clients (VS Code, Claude Desktop)"]:::client
    config["Configuration: ACCESS_TOKEN"]:::config

    %% Core Server
    server["MCP Server (index.ts)"]:::core

    %% Operations Modules
    opDevices["Operations: List Devices"]:::ops
    opAppliances["Operations: List Appliances"]:::ops
    opTV["Operations: Operate TV"]:::ops
    opAircon["Operations: Operate Aircon"]:::ops

    %% Common Utilities Subgraph
    subgraph "Common Utilities"
        commonErr["Error Handling"]:::common
        commonReq["HTTP Request Module"]:::common
        commonVer["Versioning"]:::common
    end

    %% External Dependency
    external["Nature Remo API (External)"]:::external

    %% Automated Deployment/Release
    automation["GitHub Workflows (Automated Deployment/Release)"]:::automation

    %% Connections
    client -->|"sends MCP request"| server
    config ---|"provides token"| server

    server -->|"invokes"| opDevices
    server -->|"invokes"| opAppliances
    server -->|"invokes"| opTV
    server -->|"invokes"| opAircon

    opDevices -->|"calls"| commonReq
    opAppliances -->|"calls"| commonReq
    opTV -->|"calls"| commonReq
    opAircon -->|"calls"| commonReq

    commonReq -->|"external API call"| external

    %% Additional dependency on error handling and versioning (for clarity)
    opDevices ---|"uses"| commonErr
    opDevices ---|"uses"| commonVer
    opAppliances ---|"uses"| commonErr
    opAppliances ---|"uses"| commonVer
    opTV ---|"uses"| commonErr
    opTV ---|"uses"| commonVer
    opAircon ---|"uses"| commonErr
    opAircon ---|"uses"| commonVer

    %% Automated Deployment links
    automation ---|"CI/CD process"| server

    %% Click Events
    click server "https://github.com/noboru-i/nature-remo-mcp-server/blob/main/index.ts"
    click opDevices "https://github.com/noboru-i/nature-remo-mcp-server/blob/main/operations/devices.ts"
    click opAppliances "https://github.com/noboru-i/nature-remo-mcp-server/blob/main/operations/appliances.ts"
    click opTV "https://github.com/noboru-i/nature-remo-mcp-server/blob/main/operations/appliances_tv.ts"
    click opAircon "https://github.com/noboru-i/nature-remo-mcp-server/blob/main/operations/appliances_aircon_settings.ts"
    click commonErr "https://github.com/noboru-i/nature-remo-mcp-server/blob/main/common/errors.ts"
    click commonReq "https://github.com/noboru-i/nature-remo-mcp-server/blob/main/common/request.ts"
    click commonVer "https://github.com/noboru-i/nature-remo-mcp-server/blob/main/common/version.ts"
    click automation "https://github.com/noboru-i/nature-remo-mcp-server/blob/main/.github/workflows/release.yml"

    %% Styles
    classDef core fill:#FAD7A0,stroke:#D35400,stroke-width:2px;
    classDef ops fill:#AED6F1,stroke:#2471A3,stroke-width:2px;
    classDef common fill:#D5F5E3,stroke:#229954,stroke-width:2px,stroke-dasharray: 5 5;
    classDef external fill:#F9E79F,stroke:#B7950B,stroke-width:2px,stroke-dasharray: 3 3;
    classDef client fill:#E8DAEF,stroke:#8E44AD,stroke-width:2px;
    classDef config fill:#FCF3CF,stroke:#B9770E,stroke-width:2px;
    classDef automation fill:#D6EAF8,stroke:#2874A6,stroke-width:2px,stroke-dasharray: 2 2;
```
