GitHub Trending Analyzer

Note: This repo is fully auto generated by aider with GEMINI-2.5-pro. cost USD $1.91.

This project analyzes trending GitHub repositories for a specified programming language. It fetches daily trending repositories using a Model Context Protocol (MCP) compliant server (like mcp-github-trending), randomly selects one, retrieves its README file, and uses LiteLLM to generate:

• A concise summary
• Potential use cases
• Key advantages
• A sample code snippet (if available in the README)

The analysis logic is orchestrated using LangGraph, and MCP interaction is handled via the langchain-mcp-adapters library.

Features

• Fetches trending repositories via a configured MCP server (supports stdio, sse, etc.). Configuration loaded from a separate JSON file.
• Selects a random repository from the list.
• Fetches the README content from GitHub (trying main and master branches).
• Analyzes README content using LiteLLM (configurable model).
• Outputs analysis results (summary, use cases, advantages, sample code).
• Command-line interface using Click.
• Configuration via environment variables (.env file) and a dedicated MCP config JSON file.
• Logging level configurable via LOG_LEVEL environment variable.
• Retry logic for GitHub README fetching.
• LangGraph agent orchestration.
• Includes Dockerfile for containerization.
• Makefile for common development tasks.
• Uses uv for fast package management and script execution.
• Code linting and formatting with ruff.

Prerequisites

• Python 3.11+
• uv (required for package management and running scripts)
• Docker (optional, for containerized execution)
• Access to a running MCP GitHub Trending server instance (or equivalent MCP server providing a compatible tool). Ensure the server executable is available if using stdio transport.
• Access to an LLM API compatible with LiteLLM (e.g., OpenAI, Anthropic).

Setup

1. Clone the repository:

   git clone <repository-url>
   cd github-trending-analyzer
   

2. Create MCP Configuration File: Create a JSON file (e.g., mcp_config.json) to define your MCP server connections. See mcp_config.example.json for the structure.

   • Example mcp_config.json for stdio transport:

     {
       "github_trending": {
         "command": "python",
         "args": ["/full/path/to/your/mcp_github_trending_server.py"],
         "transport": "stdio"
       }
     }
     

     • Replace /full/path/to/your/mcp_github_trending_server.py with the actual absolute path to the server executable/script. Relative paths might work depending on the execution context, but absolute paths are safer.
     • The key ("github_trending") is an internal name you choose for this configuration block.

   • Example mcp_config.json for sse transport:

     {
       "some_other_server": {
         "url": "http://localhost:8001/sse",
         "transport": "sse"
       }
     }
     

3. Create a .env file: Copy the template and fill in your configuration details:

   cp .env.template .env
   

   Edit .env with your specific values:

   • LOG_LEVEL (Optional, Default: INFO): Set the logging verbosity. Options: DEBUG, INFO, WARNING, ERROR, CRITICAL.
   • MCP_CONFIG_FILE_PATH (Required): The absolute or relative path to the JSON file you created in the previous step (e.g., MCP_CONFIG_FILE_PATH=./mcp_config.json or MCP_CONFIG_FILE_PATH=/etc/app/mcp_config.json).
   • MCP_GITHUB_TOOL_NAME (Required): The exact name of the tool exposed by your MCP server for fetching trending repositories (e.g., get_trending_repos). Check the MCP server's definition for the correct name.
   • GITHUB_API_TOKEN (Optional): Your GitHub Personal Access Token for higher API rate limits when fetching READMEs.
   • LITELLM_MODEL: The identifier of the LLM model you want to use (e.g., gpt-4o, claude-3-opus-20240229).
   • LITELLM_API_KEY (Optional but likely required): Your API key for the chosen LLM service.
   • LITELLM_API_BASE (Optional): Custom base URL if using a self-hosted or proxy service.

4. Install dependencies using uv: This command installs packages listed in pyproject.toml (including langchain-mcp-adapters) and creates/updates the uv.lock file.

   make install
   # or directly:
   # uv pip install -r pyproject.toml
   # uv lock
   

Usage

Command Line Interface (CLI) via uv run

Ensure your configured MCP server process can be started (for stdio) or is running and accessible (for sse/http). Make sure the path in MCP_CONFIG_FILE_PATH is correct relative to where you run the command. Set LOG_LEVEL in your environment or .env file to control output verbosity.

Run the analysis directly using uv run, which executes commands within the Python environment managed by uv. You must specify the programming language.