MCP GitHub Repository Creator

A Model Context Protocol (MCP) server that provides tools for AI applications like GitHub Copilot to analyze repositories and create GitHub repositories automatically.

🚀 Features

• Repository Analysis: Automatically analyze local git repositories to extract metadata. Includes traditional and AI approaches to analyze the repository
• GitHub Integration: Create private GitHub repositories with proper configuration
• Topic Management: Automatically add relevant topics based on project analysis
• MCP Compatible: Works with any MCP-compatible AI client (Copilot, Claude, etc.)
• Automated Setup: Complete workflow from analysis to GitHub repository creation

📦 Installation

1. Clone this repository:

   git clone https://github.com/flickleafy/mcp-github-repo-creator.git
   cd mcp-github-repo-creator

2. Run the setup script:

   bash setup.sh

   This will:

   • Create a Python virtual environment
   • Install the MCP SDK and dependencies
   • Set up the project for use

🛠 Usage

As an MCP Server (Recommended)

The server provides the following tools for AI applications:

1. get_repo_analysis_instructions - Get detailed instructions for repository analysis
2. analyze_and_generate_metadata_file - Analyze repository and generate metadata
3. create_github_repo_from_metadata - Create GitHub repository from metadata JSON
4. create_github_repository - Create repository using existing metadata file
5. full_repository_setup - Complete workflow: analyze → create → connect

Starting the MCP Server

# Activate virtual environment
source venv/bin/activate

# Start the MCP server
python server.py

The server runs on stdio transport and is compatible with MCP clients like:

• GitHub Copilot
• Claude Desktop
• VS Code extensions
• Custom MCP clients

MCP Client Integration

Configure your MCP client to connect to this server:

{
  "name": "github-repo-creator",
  "command": "python",
  "args": ["server.py"],
  "cwd": "/path/to/mcp-github-repo-creator"
}

Manual Usage (Alternative)

You can also use the underlying functionality directly:

# Activate virtual environment
source venv/bin/activate

# Interactive mode
python create_github_repo.py

# Direct repository creation
python create_github_repo.py --create

# Manage topics only
python create_github_repo.py --manage-topics

🎯 Workflow

1. Analysis: The AI analyzes your repository structure, README, dependencies, and code
2. Metadata Generation: Creates a github_repo_metadata.json with repository details
3. Repository Creation: Uses GitHub CLI to create a private repository
4. Configuration: Sets up topics, enables features, and connects local repository
5. Push: Pushes your local code to the new GitHub repository

🔄 Detailed Workflow Types

The MCP server supports three main workflow approaches:

🤝 Interactive Copilot Workflow (Recommended)

This approach gives Copilot more control and allows for customization:

1. Request Analysis Instructions: Ask Copilot to analyze the repository

   • Copilot uses get_repo_analysis_instructions
   • Gets detailed instructions on what to analyze
   • Analyzes your repository structure, README, and code

2. Generate Metadata: Copilot creates the metadata JSON

   • Based on its analysis, Copilot generates repository metadata
   • You can review and modify the metadata before proceeding

3. Create Repository: Copilot creates the GitHub repository

   • Uses create_github_repo_from_metadata with the generated metadata
   • Creates repository, pushes code, and configures settings

Example Chat:

"Please analyze this repository and create a GitHub repository for it. 
I want to review the metadata before you create the repo."

⚡ Full Automation Workflow

For complete automation without interaction:

1. Single Command Setup: Use the full_repository_setup tool
   • Analyzes repository automatically
   • Generates metadata file
   • Creates GitHub repository
   • Connects and pushes code
   • All in one step

Example Chat:

"Automatically set up this project on GitHub with full automation."

🛠️ Manual/Step-by-Step Workflow

For granular control over each step:

1. Generate Metadata File: analyze_and_generate_metadata_file
2. Review/Edit the generated github_repo_metadata.json
3. Create Repository: create_github_repository

Example Chat:

"First, generate a metadata file for this repository. I want to review it before creating the GitHub repo."

💬 Usage Examples with Copilot

Once configured, you can use these natural language commands with Copilot:

Analyze Repository

"Analyze this repository and tell me what metadata would be generated for GitHub."

Generate Metadata File

"Generate a github_repo_metadata.json file for this repository."

Create GitHub Repository

"Create a GitHub repository for this local project. First analyze it, generate metadata, then create the GitHub repo and connect everything."

Full Setup

"Set up this entire project on GitHub - analyze the code, create appropriate metadata, and create the repository."

Step-by-Step Example

"Please create a GitHub repository for this project. Analyze the code, 
generate appropriate metadata, and set up the repository on GitHub."

Copilot will:

• Analyze your project structure and code
• Detect the programming language and frameworks
• Generate topics and description
• Create github_repo_metadata.json
• Create the GitHub repository
• Connect your local repo to GitHub
• Push your code

🚀 Copilot Integration & Installation

Prerequisites for Copilot Integration

1. GitHub Copilot subscription (Individual, Business, or Enterprise)
2. VS Code with GitHub Copilot extension
3. GitHub CLI installed and authenticated

Method 1: VS Code Copilot Integration (Recommended)

1. Install GitHub CLI:

   # macOS
   brew install gh
   
   # Ubuntu/Debian
   sudo apt install gh
   
   # Windows (using winget)
   winget install GitHub.cli

2. Authenticate GitHub CLI:

   gh auth login

3. Clone and setup this MCP server:

   git clone https://github.com/flickleafy/mcp-github-repo-creator.git
   cd mcp-github-repo-creator
   bash setup.sh

4. Configure VS Code settings (add to your VS Code settings.json):

   {
     "github.copilot.enable": {
       "*": true,
       "mcp": true
     },
     "mcp.servers": {
       "github-repo-creator": {
         "command": "python",
         "args": ["server.py"],
         "cwd": "/full/path/to/mcp-github-repo-creator",
         "env": {
           "PATH": "/full/path/to/mcp-github-repo-creator/venv/bin:${env:PATH}"
         }
       }
     }
   }

Method 2: Claude Desktop Integration

1. Install Claude Desktop from claude.ai

2. Configure Claude Desktop (edit ~/.config/claude-desktop/config.json):

   {
     "mcpServers": {
       "github-repo-creator": {
         "command": "python",
         "args": ["/full/path/to/mcp-github-repo-creator/server.py"],
         "env": {
           "PATH": "/full/path/to/mcp-github-repo-creator/venv/bin"
         }
       }
     }
   }

3. Restart Claude Desktop and start using the commands

Automatic Installation Script

Create an easy installation script by running:

# Download and run the auto-installer
curl -sSL https://raw.githubusercontent.com/flickleafy/mcp-github-repo-creator/main/install-copilot.sh | bash

Or manually create the installer script in your project:

# Create installer script
cat > install-copilot.sh << 'EOF'
#!/bin/bash
echo "🚀 Installing MCP GitHub Repository Creator for Copilot..."

# Check dependencies
command -v python3 >/dev/null 2>&1 || { echo "❌ Python 3 is required but not installed."; exit 1; }
command -v git >/dev/null 2>&1 || { echo "❌ Git is required but not installed."; exit 1; }

# Install GitHub CLI if not present
if ! command -v gh &> /dev/null; then
    echo "📦 Installing GitHub CLI..."
    if [[ "$OSTYPE" == "darwin"* ]]; then
        brew install gh
    elif [[ "$OSTYPE" == "linux-gnu"* ]]; then
        sudo apt update && sudo apt install gh
    else
        echo "⚠️ Please install GitHub CLI manually: https://cli.github.com/"
        exit 1
    fi
fi

# Clone repository
INSTALL_DIR="$HOME/.mcp-servers/github-repo-creator"
echo "📁 Installing to $INSTALL_DIR..."
mkdir -p "$HOME/.mcp-servers"
git clone https://github.com/flickleafy/mcp-github-repo-creator.git "$INSTALL_DIR"

# Setup virtual environment
cd "$INSTALL_DIR"
python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt

# Create VS Code configuration
VSCODE_CONFIG="$HOME/.config/Code/User/settings.json"
echo "⚙️ Adding VS Code configuration..."
# Add MCP server configuration to VS Code settings

echo "✅ Installation complete!"
echo "🔧 Next steps:"
echo "1. Authenticate with GitHub: gh auth login"
echo "2. Restart VS Code"
echo "3. Start using Copilot with MCP commands!"
EOF

chmod +x install-copilot.sh

Testing the Integration

1. Open a git repository in VS Code

2. Start a chat with Copilot and try:

   "Use the MCP GitHub Repository Creator to analyze this repository and create a GitHub repo for it."
   

3. Copilot should respond with repository analysis and offer to create the GitHub repository

📋 Requirements

• Python 3.8+
• Git repository (local)
• GitHub CLI (gh) installed and authenticated
• Internet connection for GitHub API calls

GitHub CLI Setup

Install and authenticate GitHub CLI:

# Install GitHub CLI (see https://cli.github.com/)
# macOS
brew install gh

# Ubuntu/Debian
sudo apt install gh

# Authenticate
gh auth login

🔧 MCP Integration

This server implements the Model Context Protocol specification, making it compatible with various AI applications:

Available Tools

• Repository Analysis: Extracts project metadata automatically
• GitHub Repository Creation: Creates repositories with proper settings
• Topic Management: Adds relevant topics based on analysis
• Complete Workflow: End-to-end repository setup

Supported Transports

• stdio (default): Standard input/output for direct integration
• Compatible with FastMCP framework for easy deployment

📁 Project Structure

mcp-github-repo-creator/
├── server.py                    # Main MCP server using FastMCP
├── core/
│   ├── repository_analyzer.py  # Repository analysis logic
│   └── templates.py            # String templates for messages and instructions
├── create_github_repo.py       # Legacy standalone script
├── demo.py                     # Demo MCP client
├── requirements.txt            # Dependencies including MCP SDK
├── setup.sh                   # Environment setup script
├── pyproject.toml             # Optional project metadata
├── .gitignore                 # Git ignore rules
└── README.md                  # This file

Core Modules

• server.py: Main MCP server that exposes tools to AI clients
• core/repository_analyzer.py: RepositoryAnalyzer class for analyzing repository structure and generating metadata
• core/templates.py: Centralized template functions for all long string messages and instructions
• create_github_repo.py: Legacy standalone script (for direct usage)
• demo.py: Example client showing how to interact with the MCP server

📊 Example Metadata Structure

The server generates metadata in this format:

{
  "repository_name": "my-awesome-project",
  "description": "🚀 A powerful tool for automating GitHub repository creation",
  "topics": ["python", "automation", "github", "mcp", "ai-tools"],
  "created_date": "2025-01-01",
  "project_type": "CLI Tool",
  "primary_language": "Python", 
  "license": "GPL-3.0",
  "features": [
    "Command-line interface",
    "GitHub integration",
    "Automated analysis"
  ]
}

🎯 Supported Project Types

The MCP server automatically detects and properly categorizes various project types:

• AI/ML Projects: Detects TensorFlow, PyTorch, scikit-learn, Transformers, Langchain
• Web Applications: React, Vue, Angular, Svelte, Flask, Django, FastAPI, Express, Next.js
• CLI Tools: Command-line applications and utilities
• APIs: RESTful services, GraphQL, and microservices
• Mobile Apps: React Native, Flutter, Ionic
• Desktop Apps: Electron, Tauri, PyQt, Tkinter
• Libraries: Software packages, frameworks, and SDKs
• Game Development: Unity, Godot, Pygame
• DevOps Tools: Docker, Kubernetes, Terraform configurations
• Data Science: Jupyter notebooks, data analysis projects

🌐 Language Detection

Automatically detects and supports a wide range of programming languages:

Primary Languages: Python, JavaScript, TypeScript, Java, C++, C#, Go, Rust, PHP, Ruby, Swift, Kotlin, Scala, R, Shell/Bash

Web Technologies: HTML, CSS, Vue, React (JSX/TSX), Svelte, SCSS/Sass, Less

Specialized: SQL, YAML, TOML, JSON, Dockerfile, Makefile

The analyzer examines file extensions, dependencies, and project structure to accurately determine the primary language and technology stack.

🛡️ Security & Privacy

• Secure Authentication: Uses GitHub CLI for secure, token-based authentication
• Private by Default: Creates private repositories by default for security
• No Data Storage: No sensitive data stored in metadata files
• Local Processing: Repository analysis happens locally on your machine
• GitHub Best Practices: Follows GitHub's security recommendations
• Token Scope: Uses minimal required permissions through GitHub CLI

⚠️ Limitations

• GitHub CLI Required: Must have GitHub CLI installed and authenticated
• Git Repository Required: Must be run from within a git repository with commits
• Private Repositories: Creates private repositories only (can be changed manually after creation)
• GitHub API Limits: Subject to GitHub API rate limits
• Topic Restrictions: Limited to repositories that fit GitHub's topic requirements (20 topics max)
• Network Dependency: Requires internet connection for GitHub API calls

🔧 Error Handling

The MCP server provides comprehensive error handling with clear messages for common issues:

Repository Errors

• Missing git repository: Clear instructions to initialize git
• No commits: Guidance to make initial commit
• Untracked files: Prompts to add and commit files

Authentication Errors

• GitHub CLI not found: Installation instructions
• Not authenticated: Authentication setup guidance
• Token expired: Re-authentication steps

GitHub API Errors

• Repository name conflicts: Suggestions for alternative names
• Permission issues: Troubleshooting steps
• Rate limiting: Wait time recommendations

🆘 Troubleshooting

Common Issues and Solutions

"Not a git repository" Error

# Initialize git repository
git init

# Add files and make initial commit
git add .
git commit -m "Initial commit"

"GitHub CLI not authenticated" Error

# Check authentication status
gh auth status

# Re-authenticate if needed
gh auth login

"Permission denied" Error

Solutions:

• Check GitHub CLI authentication: gh auth status
• Ensure you have permission to create repositories in your account
• Verify your GitHub token has appropriate scopes
• For organization repositories, check organization permissions

"Repository name already exists" Error

Solutions:

• Choose a different repository name
• Check your GitHub account for existing repositories
• Use the suggested alternative names from the error message
• Add a suffix or prefix to make the name unique

"GitHub API rate limit exceeded" Error

Solutions:

• Wait for the rate limit to reset (usually 1 hour)
• Use authenticated requests (ensure gh auth login is completed)
• For high-volume usage, consider GitHub API rate limit best practices

"Invalid metadata format" Error

Solutions:

• Check the generated github_repo_metadata.json for syntax errors
• Ensure all required fields are present
• Validate JSON format using a JSON validator
• Re-run the metadata generation tool

"Network connectivity issues" Error

Solutions:

• Check internet connection
• Verify GitHub.com is accessible
• Check for firewall or proxy issues
• Try again after network issues are resolved

🤝 Contributing

1. If you like the project give a ⭐ to the repository
2. Create a feature branch, Make your changes, Submit a pull request
3. Ensure your code follows the project's coding standards
4. Add tests for new features or bug fixes
5. Update documentation as needed

📜 License

This project is licensed under the GNU General Public License v3.0 - see the LICENSE file for details.

🔗 Links

• Model Context Protocol
• MCP Python SDK
• GitHub CLI

---

Built with ❤️ using the Model Context Protocol