# barvhaim/remy-mcp architecture

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

- Interactive diagram: https://gitdiagram.com/barvhaim/remy-mcp
- Repository: https://github.com/barvhaim/remy-mcp

## Overview

##### Project Type and Purpose
- This is a single‐service (monolithic) backend API server implementing the Model Context Protocol (MCP).
- Its purpose is to expose both dynamic (“tools”) and static (“resources”) endpoints that surface Israeli Land Authority public tender data, integrating live government APIs and local reference data.

##### File Structure
- Top‐level:
- main.py – entry point
- src/remy_mcp/server.py – FastMCP server bootstrap
- src/remy_mcp/client/… – API‐client wrapper around external government APIs
- src/remy_mcp/models/… – Pydantic models for request/response validation
- src/remy_mcp/tools/… – dynamic MCP operations (e.g., search_tenders)
- src/remy_mcp/resources/… – static MCP resources (e.g., regions list)
- src/remy_mcp/utils & data/… – helper utilities and local reference data (e.g., settlement codes)
- Configuration & build: pyproject.toml, uv.lock, pytest.ini, scripts/run_tests.py
- Examples & tests validate end‐to‐end behavior.

##### README for Insights
- Confirms FastMCP framework, Pydantic, Requests with retry & rate‐limiting.
- Lists dynamic functions vs. static resources.
- Provides the external base‐URL: https://apps.land.gov.il/MichrazimSite/api

##### Main Components
a. Clients
- Claude Desktop (via MCP client) or any HTTP/MCP‐capable client
b. MCP Server (Python 3.11+)
- FastMCP framework
- Server bootstrap (server.py → main.py)
c. API‐Client Layer
- israeli_land_api.py uses Requests + retry + rate limiting
d. Business Logic
- Tools modules (tender_tools, settlement_tools)
- Resources modules (reference_resources, server_resources)
e. Data Layer
- Pydantic models (arg_models, tender_models, reference_models)
- Local reference data (data/kod_yeshuv.py)
f. External Dependencies
- Israeli Land Authority public REST API
g. Dev/Test & Deployment
- Examples, test suite (pytest), uv CLI tool

##### Relationships and Data Flows
- Within Server: Incoming request → Router (FastMCP) →
- If dynamic: Tools module → API‐Client → External Gov API → Response → Pydantic model → Return
- If static: Resources module → Local data or pre‐loaded reference → Pydantic model → Return
- All outbound HTTP → `https://apps.land.gov.il/MichrazimSite/api`
- Throttling/rate‐limit enforced in API‐Client layer

##### Architectural Patterns & Principles
- Layered separation (API client, business logic, models, utils)
- Protocol‐driven design (MCP dynamic vs. static endpoints)
- Type safety and validation with Pydantic
- Retry & exponential backoff for resilience
- Configuration via uv/pyproject.toml

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Clients
    subgraph "Clients"
        CLIENT["Example Usage Client"]:::external
    end
    click CLIENT "https://github.com/barvhaim/remy-mcp/blob/master/examples/example_usage.py"

    %% MCP Server
    subgraph "MCP Server"
        MAIN["main.py"]:::backend
        SERVER["server.py"]:::backend
    end
    click MAIN "https://github.com/barvhaim/remy-mcp/blob/master/main.py"
    click SERVER "https://github.com/barvhaim/remy-mcp/blob/master/src/remy_mcp/server.py"

    MAIN -->|"invokes"| SERVER

    %% API-Client Layer
    subgraph "API-Client Layer"
        API_CLIENT["Israeli Land API Client"]:::api
    end
    click API_CLIENT "https://github.com/barvhaim/remy-mcp/blob/master/src/remy_mcp/client/israeli_land_api.py"

    %% Business Logic - Tools
    subgraph "Business Logic - Tools"
        TENDER["tender_tools"]:::logic
        SETTLEMENT_TOOL["settlement_tools"]:::logic
    end
    click TENDER "https://github.com/barvhaim/remy-mcp/blob/master/src/remy_mcp/tools/tender_tools.py"
    click SETTLEMENT_TOOL "https://github.com/barvhaim/remy-mcp/blob/master/src/remy_mcp/tools/settlement_tools.py"

    %% Business Logic - Resources
    subgraph "Business Logic - Resources"
        REF_RES["reference_resources"]:::logic
        SRV_RES["server_resources"]:::logic
    end
    click REF_RES "https://github.com/barvhaim/remy-mcp/blob/master/src/remy_mcp/resources/reference_resources.py"
    click SRV_RES "https://github.com/barvhaim/remy-mcp/blob/master/src/remy_mcp/resources/server_resources.py"

    %% Data Layer - Pydantic Models
    subgraph "Data Layer - Pydantic Models"
        ARG["arg_models"]:::model
        TEND_MODEL["tender_models"]:::model
        REF_MODEL["reference_models"]:::model
    end
    click ARG "https://github.com/barvhaim/remy-mcp/blob/master/src/remy_mcp/models/arg_models.py"
    click TEND_MODEL "https://github.com/barvhaim/remy-mcp/blob/master/src/remy_mcp/models/tender_models.py"
    click REF_MODEL "https://github.com/barvhaim/remy-mcp/blob/master/src/remy_mcp/models/reference_models.py"

    %% Local Reference Data
    subgraph "Local Reference Data"
        KOD["kod_yeshuv.py"]:::data
    end
    click KOD "https://github.com/barvhaim/remy-mcp/blob/master/data/kod_yeshuv.py"

    %% Utilities
    subgraph "Utilities"
        UTIL["settlement_utils"]:::util
    end
    click UTIL "https://github.com/barvhaim/remy-mcp/blob/master/src/remy_mcp/utils/settlement_utils.py"

    %% Configuration & Build
    subgraph "Configuration & Build"
        PYPRJ["pyproject.toml"]:::config
        UVLOCK["uv.lock"]:::config
    end
    click PYPRJ "https://github.com/barvhaim/remy-mcp/blob/master/pyproject.toml"
    click UVLOCK "https://github.com/barvhaim/remy-mcp/blob/master/uv.lock"

    %% Dev/Test & Deployment
    subgraph "Dev/Test & Deployment"
        RUNTESTS["run_tests.py"]:::test
        PYTESTINI["pytest.ini"]:::test
        TESTS["tests/"]:::test
    end
    click RUNTESTS "https://github.com/barvhaim/remy-mcp/blob/master/scripts/run_tests.py"
    click PYTESTINI "https://github.com/barvhaim/remy-mcp/blob/master/pytest.ini"
    click TESTS "https://github.com/barvhaim/remy-mcp/tree/master/tests/"

    %% External Services
    subgraph "External Services"
        GOVAPI["Gov API\nhttps://apps.land.gov.il/MichrazimSite/api"]:::external
    end

    %% Data Flows
    CLIENT -->|"MCP Request"| MAIN
    SERVER -->|"routes to tools"| TENDER
    SERVER -->|"routes to tools"| SETTLEMENT_TOOL
    SERVER -->|"routes to resources"| REF_RES
    SERVER -->|"routes to resources"| SRV_RES
    SERVER -->|"uses API client"| API_CLIENT

    TENDER -->|calls| API_CLIENT
    SETTLEMENT_TOOL -->|calls| API_CLIENT
    API_CLIENT -->|"HTTP Request"| GOVAPI

    TENDER -->|validates| TEND_MODEL
    SETTLEMENT_TOOL -->|validates| ARG
    REF_RES -->|validates| REF_MODEL
    SRV_RES -->|validates| ARG

    REF_RES -->|loads| KOD
    UTIL -->|used by| SETTLEMENT_TOOL

    MAIN -->|uses config| PYPRJ
    SERVER -->|uses lockfile| UVLOCK

    RUNTESTS -->|executes| TESTS
    RUNTESTS -->|executes| MAIN
    PYTESTINI -->|configures| TESTS

    %% Styles
    classDef backend fill:#E8E8E8,stroke:#333,stroke-width:1px
    classDef api fill:#AEDFF7,stroke:#333,stroke-width:1px
    classDef logic fill:#D5E8D4,stroke:#333,stroke-width:1px
    classDef model fill:#F8CECC,stroke:#333,stroke-width:1px
    classDef data fill:#FFF2CC,stroke:#333,stroke-width:1px
    classDef util fill:#F5F5DC,stroke:#333,stroke-width:1px
    classDef config fill:#D5D5D5,stroke:#333,stroke-width:1px
    classDef test fill:#E1D5E7,stroke:#333,stroke-width:1px
    classDef external fill:#F0F0F0,stroke:#333,stroke-width:1px
```
