# oscargbocanegra/mcp-for-beginners architecture

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

- Interactive diagram: https://gitdiagram.com/oscargbocanegra/mcp-for-beginners
- Repository: https://github.com/oscargbocanegra/mcp-for-beginners

## Overview

##### Project type and purpose
- This is a minimal “hands-on tutorial” demonstrating a Model Context Protocol (MCP) server/client setup in Python.
- It uses FastMCP (server framework) and the MCP Python SDK (client library) to illustrate basic tool registration and invocation, plus resource endpoints (greeting/farewell).

##### File structure
- Top level:
- mcp_demo/
– server.py → defines and runs an MCP server
– client.py → connects to that server and invokes tools/resources
- pyproject.toml, requirements.txt, uv.lock → Python packaging & dependency management
- .github/, update-readme.sh → CI/docs tasks
- No database or external service folders yet—pure in-process client↔server via stdio/JSON-RPC.

##### README for additional insights
- Confirms Python 3.12+ environment managed by uv
- Server exposes four math tools and two resource endpoints
- Client uses `session.call_tool()` and `session.call_resource()`
- Communication is over stdio pipes orchestrated by uv

##### Main components and interactions
a. Components
1. Python Host Environment (runs both client & server processes)
2. uv Package Manager (bootstraps environment & pipelines)
3. MCP Server (FastMCP)
– Tool Registry (add, subtract, multiply, divide)
– Resource Handlers (greeting://, farewell://)
4. MCP Client (Python SDK session)
5. JSON-RPC over stdio (communication channel)
b. Relationships & data flow
- Client issues JSON-RPC requests → STDIO pipe → Server
- Server looks up tool/resource → executes handler → returns JSON-RPC response → STDIO → Client
c. Architectural patterns
- RPC-style microservice (1 process per role)
- Plugin-like tool registration (decorator-driven)
- Clear separation of concerns: server-side tool logic vs. client-side invocation
d. Key technologies
- FastMCP (server framework)
- python-sdk MCP (client library)
- uv (package manager & runner)
- Python 3.12+

## Diagram (Mermaid)

```mermaid
flowchart TD
    subgraph "Python Environment"
        style Host fill:#f0f0f0,stroke:#ccc
        subgraph "MCP Client" 
            direction TB
            ClientSDK["python-sdk MCP"]:::lib
            ClientScript["client.py"]:::frontend
            ClientSDK -->|"session.call_tool()/resource()"| ClientScript
        end
        subgraph "MCP Server"
            direction TB
            FastMCP["FastMCP Framework"]:::lib
            ServerScript["server.py"]:::backend
            Tools["Tool Registry\n(add, subtract, multiply, divide)"]:::backend
            Resources["Resource Handlers\n(greeting://, farewell://)"]:::backend
            FastMCP --> ServerScript
            ServerScript --> Tools
            ServerScript --> Resources
        end
        ClientScript -->|"JSON-RPC request"| Tools
        ClientScript -->|"JSON-RPC request"| Resources
        Tools -->|"JSON-RPC response"| ClientScript
        Resources -->|"JSON-RPC response"| ClientScript
    end

    uv["uv (runner)"]:::infra
    uv --> ClientScript
    uv --> ServerScript

    subgraph "Dependencies"
        pyproject["pyproject.toml"]:::deps
        requirements["requirements.txt"]:::deps
        uvlock["uv.lock"]:::deps
    end

    subgraph "CI / Docs"
        ciInstructions[".github/instructions/python.instructions.md"]:::infra
        updateReadme["update-readme.sh"]:::infra
    end

    %% Click Events
    click ClientScript "https://github.com/oscargbocanegra/mcp-for-beginners/blob/main/mcp_demo/client.py"
    click ServerScript "https://github.com/oscargbocanegra/mcp-for-beginners/blob/main/mcp_demo/server.py"
    click FastMCP "https://github.com/oscargbocanegra/mcp-for-beginners/blob/main/mcp_demo/__init__.py"
    click pyproject "https://github.com/oscargbocanegra/mcp-for-beginners/blob/main/pyproject.toml"
    click requirements "https://github.com/oscargbocanegra/mcp-for-beginners/blob/main/requirements.txt"
    click uvlock "https://github.com/oscargbocanegra/mcp-for-beginners/blob/main/uv.lock"
    click ciInstructions "https://github.com/oscargbocanegra/mcp-for-beginners/blob/main/.github/instructions/python.instructions.md"
    click updateReadme "https://github.com/oscargbocanegra/mcp-for-beginners/blob/main/update-readme.sh"

    %% Styles
    classDef frontend fill:#cce5ff,stroke:#66b0ff
    classDef backend fill:#ccffcc,stroke:#66d966
    classDef lib fill:#ffe5b4,stroke:#ffb84d
    classDef deps fill:#e0e0e0,stroke:#b0b0b0
    classDef infra fill:#f2dede,stroke:#e0b1b1
```
