unified-github-mcp-server/README.md

Unified GitHub MCP Server - Comprehensive GitHub API integration with multi-account support, natural language workflows, and 35+ GitHub tools

# Unified GitHub MCP Server

A comprehensive Model Context Protocol (MCP) server that provides complete GitHub API integration for AI assistants and LLMs. This unified server combines the best features from multiple GitHub MCP implementations into a single, powerful tool.

## Features

### 🔄 Multi-Account Support
- Switch between multiple GitHub accounts seamlessly
- Account-specific authentication and permissions
- Automatic account detection for repository access

### 🤖 Natural Language Workflows
- Execute complex GitHub operations using natural language commands
- Multi-step workflow automation
- Intelligent workflow parsing and execution

### 📁 Repository Management
- List, create, and delete repositories
- Repository settings and configuration
- Comprehensive repository information retrieval

### 📄 File Operations
- Read, upload, update, and delete files from repositories
- Support for binary and text files
- Batch file operations

### 🌿 Branch Operations
- Create, list, merge, and delete branches
- Branch protection and management
- Advanced branching workflows

### 🏢 Organization Management
- List and manage organizations
- Organization member management
- Organization-level operations

### 🐛 Issues & Pull Requests
- Create, list, and manage issues
- Pull request creation and management
- Advanced filtering and sorting

### 📝 Gist Management
- Create and list gists
- Public and private gist support
- Multi-file gist creation

### 🔒 Security & Compliance
- Secure token-based authentication
- Multi-account permission management
- Environment variable and JSON configuration support

## Installation

### Using NPM

```bash
npm install unified-github-mcp-server
```

### Global Installation

```bash
npm install -g unified-github-mcp-server
```

### Development Installation

```bash
git clone <repository-url>
cd unified-github-mcp-server
npm install
npm run build
```

## Configuration

### Environment Variables

Set your GitHub personal access token:

```bash
export GITHUB_TOKEN=your_github_token_here
export GITHUB_USERNAME=your_username
export GITHUB_EMAIL=your_email@example.com
```

### JSON Configuration (Multi-Account)

Create a `config.json` file:

```json
{
  "accounts": {
    "personal": {
      "username": "your-username",
      "token": "ghp_your_personal_token",
      "email": "personal@example.com",
      "default": true
    },
    "work": {
      "username": "work-username", 
      "token": "ghp_your_work_token",
      "email": "work@company.com"
    }
  },
  "currentAccount": "personal"
}
```

### MCP Client Configuration

For Augment or other MCP clients:

```json
{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["unified-github-mcp-server"],
      "env": {
        "GITHUB_TOKEN": "your_github_token_here"
      }
    }
  }
}
```

## Available Tools

### Account Management
- `switch_account` - Switch between configured accounts
- `list_accounts` - List all configured accounts

### Repository Management
- `list_repositories` - List repositories for authenticated user
- `get_repository` - Get repository information
- `create_repository` - Create a new repository
- `delete_repository` - Delete a repository
- `get_user_info` - Get authenticated user information

### File Management
- `get_file_content` - Get file content from repository
- `upload_file` - Create or upload a file
- `update_file` - Update existing file content
- `delete_file` - Delete a file from repository

### Branch Management
- `create_branch` - Create a new branch
- `list_branches` - List all branches
- `merge_branch` - Merge branches
- `delete_branch` - Delete a branch

### Organization Management
- `list_organizations` - List user organizations
- `get_organization` - Get organization details
- `list_org_members` - List organization members

### Issues & Pull Requests
- `list_issues` - List repository issues
- `create_issue` - Create a new issue
- `list_pull_requests` - List pull requests
- `create_pull_request` - Create a new pull request

### Gist Management
- `list_gists` - List user gists
- `create_gist` - Create a new gist

## Usage Examples

### Basic Repository Operations

```javascript
// List repositories
await callTool('list_repositories', {
  account: 'personal',
  type: 'owner',
  sort: 'updated'
});

// Create a new repository
await callTool('create_repository', {
  name: 'my-new-repo',
  description: 'A new repository',
  private: false,
  auto_init: true
});
```

### Multi-Account Operations

```javascript
// Switch to work account
await callTool('switch_account', {
  account: 'work'
});

// Create repository on work account
await callTool('create_repository', {
  account: 'work',
  name: 'work-project'
});
```

### File Operations

```javascript
// Upload a new file
await callTool('upload_file', {
  owner: 'username',
  repo: 'repository',
  path: 'src/index.js',
  content: 'console.log("Hello World!");',
  message: 'Add initial index.js file'
});
```

## Development

### Building

```bash
npm run build
```

### Running in Development

```bash
npm run dev
```

### Testing

```bash
npm test
```

## Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests if applicable
5. Submit a pull request

## License

MIT License - see LICENSE file for details

## Support

For issues and questions:
- Create an issue on GitHub
- Check the documentation
- Review existing issues for solutions

## Changelog

### v4.0.0
- Initial unified release
- Combined features from multiple GitHub MCP servers
- Added multi-account support
- Enhanced organization and gist management
- Improved error handling and validation