github-events-monitor 0.2.3

GitHub Events Monitor with FastAPI and MCP server

GitHub Events Monitor

A production-ready Python application that monitors GitHub Events API and provides real-time metrics via REST API and MCP (Model Context Protocol) server.

🎯 Features

• Real-time GitHub Events Monitoring: Streams WatchEvent, PullRequestEvent, and IssuesEvent
• REST API: FastAPI-based metrics and visualization endpoints
• MCP Server: Model Context Protocol integration for AI tools (Claude Desktop, Cursor)
• Production Ready: Comprehensive testing (35 tests), Docker support, proper packaging
• Scalable Architecture: SQLite with easy PostgreSQL migration path

🚀 Quick Start

Setup with uv

uv sync

Setup with pip

pip install -r requirements.txt

Setup with poetry

poetry install

Run the application

uv run github-events-monitor-api
# or
python -m github_events_monitor.api

Run the MCP server

uv run github-events-monitor-mcp
# or
python -m github_events_monitor.mcp_server

Run the tests

uv run pytest
# or
pytest

Local Development

export GITHUB_TOKEN=your_github_token_here

# Run REST API server
python -m github_events_monitor.api

# Or run MCP server
python -m github_events_monitor.mcp_server

Docker Deployment

# Using Docker Compose (recommended)
docker-compose up -d

# Or with Docker directly
docker run -d \
  --name github-events-monitor \
  -p 8000:8000 \
  -e GITHUB_TOKEN=your_token \
  sparesparrow/github-events-monitor:latest

📊 API Endpoints

Core Metrics (Assignment Requirements)

• GET /metrics/event-counts?offset_minutes=10 - Event counts by type with time offset
• GET /metrics/pr-interval?repo=owner/repo - Average time between pull requests

Additional Features

• GET /metrics/repository-activity?repo=owner/repo&hours=24 - Repository activity summary
• GET /metrics/trending?hours=24&limit=10 - Trending repositories
• GET /visualization/trending-chart - Chart visualization (bonus)
• GET /health - Health check endpoint

Documentation

• Interactive API docs available at http://localhost:8000/docs
• OpenAPI specification at http://localhost:8000/openapi.json

🎯 Use Cases

1. Real-time Repository Health Check

Monitor short-term activity and overall health when you need a quick pulse (on-call, triage, stakeholder reviews).

# Get event volume by type over last 60 minutes
curl "http://localhost:8000/metrics/event-counts?offset_minutes=60"

# Check repository activity for last 24 hours
curl "http://localhost:8000/metrics/repository-activity?repo=owner/repo&hours=24"

2. Release Readiness Assessment

Assess if a codebase is trending toward a stable release by looking at PR cadence and activity distribution.

# Get average time between pull requests
curl "http://localhost:8000/metrics/pr-interval?repo=owner/repo"

3. Development Velocity Tracking

Track how frequently contributors open pull requests as a proxy for development velocity.

4. Incident Detection

Detect sudden spikes in Issues or PRs that may indicate incidents or regressions.

5. Community Interest Monitoring

Use WatchEvent counts as an interest/awareness signal for marketing or devrel purposes.

🏗️ Architecture

GitHub API → [Background Collector] → [SQLite DB] → [Metrics Engine] → [REST API / MCP Server]

• Background Collector: Async polling with rate limiting and ETag caching
• SQLite Database: Local storage with optimized indices
• REST API: FastAPI endpoints for metrics and visualizations
• MCP Server: AI tool integration via Model Context Protocol

🧪 Testing

# Run all tests
pytest

# Run specific test categories
pytest tests/unit          # Unit tests
pytest tests/integration   # Integration tests

# With coverage
pytest --cov=src/github_events_monitor

Test Results: 35/35 tests passing (100% success rate)

📦 Project Structure

src/
└── github_events_monitor/
    ├── api.py              # REST API endpoints
    ├── collector.py        # GitHub events collection
    ├── config.py           # Configuration management
    └── mcp_server.py       # MCP server implementation

tests/
├── unit/                   # Unit tests
└── integration/            # Integration tests

docs/                       # Documentation
├── ARCHITECTURE.md         # System architecture and C4 diagrams
├── DEPLOYMENT.md           # Deployment guides
├── API.md                  # API documentation
├── DEVELOPMENT.md          # Development setup
└── ASSIGNMENT.md           # Assignment compliance

🔧 Configuration

Environment variables:

Variable	Default	Description
GITHUB_TOKEN	None	GitHub Personal Access Token (recommended for higher rate limits)
DATABASE_PATH	./github_events.db	SQLite database file path
API_HOST	0.0.0.0	API server host
API_PORT	8000	API server port
POLL_INTERVAL	300	GitHub API polling interval (seconds)
MCP_MODE	false	Set to true to run MCP server instead of REST API

📋 Assignment Compliance

This project fully implements the specified assignment requirements:

• ✅ GitHub Events Streaming: Monitors WatchEvent, PullRequestEvent, IssuesEvent
• ✅ REST API: Provides metrics at any time
• ✅ Required Metrics:
  • Average time between pull requests for a repository
  • Event counts grouped by type for a given time offset
• ✅ Bonus Visualization: Chart endpoints for meaningful visualizations
• ✅ Python Implementation: Pure Python 3.11+ with async architecture
• ✅ Documentation: Comprehensive README and C4 Level 1 diagram
• ✅ Production Quality: 8-hour development estimate, production-ready code

🚀 Deployment Options

Local Development

Quick setup for development and testing.

Docker

Containerized deployment for consistent environments.

Production

Scalable deployment with proper monitoring and error handling.

See docs/DEPLOYMENT.md for detailed deployment guides.

🤝 MCP Integration

The project includes a full MCP server implementation compatible with:

• Claude Desktop
• Cursor IDE
• Other MCP-compatible tools

Tools available:

• get_event_counts - Retrieve event counts with time filtering
• get_repository_activity - Get repository activity summaries
• get_trending_repositories - Find trending repositories
• get_avg_pr_interval - Calculate average PR intervals

📖 Documentation

• Architecture: System design and C4 diagrams
• Deployment: Docker, local, and production deployment
• API Reference: Complete API documentation
• Development: Development setup and guidelines
• Assignment: Assignment requirements compliance

📊 Quality Metrics

• Tests: 35 tests (100% passing)
• Coverage: Comprehensive unit, integration, and API tests
• Performance: <100ms API response times
• Security: Environment-based configuration, input validation
• Documentation: Complete API docs and architecture diagrams

🔒 Security

• No sensitive data hardcoded
• Environment variable configuration
• Input validation with Pydantic
• Rate limiting for API protection
• Only public GitHub data accessed

📝 License

MIT License - see LICENSE file for details.

🙋 Support

• Documentation: Comprehensive guides in /docs
• API Docs: Interactive documentation at /docs endpoint
• Issues: Report issues on GitHub repository
• Examples: See use cases and examples above

---

Status: ✅ Production Ready | Version: 0.2.3 | Tests: 35/35 Passing