# rugvedp/trends-mcp architecture

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

- Interactive diagram: https://gitdiagram.com/rugvedp/trends-mcp
- Repository: https://github.com/rugvedp/trends-mcp

## Overview

1. **Repository shape**
   - This is a small Python MCP service centered on a single server entrypoint: `src/server.py` (also referenced as `server.py` in the README).
   - The other top-level files are support artifacts: `requirements.txt` for Python dependencies, `mcp_config_mac.json` / `mcp_config_win.json` for client launch configuration, `test.py` for local testing, and `temp.json` as a scratch/output file.

2. **Core runtime boundary**
   - The main runtime is **FastMCP**.
   - The server is launched either directly with `fastmcp run server.py` or indirectly through an MCP client configuration that shells out via `uv`.
   - This makes the repository an MCP tool provider rather than a traditional web application.

3. **Primary responsibility**
   - The service aggregates “what’s trending” data from social platforms and exposes it as MCP tools.
   - Its job is to translate MCP tool calls into platform-specific scraping/API requests, then return normalized results to the caller.

4. **Exposed tool layer**
   - The README lists six tools:
     - YouTube comments by video ID
     - YouTube global trending
     - YouTube region-specific trending
     - YouTube video metadata
     - TikTok trending summaries
     - Instagram Reels weekly trend scraping
   - These tools form the public API surface of the repository.

5. **YouTube subsystem**
   - YouTube features are implemented through a mix of scraping and metadata extraction.
   - Dependencies such as `youtube-comment-downloader` and `yt_dlp` suggest two different data paths:
     - comment retrieval from a video ID
     - video/trending metadata extraction
   - The YouTube trending endpoints likely read from public feeds or pages rather than authenticated APIs.

6. **TikTok subsystem**
   - TikTok trending is handled via **RapidAPI**, not direct scraping.
   - The README indicates an external token is required, passed through environment configuration (`tiktok` in the MCP config).
   - This creates a clear dependency boundary: the server delegates TikTok data acquisition to a third-party API provider.

7. **Instagram subsystem**
   - Instagram Reels trends are collected by scraping Later.com’s blog post about trends.
   - This is a pure HTML-parsing path using `requests` and `beautifulsoup4`.
   - The dependency is intentionally indirect: the repo does not talk to Instagram itself, but to a third-party article that summarizes trends.

8. **Data flow**
   - MCP client or local CLI invokes a tool.
   - FastMCP routes the call into the corresponding function in `server.py`.
   - That function fetches data from an external site/API, parses or summarizes it, then returns structured content back through the MCP response channel.
   - The architecture is therefore request/response with no persistent internal datastore.

9. **External integrations and trust boundaries**
   - External dependencies are the main architectural risk and variability:
     - YouTube public pages and unofficial comment scraping
     - TikTok RapidAPI
     - Later.com HTML structure
   - The README explicitly notes that YouTube scraping and Instagram parsing may break if upstream layouts change, which means the system is brittle to upstream UI changes.

10. **Configuration and deployment**
   - The provided MCP config files are important for local integration with desktop or CLI MCP clients.
   - They define the command invocation and environment variables needed to start the server.
   - The repo appears designed for local/private use rather than a hosted multi-tenant service.

11. **Dependencies that materially affect the architecture**
   - `fastmcp` defines the tool-server model.
   - `requests` and `beautifulsoup4` support HTTP fetching and parsing.
   - `yt_dlp` and `youtube-comment-downloader` support YouTube-specific extraction.
   - These libraries imply a scraping-heavy architecture with lightweight Python orchestration, not a database-backed service.

12. **What to draw in an architecture diagram**
   - A central FastMCP server box in Python.
   - Six tool handlers inside it.
   - Three external data-source groups: YouTube, TikTok RapidAPI, and Later.com.
   - A client boundary on the left for MCP consumers/CLI.
   - An env-config/input boundary for the TikTok token.
   - No persistent storage, queueing, or internal microservices are indicated by the repository structure.

Main entry points: [`src/server.py`](https://github.com/rugvedp/trends-mcp/blob/main/src/server.py) (FastMCP server), [`requirements.txt`](https://github.com/rugvedp/trends-mcp/blob/main/requirements.txt) (Dependencies), [`mcp_config_mac.json`](https://github.com/rugvedp/trends-mcp/blob/main/mcp_config_mac.json) (Mac config), [`mcp_config_win.json`](https://github.com/rugvedp/trends-mcp/blob/main/mcp_config_win.json) (Windows config)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_client["MCP clients"]
  node_mcp_client(("MCP client<br/>consumer"))
  node_local_cli(("uv/CLI<br/>launcher"))
end

subgraph group_runtime["Python MCP runtime"]
  node_fastmcp_server["FastMCP server<br/>mcp runtime<br/>[server.py]"]
  node_tool_yt_comments["YT comments<br/>tool<br/>[server.py]"]
  node_tool_yt_global["YT trending<br/>tool<br/>[server.py]"]
  node_tool_yt_region["YT region trend<br/>tool<br/>[server.py]"]
  node_tool_yt_meta["YT metadata<br/>tool<br/>[server.py]"]
  node_tool_tiktok["TikTok trend<br/>tool<br/>[server.py]"]
  node_tool_instagram["Instagram reels<br/>tool<br/>[server.py]"]
end

subgraph group_sources["External sources"]
  node_youtube_public["YouTube pages<br/>public web source"]
  node_youtube_comments_source["Comment source<br/>scrape path"]
  node_youtube_metadata_source["YT metadata feed<br/>metadata source"]
  node_tiktok_rapidapi[("RapidAPI<br/>third-party api")]
  node_later_blog["Later.com post<br/>html source"]
end

subgraph group_config["Support files"]
  node_requirements["Dependencies<br/>python deps<br/>[requirements.txt]"]
  node_mac_config["Mac config<br/>mcp config"]
  node_win_config["Windows config<br/>mcp config"]
  node_scratch["Scratch file<br/>local artifact<br/>[temp.json]"]
  node_test_local["Local test<br/>test harness<br/>[test.py]"]
end

node_mcp_client -->|"MCP calls"| node_fastmcp_server
node_local_cli -->|"launches"| node_mac_config
node_local_cli -->|"launches"| node_win_config
node_mac_config -.->|"runs"| node_fastmcp_server
node_win_config -.->|"runs"| node_fastmcp_server
node_requirements -.->|"supports"| node_fastmcp_server
node_test_local -.->|"tests"| node_fastmcp_server
node_fastmcp_server -->|"exposes"| node_tool_yt_comments
node_fastmcp_server -->|"exposes"| node_tool_yt_global
node_fastmcp_server -->|"exposes"| node_tool_yt_region
node_fastmcp_server -->|"exposes"| node_tool_yt_meta
node_fastmcp_server -->|"exposes"| node_tool_tiktok
node_fastmcp_server -->|"exposes"| node_tool_instagram
node_tool_yt_comments -->|"scrapes"| node_youtube_comments_source
node_tool_yt_global -->|"reads"| node_youtube_public
node_tool_yt_region -->|"reads"| node_youtube_public
node_tool_yt_meta -->|"extracts"| node_youtube_metadata_source
node_tool_tiktok -->|"queries"| node_tiktok_rapidapi
node_tool_instagram -->|"parses"| node_later_blog
node_tool_yt_comments -.->|"depends on"| node_requirements
node_tool_yt_meta -.->|"depends on"| node_requirements
node_tool_tiktok -.->|"uses token"| node_mac_config

click node_fastmcp_server "https://github.com/rugvedp/trends-mcp/blob/main/src/server.py"
click node_tool_yt_comments "https://github.com/rugvedp/trends-mcp/blob/main/src/server.py"
click node_tool_yt_global "https://github.com/rugvedp/trends-mcp/blob/main/src/server.py"
click node_tool_yt_region "https://github.com/rugvedp/trends-mcp/blob/main/src/server.py"
click node_tool_yt_meta "https://github.com/rugvedp/trends-mcp/blob/main/src/server.py"
click node_tool_tiktok "https://github.com/rugvedp/trends-mcp/blob/main/src/server.py"
click node_tool_instagram "https://github.com/rugvedp/trends-mcp/blob/main/src/server.py"
click node_requirements "https://github.com/rugvedp/trends-mcp/blob/main/requirements.txt"
click node_mac_config "https://github.com/rugvedp/trends-mcp/blob/main/mcp_config_mac.json"
click node_win_config "https://github.com/rugvedp/trends-mcp/blob/main/mcp_config_win.json"
click node_scratch "https://github.com/rugvedp/trends-mcp/blob/main/temp.json"
click node_test_local "https://github.com/rugvedp/trends-mcp/blob/main/test.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_mcp_client,node_local_cli toneBlue
class node_fastmcp_server,node_tool_yt_comments,node_tool_yt_global,node_tool_yt_region,node_tool_yt_meta,node_tool_tiktok,node_tool_instagram toneAmber
class node_youtube_public,node_youtube_comments_source,node_youtube_metadata_source,node_tiktok_rapidapi,node_later_blog toneMint
class node_requirements,node_mac_config,node_win_config,node_scratch,node_test_local toneRose
```

## Components

### MCP clients

Local desktop or CLI consumers that invoke the server

- **MCP client**: consumer · Calls exposed tools through MCP
- **uv/CLI**: launcher · Starts the server locally from config or shell

### Python MCP runtime

FastMCP server and its tool handlers

- [FastMCP server](https://github.com/rugvedp/trends-mcp/blob/main/src/server.py): mcp runtime · Main server entrypoint and dispatcher · `src/server.py`
- [YT comments](https://github.com/rugvedp/trends-mcp/blob/main/src/server.py): tool · Fetch comments by video ID · `src/server.py`
- [YT trending](https://github.com/rugvedp/trends-mcp/blob/main/src/server.py): tool · Fetch global YouTube trending content · `src/server.py`
- [YT region trend](https://github.com/rugvedp/trends-mcp/blob/main/src/server.py): tool · Fetch region-specific YouTube trending content · `src/server.py`
- [YT metadata](https://github.com/rugvedp/trends-mcp/blob/main/src/server.py): tool · Extract YouTube video metadata · `src/server.py`
- [TikTok trend](https://github.com/rugvedp/trends-mcp/blob/main/src/server.py): tool · Summarize TikTok trending content · `src/server.py`
- [Instagram reels](https://github.com/rugvedp/trends-mcp/blob/main/src/server.py): tool · Scrape weekly Instagram Reels trends · `src/server.py`

### External sources

Upstream sites and APIs scraped or queried by the tools

- **YouTube pages**: public web source · Public video, trending, and feed pages
- **Comment source**: scrape path · Unofficial comment retrieval from video IDs
- **YT metadata feed**: metadata source · Video metadata extraction path used by yt_dlp
- **RapidAPI**: third-party api · External TikTok data provider requiring a token
- **Later.com post**: html source · Blog article parsed for Instagram Reels trends

### Support files

Launch configs and local support artifacts

- [Dependencies](https://github.com/rugvedp/trends-mcp/blob/main/requirements.txt): python deps · Pinned runtime libraries and scraper dependencies · `requirements.txt`
- [Mac config](https://github.com/rugvedp/trends-mcp/blob/main/mcp_config_mac.json): mcp config · macOS MCP launch configuration · `mcp_config_mac.json`
- [Windows config](https://github.com/rugvedp/trends-mcp/blob/main/mcp_config_win.json): mcp config · Windows MCP launch configuration · `mcp_config_win.json`
- [Scratch file](https://github.com/rugvedp/trends-mcp/blob/main/temp.json): local artifact · Temporary output or test data · `temp.json`
- [Local test](https://github.com/rugvedp/trends-mcp/blob/main/test.py): test harness · Manual testing entrypoint · `test.py`

## Connections

- MCP client → FastMCP server: MCP calls · Client invokes server tools
- uv/CLI → Mac config: launches · Local CLI can start the server using config
- uv/CLI → Windows config: launches · Windows client config starts the server
- Mac config → FastMCP server: runs · Launch config points at the FastMCP entrypoint
- Windows config → FastMCP server: runs · Launch config points at the FastMCP entrypoint
- Dependencies → FastMCP server: supports · Dependencies enable the MCP runtime and scrapers
- Local test → FastMCP server: tests · Local testing exercises server behavior
- FastMCP server → YT comments: exposes · Registers tool handler
- FastMCP server → YT trending: exposes · Registers tool handler
- FastMCP server → YT region trend: exposes · Registers tool handler
- FastMCP server → YT metadata: exposes · Registers tool handler
- FastMCP server → TikTok trend: exposes · Registers tool handler
- FastMCP server → Instagram reels: exposes · Registers tool handler
- YT comments → Comment source: scrapes · Fetches comments from video IDs
- YT trending → YouTube pages: reads · Pulls global trending data from public pages
- YT region trend → YouTube pages: reads · Pulls region-specific trending data from public pages
- YT metadata → YT metadata feed: extracts · Uses metadata extraction path for videos
- TikTok trend → RapidAPI: queries · Delegates TikTok trending lookup to RapidAPI
- Instagram reels → Later.com post: parses · Scrapes trend summaries from Later.com
- YT comments → Dependencies: depends on · Uses scraper libraries
- YT metadata → Dependencies: depends on · Uses yt_dlp metadata extraction
- TikTok trend → Mac config: uses token · MCP config provides environment token for the API