# yun30153015/servers architecture

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

- Interactive diagram: https://gitdiagram.com/yun30153015/servers
- Repository: https://github.com/yun30153015/servers

## Overview

##### Project Type and Purpose
- This is an open-source, monorepo “toolbox” of reference implementations for the Model Context Protocol (MCP).
- Each subfolder under src/ is a standalone MCP server (microservice) implemented either in TypeScript (using the Typescript MCP SDK) or Python (using the Python MCP SDK).
- Purpose: demonstrate how to give LLMs secure, controlled access to various tools and data sources, and to serve as templates for community-built MCP servers.

##### File-Structure Analysis
- Top-level files and directories:
- **package.json, tsconfig.json** – TypeScript monorepo configuration.
- **scripts/** – release and version-bump automation (Python script).
- **.github/workflows/** – CI/CD pipelines: python.yml, typescript.yml, release.yml, version-check.yml.
- **src/** – one folder per MCP server, each containing its own Dockerfile, code entrypoint (index.ts or __main__.py), SDK config (package.json or pyproject.toml), and tsconfig.json/uv.lock.
- Each server folder is a self-contained microservice:
– Dockerfile for containerized deployment.
– Language-specific project file (package.json or pyproject.toml).
– Entrypoint that registers MCP tools and exposes STDIO/SSE interface.

##### Key README Insights
- Alphabetical list of “🌟 Reference Servers” with their responsibilities.
- Usage examples: how to start TS servers via `npx` and Python servers via `uvx` or `pip`.
- Encourages addition of new servers; underscores modular, extensible architecture.

a. Main Components
- **Monorepo Root**: config, scripts, CI/CD workflows.
- **MCP Server Modules** (grouped by language):
- TypeScript servers (e.g. memory, filesystem, github, postgres, etc.)
- Python servers (git, fetch, sqlite, time, sentry)
- **SDKs**:
- Typescript MCP SDK
- Python MCP SDK
- **CI/CD Pipeline** (GitHub Actions): build, test, release.
- **Package Registries**:
- npm registry (for TS packages)
- PyPI or UVX registry (for Python packages)
- **MCP Clients** (e.g., Claude Desktop or other LLM clients)
- **External Services/APIs** each server integrates with (AWS Bedrock, Brave Search API, PostgreSQL, Redis, Google Drive, etc.).

b. Relationships & Data Flow
- **Developer → GitHub**: push to monorepo triggers CI workflows.
- **CI/CD →** runs linter/tests on each server, builds Docker images, publishes packages.
- **MCP Client →** invokes `npx @modelcontextprotocol/server-xyz` or `uvx mcp-server-xyz` to launch a server process.
- **MCP Server →** uses the SDK to parse LLM tool requests, calls out to its external service, returns structured responses.
- **Package Registry →** clients install new or updated server packages.

c. Architectural Patterns & Principles
- **Modular Microservices**: one server per domain; independent lifecycles.
- **SDK-Driven**: minimal glue code; servers declare tools via SDK abstractions.
- **Container-First**: Dockerfiles per module for reproducible deployments.
- **CI/CD-Automated Release**: GitHub Actions for multi-language builds and publishing.
- **Extensible & Community-oriented**: easily drop in new folders under src/, add to alpha-sorted list.

d. Technologies & Frameworks
- Node.js & TypeScript, NPM
- Python 3.x, `uvx`/pip, Poetry/pyproject.toml
- GitHub Actions, Docker
- Model Context Protocol SDKs (TS & Python)
- Optional: Docker Compose if co-running multiple servers locally.

##### Detail & Granularity
- **all** sub-systems:
- Monorepo config (root files, scripts).
- CI workflows per language.
- SDK dependencies.
- Packaging targets.
- Runtime transports (STDIO/SSE).
- Each external service integrated.

## Diagram (Mermaid)

```mermaid
graph TB
    %% Actors
    Developer["Developer"]:::actor
    GitHub["GitHub Repo"]:::repo
    Client["MCP Client (LLM)"]:::client

    %% CI/CD Pipeline
    subgraph "CI/CD Pipelines"
        direction TB
        CI_Python["Python CI (python.yml)"]:::ci
        CI_TS["TypeScript CI (typescript.yml)"]:::ci
        CI_Release["Release Workflow (release.yml)"]:::ci
        CI_Version["Version Check (version-check.yml)"]:::ci
    end

    %% Monorepo Root
    subgraph "Monorepo Root"
        direction TB
        RootPkg["package.json"]:::root
        RootTsConfig["tsconfig.json (root)"]:::root
        Scripts["scripts/release.py"]:::root
        Workflows[".github/workflows"]:::root
    end

    %% SDKs
    subgraph "MCP SDKs"
        direction TB
        TS_SDK["TypeScript MCP SDK"]:::sdk
        PY_SDK["Python MCP SDK"]:::sdk
    end

    %% TypeScript Servers
    subgraph "TypeScript MCP Server Modules"
        direction TB
        AWSKB["aws-kb-retrieval-server"]:::ts
        Brave["brave-search"]:::ts
        Everart["everart"]:::ts
        Everything["everything"]:::ts
        FS["filesystem"]:::ts
        GDrive["gdrive"]:::ts
        GitHubSrv["github"]:::ts
        GitLab["gitlab"]:::ts
        GMaps["google-maps"]:::ts
        Memory["memory"]:::ts
        Postgres["postgres"]:::ts
        Puppeteer["puppeteer"]:::ts
        Redis["redis"]:::ts
        SeqThinking["sequentialthinking"]:::ts
        Slack["slack"]:::ts
    end

    %% Python Servers
    subgraph "Python MCP Server Modules"
        direction TB
        Fetch["fetch"]:::py
        GitSrv["git"]:::py
        Sentry["sentry"]:::py
        SQLite["sqlite"]:::py
        TimeSrv["time"]:::py
    end

    %% External Services
    subgraph "External Services & APIs"
        direction TB
        AWS_Bedrock["AWS Bedrock"]:::external
        BraveAPI["Brave Search API"]:::external
        PostgresDB["PostgreSQL"]:::external
        RedisDB["Redis"]:::external
        GoogleDriveAPI["Google Drive API"]:::external
        GitHubAPI["GitHub API"]:::external
        GitLabAPI["GitLab API"]:::external
        GoogleMapsAPI["Google Maps API"]:::external
        SQLiteDB["SQLite DB"]:::external
        SentryAPI["Sentry"]:::external
        TimeAPI["Timezone/Time API"]:::external
    end

    %% Registries
    subgraph "Package Registries"
        direction TB
        npm["npm Registry"]:::registry
        PyPI["PyPI/UVX Registry"]:::registry
    end

    %% Relationships
    Developer -->|push code| GitHub
    GitHub -->|triggers| CI_Python
    GitHub -->|triggers| CI_TS
    GitHub -->|triggers| CI_Release
    GitHub -->|triggers| CI_Version

    CI_Python -->|runs on| Fetch
    CI_Python -->|runs on| GitSrv
    CI_Python -->|runs on| Sentry
    CI_Python -->|runs on| SQLite
    CI_Python -->|runs on| TimeSrv

    CI_TS -->|runs on| AWSKB
    CI_TS -->|runs on| Brave
    CI_TS -->|runs on| Everart
    CI_TS -->|runs on| Everything
    CI_TS -->|runs on| FS
    CI_TS -->|runs on| GDrive
    CI_TS -->|runs on| GitHubSrv
    CI_TS -->|runs on| GitLab
    CI_TS -->|runs on| GMaps
    CI_TS -->|runs on| Memory
    CI_TS -->|runs on| Postgres
    CI_TS -->|runs on| Puppeteer
    CI_TS -->|runs on| Redis
    CI_TS -->|runs on| SeqThinking
    CI_TS -->|runs on| Slack

    CI_Release -->|publishes to| npm
    CI_Release -->|publishes to| PyPI

    Client -->|npx install| AWSKB
    Client -->|npx install| Brave
    Client -->|npx install| ... 
    Client -->|uvx install| Fetch
    Client -->|uvx install| GitSrv

    AWSKB -->|calls| AWS_Bedrock
    Brave -->|calls| BraveAPI
    Postgres -->|connects| PostgresDB
    Redis -->|connects| RedisDB
    GDrive -->|calls| GoogleDriveAPI
    GitHubSrv -->|calls| GitHubAPI
    GitLab -->|calls| GitLabAPI
    GMaps -->|calls| GoogleMapsAPI
    SQLite -->|reads/writes| SQLiteDB
    Sentry -->|sends events| SentryAPI
    TimeSrv -->|fetches time| TimeAPI

    RootPkg --> RootTsConfig
    RootPkg --> Scripts
    RootPkg --> Workflows

    %% Monorepo contains SDKs and modules
    RootPkg --> TS_SDK
    RootPkg --> PY_SDK
    TS_SDK --> AWSKB
    TS_SDK --> Brave
    TS_SDK --> Everart
    TS_SDK --> Everything
    TS_SDK --> FS
    TS_SDK --> GDrive
    TS_SDK --> GitHubSrv
    TS_SDK --> GitLab
    TS_SDK --> GMaps
    TS_SDK --> Memory
    TS_SDK --> Postgres
    TS_SDK --> Puppeteer
    TS_SDK --> Redis
    TS_SDK --> SeqThinking
    TS_SDK --> Slack

    PY_SDK --> Fetch
    PY_SDK --> GitSrv
    PY_SDK --> Sentry
    PY_SDK --> SQLite
    PY_SDK --> TimeSrv

    %% Click Events
    click RootPkg "https://github.com/yun30153015/servers/blob/main/./package.json"
    click RootTsConfig "https://github.com/yun30153015/servers/blob/main/./tsconfig.json"
    click Scripts "https://github.com/yun30153015/servers/blob/main/./scripts/release.py"
    click CI_Python "https://github.com/yun30153015/servers/blob/main/.github/workflows/python.yml"
    click CI_TS "https://github.com/yun30153015/servers/blob/main/.github/workflows/typescript.yml"
    click CI_Release "https://github.com/yun30153015/servers/blob/main/.github/workflows/release.yml"
    click CI_Version "https://github.com/yun30153015/servers/blob/main/.github/workflows/version-check.yml"

    click AWSKB "https://github.com/yun30153015/servers/tree/main/./src/aws-kb-retrieval-server"
    click Brave "https://github.com/yun30153015/servers/tree/main/./src/brave-search"
    click Everart "https://github.com/yun30153015/servers/tree/main/./src/everart"
    click Everything "https://github.com/yun30153015/servers/tree/main/./src/everything"
    click FS "https://github.com/yun30153015/servers/tree/main/./src/filesystem"
    click GDrive "https://github.com/yun30153015/servers/tree/main/./src/gdrive"
    click GitHubSrv "https://github.com/yun30153015/servers/tree/main/./src/github"
    click GitLab "https://github.com/yun30153015/servers/tree/main/./src/gitlab"
    click GMaps "https://github.com/yun30153015/servers/tree/main/./src/google-maps"
    click Memory "https://github.com/yun30153015/servers/tree/main/./src/memory"
    click Postgres "https://github.com/yun30153015/servers/tree/main/./src/postgres"
    click Puppeteer "https://github.com/yun30153015/servers/tree/main/./src/puppeteer"
    click Redis "https://github.com/yun30153015/servers/tree/main/./src/redis"
    click SeqThinking "https://github.com/yun30153015/servers/tree/main/./src/sequentialthinking"
    click Slack "https://github.com/yun30153015/servers/tree/main/./src/slack"

    click Fetch "https://github.com/yun30153015/servers/tree/main/./src/fetch"
    click GitSrv "https://github.com/yun30153015/servers/tree/main/./src/git"
    click Sentry "https://github.com/yun30153015/servers/tree/main/./src/sentry"
    click SQLite "https://github.com/yun30153015/servers/tree/main/./src/sqlite"
    click TimeSrv "https://github.com/yun30153015/servers/tree/main/./src/time"

    %% Styles
    classDef actor fill:#f9f,stroke:#333,stroke-width:1px
    classDef repo fill:#bbb,stroke:#333,stroke-width:1px
    classDef client fill:#cff,stroke:#333,stroke-width:1px
    classDef ci fill:#f90,stroke:#333,stroke-width:1px
    classDef root fill:#ddd,stroke:#333,stroke-width:1px
    classDef sdk fill:#ff9,stroke:#333,stroke-width:1px
    classDef ts fill:#9cf,stroke:#333,stroke-width:1px
    classDef py fill:#9f9,stroke:#333,stroke-width:1px
    classDef external fill:#eee,stroke:#333,stroke-width:1px,stroke-dasharray: 5 5
    classDef registry fill:#c9f,stroke:#333,stroke-width:1px
```
