AI Agent with Custom GitHub MCP Tools

A complete AI agent system with custom Model Context Protocol (MCP) tools for GitHub repository analysis. Built with LangGraph, Gemini AI, FastMCP, and React.

🎯 What This Does

An AI agent that can:

• 📊 Analyze GitHub repositories - Get stars, forks, issues, activity stats
• 📦 Scan dependencies - Discover dependencies across Python, Node.js, Go, Rust, Ruby, Java
• 💬 Stream responses - Real-time AI responses through a web interface
• 🔧 Use custom tools - Extensible MCP architecture for adding new capabilities

🏗️ Architecture

┌─────────────────────────────────────────────────────────────────┐
│                         Browser (localhost:5173)                │
│                    React + TypeScript Frontend                  │
└────────────────────────────┬────────────────────────────────────┘
                             │
                             ↓
┌─────────────────────────────────────────────────────────────────┐
│                    UI Backend (localhost:5003)                  │
│                   Fastify + Node.js Proxy                       │
└────────────────────────────┬────────────────────────────────────┘
                             │
                             ↓
┌─────────────────────────────────────────────────────────────────┐
│                      Agent (localhost:8081)                     │
│              LangGraph + Gemini AI + LangChain                  │
└────────────────────────────┬────────────────────────────────────┘
                             │
                             ↓
┌─────────────────────────────────────────────────────────────────┐
│                   MCP Server (localhost:5001)                   │
│                    FastMCP + Custom Tools                       │
│  • GitHub Stats Tool        • GitHub Dependencies Tool          │
│  • Multiply Tool            • Code Review Tool                  │
└────────────────────────────┬────────────────────────────────────┘
                             │
                             ↓
                    GitHub Public API

🚀 Quick Start

Prerequisites

• Python 3.11+ for MCP server and agent
• Node.js 18+ for UI
• Gemini API key from https://ai.google.dev/

Step 1: Start the MCP Server

cd template-mcp-server

# Install dependencies
pip install -e .

# Start the server
python -m template_mcp_server.src.main

# Server runs on http://localhost:5001

Step 2: Start the Agent

cd template-agent

# Create .env file
cat > .env << EOF
GEMINI_API_KEY="your-gemini-api-key-here"
MCP_SERVER_HOST=http://localhost:5001/mcp/
MCP_TRANSPORT_PROTOCOL=streamable_http
AGENT_HOST=http://127.0.0.1:8081
AGENT_PORT=8081
EOF

# Install dependencies
pip install -e .

# Start the agent
python -m template_agent.src.main

# Agent runs on http://127.0.0.1:8081

Step 3: Start the UI

cd template-ui

# Create .env file
cat > .env << EOF
AGENT_HOST=http://127.0.0.1:8081
PORT=5003
AUTH_ENABLED=false
COOKIE_SIGN=super-secret-cookie-signing-key-minimum-32-chars-long
EOF

# Install dependencies
npm install

# Start both frontend and backend
npm run dev

# UI opens at http://localhost:5173

Step 4: Try It Out!

Open http://localhost:5173 and ask:

• "What are the stats for facebook/react?"
• "What are the dependencies for langchain-ai/langgraph?"
• "What is 25 times 17?"

📦 Project Structure

Hackathon/
├── template-mcp-server/          # Custom MCP tools server
│   ├── template_mcp_server/
│   │   └── src/
│   │       ├── tools/
│   │       │   ├── github_stats_tool.py       ⭐ Custom
│   │       │   └── github_dependencies_tool.py ⭐ Custom
│   │       ├── mcp.py            # Tool registration
│   │       └── settings.py       # Configuration
│   └── HACKATHON_SETUP.md        # Detailed MCP docs
│
├── template-agent/               # AI Agent with LangGraph
│   ├── template_agent/
│   │   └── src/
│   │       ├── core/
│   │       │   ├── agent.py      # Agent initialization
│   │       │   └── manager.py    # Conversation management
│   │       └── routes/
│   │           └── stream.py     # Streaming endpoint
│   ├── .env                      # Config (create this)
│   └── HACKATHON_SETUP.md        # Detailed agent docs
│
├── template-ui/                  # Web interface
│   ├── src/
│   │   ├── frontend/             # React app
│   │   └── server/               # Fastify backend
│   │       └── controllers/
│   │           └── v1/
│   │               └── agent.ts  # Proxy to agent
│   ├── index.html                # Frontend entry
│   ├── .env                      # Config (create this)
│   └── HACKATHON_SETUP.md        # Detailed UI docs
│
└── README.md                     # This file

🔧 Custom Tools We Built

1. GitHub Repository Stats

• Tool: get_github_repo_stats
• Input: owner/repo (e.g., microsoft/vscode)
• Output: Stars, forks, issues, PRs, languages, dates, URLs
• File: template-mcp-server/template_mcp_server/src/tools/github_stats_tool.py

2. GitHub Dependency Scanner

• Tool: get_github_dependencies
• Input: owner/repo
• Output: Dependencies by ecosystem (Python, Node.js, Go, Rust, Ruby, Java)
• File: template-mcp-server/template_mcp_server/src/tools/github_dependencies_tool.py

🎨 Key Features

• ✅ Real-time streaming - See AI responses as they're generated
• ✅ Tool use visualization - Watch the agent decide which tools to use
• ✅ Custom MCP tools - Easily add new capabilities
• ✅ Conversation history - Maintains context across messages
• ✅ HTML rendering - Agent can return styled HTML responses
• ✅ Error handling - Graceful fallbacks and error messages

🛠️ Tech Stack

MCP Server

• FastMCP - MCP protocol implementation
• Python 3.11 - Runtime
• Pydantic - Configuration management

Agent

• LangGraph - Agent orchestration
• LangChain - LLM framework
• Google Gemini - AI model (gemini-2.5-flash)
• Uvicorn - ASGI server

UI

• React 18 - Frontend framework
• TypeScript - Type safety
• Vite - Build tool and dev server
• Fastify - Backend API server
• TailwindCSS - Styling

📝 Configuration Files

MCP Server

No configuration needed - uses defaults from settings.py

Agent: template-agent/.env

GEMINI_API_KEY="your-key-here"              # Required
MCP_SERVER_HOST=http://localhost:5001/mcp/ # MCP endpoint
MCP_TRANSPORT_PROTOCOL=streamable_http      # Must match server
AGENT_HOST=http://127.0.0.1:8081            # Agent endpoint
AGENT_PORT=8081                             # Agent port

UI: template-ui/.env

AGENT_HOST=http://127.0.0.1:8081            # Agent endpoint
PORT=5003                                   # Backend port
AUTH_ENABLED=false                          # For development
COOKIE_SIGN=your-secret-key-here            # Cookie signing

🐛 Troubleshooting

MCP Server won't start

• Check if port 5001 is available: lsof -i :5001
• Verify Python 3.11+: python --version
• Check logs in terminal output

Agent won't start

• Verify Gemini API key is set in .env
• Check MCP server is running on port 5001
• Check if port 8081 is available: lsof -i :8081
• View logs: tail -f agent.log

UI won't start

• Check if ports 5003 and 5173 are available
• Verify Node.js 18+: node --version
• Check agent is running on port 8081
• View backend logs: tail -f server.log

"429 Quota Exceeded" Error

• You've hit Gemini's free tier limit (250 requests/day)
• Wait for quota reset or upgrade to paid plan
• Get new API key from different Google account

UI shows "failed to fetch"

• Verify all services are running
• Check browser console for CORS errors
• Ensure .env files have correct ports
• Try restarting the UI backend

📚 Further Reading

• Model Context Protocol (MCP)
• LangGraph Documentation
• Google Gemini API
• FastMCP

📊 Monitoring

View Logs

# MCP Server (stdout)
cd template-mcp-server && python -m template_mcp_server.src.main

# Agent
tail -f template-agent/agent.log

# UI Backend
tail -f template-ui/server.log

# UI Frontend
Check browser console (F12)

Check Service Status

# MCP Server
curl http://localhost:5001/

# Agent
curl http://127.0.0.1:8081/

# UI Backend
curl http://localhost:5003/

# UI Frontend
curl http://localhost:5173/

🎯 Example Interactions

GitHub Repository Analysis

User: "Compare the stats for facebook/react and vuejs/vue"

Agent:

1. Calls get_github_repo_stats("facebook/react")
2. Calls get_github_repo_stats("vuejs/vue")
3. Synthesizes comparison with Gemini
4. Returns styled HTML comparison

Dependency Discovery

User: "What dependencies does langchain-ai/langgraph use?"

Agent:

1. Calls get_github_dependencies("langchain-ai/langgraph")
2. Parses pyproject.toml
3. Returns organized list by category

Multi-Tool Usage

User: "Get stats for microsoft/vscode and check its dependencies"

Agent:

1. Calls get_github_repo_stats("microsoft/vscode")
2. Calls get_github_dependencies("microsoft/vscode")
3. Combines results into comprehensive report

🚦 Ports Summary

Service	Port	URL
MCP Server	5001	http://localhost:5001
Agent	8081	http://127.0.0.1:8081
UI Backend	5003	http://localhost:5003
UI Frontend	5173	http://localhost:5173

🎓 What We Learned

• MCP Protocol: How to build custom tools that AI agents can discover and use
• LangGraph: Agent orchestration with tool calling
• Streaming: Real-time response streaming through multiple proxy layers
• Tool Design: Structuring tool inputs/outputs for optimal AI use
• Full Stack AI: Connecting frontend → backend → agent → MCP tools → external APIs

📄 License

See individual project LICENSE files.

---

Built during Red Hat Hackathon 🎉