# zulfaaisha832-max/ai-news-mcp-agent architecture

> Architecture diagram of the GitHub repository zulfaaisha832-max/ai-news-mcp-agent, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-09-30). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/zulfaaisha832-max/ai-news-mcp-agent
- Repository: https://github.com/zulfaaisha832-max/ai-news-mcp-agent

## Overview

AI News MCP Agent is a personal research assistant: the agent fetches and filters news, generates a summary and learning recommendations, then uses its MCP tool connections to find YouTube resources, save a report to Notion, and send a Gmail notification. The graph also preserves the documented service integrations and the separate script-based entry point. Source excerpts establish the main agent calls and news/Gemini behavior; some server and integration details are documented only in the README, so those edges cite it.

Main entry points: [`agent.py`](https://github.com/zulfaaisha832-max/ai-news-mcp-agent/blob/master/agent.py) (Agent Orchestrator), [`mcp_client.py`](https://github.com/zulfaaisha832-max/ai-news-mcp-agent/blob/master/mcp_client.py) (MCP Client), [`main.py`](https://github.com/zulfaaisha832-max/ai-news-mcp-agent/blob/master/main.py) (Script Entry Point), [`servers/notion_server.py`](https://github.com/zulfaaisha832-max/ai-news-mcp-agent/blob/master/servers/notion_server.py) (Notion Tool Server)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_workflow["Agent Workflow"]
  node_agent["Agent Orchestrator<br/>[agent.py]"]
  node_brain["Tool Decision<br/>[ai_brain.py]"]
  node_mcpclient["MCP Client<br/>[mcp_client.py]"]
end

subgraph group_analysis["News And Learning"]
  node_news["News Fetching<br/>[news.py]"]
  node_summary["News Summary<br/>[summary.py]"]
  node_learning["Learning Suggestions<br/>[learning.py]"]
end

subgraph group_mcp["MCP Integrations"]
  node_notionserver["Notion Tool Server<br/>[notion_server.py]"]
  node_youtubeserver["YouTube Tool Server<br/>[youtube_server.py]"]
  node_gmailserver["Gmail Tool Server<br/>[gmail_server.py]"]
end

subgraph group_scripts["Standalone Scripts"]
  node_mainentry["Script Entry Point<br/>[main.py]"]
  node_youtube_tool["YouTube Search Script<br/>[youtube.py]"]
  node_notion_tool["Notion Script Tool<br/>[notion.py]"]
  node_gmail_tool["Gmail Script Tool<br/>[gmail.py]"]
end

node_user(("Report Request"))
node_notionapi[("Notion")]
node_youtubeapi["YouTube"]
node_gmailapi["Gmail"]
node_newsapi["News API"]
node_gemini["Gemini"]

node_user -->|"requests report"| node_agent
node_agent -->|"connects servers"| node_mcpclient
node_agent -->|"fetches news"| node_news
node_agent -->|"generates summary"| node_summary
node_agent -->|"generates learning"| node_learning
node_agent -->|"chooses tools"| node_brain
node_news -->|"requests articles"| node_newsapi
node_summary -->|"generates summary"| node_gemini
node_learning -->|"generates suggestions"| node_gemini
node_brain -->|"requests decision"| node_gemini
node_mcpclient -->|"starts server"| node_notionserver
node_mcpclient -->|"starts server"| node_youtubeserver
node_mcpclient -->|"starts server"| node_gmailserver
node_agent -->|"calls search tool"| node_youtubeserver
node_agent -->|"calls save tool"| node_notionserver
node_agent -->|"calls email tool"| node_gmailserver
node_notionserver -->|"creates report page"| node_notionapi
node_youtubeserver -.->|"searches videos"| node_youtubeapi
node_gmailserver -->|"sends report email"| node_gmailapi
node_mainentry -->|"runs script"| node_notion_tool
node_mainentry -->|"runs script"| node_gmail_tool
node_mainentry -->|"runs script"| node_youtube_tool
node_notion_tool -->|"stores knowledge"| node_notionapi
node_gmail_tool -->|"sends notifications"| node_gmailapi
node_youtube_tool -->|"searches resources"| node_youtubeapi

click node_agent "https://github.com/zulfaaisha832-max/ai-news-mcp-agent/blob/master/agent.py"
click node_brain "https://github.com/zulfaaisha832-max/ai-news-mcp-agent/blob/master/ai_brain.py"
click node_mcpclient "https://github.com/zulfaaisha832-max/ai-news-mcp-agent/blob/master/mcp_client.py"
click node_news "https://github.com/zulfaaisha832-max/ai-news-mcp-agent/blob/master/tools/news.py"
click node_summary "https://github.com/zulfaaisha832-max/ai-news-mcp-agent/blob/master/tools/summary.py"
click node_learning "https://github.com/zulfaaisha832-max/ai-news-mcp-agent/blob/master/tools/learning.py"
click node_notionserver "https://github.com/zulfaaisha832-max/ai-news-mcp-agent/blob/master/servers/notion_server.py"
click node_youtubeserver "https://github.com/zulfaaisha832-max/ai-news-mcp-agent/blob/master/servers/youtube_server.py"
click node_gmailserver "https://github.com/zulfaaisha832-max/ai-news-mcp-agent/blob/master/servers/gmail_server.py"
click node_mainentry "https://github.com/zulfaaisha832-max/ai-news-mcp-agent/blob/master/main.py"
click node_youtube_tool "https://github.com/zulfaaisha832-max/ai-news-mcp-agent/blob/master/tools/youtube.py"
click node_notion_tool "https://github.com/zulfaaisha832-max/ai-news-mcp-agent/blob/master/tools/notion.py"
click node_gmail_tool "https://github.com/zulfaaisha832-max/ai-news-mcp-agent/blob/master/tools/gmail.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_agent,node_brain,node_mcpclient toneBlue
class node_news,node_summary,node_learning,node_notionapi toneAmber
class node_notionserver,node_youtubeserver,node_gmailserver,node_user,node_newsapi toneMint
class node_mainentry,node_youtube_tool,node_notion_tool,node_gmail_tool toneRose
class node_youtubeapi,node_gmailapi,node_gemini toneIndigo
```

## Components

### Agent Workflow

- [Agent Orchestrator](https://github.com/zulfaaisha832-max/ai-news-mcp-agent/blob/master/agent.py): `agent.py`
- [Tool Decision](https://github.com/zulfaaisha832-max/ai-news-mcp-agent/blob/master/ai_brain.py): `ai_brain.py`
- [MCP Client](https://github.com/zulfaaisha832-max/ai-news-mcp-agent/blob/master/mcp_client.py): `mcp_client.py`

### News And Learning

- [News Fetching](https://github.com/zulfaaisha832-max/ai-news-mcp-agent/blob/master/tools/news.py): `tools/news.py`
- [News Summary](https://github.com/zulfaaisha832-max/ai-news-mcp-agent/blob/master/tools/summary.py): `tools/summary.py`
- [Learning Suggestions](https://github.com/zulfaaisha832-max/ai-news-mcp-agent/blob/master/tools/learning.py): `tools/learning.py`

### MCP Integrations

- [Notion Tool Server](https://github.com/zulfaaisha832-max/ai-news-mcp-agent/blob/master/servers/notion_server.py): `servers/notion_server.py`
- [YouTube Tool Server](https://github.com/zulfaaisha832-max/ai-news-mcp-agent/blob/master/servers/youtube_server.py): `servers/youtube_server.py`
- [Gmail Tool Server](https://github.com/zulfaaisha832-max/ai-news-mcp-agent/blob/master/servers/gmail_server.py): `servers/gmail_server.py`

### Standalone Scripts

- [Script Entry Point](https://github.com/zulfaaisha832-max/ai-news-mcp-agent/blob/master/main.py): `main.py`
- [YouTube Search Script](https://github.com/zulfaaisha832-max/ai-news-mcp-agent/blob/master/tools/youtube.py): `tools/youtube.py`
- [Notion Script Tool](https://github.com/zulfaaisha832-max/ai-news-mcp-agent/blob/master/tools/notion.py): `tools/notion.py`
- [Gmail Script Tool](https://github.com/zulfaaisha832-max/ai-news-mcp-agent/blob/master/tools/gmail.py): `tools/gmail.py`

### Other components

- **Report Request**
- **Notion**
- **YouTube**
- **Gmail**
- **News API**
- **Gemini**

## Connections

- Report Request → Agent Orchestrator: requests report (evidence: `README.md`)
- Agent Orchestrator → MCP Client: connects servers (evidence: `agent.py`)
- Agent Orchestrator → News Fetching: fetches news (evidence: `agent.py`)
- Agent Orchestrator → News Summary: generates summary (evidence: `agent.py`)
- Agent Orchestrator → Learning Suggestions: generates learning (evidence: `agent.py`)
- Agent Orchestrator → Tool Decision: chooses tools (evidence: `agent.py`)
- News Fetching → News API: requests articles (evidence: `tools/news.py`)
- News Summary → Gemini: generates summary (evidence: `tools/summary.py`)
- Learning Suggestions → Gemini: generates suggestions (evidence: `tools/learning.py`)
- Tool Decision → Gemini: requests decision (evidence: `ai_brain.py`)
- MCP Client → Notion Tool Server: starts server (evidence: `mcp_client.py`)
- MCP Client → YouTube Tool Server: starts server (evidence: `mcp_client.py`)
- MCP Client → Gmail Tool Server: starts server (evidence: `mcp_client.py`)
- Agent Orchestrator → YouTube Tool Server: calls search tool (evidence: `agent.py`)
- Agent Orchestrator → Notion Tool Server: calls save tool (evidence: `agent.py`)
- Agent Orchestrator → Gmail Tool Server: calls email tool (evidence: `agent.py`)
- Notion Tool Server → Notion: creates report page (evidence: `servers/notion_server.py`)
- YouTube Tool Server → YouTube: searches videos (evidence: `README.md`)
- Gmail Tool Server → Gmail: sends report email (evidence: `servers/gmail_server.py`)
- Script Entry Point → Notion Script Tool: runs script (evidence: `main.py`)
- Script Entry Point → Gmail Script Tool: runs script (evidence: `main.py`)
- Script Entry Point → YouTube Search Script: runs script (evidence: `main.py`)
- Notion Script Tool → Notion: stores knowledge (evidence: `README.md`)
- Gmail Script Tool → Gmail: sends notifications (evidence: `README.md`)
- YouTube Search Script → YouTube: searches resources (evidence: `README.md`)