# modelcontextprotocol/registry architecture

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

- Interactive diagram: https://gitdiagram.com/modelcontextprotocol/registry
- Repository: https://github.com/modelcontextprotocol/registry

## Overview

##### Project Type and Purpose
- This is a backend-only, RESTful registry service written in Go.
- It exposes HTTP endpoints (health, ping, servers, publish) for managing metadata about MCP servers.
- It supports both MongoDB and in-memory stores, uses GitHub for authentication, and provides a CLI “publisher” tool to push entries.

##### Top‐Level Components
a. API Server Container (Go service)
b. Database (MongoDB or in-memory)
c. External Auth Service (GitHub OAuth)
d. CLI Publisher Tool
e. Utility Scripts (for testing)
f. Docker Compose/Container Orchestration

- Configuration (internal/config)
- HTTP Server & Router (internal/api/server.go + internal/api/router)
- Handlers (internal/api/handlers/v0)
- Business Logic / Services (internal/service)
- Data Layer / Repositories (internal/database + internal/model)
- Auth Module (internal/auth)

##### Relationships & Data Flow
1) Client → HTTP(S) → API Server
2) Router dispatches to v0 handlers
3) Handlers call Service layer
4) Service layer uses Database interface (Mongo or Memory)
5) Service layer calls Auth module for “publish” endpoints (GitHub client)
6) Database persists/fetches data
7) CLI Publisher → HTTP POST /v0/publish → API Server
8) Docker Compose orchestrates API + MongoDB + seed import

##### Architectural Patterns & Principles
- Hexagonal / Clean Architecture: clear separation between API adapters, business logic, persistence interfaces, and external clients.
- Dependency Injection via interfaces (database, auth).
- Layered approach: Router → Handlers → Services → Repositories.
- Pluggable data store (memory or Mongo) via strategy pattern.

##### Technologies & Frameworks
- Go modules, Go 1.18+
- Gin or built-in net/http (internal/api/router)
- MongoDB driver (internal/database/mongo)
- Docker & Docker Compose
- OpenAPI/Swagger (api/openapi.yaml, internal/docs)
- GitHub OAuth (internal/auth/github.go)

b. Within the registry container, subdivide into:
- Config Module
- HTTP Server & Router
- Handlers (v0)
- Services (registry_service, fake_service)
- Database Abstraction (memory, mongo)
- Auth Module
e. Outside the Docker boundary, place “Client” (web or CLI) and show HTTP calls (GET /v0/servers, POST /v0/publish).

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Clients
    Client["Client (Web)"]:::external
    CLI["CLI Publisher"]:::external
    Scripts["Test Scripts"]:::external
    SeedFile["Seed Data (data/seed_2025_05_16.json)"]:::external
    GitHub["GitHub OAuth"]:::external

    %% Docker Compose Network Boundary
    subgraph "Docker Compose Network"
        direction TB
        subgraph "Registry Service (Go API)"
            direction TB
            MainApp["Registry Service"]:::apiAdapter
            Config["Config Module\n(internal/config)"]:::apiAdapter
            Server["HTTP Server\n(internal/api/server.go)"]:::apiAdapter
            Router["Router\n(internal/api/router)"]:::apiAdapter
            subgraph "Handlers v0"
                direction TB
                Health["health.go"]:::apiAdapter
                Ping["ping.go"]:::apiAdapter
                ServersH["servers.go"]:::apiAdapter
                PublishH["publish.go"]:::apiAdapter
                AuthH["auth.go"]:::apiAdapter
                SwaggerH["swagger.go"]:::apiAdapter
            end
            subgraph "Services"
                direction TB
                CoreService["service.go"]:::business
                RegistryS["registry_service.go"]:::business
                FakeS["fake_service.go"]:::business
            end
            subgraph "Database Abstraction"
                direction TB
                DBInterface["database.go"]:::persistence
                MongoAbstr["mongo.go"]:::persistence
                MemoryAbstr["memory.go"]:::persistence
                ImportDB["import.go"]:::persistence
                Model["model.go"]:::persistence
            end
            subgraph "Auth Module"
                direction TB
                AuthCore["auth.go"]:::apiAdapter
                GitHubClient["github.go"]:::external
                AuthServ["service.go"]:::business
            end
        end
        MongoDB["MongoDB"]:::persistence
    end

    %% Connections
    Client -->|HTTP GET /v0/servers| Server
    Client -->|HTTP GET /v0/health| Server
    CLI -->|HTTP POST /v0/publish| Server
    Scripts -->|curl /v0/health| Server
    Scripts -->|curl /v0/servers| Server
    Server -->|route| Router
    Router -->|v0 routes| Health
    Router -->|v0 routes| Ping
    Router -->|v0 routes| ServersH
    Router -->|v0 routes| PublishH
    Router -->|v0 routes| AuthH
    Router -->|v0 routes| SwaggerH
    Health -->|"call"| CoreService
    Ping -->|"call"| CoreService
    ServersH -->|"call RegistryService"| RegistryS
    PublishH -->|"call RegistryService"| RegistryS
    PublishH -->|"auth"| AuthCore
    AuthH -->|"call Auth Service"| AuthServ
    RegistryS -->|"DB Query"| DBInterface
    CoreService -->|"DB Query"| DBInterface
    DBInterface -->|use mongo| MongoAbstr
    DBInterface -->|use memory| MemoryAbstr
    MongoAbstr -->|persist| MongoDB
    ImportDB -->|seed import| MongoDB
    RegistryS -->|"validate token"| GitHubClient
    AuthServ -->|"validate token"| GitHubClient

    SeedFile -->|import on startup| ImportDB

    %% Click Events
    click MainApp "https://github.com/modelcontextprotocol/registry/blob/main/cmd/registry/main.go"
    click Config "https://github.com/modelcontextprotocol/registry/blob/main/internal/config/config.go"
    click Server "https://github.com/modelcontextprotocol/registry/blob/main/internal/api/server.go"
    click Router "https://github.com/modelcontextprotocol/registry/blob/main/internal/api/router/router.go"
    click Health "https://github.com/modelcontextprotocol/registry/blob/main/internal/api/handlers/v0/health.go"
    click Ping "https://github.com/modelcontextprotocol/registry/blob/main/internal/api/handlers/v0/ping.go"
    click ServersH "https://github.com/modelcontextprotocol/registry/blob/main/internal/api/handlers/v0/servers.go"
    click PublishH "https://github.com/modelcontextprotocol/registry/blob/main/internal/api/handlers/v0/publish.go"
    click AuthH "https://github.com/modelcontextprotocol/registry/blob/main/internal/api/handlers/v0/auth.go"
    click SwaggerH "https://github.com/modelcontextprotocol/registry/blob/main/internal/api/handlers/v0/swagger.go"
    click CoreService "https://github.com/modelcontextprotocol/registry/blob/main/internal/service/service.go"
    click RegistryS "https://github.com/modelcontextprotocol/registry/blob/main/internal/service/registry_service.go"
    click FakeS "https://github.com/modelcontextprotocol/registry/blob/main/internal/service/fake_service.go"
    click DBInterface "https://github.com/modelcontextprotocol/registry/blob/main/internal/database/database.go"
    click MongoAbstr "https://github.com/modelcontextprotocol/registry/blob/main/internal/database/mongo.go"
    click MemoryAbstr "https://github.com/modelcontextprotocol/registry/blob/main/internal/database/memory.go"
    click ImportDB "https://github.com/modelcontextprotocol/registry/blob/main/internal/database/import.go"
    click Model "https://github.com/modelcontextprotocol/registry/blob/main/internal/model/model.go"
    click AuthCore "https://github.com/modelcontextprotocol/registry/blob/main/internal/auth/auth.go"
    click GitHubClient "https://github.com/modelcontextprotocol/registry/blob/main/internal/auth/github.go"
    click AuthServ "https://github.com/modelcontextprotocol/registry/blob/main/internal/auth/service.go"
    click CLI "https://github.com/modelcontextprotocol/registry/blob/main/tools/publisher/main.go"
    click CLI "https://github.com/modelcontextprotocol/registry/blob/main/tools/publisher/build.sh"
    click CLI "https://github.com/modelcontextprotocol/registry/blob/main/tools/publisher/mcp.json"
    click CLI "https://github.com/modelcontextprotocol/registry/blob/main/tools/publisher/README.md"
    click Scripts "https://github.com/modelcontextprotocol/registry/blob/main/scripts/test_endpoints.sh"
    click Scripts "https://github.com/modelcontextprotocol/registry/blob/main/scripts/test_publish.sh"
    click SeedFile "https://github.com/modelcontextprotocol/registry/blob/main/data/seed_2025_05_16.json"

    %% Styles
    classDef apiAdapter fill:#e0f7fa,stroke:#0277bd,color:#01579b
    classDef business fill:#e8f5e9,stroke:#2e7d32,color:#1b5e20
    classDef persistence fill:#fff3e0,stroke:#ef6c00,color:#e65100
    classDef external fill:#eceff1,stroke:#607d8b,color:#37474f
```
