# alucek/quick-mcp-example architecture

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

- Interactive diagram: https://gitdiagram.com/alucek/quick-mcp-example
- Repository: https://github.com/alucek/quick-mcp-example

## Overview

##### Project type and purpose
- This is a minimal example of a Model Context Protocol (MCP) system, consisting of:
– An MCP Server (“mcp_server.py”) exposing tools, resources, prompts
– A CLI-based MCP Client (“client.py”) that connects to and interacts with the server
– Supplementary material (not code) in “MCP_Setup.ipynb” for vector-DB setup
- Purpose: demonstrate how to standardize LLM interactions by plugging in data sources (vector DB), invoking tools, selecting resources, and running preset prompts via the protocol

##### File structure
- Top-level scripts
– mcp_server.py: server implementation (HTTP or RPC endpoints, tool and resource registration)
– client.py: simple command-line client that connects to the server, passes messages, displays responses
- Configuration files
– pyproject.toml, uv.lock, .python-version: dependency and environment management
– .gitignore
- Documentation & assets
– MCP_Setup.ipynb: Jupyter notebook to build the Chroma vector DB and embed PDF content
– media/: static images (mcp_arch.png, core_comp.png, mcp_plan.png)

##### Extract architecture insights from README
- Three logical roles in MCP ecosystem:
– Servers: expose tools (function calls), resources (URIs), prompts (templates)
– Clients: manage connections, LLM integration, message routing
– Hosts (not implemented here): UI layers, embedding in larger applications
- Example flow:
1. Client connects to server
2. Server advertises available tools/resources/prompts
3. Client requests context or executes tool (e.g. vector DB query via Chroma)
4. LLM responses pass back through client for display

a. Main components
– CLI Client (client.py)
– MCP Server (mcp_server.py)
– Vector Database (ChromaDB instance configured via MCP_Setup.ipynb)
– LLM Provider (external API or local model invoked by client)
– Static Resources (PDFs, config files exposed by server)
– Prompts registry (in-memory or file-backed templates)
b. Relationships & data flow
1. Client initializes and opens protocol connection to Server
2. Server registers and advertises:
- Tools → e.g. “vector_search()”
- Resources → e.g. “/datasets/manual.pdf”
- Prompts → e.g. “summarize_document”
3. Client requests resource list; user selects context
4. Client sends LLM request, optionally invoking tool → Server calls ChromaDB, returns results
5. Client feeds tool output or static resource into LLM prompt via LLM Provider
6. LLM response routed back to Client for display in CLI
c. Architectural patterns & principles
– Protocol-oriented modularity: server interface decoupled from client UI
– Single responsibility: each component focuses on one concern (tool execution, message passing, data storage)
– Plug-and-play extensibility: new servers, clients or hosts can be introduced without breaking the protocol
d. Key technologies & frameworks
– Python (async or sync HTTP/RPC framework in mcp_server.py)
– ChromaDB for vector retrieval
– Jupyter Notebook for initial DB setup (MCP_Setup.ipynb)
– uv for virtual environment & dependency management
– Standard JSON-RPC or HTTP for client-server communication

– Client (CLI)
– MCP Server
– Vector Database
– LLM Provider
– Static Resources
– Prompts Registry
– Client → Server (API call: listTools, callTool, listResources, runPrompt)
– Server → Vector DB (tool invocation: vector_search)
– Client → LLM Provider (final prompt execution)
– Resource fetch (Client or Server → Static Resources)
– Blue for compute components (Client, Server)
– Green for data stores (ChromaDB, Static Resources)
– Orange for external services (LLM Provider)

##### Detail without over-complication
- Every protocol endpoint or message type relevant to this example
- Where tools vs. resources vs. prompts diverge in the flow

## Diagram (Mermaid)

```mermaid
flowchart TB
    %% Compute components
    Client["CLI Client"]:::compute
    Server["MCP Server"]:::compute

    %% Data stores
    VectorDB["ChromaDB (Vector DB)"]:::datastore
    StaticRes["Static Resources"]:::datastore
    Prompts["Prompts Registry"]:::datastore
    Doc["Project Documentation (README.md)"]:::datastore

    subgraph "Configuration Files"
        PYProj["pyproject.toml"]:::datastore
        UVLock["uv.lock"]:::datastore
        PythonVer[".python-version"]:::datastore
        GitIgnore[".gitignore"]:::datastore
    end

    %% External services
    LLM["LLM Provider"]:::external

    %% Connections
    Client -->|"listTools, listResources, callTool, runPrompt"| Server
    Server -->|"vector_search()"| VectorDB
    Server -->|"load resources"| StaticRes
    Server -->|"load prompts"| Prompts
    Client -->|"executePrompt"| LLM
    LLM -->|"response"| Client

    %% Click Events
    click Server "https://github.com/alucek/quick-mcp-example/blob/main/mcp_server.py"
    click Client "https://github.com/alucek/quick-mcp-example/blob/main/client.py"
    click VectorDB "https://github.com/alucek/quick-mcp-example/blob/main/MCP_Setup.ipynb"
    click StaticRes "https://github.com/alucek/quick-mcp-example/tree/main/media/"
    click Doc "https://github.com/alucek/quick-mcp-example/blob/main/README.md"
    click PYProj "https://github.com/alucek/quick-mcp-example/blob/main/pyproject.toml"
    click UVLock "https://github.com/alucek/quick-mcp-example/blob/main/uv.lock"
    click PythonVer "https://github.com/alucek/quick-mcp-example/blob/main/.python-version"
    click GitIgnore "https://github.com/alucek/quick-mcp-example/blob/main/.gitignore"

    %% Styles
    classDef compute fill:#ADD8E6,stroke:#000,stroke-width:1px
    classDef datastore fill:#90EE90,stroke:#000,stroke-width:1px
    classDef external fill:#FFA500,stroke:#000,stroke-width:1px
```
