GitHub Repository Architecture Summary Generator

An AI-powered agent that generates comprehensive architecture summaries for GitHub repositories using Amazon Bedrock and Model Context Protocol (MCP).

Available in both TypeScript and Python implementations!

Features

• 🤖 Uses latest AI SDK / LangChain with MCP (Model Context Protocol) client
• 🔗 Integrates with GitHub MCP server
• ☁️ Powered by Amazon Bedrock models
• 📊 Generates detailed repository architecture summaries with Mermaid diagrams
• 🔄 Supports streaming responses for real-time output
• 🐍 NEW: Python implementation using LangChain + LangGraph

Prerequisites

• Node.js 18+
• AWS Account with Bedrock access
• GitHub Personal Access Token
• Access to GitHub SSE MCP server endpoint

Installation

1. Clone the repository:

git clone <your-repo-url>
cd github-sumary

2. Install dependencies:

npm install

3. Set up environment variables: Create a .env file with the following variables:

AWS_REGION=us-east-1
AWS_ACCESS_KEY_ID=your_access_key_id
AWS_SECRET_ACCESS_KEY=your_secret_access_key
GITHUB_TOKEN=your_github_personal_access_token
GITHUB_SSE_MCP_URL=https://github.com/mcp-sse-endpoint
BEDROCK_MODEL=meta.llama3-8b-instruct-v1:0

Usage

Development Mode

npm run dev <repo-owner> <repo-name>

Example:

npm run dev vercel next.js

Production Mode

1. Build the project:

npm run build

2. Run the built application:

npm start <repo-owner> <repo-name>

How It Works

1. MCP Client Initialization: Connects to the GitHub SSE MCP server using Server-Sent Events (SSE) transport
2. Repository Data Retrieval:
   • First attempts to use MCP tools from the GitHub SSE MCP server
   • Falls back to GitHub REST API if MCP tools are unavailable
3. Architecture Analysis: Uses Amazon Bedrock to analyze the repository data
4. Summary Generation: Generates a comprehensive markdown summary including:
   • Repository overview
   • Technology stack and dependencies
   • Project structure and organization
   • Key components and modules
   • Architecture patterns
   • Build and deployment setup
   • Notable features and design decisions

Implementations

This project has two implementations:

1. TypeScript (Original)

• Location: src/index.ts
• Framework: Vercel AI SDK
• MCP Transport: HTTP/SSE
• Agent: Experimental_Agent from AI SDK
• View TypeScript Documentation

2. Python (New)

• Location: python/
• Framework: LangChain + LangGraph
• MCP Transport: stdio (runs MCP server locally)
• Agent: ReAct agent from LangGraph
• View Python Documentation
• Quick Start Guide

Project Structure

github-sumary/
├── src/
│   └── index.ts          # TypeScript implementation
├── python/               # Python implementation (NEW)
│   ├── main.py          # Main Python application
│   ├── requirements.txt  # Python dependencies
│   ├── setup.sh         # Automated setup script
│   ├── README.md        # Python documentation
│   ├── QUICKSTART.md    # Quick start guide
│   └── IMPLEMENTATION_NOTES.md  # Technical details
├── dist/                 # Compiled JavaScript (generated)
├── package.json          # TypeScript dependencies
├── tsconfig.json         # TypeScript configuration
└── README.md             # This file

Configuration

AWS Bedrock

Ensure your AWS credentials have permissions to access Amazon Bedrock models. The default model is meta.llama3-8b-instruct-v1:0, but you can change it via the BEDROCK_MODEL environment variable.

GitHub Token

Your GitHub token needs the following scopes:

• repo (for private repositories)
• read:org (if accessing organization repositories)

GitHub SSE MCP Server

The application expects a GitHub SSE MCP server endpoint. If the server provides repository-related tools, they will be used automatically. Otherwise, the application falls back to the GitHub REST API.

Scripts

• npm run dev - Run in development mode with TypeScript
• npm run build - Compile TypeScript to JavaScript
• npm start - Run the compiled application
• npm run type-check - Type check without emitting files

Dependencies

• ai - Vercel AI SDK for AI model interactions
• @ai-sdk/amazon-bedrock - Amazon Bedrock provider for AI SDK
• @modelcontextprotocol/sdk - Model Context Protocol SDK
• dotenv - Environment variable management
• typescript - TypeScript compiler
• tsx - TypeScript execution for development

Error Handling

The application includes comprehensive error handling:

• Validates required environment variables
• Handles MCP connection failures gracefully
• Falls back to GitHub API if MCP tools fail
• Provides clear error messages for debugging

License

MIT

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.