# craigsdennis/whoa architecture

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

- Interactive diagram: https://gitdiagram.com/craigsdennis/whoa
- Repository: https://github.com/craigsdennis/whoa

## Overview

##### Project type and purpose
- This is a serverless “Remote MCP Server” built in TypeScript and designed to run on Cloudflare Workers.
- Its purpose is to expose an SSE-based Model Context Protocol (MCP) endpoint (`/sse`) that clients (e.g. Cloudflare AI Playground or local MCP clients like Claude Desktop via `mcp-remote`) can connect to, and to host user-defined “tools” that implement MCP functionality without requiring authentication.

##### File structure
- Top-level config files:
- `wrangler.jsonc` (Cloudflare Workers deployment config)
- `biome.json` (tooling/runtime config)
- `tsconfig.json` (TypeScript compiler settings)
- `package.json` / `package-lock.json` (dependencies & scripts)
- Source code:
- `src/index.ts` — contains the `init()` method where the MCP server is constructed and user tools are registered via `this.server.tool(...)`.
- Type definitions:
- `worker-configuration.d.ts` — custom typing for the Worker environment.

##### README for additional insights
- Shows how to deploy to Cloudflare Workers (UI button or `npm create cloudflare@latest …`).
- Explains how to register custom tools in the MCP server.
- Describes two client use cases: web playground (SSE over HTTP) and local MCP clients (via `mcp-remote` proxy).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Clients
    Browser["Cloudflare AI Playground (Browser UI)"]:::client
    Local["Local MCP Client (Claude Desktop + mcp-remote)"]:::client

    %% Edge Network
    subgraph "Edge / CDN"
        Edge["Cloudflare Edge Network"]:::edge
    end

    %% Worker and MCP Server
    subgraph "Cloudflare Worker (MCP Server)"
        Init["init()"]:::edge
        SSE["SSE Endpoint (/sse)"]:::edge
        ToolsGroup["Registered Tool Handlers"]:::tool
    end

    %% Deployment Tooling
    subgraph "Deployment Tooling"
        Actions["GitHub Actions / Wrangler CLI"]:::config
        Wrangler["wrangler.jsonc"]:::config
    end

    %% Configuration Files
    subgraph "Configuration"
        Biome["biome.json"]:::config
        TSConfig["tsconfig.json"]:::config
        PackageJSON["package.json"]:::config
        PackageLock["package-lock.json"]:::config
        Types["worker-configuration.d.ts"]:::config
        Readme["README.md"]:::config
        GitIgnore[".gitignore"]:::config
    end

    %% Relationships
    Browser -->|"HTTP/SSE"| Edge
    Local -->|"HTTP/SSE via mcp-remote"| Edge
    Edge -->|"Invoke Worker"| Init
    Init -->|"Registers tools"| ToolsGroup
    Edge -->|"Handles /sse"| SSE
    SSE -->|"Route messages"| ToolsGroup
    ToolsGroup -->|"Send SSE responses"| SSE
    Actions -->|"Deploy via Wrangler"| Wrangler
    Wrangler -->|"Configure Worker"| Init

    %% Config dependencies
    Biome --> Init
    TSConfig --> Init
    PackageJSON --> Init
    PackageLock --> Init
    Types --> Init
    Readme --> Init
    GitIgnore --> Init

    %% Click Events
    click Init "https://github.com/craigsdennis/whoa/blob/main/src/index.ts"
    click SSE "https://github.com/craigsdennis/whoa/blob/main/src/index.ts"
    click ToolsGroup "https://github.com/craigsdennis/whoa/blob/main/src/index.ts"
    click Wrangler "https://github.com/craigsdennis/whoa/blob/main/wrangler.jsonc"
    click Biome "https://github.com/craigsdennis/whoa/blob/main/biome.json"
    click TSConfig "https://github.com/craigsdennis/whoa/blob/main/tsconfig.json"
    click PackageJSON "https://github.com/craigsdennis/whoa/blob/main/package.json"
    click PackageLock "https://github.com/craigsdennis/whoa/blob/main/package-lock.json"
    click Types "https://github.com/craigsdennis/whoa/blob/main/worker-configuration.d.ts"
    click Readme "https://github.com/craigsdennis/whoa/blob/main/README.md"
    click GitIgnore "https://github.com/craigsdennis/whoa/blob/main/.gitignore"

    %% Styles
    classDef client fill:#D0E6FF,stroke:#003366,color:#003366
    classDef edge fill:#E6FFE6,stroke:#006600,color:#006600
    classDef tool fill:#FFE6CC,stroke:#CC6600,color:#CC6600
    classDef config fill:#F2F2F2,stroke:#666666,color:#333333
```
