# purrify4/servers architecture

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

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

## Overview

##### Project type and purpose
- This is an open-source **monorepo** of reference implementations for the Model Context Protocol (MCP).
- It contains **dozens of independent “server” packages** (e.g., aws-kb-retrieval-server, brave-search, git, postgres, sqlite, etc.), each exposing a set of tools over the MCP transport (STDIO or SSE) for LLM clients to tap into external services and data sources.

##### Top-level file structure and indicators of architecture
- `.github/workflows/`: CI/CD pipelines for TypeScript, Python, release automation, version checks
- `package.json` + `package-lock.json` + `scripts/`: orchestrate builds, tests, and publishing to npm or PyPI
- `src/`
- One directory per MCP server implementation
- Each contains a `README.md`, a language-specific entrypoint (`index.ts` or `server.py`), a `Dockerfile`, and its own `package.json` or Python packaging files
- `tsconfig.json`: overarching TypeScript compiler config

##### Key components
A. **Monorepo Codebase**
- Single GitHub repo with multiple MCP server modules
- Shared CI/CD configs and release scripts
B. **CI/CD Pipeline (GitHub Actions)**
- **Jobs**:
- Lint / compile / test TypeScript packages
- Lint / test Python packages
- Build Docker images for each server
- Publish npm packages and PyPI artifacts
C. **Artifact Registries**
- **npm registry** (for TypeScript-based servers)
- **PyPI** (for Python-based servers)
- **Docker registry** (for Docker images, optional)
D. **MCP Clients**
- CLI wrappers: `npx @modelcontextprotocol/server-<name>`
- `uvx` or `pip install mcp-server-<name>`
- LLM UI clients (e.g., Claude Desktop) configured to spawn these servers as subprocesses or over SSE
E. **Individual Server Modules**
- Each is a microservice implementing the MCP interface
- Transport layers: STDIO or Server-Sent Events
- Core logic: translates MCP tool calls into external API calls (e.g., GitHub REST, AWS Bedrock, PostgreSQL queries, file system operations)
F. **External Services & Data Sources**
- Web APIs (GitHub, GitLab, Brave Search, Google Maps, etc.)
- Databases (Postgres, SQLite, Redis, Memory graph)
- Cloud services (AWS KB, Sentry, GDrive, etc.)
- Local filesystem, code repositories

##### Relationships and data flow
1. **Developer** commits code → **GitHub**
2. **GitHub Actions** CI builds & tests each language SDK sub-project → publishes to registries
3. **User / LLM client** invokes a server:
a. `npx @modelcontextprotocol/server-memory` or `uvx mcp-server-git`
b. Client spawns the process (STDIO/SSE) and sends JSON‐RPC style MCP requests
4. **Server module** receives requests → uses its SDK to call external service → returns structured JSON results
5. **LLM client** ingests results, grounds its reasoning

##### Architectural patterns and design principles
- **Microservice modules**: each server folder is a standalone package, Dockerfile, and tests
- **Monorepo with tooling cohesion**: shared CI, release scripts, linting across TS and Python
- **Transport abstraction**: servers can communicate over STDIO or HTTP/SSE without changing core logic
- **Extensible plug-in style**: add new servers simply by dropping a folder under `src/` and configuring its build

##### Technologies and frameworks
- TypeScript + Node.js + `@modelcontextprotocol/typescript-sdk`
- Python + `modelcontextprotocol` Python SDK + `uvx` packaging
- Docker for containerizing each server
- GitHub Actions for CI/CD
- npm & PyPI for distribution
- STDIO & Server-Sent Events for transport

##### Elements
- **Clear component labels** (e.g., “GitHub Actions CI”, “npm Registry”, “MCP Server: postgres”, “LLM Client”)
- Repositories & code (e.g., blue rectangles)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Monorepo Codebase
    subgraph "Monorepo Codebase"
        RC["package.json, package-lock.json"]:::repo
        TS_CFG["tsconfig.json"]:::repo
        SCRIPTS["scripts/"]:::repo
        REL_SCRIPT["release.py"]:::repo
    end

    %% CI/CD Layer
    subgraph "CI/CD (GitHub Actions)"
        TS_CI["TypeScript Workflow"]:::cicd
        PY_CI["Python Workflow"]:::cicd
        REL_CI["Release Workflow"]:::cicd
        VER_CI["Version Check Workflow"]:::cicd
    end

    %% Artifact Registries
    subgraph "Artifact Registries"
        NPM_REG["npm Registry"]:::registry
        PYPI_REG["PyPI"]:::registry
        DOCKER_REG["Docker Registry"]:::registry
    end

    %% MCP Clients
    subgraph "MCP Clients"
        CLI_TS["npx @modelcontextprotocol/server-aws-kb-retrieval"]:::runtime
        CLI_PY["uvx mcp-server-git"]:::runtime
        UI_CLIENT["LLM UI Client"]:::runtime
    end

    %% MCP Servers
    subgraph "MCP Servers"
        AWS_TS["MCP Server: aws-kb-retrieval"]:::runtime
        GIT_PY["MCP Server: git"]:::runtime
        EVERYTHING["Transport Abstractions"]:::runtime
    end

    %% External Services & Data Sources
    subgraph "External Services & Data Sources"
        WEB_APIS["Web APIs (GitHub, GitLab, etc.)"]:::external
        DBS["Databases (Postgres, SQLite)"]:::external
        CLOUD["Cloud Services (AWS KB, Sentry, etc.)"]:::external
        FS["Local Filesystem & Repos"]:::external
    end

    %% Relationships
    RC --> TS_CI
    TS_CFG --> TS_CI
    SCRIPTS --> TS_CI
    RC --> PY_CI
    SCRIPTS --> PY_CI
    RC --> VER_CI
    TS_CFG --> VER_CI

    TS_CI --> NPM_REG
    PY_CI --> PYPI_REG
    REL_CI --> NPM_REG
    REL_CI --> PYPI_REG
    REL_CI --> DOCKER_REG

    CLI_TS -->|"spawn STDIO/SSE"| AWS_TS
    CLI_PY -->|"spawn STDIO/SSE"| GIT_PY
    UI_CLIENT -->|"spawn subprocess"| AWS_TS
    UI_CLIENT -->|"spawn subprocess"| GIT_PY

    AWS_TS -->|calls| WEB_APIS
    AWS_TS -->|calls| CLOUD
    GIT_PY -->|queries| DBS
    GIT_PY -->|reads| FS
    EVERYTHING -->|provides| AWS_TS
    EVERYTHING -->|provides| GIT_PY

    %% Click Events
    click RC "https://github.com/purrify4/servers/blob/main//package.json"
    click TS_CFG "https://github.com/purrify4/servers/blob/main//tsconfig.json"
    click SCRIPTS "https://github.com/purrify4/servers/tree/main//scripts/"
    click REL_SCRIPT "https://github.com/purrify4/servers/blob/main//scripts/release.py"
    click TS_CI "https://github.com/purrify4/servers/blob/main//.github/workflows/typescript.yml"
    click PY_CI "https://github.com/purrify4/servers/blob/main//.github/workflows/python.yml"
    click REL_CI "https://github.com/purrify4/servers/blob/main//.github/workflows/release.yml"
    click VER_CI "https://github.com/purrify4/servers/blob/main//.github/workflows/version-check.yml"
    click AWS_TS "https://github.com/purrify4/servers/blob/main//src/aws-kb-retrieval-server/index.ts"
    click GIT_PY "https://github.com/purrify4/servers/blob/main//src/git/src/mcp_server_git/server.py"
    click EVERYTHING "https://github.com/purrify4/servers/blob/main//src/everything/sse.ts"

    %% Styles
    classDef repo fill:#bbdefb,stroke:#333,stroke-width:1px
    classDef cicd fill:#c8e6c9,stroke:#333,stroke-width:1px
    classDef registry fill:#a5d6a7,stroke:#333,stroke-width:1px
    classDef runtime fill:#ffe082,stroke:#333,stroke-width:1px
    classDef external fill:#e1bee7,stroke:#333,stroke-width:1px
```
