jaegis-github-mcp-server/README.md

GitHub MCP Server - AI-powered Model Context Protocol server with JAEGIS AI documentation intelligence, natural language workflows, and 45+ comprehensive GitHub tools

# jaegis-github-mcp-server

> AI-powered GitHub automation with 32+ tools, JAEGIS AI documentation intelligence, and natural language workflows

[![npm version](https://badge.fury.io/js/jaegis-github-mcp-server.svg)](https://www.npmjs.com/package/jaegis-github-mcp-server)
[![Node.js](https://img.shields.io/badge/node-%3E%3D18.0.0-brightgreen)](https://nodejs.org/)
[![MCP](https://img.shields.io/badge/MCP-Model%20Context%20Protocol-blue)](https://modelcontextprotocol.io/)

## 🚀 Quick Start

### NPX (Recommended)
```bash
# List all available tools
npx jaegis-github-mcp-server@latest --list-tools --format=table

# Get tools schema for MCP integration
npx jaegis-github-mcp-server@latest --tools-json

# Start the MCP server
npx jaegis-github-mcp-server@latest
```

### Global Installation
```bash
npm install -g jaegis-github-mcp-server
github-mcp-server --list-tools
```

## 📊 Tool Inventory (32 Tools)

| Category | Tools | Description |
|----------|-------|-------------|
| **Repository Management** | 5 | Create, update, delete, list repositories |
| **File Operations** | 4 | CRUD operations for files in repositories |
| **Branch Management** | 3 | Create, list, delete branches |
| **Pull Requests** | 3 | Create, list, merge pull requests |
| **Issues** | 3 | Create, list, update issues |
| **Advanced Repository Management** | 8 | Bulk operations, sync, merge repositories |
| **JAEGIS AI Documentation Intelligence** | 5 | AI-powered analysis and insights |
| **Natural Language Workflows** | 1 | Execute complex workflows with natural language |

### Core Tools
- `create_repository` - Create new repositories with configuration
- `get_file` / `create_file` / `update_file` / `delete_file` - File operations
- `create_branch` / `list_branches` / `delete_branch` - Branch management
- `create_pull_request` / `merge_pull_request` - PR workflows
- `create_issue` / `list_issues` / `update_issue` - Issue management

### Advanced Tools
- `reorganize_repository` - Smart repository restructuring
- `bulk_upload_with_structure` - Multi-file uploads with directory structure
- `batch_file_operations` - Coordinated multi-file operations
- `sync_local_to_remote` - Bidirectional synchronization
- `merge_repositories` - Multi-repository consolidation
- `cross_account_transfer` - Cross-account repository transfers

### JAEGIS AI Intelligence
- `analyze_documentation_quality` - AI-powered documentation analysis
- `track_development_velocity` - Development metrics with AI insights
- `monitor_repository_intelligence` - Intelligent repository monitoring
- `analyze_dependencies_intelligence` - Smart dependency analysis
- `generate_mermaid_diagrams` - AI-powered diagram generation

## 🔧 Environment Setup

### Required Variables
```bash
export GITHUB_TOKEN=ghp_your_token_here        # GitHub personal access token
export GITHUB_USERNAME=your_username           # GitHub username
export GITHUB_EMAIL=your_email@example.com     # GitHub email (optional)
```

### Generate GitHub Token
1. Go to [GitHub Settings > Tokens](https://github.com/settings/tokens)
2. Click "Generate new token (classic)"
3. Select scopes: `repo`, `user`, `admin:repo_hook`
4. Copy the generated token

### Token Format Validation
- ✅ `ghp_*` - Personal access token
- ✅ `github_pat_*` - Fine-grained personal access token
- ❌ Other formats will show warnings

## 🎯 MCP Client Integration

### Augment Code
```json
{
  "github": {
    "command": "npx",
    "args": ["jaegis-github-mcp-server@latest"],
    "env": {
      "GITHUB_TOKEN": "ghp_your_token_here",
      "GITHUB_USERNAME": "your_username",
      "GITHUB_EMAIL": "your_email@example.com"
    }
  }
}
```

### Claude Desktop
```json
{
  "mcpServers": {
    "github": {
      "command": "npx",
      "args": ["jaegis-github-mcp-server@latest"],
      "env": {
        "GITHUB_TOKEN": "ghp_your_token_here",
        "GITHUB_USERNAME": "your_username"
      }
    }
  }
}
```

## 📖 Usage Examples

### Repository Management
```javascript
// Create a new repository
{
  "tool": "create_repository",
  "parameters": {
    "name": "my-new-repo",
    "description": "A new repository",
    "private": false,
    "auto_init": true
  }
}
```

### File Operations
```javascript
// Create a new file
{
  "tool": "create_file",
  "parameters": {
    "owner": "username",
    "repo": "repository",
    "path": "src/index.js",
    "content": "console.log('Hello World');",
    "message": "Add initial index.js"
  }
}
```

### AI-Powered Analysis
```javascript
// Analyze documentation quality
{
  "tool": "analyze_documentation_quality",
  "parameters": {
    "owner": "username",
    "repo": "repository",
    "generate_improvements": true
  }
}
```

## 🛠️ Command Line Options

```bash
github-mcp-server [OPTIONS]

OPTIONS:
  --list-tools         List all available tools with descriptions
  --tools-json         Output complete MCP tools schema as JSON
  --format=table       Use table format for tool listings (default: JSON)
  --help, -h          Show this help message

EXAMPLES:
  github-mcp-server --list-tools --format=table
  github-mcp-server --tools-json > tools-schema.json
  github-mcp-server  # Start MCP server
```

## 🔒 Security Features

- ✅ **Credential Sanitization** - Sensitive values masked in logs
- ✅ **Environment-based Authentication** - No hardcoded credentials
- ✅ **Token Format Validation** - Validates GitHub token formats
- ✅ **Multi-account Support** - Secure account switching
- ✅ **Error Handling** - Comprehensive error messages without credential exposure

## 🚨 Troubleshooting

### Common Issues

**"GitHub token is required"**
```bash
# Set your GitHub token
export GITHUB_TOKEN=ghp_your_token_here
```

**"API rate limit exceeded"**
- Use authenticated requests (token required)
- Wait for rate limit reset
- Consider GitHub Apps for higher limits

**"Repository not found"**
- Check repository name and owner
- Verify token has access to the repository
- Ensure repository exists and is accessible

**"Permission denied"**
- Verify token has required scopes
- Check repository permissions
- Ensure token is not expired

## 📦 Package Information

- **Package**: `jaegis-github-mcp-server`
- **Version**: 3.1.0
- **Node.js**: >=18.0.0
- **License**: MIT

## 🤝 Contributing

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

## 📄 License

MIT License - see [LICENSE](LICENSE) file for details.

---

**Built with ❤️ by the JAEGIS Team**

For more information, visit [JAEGIS Documentation](https://jaegis.ai/docs)