# chasebank2017/magic-mcp architecture

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

- Interactive diagram: https://gitdiagram.com/chasebank2017/magic-mcp
- Repository: https://github.com/chasebank2017/magic-mcp

## Overview

##### Project Type & Purpose
- This is a Node.js/TypeScript-based command-line tool that functions as an AI Agent to generate UI components from natural language descriptions. The tool integrates directly with popular IDEs (such as Cursor, Windsurf, and VSCode with Cline) and uses external services (for instance, SVGL for logos and the 21st.dev component library) to build, fetch, or search for UI components.
- Its purpose is to streamline the UI development process by leveraging AI, making it easy for developers to create modern, customizable components on the fly.

##### Identifying the Main Components
- CLI/IDE Integration: The project is meant to be installed and invoked using npx commands via @smithery/cli. It must interact with various IDE configurations detailed in the README (like Cursor, Windsurf, and VSCode + Cline configurations).
- Core Engine (src/index.ts): This serves as the entry point, orchestrating the overall flow by calling into various tool modules.
- Tool Modules (src/tools):
- create-ui.ts – Likely responsible for generating the UI component based on the provided natural language input.
- fetch-ui.ts – Handles retrieval of UI components or assets.
- logo-search.ts – Deals with searching for logos or brand assets, possibly integrating with SVGL.
- Utility Functions (src/utils):
- base-tool.ts – General abstractions or base functionalities shared by the various tools.
- http-client.ts – Handles HTTP requests, probably for interactions with external APIs or services (such as the 21st.dev component library or SVGL).
- Supporting Configuration Files:
- Dockerfile – Indicates that the project can be containerized, suggesting deployment or isolated runtime scenarios.
- smithery.yaml – Likely a configuration file for @smithery/cli, used to manage installation or runtime options.
- Other configuration files like package.json, tsconfig.json, .gitignore, and llms-install.md, which drive build, dependency management, and development setup.

##### Relationships & Data Flow
- From the core engine, branch out to each of the tool modules—“Create UI”, “Fetch UI”, and “Logo Search”—indicating that the engine routes the command to the appropriate module depending on the user’s request.
- Each tool module interacts with utility components (especially the HTTP Client) when external communication is necessary (such as calling the API for component generation or fetching assets).
- Additionally, indicate that configuration files (like smithery.yaml) and the Dockerfile play roles in deployment or runtime configuration.

##### Architectural Patterns & Design Principles
- Modularity: The separation into src/index.ts (orchestrator), tools (specific actions), and utils (shared logic) reflects a modular design where each part is responsible for a clear, distinct task.
- Integration Pattern: Emphasis on CLI/IDE integration with external services through HTTP and configuration files ensures a loosely coupled design.
- Type Safety: The use of TypeScript (tsconfig.json and type-safe code) is a key design principle that underpins the development approach.

## Diagram (Mermaid)

```mermaid
flowchart TD
    CLIIntegration["CLI/IDE Integration"]:::integration
    subgraph "Configuration & Deployment"
        CLIConfig["CLI/IDE Config"]:::config
        Containerization["Containerization/Deployment"]:::config
    end
    CoreEngine["Core Engine (index.ts)"]:::core
    subgraph "Tool Modules"
        CreateUI["Tool: Create UI"]:::tools
        FetchUI["Tool: Fetch UI"]:::tools
        LogoSearch["Tool: Logo Search"]:::tools
    end
    subgraph "Utilities"
        BaseTool["Utility: Base Tool"]:::utilities
        HTTPClient["Utility: HTTP Client"]:::utilities
    end
    ExternalServices["External Services"]:::external

    %% Data/Command Flow
    CLIIntegration --> CLIConfig
    CLIIntegration --> Containerization
    CLIIntegration --> CoreEngine
    CoreEngine --> CreateUI
    CoreEngine --> FetchUI
    CoreEngine --> LogoSearch
    CreateUI --> BaseTool
    CreateUI --> HTTPClient
    FetchUI --> BaseTool
    FetchUI --> HTTPClient
    LogoSearch --> BaseTool
    LogoSearch --> HTTPClient
    HTTPClient --> ExternalServices

    %% Click Events
    click CLIIntegration "https://github.com/chasebank2017/magic-mcp/blob/main/smithery.yaml"
    click CoreEngine "https://github.com/chasebank2017/magic-mcp/blob/main/src/index.ts"
    click CreateUI "https://github.com/chasebank2017/magic-mcp/blob/main/src/tools/create-ui.ts"
    click FetchUI "https://github.com/chasebank2017/magic-mcp/blob/main/src/tools/fetch-ui.ts"
    click LogoSearch "https://github.com/chasebank2017/magic-mcp/blob/main/src/tools/logo-search.ts"
    click BaseTool "https://github.com/chasebank2017/magic-mcp/blob/main/src/utils/base-tool.ts"
    click HTTPClient "https://github.com/chasebank2017/magic-mcp/blob/main/src/utils/http-client.ts"
    click Containerization "https://github.com/chasebank2017/magic-mcp/tree/main/Dockerfile"

    %% Styles
    classDef integration fill:#D1E8FF,stroke:#000,stroke-width:1px;
    classDef core fill:#A9DFBF,stroke:#000,stroke-width:1px;
    classDef tools fill:#F9E79F,stroke:#000,stroke-width:1px;
    classDef utilities fill:#F5B7B1,stroke:#000,stroke-width:1px;
    classDef external fill:#D2B4DE,stroke:#000,stroke-width:1px;
    classDef config fill:#FAD7A0,stroke:#000,stroke-width:1px;
```
