# GitHub MCP Server

A Model Context Protocol (MCP) server that integrates with GitHub's API to provide tools for automation and workflow orchestration. This server enables triggering repository dispatch events, creating issues, and retrieving repository information.

## Features

- **🎯 Repository Dispatch**: Trigger GitHub `repository_dispatch` events with custom event types and JSON payloads (with full 日本語 support)
- **🐛 Issue Creation**: Create GitHub issues as a fallback mechanism
- **📊 Repository Information**: Retrieve detailed repository metadata
- **🔐 Secure Authentication**: PAT-based authentication with environment variable management
- **🧪 Comprehensive Testing**: Full pytest coverage with unit tests
- **📝 Japanese Language Support**: Handle Japanese characters in payloads and metadata

## Prerequisites

- Python 3.9+
- A GitHub Personal Access Token (PAT) with `repo` and `workflow` scopes
- `git` for version control

## Installation

### From Source

```bash
git clone https://github.com/ai-info-x/github-mcp-server.git
cd github-mcp-server
pip install -e .
```

### With Development Dependencies

```bash
pip install -e ".[dev]"
```

## Authentication Setup

### Step 1: Generate GitHub Personal Access Token

1. Go to https://github.com/settings/tokens
2. Click **Generate new token (classic)**
3. Give it a descriptive name: `github-mcp-server`
4. Select required scopes:
   - ✓ `repo` (full control of private repositories)
   - ✓ `workflow` (update GitHub Action workflows)
5. Set expiration (90 days recommended)
6. Click **Generate token** and **copy** the token immediately

### Step 2: Configure Environment

#### Option A: Using `.env` File (Recommended)

```bash
# Copy the template
cp .env.template .env

# Edit .env with your token
# GITHUB_TOKEN=ghp_your_token_here
```

#### Option B: Export Environment Variable

```bash
export GITHUB_TOKEN="ghp_your_token_here"
```

#### Option C: System-wide Configuration

```bash
# Permanently set in ~/.bashrc or ~/.zshrc
echo 'export GITHUB_TOKEN="ghp_your_token_here"' >> ~/.bashrc
source ~/.bashrc
```

**⚠️ Security Note:** Never commit `.env` to version control. The `.gitignore` already excludes it.

## Usage

### Running the MCP Server

```bash
# With environment variable set
GITHUB_TOKEN=ghp_your_token_here python -m src.github_mcp_server

# Or with .env file
python -m src.github_mcp_server
```

### Available Tools

#### 1. `trigger_repository_dispatch`

Trigger a custom repository dispatch event.

**Parameters:**
- `owner` (string, required): Repository owner (username or organization)
- `repo` (string, required): Repository name
- `event_type` (string, required): Event type identifier (e.g., `my-event`, `build-trigger`)
- `payload` (object, optional): Event payload as JSON object

**Example:**

```python
{
    "owner": "ai-info-x",
    "repo": "my-repo",
    "event_type": "build-release",
    "payload": {
        "version": "v1.0.0",
        "message": "Release build initiated",
        "環境": "本番"  # Japanese characters supported
    }
}
```

**Response:**

```json
{
    "success": true,
    "message": "Repository dispatch 'build-release' triggered successfully",
    "owner": "ai-info-x",
    "repo": "my-repo",
    "event_type": "build-release",
    "payload": {
        "version": "v1.0.0",
        "message": "Release build initiated",
        "環境": "本番"
    }
}
```

#### 2. `create_issue`

Create a GitHub issue (useful as a fallback when dispatch fails).

**Parameters:**
- `owner` (string, required): Repository owner
- `repo` (string, required): Repository name
- `title` (string, required): Issue title
- `body` (string, optional): Issue description
- `labels` (array, optional): Issue labels (e.g., `["bug", "urgent"]`)

**Example:**

```python
{
    "owner": "ai-info-x",
    "repo": "my-repo",
    "title": "Auto-generated notification",
    "body": "This issue was created as a fallback notification",
    "labels": ["automated", "notification"]
}
```

**Response:**

```json
{
    "success": true,
    "message": "Issue created successfully",
    "issue_number": 42,
    "issue_url": "https://github.com/ai-info-x/my-repo/issues/42",
    "title": "Auto-generated notification"
}
```

#### 3. `get_repository_info`

Retrieve comprehensive repository information.

**Parameters:**
- `owner` (string, required): Repository owner
- `repo` (string, required): Repository name

**Example:**

```python
{
    "owner": "ai-info-x",
    "repo": "github-mcp-server"
}
```

**Response:**

```json
{
    "success": true,
    "name": "github-mcp-server",
    "full_name": "ai-info-x/github-mcp-server",
    "description": "MCP Server with GitHub repository_dispatch API integration",
    "url": "https://github.com/ai-info-x/github-mcp-server",
    "clone_url_https": "https://github.com/ai-info-x/github-mcp-server.git",
    "clone_url_ssh": "git@github.com:ai-info-x/github-mcp-server.git",
    "private": false,
    "stars": 5,
    "forks": 2,
    "language": "Python",
    "default_branch": "main"
}
```

## Testing

### Run All Tests

```bash
pytest
```

### Run with Coverage

```bash
pytest --cov=src --cov-report=html
```

### Run Specific Test

```bash
pytest tests/test_github_mcp.py::TestTriggerRepositoryDispatch::test_trigger_dispatch_success -v
```

## Project Structure

```
github-mcp-server/
├── src/
│   └── github_mcp_server.py       # Main MCP server implementation
├── tests/
│   └── test_github_mcp.py         # Test suite
├── README.md                      # This file
├── .env.template                  # Environment template
├── .gitignore                      # Git ignore rules
├── pyproject.toml                 # Project configuration & dependencies
└── .git/                           # Git repository
```

## Development

### Setting Up Development Environment

```bash
# Clone and install
git clone https://github.com/ai-info-x/github-mcp-server.git
cd github-mcp-server

# Create virtual environment (optional)
python -m venv venv
source venv/bin/activate  # or `venv\Scripts\activate` on Windows

# Install with dev dependencies
pip install -e ".[dev]"
```

### Code Style

This project uses `black` for code formatting and `flake8` for linting.

```bash
# Format code
black src/ tests/

# Check linting
flake8 src/ tests/
```

### Type Checking

```bash
mypy src/
```

## Error Handling

All tools return consistent JSON responses with `success` flag and error information:

**Success Response:**
```json
{
    "success": true,
    "message": "Operation successful",
    ...
}
```

**Error Response:**
```json
{
    "success": false,
    "error": "Error description",
    "status": 404
}
```

Common GitHub API errors:
- **404 Not Found**: Repository or user doesn't exist
- **401 Unauthorized**: Invalid or expired token
- **403 Forbidden**: Insufficient permissions
- **422 Unprocessable Entity**: Invalid payload or parameters

## Troubleshooting

### "GITHUB_TOKEN environment variable is required"

Ensure your token is set:

```bash
# Check if set
echo $GITHUB_TOKEN

# If not set, export it
export GITHUB_TOKEN="ghp_your_token_here"
```

### "401 Unauthorized"

Your token may be invalid or expired:
1. Check token at https://github.com/settings/tokens
2. Regenerate if necessary
3. Update environment variable

### "403 Forbidden"

Your token lacks required scopes:
1. Go to https://github.com/settings/tokens
2. Edit the token
3. Ensure `repo` and `workflow` scopes are enabled

### "Repository not found"

Verify:
- Repository exists and is accessible
- Correct owner/repo names
- Owner is username (not organization) if querying user repos

## Repository URLs

- **GitHub**: https://github.com/ai-info-x/github-mcp-server
- **Clone (HTTPS)**: https://github.com/ai-info-x/github-mcp-server.git
- **Clone (SSH)**: git@github.com:ai-info-x/github-mcp-server.git

## License

MIT License - See LICENSE file for details

## Contributing

Contributions are welcome! Please:

1. Fork the repository
2. Create a feature branch (`git checkout -b feature/your-feature`)
3. Commit changes with clear messages
4. Write/update tests for new functionality
5. Ensure all tests pass (`pytest`)
6. Push to your fork
7. Create a Pull Request

## Support

For issues, questions, or suggestions:
- Open an issue at https://github.com/ai-info-x/github-mcp-server/issues
- Check existing issues for similar problems
- Provide detailed reproduction steps

## Changelog

### v0.1.0 (Initial Release)
- ✨ Repository dispatch event triggering
- ✨ Issue creation with labels
- ✨ Repository information retrieval
- ✨ Japanese language support in payloads
- ✨ Comprehensive test suite
- 📝 Complete documentation