# sepehr071/amar-mcp architecture

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

- Interactive diagram: https://gitdiagram.com/sepehr071/amar-mcp
- Repository: https://github.com/sepehr071/amar-mcp

## Overview

amar-mcp is a read-only MCP server that exposes Iran’s Statistical Centre data to AI clients. The main workflow is an MCP tool request, server dispatch, retrieval of catalog pages or files, and parsing into compact JSON. The graph separates catalog/news/calendar, statistical data tools, macroeconomic tools, and shared transport/registration. README-documented capabilities are included, but unsampled tool implementations are represented at their existing module paths; edges are limited to relationships shown in the excerpts or README.

Main entry points: [`src/amar_mcp/server.py`](https://github.com/sepehr071/amar-mcp/blob/main/src/amar_mcp/server.py) (MCP server), [`src/amar_mcp/http.py`](https://github.com/sepehr071/amar-mcp/blob/main/src/amar_mcp/http.py) (HTTP client), [`src/amar_mcp/site.py`](https://github.com/sepehr071/amar-mcp/blob/main/src/amar_mcp/site.py) (Release details), [`src/amar_mcp/data.py`](https://github.com/sepehr071/amar-mcp/blob/main/src/amar_mcp/data.py) (CPI inflation)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_entry["MCP entry"]
  node_server["MCP server<br/>[server.py]"]
  node_registry["Tool registry<br/>[registry.py]"]
end

subgraph group_catalog["Portal catalog"]
  node_search["Release search<br/>[site.py]"]
  node_release["Release details<br/>[site.py]"]
  node_calendar["Publishing calendar<br/>[site.py]"]
  node_news["News reader<br/>[site.py]"]
end

subgraph group_statistics["Statistical data"]
  node_inflation["CPI inflation<br/>[data.py]"]
  node_labour["Labour force<br/>[data.py]"]
  node_population["Census population<br/>[data.py]"]
  node_table["Excel table reader<br/>[data.py]"]
end

subgraph group_macroeconomy["Macro data"]
  node_indicators["Macro indicators<br/>[macro.py]"]
  node_gdp["GDP growth<br/>[macro.py]"]
  node_ppi["Producer prices<br/>[macro.py]"]
end

subgraph group_transport["Shared infrastructure"]
  node_http["HTTP client<br/>[http.py]"]
end

node_client(("MCP client"))
node_portal["amar.org.ir"]
node_workbooks["Excel workbooks"]

node_client -->|"calls tools"| node_server
node_server -->|"registers tools"| node_registry
node_server -->|"dispatches"| node_search
node_server -->|"dispatches"| node_release
node_server -->|"dispatches"| node_calendar
node_server -->|"dispatches"| node_news
node_server -->|"dispatches"| node_inflation
node_server -->|"dispatches"| node_labour
node_server -->|"dispatches"| node_population
node_server -->|"dispatches"| node_table
node_server -->|"dispatches"| node_indicators
node_server -->|"dispatches"| node_gdp
node_server -->|"dispatches"| node_ppi
node_search -->|"fetches pages"| node_http
node_release -->|"fetches pages"| node_http
node_calendar -->|"fetches calendar"| node_http
node_news -->|"fetches news"| node_http
node_inflation -->|"downloads files"| node_http
node_labour -->|"downloads files"| node_http
node_population -->|"downloads files"| node_http
node_table -->|"downloads files"| node_http
node_inflation -->|"loads release"| node_release
node_table -->|"loads release"| node_release
node_indicators -->|"downloads files"| node_http
node_indicators -->|"finds workbook"| node_release
node_gdp -->|"downloads files"| node_http
node_gdp -->|"finds workbook"| node_release
node_ppi -->|"downloads files"| node_http
node_ppi -->|"finds workbook"| node_release
node_http -->|"requests data"| node_portal
node_http -->|"downloads files"| node_workbooks
node_table -->|"parses sheets"| node_workbooks
node_inflation -->|"parses CPI"| node_workbooks
node_indicators -->|"parses indicators"| node_workbooks
node_gdp -->|"parses GDP"| node_workbooks
node_ppi -->|"parses PPI"| node_workbooks

click node_server "https://github.com/sepehr071/amar-mcp/blob/main/src/amar_mcp/server.py"
click node_registry "https://github.com/sepehr071/amar-mcp/blob/main/src/amar_mcp/registry.py"
click node_search "https://github.com/sepehr071/amar-mcp/blob/main/src/amar_mcp/site.py"
click node_release "https://github.com/sepehr071/amar-mcp/blob/main/src/amar_mcp/site.py"
click node_calendar "https://github.com/sepehr071/amar-mcp/blob/main/src/amar_mcp/site.py"
click node_news "https://github.com/sepehr071/amar-mcp/blob/main/src/amar_mcp/site.py"
click node_inflation "https://github.com/sepehr071/amar-mcp/blob/main/src/amar_mcp/data.py"
click node_labour "https://github.com/sepehr071/amar-mcp/blob/main/src/amar_mcp/data.py"
click node_population "https://github.com/sepehr071/amar-mcp/blob/main/src/amar_mcp/data.py"
click node_table "https://github.com/sepehr071/amar-mcp/blob/main/src/amar_mcp/data.py"
click node_indicators "https://github.com/sepehr071/amar-mcp/blob/main/src/amar_mcp/macro.py"
click node_gdp "https://github.com/sepehr071/amar-mcp/blob/main/src/amar_mcp/macro.py"
click node_ppi "https://github.com/sepehr071/amar-mcp/blob/main/src/amar_mcp/macro.py"
click node_http "https://github.com/sepehr071/amar-mcp/blob/main/src/amar_mcp/http.py"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_server,node_registry,node_client toneBlue
class node_search,node_release,node_calendar,node_news toneAmber
class node_inflation,node_labour,node_population,node_table toneMint
class node_indicators,node_gdp,node_ppi toneRose
class node_http,node_portal,node_workbooks toneIndigo
```

## Components

### MCP entry

- [MCP server](https://github.com/sepehr071/amar-mcp/blob/main/src/amar_mcp/server.py): `src/amar_mcp/server.py`
- [Tool registry](https://github.com/sepehr071/amar-mcp/blob/main/src/amar_mcp/registry.py): `src/amar_mcp/registry.py`

### Portal catalog

- [Release search](https://github.com/sepehr071/amar-mcp/blob/main/src/amar_mcp/site.py): `src/amar_mcp/site.py`
- [Release details](https://github.com/sepehr071/amar-mcp/blob/main/src/amar_mcp/site.py): `src/amar_mcp/site.py`
- [Publishing calendar](https://github.com/sepehr071/amar-mcp/blob/main/src/amar_mcp/site.py): `src/amar_mcp/site.py`
- [News reader](https://github.com/sepehr071/amar-mcp/blob/main/src/amar_mcp/site.py): `src/amar_mcp/site.py`

### Statistical data

- [CPI inflation](https://github.com/sepehr071/amar-mcp/blob/main/src/amar_mcp/data.py): `src/amar_mcp/data.py`
- [Labour force](https://github.com/sepehr071/amar-mcp/blob/main/src/amar_mcp/data.py): `src/amar_mcp/data.py`
- [Census population](https://github.com/sepehr071/amar-mcp/blob/main/src/amar_mcp/data.py): `src/amar_mcp/data.py`
- [Excel table reader](https://github.com/sepehr071/amar-mcp/blob/main/src/amar_mcp/data.py): `src/amar_mcp/data.py`

### Macro data

- [Macro indicators](https://github.com/sepehr071/amar-mcp/blob/main/src/amar_mcp/macro.py): `src/amar_mcp/macro.py`
- [GDP growth](https://github.com/sepehr071/amar-mcp/blob/main/src/amar_mcp/macro.py): `src/amar_mcp/macro.py`
- [Producer prices](https://github.com/sepehr071/amar-mcp/blob/main/src/amar_mcp/macro.py): `src/amar_mcp/macro.py`

### Shared infrastructure

- [HTTP client](https://github.com/sepehr071/amar-mcp/blob/main/src/amar_mcp/http.py): `src/amar_mcp/http.py`

### Other components

- **MCP client**
- **amar.org.ir**
- **Excel workbooks**

## Connections

- MCP client → MCP server: calls tools (evidence: `README.md`)
- MCP server → Tool registry: registers tools (evidence: `src/amar_mcp/server.py`)
- MCP server → Release search: dispatches (evidence: `src/amar_mcp/server.py`)
- MCP server → Release details: dispatches (evidence: `src/amar_mcp/server.py`)
- MCP server → Publishing calendar: dispatches (evidence: `src/amar_mcp/server.py`)
- MCP server → News reader: dispatches (evidence: `src/amar_mcp/server.py`)
- MCP server → CPI inflation: dispatches (evidence: `src/amar_mcp/server.py`)
- MCP server → Labour force: dispatches (evidence: `src/amar_mcp/server.py`)
- MCP server → Census population: dispatches (evidence: `src/amar_mcp/server.py`)
- MCP server → Excel table reader: dispatches (evidence: `src/amar_mcp/server.py`)
- MCP server → Macro indicators: dispatches (evidence: `src/amar_mcp/server.py`)
- MCP server → GDP growth: dispatches (evidence: `src/amar_mcp/server.py`)
- MCP server → Producer prices: dispatches (evidence: `src/amar_mcp/server.py`)
- Release search → HTTP client: fetches pages (evidence: `src/amar_mcp/site.py`)
- Release details → HTTP client: fetches pages (evidence: `src/amar_mcp/site.py`)
- Publishing calendar → HTTP client: fetches calendar (evidence: `src/amar_mcp/site.py`)
- News reader → HTTP client: fetches news (evidence: `src/amar_mcp/site.py`)
- CPI inflation → HTTP client: downloads files (evidence: `src/amar_mcp/data.py`)
- Labour force → HTTP client: downloads files (evidence: `src/amar_mcp/data.py`)
- Census population → HTTP client: downloads files (evidence: `src/amar_mcp/data.py`)
- Excel table reader → HTTP client: downloads files (evidence: `src/amar_mcp/data.py`)
- CPI inflation → Release details: loads release (evidence: `src/amar_mcp/data.py`)
- Excel table reader → Release details: loads release (evidence: `src/amar_mcp/data.py`)
- Macro indicators → HTTP client: downloads files (evidence: `src/amar_mcp/macro.py`)
- Macro indicators → Release details: finds workbook (evidence: `src/amar_mcp/macro.py`)
- GDP growth → HTTP client: downloads files (evidence: `src/amar_mcp/macro.py`)
- GDP growth → Release details: finds workbook (evidence: `src/amar_mcp/macro.py`)
- Producer prices → HTTP client: downloads files (evidence: `src/amar_mcp/macro.py`)
- Producer prices → Release details: finds workbook (evidence: `src/amar_mcp/macro.py`)
- HTTP client → amar.org.ir: requests data (evidence: `README.md`)
- HTTP client → Excel workbooks: downloads files (evidence: `README.md`)
- Excel table reader → Excel workbooks: parses sheets (evidence: `src/amar_mcp/data.py`)
- CPI inflation → Excel workbooks: parses CPI (evidence: `src/amar_mcp/data.py`)
- Macro indicators → Excel workbooks: parses indicators (evidence: `src/amar_mcp/macro.py`)
- GDP growth → Excel workbooks: parses GDP (evidence: `src/amar_mcp/macro.py`)
- Producer prices → Excel workbooks: parses PPI (evidence: `src/amar_mcp/macro.py`)
