# valesh-gosats/sofi-remote-mcp-server architecture

> Architecture diagram of the GitHub repository valesh-gosats/sofi-remote-mcp-server, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-10-13). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/valesh-gosats/sofi-remote-mcp-server
- Repository: https://github.com/valesh-gosats/sofi-remote-mcp-server

## Overview

##### Project type and purpose
- This is a small, serverless “Remote MCP Server” demo built on Cloudflare Workers. It implements a Model Context Protocol (MCP) server without authentication, exposing an SSE endpoint (`/sse`) that clients (e.g. Cloudflare AI Playground or Claude Desktop via `mcp-remote`) can connect to.

##### File structure
- Top-level files:
– package.json / package-lock.json: Node build & dependency management
– wrangler.jsonc: Cloudflare Workers deployment config
– tsconfig.json + worker-configuration.d.ts + biome.json: TypeScript and linting setup
– src/index.ts: Core Worker code where the MCP server and tools are registered
- No separate frontend or backend directories: it’s a single serverless function

##### Key README insights
- Describes how to deploy to Workers and how to register custom tools in `src/index.ts` via `this.server.tool(...)`
- Shows two clients: the web-based Playground (connect via URL) and Claude Desktop (via `mcp-remote` proxy)

##### Main components
A. Developer & Build Pipeline
- Git repo (with src/ + config files)
- npm build step (tsc → Worker bundle)
- wrangler CLI → Cloudflare Workers
B. Cloudflare Workers Runtime
- MCP Server instance
– init() method: registers Tools
– Event handler for HTTP/SSE connections at `/sse`
C. Tools Module(s)
- Each tool added via `this.server.tool(name, handler)`
- Can invoke external APIs or perform compute
D. SSE Endpoint & Streaming
- `/sse` path streams MCP events to connected clients
E. Clients
1. Cloudflare AI Playground (browser)
2. Local MCP Client (e.g. Claude Desktop via `mcp-remote`)

##### Relationships & Interactions
- Developer pushes code → CI / local `wrangler publish` → deploy Worker
- Worker bundle runs in Cloudflare’s edge network
- Client initiates HTTP GET to `/sse` → Worker sets up SSE stream
- Worker dispatches incoming MCP messages to registered Tools → Tools return responses → Worker writes events to SSE stream → client UI renders results

##### Architectural patterns & principles
- Serverless / Functions-as-a-Service (FaaS) at the edge
- Event-driven (SSE stream)
- Pluggable “tools” as handlers (inversion of control)
- Single responsibility: Worker only hosts MCP server and delegates logic to tools

##### Technologies & frameworks
– Cloudflare Workers (Runtime)
– Wrangler (CLI & deployment)
– TypeScript (src/index.ts, tsconfig.json)
– MCP (Model Context Protocol) library in src
– SSE (Server-Sent Events) for streaming
– mcp-remote (optional proxy for local clients)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Build & Deploy Layer
    subgraph "Build & Deploy" 
        direction TB
        Developer["Developer"]:::build
        Repo["Git Repository"]:::build
        npm["npm Build (tsc)"]:::build
        Wrangler["Wrangler CLI"]:::build
        Config["TypeScript Definitions"]:::build

        Developer --> Repo
        Repo --> npm
        npm --> Wrangler
        Repo --> Config

        click Repo "https://github.com/valesh-gosats/sofi-remote-mcp-server/blob/main/package.json"
        click Repo "https://github.com/valesh-gosats/sofi-remote-mcp-server/blob/main/package-lock.json"
        click Repo "https://github.com/valesh-gosats/sofi-remote-mcp-server/blob/main/tsconfig.json"
        click Repo "https://github.com/valesh-gosats/sofi-remote-mcp-server/blob/main/biome.json"
        click Wrangler "https://github.com/valesh-gosats/sofi-remote-mcp-server/blob/main/wrangler.jsonc"
        click Config "https://github.com/valesh-gosats/sofi-remote-mcp-server/blob/main/worker-configuration.d.ts"
    end

    %% Cloudflare Edge Runtime
    subgraph "Cloudflare Edge" 
        direction TB
        Worker["Cloudflare Worker Runtime\n(MCP Server)"]:::cf
        Tools["Tools Module\n(this.server.tool)"]:::tools
        SSE["SSE Endpoint\n/sse (Server-Sent Events)"]:::cf

        Worker --> Tools
        Worker --> SSE

        click Worker "https://github.com/valesh-gosats/sofi-remote-mcp-server/blob/main/src/index.ts"
        click Tools "https://github.com/valesh-gosats/sofi-remote-mcp-server/blob/main/src/index.ts"
        click SSE "https://github.com/valesh-gosats/sofi-remote-mcp-server/blob/main/src/index.ts"
    end

    %% Clients
    subgraph "Clients" 
        direction TB
        Playground["Cloudflare AI Playground"]:::client
        Claude["Claude Desktop\n(via mcp-remote)"]:::client
    end

    %% Interactions
    Wrangler -->|deploy| Worker
    Playground -->|HTTP GET /sse| SSE
    Claude -->|HTTP GET /sse| SSE
    SSE -->|SSE Stream| Playground
    SSE -->|SSE Stream| Claude
    Worker -->|dispatch MCP messages| Tools
    Tools -->|return responses| Worker

    %% Styles
    classDef build fill:#EFEFEF,stroke:#333,stroke-width:1px;
    classDef cf fill:#BBDEFB,stroke:#0D47A1,stroke-width:1px;
    classDef tools fill:#C8E6C9,stroke:#256029,stroke-width:1px;
    classDef client fill:#FFE0B2,stroke:#E65100,stroke-width:1px;
```
