rugvedp/trends-mcp

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.