# 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:

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

2. Run the setup script:

   ```bash
   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

```bash
# 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:

```json
{
  "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:

```bash
# 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**:

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

2. **Authenticate GitHub CLI**:

   ```bash
   gh auth login
   ```

3. **Clone and setup this MCP server**:

   ```bash
   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):

   ```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](https://claude.ai/download)

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

   ```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:

```bash
# 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:

```bash
# 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:

```bash
# 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:

```json
{
  "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

```bash
# Initialize git repository
git init

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

#### "GitHub CLI not authenticated" Error

```bash
# 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](https://modelcontextprotocol.io/)
- [MCP Python SDK](https://github.com/modelcontextprotocol/python-sdk)
- [GitHub CLI](https://cli.github.com/)

---

*Built with ❤️ using the Model Context Protocol*