# getdatanaut/openmcp architecture

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

- Interactive diagram: https://gitdiagram.com/getdatanaut/openmcp
- Repository: https://github.com/getdatanaut/openmcp

## Overview

##### Project type and purpose
- This is a monorepo (managed by Yarn v4 and Nx) containing:
- A web frontend (“apps/web” – a Remix/React SSR app deployed with Wrangler)
- A CLI tool (“packages/cli”)
- A server implementation (“packages/server”)
- Supporting libraries (“packages/manager”, “packages/openapi”, “packages/schemas”, “packages/utils”)
- Purpose: provide an API‐first platform (“MCP”) with an interactive CLI and web UI, driven by OpenAPI specs and shared schemas, plus server runtime.

##### File structure
- Top‐level config:
- .github/workflows + custom actions for CI/CD
- nx.json + yarnrc for workspace orchestration
- apps/web: React/Remix SSR with route files, client.tsx, ssr.tsx, deployed as a Cloudflare Worker (wrangler.jsonc)
- packages/cli: Node‐based command‐line tool, using internal libraries (datanaut, mcp‐clients, openapi, platform, remix utils, etc.)
- packages/manager: core in‐process manager for client–server coordination
- packages/openapi: tools for loading, validating, and converting OpenAPI documents
- packages/schemas: shared TypeScript schemas for MCP resources
- packages/server: HTTP server that exposes MCP endpoints, using shared schemas and manager
- packages/utils: generic utility functions (docs parsing, variable replacement, etc.)

##### Architectural patterns
- Monorepo with modular packages promotes code sharing and consistent versions
- API‐first design: OpenAPI library drives client/server contract
- Separation of concerns:
- “manager” library encapsulates business logic and in‐memory state
- “server” exposes routes and transforms HTTP⇄manager calls
- “cli” and “web” are thin clients consuming APIs

##### Main components & interactions
a. Components:
- GitHub Actions / CI pipeline (build/test)
- Monorepo orchestrator (Yarn/Nx)
- Shared libraries: schemas, utils, openapi, manager
- Backend server (“packages/server”)
- CLI tool (“packages/cli”)
- Web app (“apps/web”)
- External services (e.g. Cloudflare Workers, external OpenAPI endpoints)
b. Relationships & data flow:
- “cli” and “web” → HTTP/gRPC calls → “server”
- “server” ↔ in‐process “manager” (state + resource management)
- “manager” uses shared “schemas” and “utils” to validate and manipulate data
- “cli” and “server” use “openapi” library to load/validate spec files
- Deployment: “apps/web” → Cloudflare Workers; “server” → Node host or container
c. Architectural patterns:
- Monorepo modularization
- API‐first with OpenAPI-driven code
- SSR frontend separated from API backend
- Command pattern in CLI (commands/install, upload, run, etc.)
d. Key technologies:
- Node.js, TypeScript, Nx, Yarn Workspaces
- React/Remix for SSR web
- Cloudflare Workers (wrangler)
- Vitest for testing, ESlint, Turborepo logs
- OpenAPI library, in‐memory manager

##### Essential elements
- That everything lives in one repo, built and tested together (CI/CD)
- API boundary between clients (CLI/Web) and the server
- Don’t break libraries into too many pieces—group by responsibility (schemas, utils, openapi, manager)
- Deployment targets: CF Workers for web, Node host for server, global installation for CLI

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% CI/CD
    subgraph "CI/CD Pipeline"
        GitHubActions["GitHub Actions / CI"]:::cicd
        CustomActions["Custom Actions"]:::cicd
    end

    %% Monorepo Orchestrator
    subgraph "Monorepo Orchestrator"
        YarnNx["Yarn v4 & Nx"]:::orchestrator
    end

    %% Shared Libraries
    subgraph "Shared Libraries"
        Schemas["Schemas Library"]:::shared
        Utils["Utils Library"]:::shared
        OpenAPI["OpenAPI Library"]:::shared
        Manager["Manager Library"]:::shared
    end

    %% Backend Server
    subgraph "API Server" 
        Server["Server (packages/server)"]:::backend
        subgraph "Server Internal"
            ServerCore["Core Server Logic"]:::backend
            ManagerCall["Manager Calls"]:::backend
        end
    end

    %% Clients
    Web["Web App (apps/web)"]:::frontend
    CLI["CLI Tool (packages/cli)"]:::frontend

    %% External Services
    CFWorker["Cloudflare Workers"]:::external
    ExternalAPI["External OpenAPI Endpoints"]:::external

    %% Connections
    GitHubActions -->|triggers build/tests| YarnNx
    CustomActions -->|custom CI tasks| YarnNx

    YarnNx -->|build/test| Web
    YarnNx -->|build/test| CLI
    YarnNx -->|build/test| Server
    YarnNx -->|link| Schemas
    YarnNx -->|link| Utils
    YarnNx -->|link| OpenAPI
    YarnNx -->|link| Manager

    Web -->|"SSR API calls"| Server
    Web --> CFWorker
    CLI -->|"HTTP RPC / REST"| Server
    CLI --> ExternalAPI

    Server -->|"in-process calls"| Manager
    Manager --> Schemas
    Manager --> Utils

    CLI -->|"spec load & validation"| OpenAPI
    Server -->|"spec load & validation"| OpenAPI

    Server --> ExternalAPI

    %% Click Events
    click GitHubActions "https://github.com/getdatanaut/openmcp/tree/main/.github/workflows"
    click CustomActions "https://github.com/getdatanaut/openmcp/tree/main/.github/actions"
    click YarnNx "https://github.com/getdatanaut/openmcp/blob/main/nx.json"
    click YarnNx "https://github.com/getdatanaut/openmcp/blob/main/yarnrc.yml"
    click YarnNx "https://github.com/getdatanaut/openmcp/blob/main/package.json"
    click Web "https://github.com/getdatanaut/openmcp/tree/main/apps/web"
    click CLI "https://github.com/getdatanaut/openmcp/tree/main/packages/cli"
    click Server "https://github.com/getdatanaut/openmcp/tree/main/packages/server"
    click Manager "https://github.com/getdatanaut/openmcp/tree/main/packages/manager"
    click OpenAPI "https://github.com/getdatanaut/openmcp/tree/main/packages/openapi"
    click Schemas "https://github.com/getdatanaut/openmcp/tree/main/packages/schemas"
    click Utils "https://github.com/getdatanaut/openmcp/tree/main/packages/utils"

    %% Styles
    classDef cicd fill:#cccccc,stroke:#333,stroke-width:1px
    classDef orchestrator fill:#bbbbbb,stroke:#333,stroke-width:1px
    classDef frontend fill:#a0c4ff,stroke:#333,stroke-width:1px
    classDef backend fill:#b9fbc0,stroke:#333,stroke-width:1px
    classDef shared fill:#fdffb6,stroke:#333,stroke-width:1px
    classDef external fill:#ffadad,stroke:#333,stroke-width:1px
```
