# buga-luga/cursor-mcp architecture

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

- Interactive diagram: https://gitdiagram.com/buga-luga/cursor-mcp
- Repository: https://github.com/buga-luga/cursor-mcp

## Overview

##### Main Components

a) Client-Side Architecture:
- Next.js 14 Frontend Application
- MCP Controller Component
- Custom Hooks Layer (use-mcp)
- Client-side Protocol Handlers (WebSocket, SSE, STDIO)

b) Server-Side Architecture:
- Next.js Server Components
- MCP Server Implementation
- Protocol Handlers (SSE, STDIO)
- File System Integration

c) SDK Layer:
- TypeScript SDK Core
- Protocol Definitions
- Transport Layer
- In-Memory Handlers

**[Frontend Layer] <-> [Communication Layer] <-> [Backend Services]**

##### Key Relationships to Highlight

a) Frontend Flow:
**UI Components -> MCP Controller -> Custom Hooks -> Protocol Clients**

b) Communication Layer:
**Protocol Handlers (WebSocket/SSE/STDIO) <-> Transport Layer <-> Protocol Definitions**

c) Backend Integration:
**Server Components -> MCP Server -> Claude Desktop**

##### Specific Implementation Details

Key architectural elements:
- Model Context Protocol implementation details
- Next.js 14 App Router integration
- TypeScript type system flow
- Error handling pathways
- State management flow

##### Technical Stack Indicators

Technology badges for:
- Next.js 14
- TypeScript
- WebSocket/SSE
- Radix UI
- Zod (for validation)

##### Notes for Implementation

- Version information
- Document external dependencies
- Scaling considerations

This system design should reflect the project's focus on type-safety, modern React patterns, and the Model Context Protocol specifications while showing how all components interact to create a cohesive desktop integration solution.

## Diagram (Mermaid)

```mermaid
flowchart TB
    subgraph Frontend
        UI[Next.js UI Components]
        MCP[MCP Controller]
        Hooks[Custom Hooks Layer]
        ClientHandlers[Client Protocol Handlers]
    end

    subgraph Communication
        Protocol[Protocol Definitions]
        Transport[Transport Layer]
        InMemory[In-Memory Handlers]
    end

    subgraph Backend
        Server[MCP Server Implementation]
        ServerHandlers[Server Protocol Handlers]
        Tools[Tools & Utilities]
        Claude[Claude Desktop]
    end

    %% Frontend Connections
    UI --> MCP
    MCP --> Hooks
    Hooks --> ClientHandlers

    %% Communication Layer Connections
    ClientHandlers <--> Protocol
    Protocol <--> Transport
    Transport <--> InMemory
    Transport <--> ServerHandlers

    %% Backend Connections
    ServerHandlers --> Server
    Server --> Tools
    Tools --> Claude

    %% Component Mappings
    click UI "https://github.com/Buga-luga/cursor-mcp/tree/main/app"
    click MCP "https://github.com/Buga-luga/cursor-mcp/blob/main/components/mcp-controller.tsx"
    click Hooks "https://github.com/Buga-luga/cursor-mcp/blob/main/lib/hooks/use-mcp.ts"
    click ClientHandlers "https://github.com/Buga-luga/cursor-mcp/tree/main/sdk/client"
    click Protocol "https://github.com/Buga-luga/cursor-mcp/blob/main/sdk/shared/protocol.ts"
    click Transport "https://github.com/Buga-luga/cursor-mcp/blob/main/sdk/shared/transport.ts"
    click InMemory "https://github.com/Buga-luga/cursor-mcp/blob/main/sdk/inMemory.ts"
    click Server "https://github.com/Buga-luga/cursor-mcp/tree/main/sdk/server"
    click ServerHandlers "https://github.com/Buga-luga/cursor-mcp/tree/main/sdk/server"
    click Tools "https://github.com/Buga-luga/cursor-mcp/blob/main/src/tools/tool-framework.ts"

    %% Styling
    classDef frontend fill:#3b82f6,color:#fff
    classDef communication fill:#22c55e,color:#fff
    classDef backend fill:#f97316,color:#fff
    classDef external fill:#6b7280,color:#fff

    class UI,MCP,Hooks,ClientHandlers frontend
    class Protocol,Transport,InMemory communication
    class Server,ServerHandlers,Tools backend
    class Claude external

    %% Legend
    subgraph Legend
        Frontend_L[Frontend Component]:::frontend
        Comm_L[Communication Component]:::communication
        Backend_L[Backend Component]:::backend
        External_L[External Service]:::external
    end
```
