# jpisnice/shadcn-ui-mcp-server architecture

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

- Interactive diagram: https://gitdiagram.com/jpisnice/shadcn-ui-mcp-server
- Repository: https://github.com/jpisnice/shadcn-ui-mcp-server

## Overview

##### Project type and purpose
- This is a full-stack CLI-based MCP (Model Context Protocol) server written in TypeScript/Node.js.
- It exposes a suite of “tools” over the MCP JSON-RPC interface, letting AI-powered editors and IDEs (VS Code, Claude Desktop, Continue.dev, Cursor) query and fetch shadcn/ui v4 component source, demos, metadata, blocks, and repository structure via the GitHub API.

##### File structure
- Top-level:
- package.json / tsconfig.json → Node.js/TypeScript CLI project
- src/index.ts → entrypoint for “npx @jpisnice/shadcn-ui-mcp-server”
- src/handler.ts → request dispatcher binding MCP messages to tool handlers
- src/tools/… → domain logic organized into “blocks”, “components”, “repository” subdirectories
- src/utils/… → infrastructure helpers (API client, caching, circuit breaker, logging, validation)
- src/prompts.ts, src/resource-templates.ts → templates for constructing responses
- Helpers: .github/workflows, docs/, examples.sh, test-package.sh for CI, docs and examples.

##### README for architecture insights
- Describes key features (component source, demos, blocks, metadata, directory browsing)
- Lists provided tools and how they map to commands (get_component, list_blocks, get_directory_structure, etc.)
- Calls out GitHub API integration with caching and rate-limit handling

##### Main components
a. Clients
- Editor/IDE Extensions (VS Code Continue, Claude, Cursor, etc.)
- CLI wrapper (“npx @jpisnice/shadcn-ui-mcp-server”)
b. MCP Server Process
- Entrypoint (index.ts) — parses CLI args, configures GitHub token, starts MCP server over STDIO
- Handler (handler.ts) — routes incoming MCP JSON-RPC requests to the appropriate tool
- Tool Registry (src/tools/index.ts) — enumerates domain tools
- Domain Tools
– Components: get_component, list_components, get_component_demo, get_component_metadata
– Blocks: get_block, list_blocks
– Repository: get_directory_structure
- Resource Layer (prompts.ts, resource-templates.ts, resources.ts) — transforms raw data into templated responses
- Schemas (src/schemas) — type definitions for components/blocks
c. Infrastructure & Integrations
- Utilities (src/utils)
– api.ts & axios.ts — HTTP client to GitHub API
– cache.ts — in-memory or file caching layer
– circuit-breaker.ts — retry/backoff on API errors
– logger.ts — structured logging to console or file (mcp-server.log)
– validation.ts — input/output validation
- External Services
– GitHub REST API (rate-limited, authenticated)
d. Configuration & CI
- GitHub Actions workflows (.github/workflows)
- Documentation and examples (docs/, examples.sh)

##### Relationships and interactions
- Editor/IDE spawns the CLI via “npx …”
- CLI initializes the MCP server over STDIO
- Incoming JSON-RPC requests → Handler → Tool Registry → Specific Tool Function
- Tool Function → calls GitHub API via axios (through cache + circuit-breaker) → raw JSON
- Logger records each step; cache persists frequent GitHub lookups; circuit-breaker prevents API overuse

##### Architectural patterns and principles
- Layered architecture: Presentation (CLI/MCP), Application (Handler/Registry), Domain (Tools), Infrastructure (Utilities), Integration (GitHub)
- Separation of concerns: each tool has its own folder and well-defined interface
- Resiliency patterns: caching, circuit breaker for external API calls
- Template/Strategy pattern: resource-templates for uniform responses
- Plugin-style tool registration: dynamic registry in src/tools/index.ts

##### Technologies, frameworks, libraries
- Node.js, TypeScript, npx
- MCP JSON-RPC protocol (Model Context Protocol)
- axios (HTTP client)
- In-memory/file cache, circuit breaker implementation
- GitHub REST API
- GitHub Actions for CI

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Clients & Entry
    subgraph "Clients & Entry"
        IDE["Editor/IDE Extensions"]:::clients
        CLI["CLI Entrypoint<br/>index.ts"]:::clients
    end

    IDE -->|spawn| CLI

    click CLI "https://github.com/jpisnice/shadcn-ui-mcp-server/blob/master/src/index.ts"

    %% Core MCP Server
    subgraph "MCP Server Core"
        HANDLER["Request Dispatcher<br/>handler.ts"]:::core
        REGISTRY["Tool Registry<br/>index.ts"]:::core

        subgraph "Domain Tools"
            subgraph "Components"
                GC["get_component<br/>get-component.ts"]:::core
                LC["list_components<br/>list-components.ts"]:::core
                GD["get_component_demo<br/>get-component-demo.ts"]:::core
                GM["get_component_metadata<br/>get-component-metadata.ts"]:::core
            end
            subgraph "Blocks"
                GB["get_block<br/>get-block.ts"]:::core
                LB["list_blocks<br/>list-blocks.ts"]:::core
            end
            subgraph "Repository"
                GDSTR["get_directory_structure<br/>get-directory-structure.ts"]:::core
            end
        end

        subgraph "Resource Layer"
            PROMPTS["Prompt Templates<br/>prompts.ts"]:::core
            RESP_TEMPL["Response Templates<br/>resource-templates.ts"]:::core
            RESOURCES["Resource Transforms<br/>resources.ts"]:::core
        end

        SCHEMA["Component Schema<br/>component.ts"]:::core
    end

    CLI -->|STDIO/JSON-RPC| HANDLER
    HANDLER -->|"routes"| REGISTRY
    REGISTRY --> GC
    REGISTRY --> LC
    REGISTRY --> GD
    REGISTRY --> GM
    REGISTRY --> GB
    REGISTRY --> LB
    REGISTRY --> GDSTR

    %% Tools to Infrastructure
    GC --> UT_CACHE
    LC --> UT_CACHE
    GD --> UT_CACHE
    GM --> UT_CACHE
    GB --> UT_CACHE
    LB --> UT_CACHE
    GDSTR --> UT_CACHE

    %% Infrastructure & Utilities
    subgraph "Infrastructure & Utilities"
        UT_API["GitHub API Client<br/>api.ts"]:::infra
        UT_AX["Axios Wrapper<br/>axios.ts"]:::infra
        UT_CACHE["Cache Layer<br/>cache.ts"]:::infra
        UT_CB["Circuit Breaker<br/>circuit-breaker.ts"]:::infra
        UT_LOG["Logger<br/>logger.ts"]:::infra
        UT_VAL["Validation<br/>validation.ts"]:::infra
    end

    UT_CACHE --> UT_CB
    UT_CB --> UT_AX
    UT_AX --> UT_API
    UT_API -->|HTTP/REST| GITHUB

    %% External Service
    GITHUB["GitHub REST API"]:::external

    %% Back to Core
    UT_CB -.-> UT_LOG
    UT_CB -.-> UT_VAL

    UT_API -->|raw JSON| RESOURCES
    RESOURCES --> PROMPTS
    PROMPTS --> RESP_TEMPL
    RESP_TEMPL --> SCHEMA
    SCHEMA --> HANDLER
    HANDLER -->|JSON-RPC Response| CLI

    %% CI & Docs
    subgraph "CI & Documentation"
        CI["Workflows (.github/workflows)"]:::infra
        DOCS["docs/"]:::infra
        EXAMPLES["examples.sh<br/>test-package.sh"]:::infra
    end

    %% Click events
    click HANDLER "https://github.com/jpisnice/shadcn-ui-mcp-server/blob/master/src/handler.ts"
    click REGISTRY "https://github.com/jpisnice/shadcn-ui-mcp-server/blob/master/src/tools/index.ts"
    click GC "https://github.com/jpisnice/shadcn-ui-mcp-server/blob/master/src/tools/components/get-component.ts"
    click LC "https://github.com/jpisnice/shadcn-ui-mcp-server/blob/master/src/tools/components/list-components.ts"
    click GD "https://github.com/jpisnice/shadcn-ui-mcp-server/blob/master/src/tools/components/get-component-demo.ts"
    click GM "https://github.com/jpisnice/shadcn-ui-mcp-server/blob/master/src/tools/components/get-component-metadata.ts"
    click GB "https://github.com/jpisnice/shadcn-ui-mcp-server/blob/master/src/tools/blocks/get-block.ts"
    click LB "https://github.com/jpisnice/shadcn-ui-mcp-server/blob/master/src/tools/blocks/list-blocks.ts"
    click GDSTR "https://github.com/jpisnice/shadcn-ui-mcp-server/blob/master/src/tools/repository/get-directory-structure.ts"
    click PROMPTS "https://github.com/jpisnice/shadcn-ui-mcp-server/blob/master/src/prompts.ts"
    click RESP_TEMPL "https://github.com/jpisnice/shadcn-ui-mcp-server/blob/master/src/resource-templates.ts"
    click RESOURCES "https://github.com/jpisnice/shadcn-ui-mcp-server/blob/master/src/resources.ts"
    click SCHEMA "https://github.com/jpisnice/shadcn-ui-mcp-server/blob/master/src/schemas/component.ts"
    click UT_API "https://github.com/jpisnice/shadcn-ui-mcp-server/blob/master/src/utils/api.ts"
    click UT_AX "https://github.com/jpisnice/shadcn-ui-mcp-server/blob/master/src/utils/axios.ts"
    click UT_CACHE "https://github.com/jpisnice/shadcn-ui-mcp-server/blob/master/src/utils/cache.ts"
    click UT_CB "https://github.com/jpisnice/shadcn-ui-mcp-server/blob/master/src/utils/circuit-breaker.ts"
    click UT_LOG "https://github.com/jpisnice/shadcn-ui-mcp-server/blob/master/src/utils/logger.ts"
    click UT_VAL "https://github.com/jpisnice/shadcn-ui-mcp-server/blob/master/src/utils/validation.ts"
    click CI "https://github.com/jpisnice/shadcn-ui-mcp-server/tree/master/.github/workflows/"
    click DOCS "https://github.com/jpisnice/shadcn-ui-mcp-server/tree/master/docs/"
    click EXAMPLES "https://github.com/jpisnice/shadcn-ui-mcp-server/blob/master/examples.sh"

    %% Styles
    classDef clients fill:#D6E9FF,stroke:#0366d6,color:#0366d6,stroke-width:1px;
    classDef core fill:#D6FFD6,stroke:#228B22,color:#228B22,stroke-width:1px;
    classDef infra fill:#FFE5B4,stroke:#FF8C00,color:#FF8C00,stroke-width:1px;
    classDef external fill:#F0F0F0,stroke:#A9A9A9,color:#696969,stroke-width:1px;
```
