# liuyoshio/mcp-compass architecture

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

- Interactive diagram: https://gitdiagram.com/liuyoshio/mcp-compass
- Repository: https://github.com/liuyoshio/mcp-compass

## Overview

##### Project Overview & Purpose
- MCP Compass is a discovery and recommendation service for MCP (Model Context Protocol) servers. It enables AI assistants to find available MCP services using natural language queries and provides rich metadata with real‐time updates.
- The project is a lightweight Node.js/TypeScript application (as indicated by the presence of package.json, pnpm-lock.yaml, tsconfig.json, and a single src/index.ts file). It is designed to be integrated as an MCP service via command line (using npx or node) into AI assistants.

##### Analyzing the File Structure
- Top-level files: Standard project files (.gitignore, LICENSE, README.md, tsconfig.json, package.json) indicate a typical Node/TS project.
- assets: Contains static resources (e.g., demo images used in the README). This folder supports the presentation aspect of the service.
- src: Contains the main source code. Currently, it only has index.ts, which is likely the entry point where the service is initialized.
- The minimal file structure implies that the core logic is contained in a small codebase, suggesting the “backend” is built as a single service module without a separate “frontend” layer.

##### Determining the Main Components
a. External Clients/Consumers:
- AI Assistants or End-Users that interact with MCP Compass via natural language queries.
- As external clients sending requests to the service.

b. MCP Compass Service (Backend):
- The core Node.js/TypeScript application (represented by the src/index.ts). This includes the API endpoints (or command-line interface) for processing discovery requests.
- That this service handles smart search queries, collects rich metadata, and manages real-time update functionality.

c. MCP Server Registry/External Data Sources:
- As per the README and demonstration (e.g., the badge image linking to an MCP server), there is integration with external MCP service listings or real-time updates.

d. Configuration & Deployment Components:
- That the MCP Compass service can be used as an MCP Service via configuration (e.g., using npx or node command as described). This is an important design aspect for service integration.

##### Highlighting Relationships and Interactions
- Make clear that the MCP Compass service acts as a mediator – receiving user queries, processing and possibly enriching the query with backend logic, and finally returning detailed information on available MCP services.

##### Architectural Patterns & Design Principles
- Separation of concerns:
- The service’s API layer handles communication with external clients.
- The core logic layer processes search queries and manages metadata.
- An integration layer (or external interfaces) fetches and synchronizes real-time MCP service data.
- That although the project is small, these distinctions guide how the system might evolve or be integrated with other components.

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% External Clients
    Client["AI Assistants / End-Users"]:::external

    %% MCP Compass Service
    Service["MCP Compass Service (Backend)<br>handles smart search queries, metadata & real-time updates"]:::backend
    click Service "https://github.com/liuyoshio/mcp-compass/blob/main/src/index.ts"

    %% External MCP Server Registry/Data Sources
    ExtServer["External MCP Server Registry/Data Sources"]:::external

    %% Configuration & Deployment Components
    subgraph "Configuration & Deployment"
        PKG["package.json"]:::config
        TS["tsconfig.json"]:::config
        PNPM["pnpm-lock.yaml"]:::config
    end
    click PKG "https://github.com/liuyoshio/mcp-compass/blob/main/package.json"
    click TS "https://github.com/liuyoshio/mcp-compass/blob/main/tsconfig.json"
    click PNPM "https://github.com/liuyoshio/mcp-compass/blob/main/pnpm-lock.yaml"

    %% Assets (Supporting Presentation)
    subgraph "Static Assets"
        ASSETS["Assets"]:::asset
    end
    click ASSETS "https://github.com/liuyoshio/mcp-compass/tree/main/assets"

    %% Relationships
    Client -->|"sendsQuery"| Service
    Service -->|"fetchesUpdates"| ExtServer
    ExtServer -->|"returnsData"| Service
    Service -->|"returnsRecs"| Client

    %% Support Relationships
    Service -.->|"usesConfig"| PKG
    Service -.->|"usesConfig"| TS
    Service -.->|"usesConfig"| PNPM
    Service -.->|"servesAssets"| ASSETS

    %% Styles
    classDef backend fill:#FDEBD0,stroke:#D35400,stroke-width:2px;
    classDef external fill:#D5F5E3,stroke:#27AE60,stroke-width:2px;
    classDef config fill:#D6EAF8,stroke:#2471A3,stroke-width:2px;
    classDef asset fill:#FADBD8,stroke:#922B21,stroke-width:2px;
```
