jaegis-github-mcp-server
Version:
GitHub MCP Server - AI-powered Model Context Protocol server with JAEGIS AI documentation intelligence, natural language workflows, and 57+ comprehensive GitHub tools
373 lines (291 loc) • 10.4 kB
Markdown
# jaegis-github-mcp-server
> AI-powered GitHub automation with 57+ tools, JAEGIS AI documentation intelligence, and natural language workflows
[](https://www.npmjs.com/package/jaegis-github-mcp-server)
[](https://nodejs.org/)
[](https://modelcontextprotocol.io/)
## Quick links
- Authentication: [docs/authentication.md](docs/authentication.md)
- API Reference: [docs/api-reference.md](docs/api-reference.md)
- Security: [docs/security.md](docs/security.md)
- Upgrade Guide: [docs/upgrade.md](docs/upgrade.md)
- Examples: [examples/](examples/)
## 🚀 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 (57 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** | 9 | Bulk ops, sync, merge repositories, cross-account transfer |
| **JAEGIS AI Documentation Intelligence** | 5 | AI-powered analysis and insights |
| **GitHub Actions & CI/CD** | 17 | Workflows, runs, pages, triggers, marketplace listing |
| **Repository Security** | 7 | Secrets, environments, protections |
| **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
### Option A) GitHub App (recommended for orgs)
```ini
# ~/.mcp/.env (Unix) or %USERPROFILE%\.mcp\.env (Windows)
GITHUB_AUTH_MODE=app
GITHUB_APP_ID=YOUR_APP_ID
GITHUB_APP_INSTALLATION_ID=YOUR_INSTALLATION_ID
# Choose exactly one private key source:
GITHUB_APP_PRIVATE_KEY_PATH=~/.mcp/private-key.pem
# GITHUB_APP_PRIVATE_KEY_BASE64=BASE64_ENCODED_PEM
# GITHUB_APP_PRIVATE_KEY=-----BEGIN PRIVATE KEY-----\n...\n-----END PRIVATE KEY-----
GITHUB_USERNAME=your-username
GITHUB_EMAIL=user@example.com
```
Validation (as of 5 September 2025):
```bash
npx jaegis-github-mcp-server@latest --config-check
```
Expected (sanitized):
```json
{
"server": "github-mcp-server",
"auth_mode": "app",
"authOk": true,
"login": "your-username-or-org",
"installation_id": "YOUR_INSTALLATION_ID"
}
```
### Option B) Personal Access Token (PAT)
```bash
export GITHUB_TOKEN=ghp_****...****
export GITHUB_USERNAME=your-username
export GITHUB_EMAIL=user@example.com
```
### 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_****...****",
"GITHUB_USERNAME": "your-username",
"GITHUB_EMAIL": "user@example.com"
}
}
}
```
### Claude Desktop
```json
{
"mcpServers": {
"github": {
"command": "npx",
"args": ["jaegis-github-mcp-server@latest"],
"env": {
"GITHUB_TOKEN": "ghp_****...****",
"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)
--config-check Validate authentication and print a JSON report
--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 --config-check
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
### GitHub App config-check shows authOk: false (fixed in v3.3.1)
- Cause: Using GET /user with installation tokens returns 403. Fixed by validating via installation endpoints and App JWT.
- Validate and expect success:
- Upgrading? See [Upgrade Guide](docs/upgrade.md) for details.
```bash
npx jaegis-github-mcp-server@latest --config-check
```
Expected (sanitized):
```json
{
"auth_mode": "app",
"authOk": true,
"login": "your-username-or-org"
}
```
### Common Issues
**"GitHub token is required"**
```bash
# PAT mode
export GITHUB_TOKEN=ghp_****...****
```
**"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.3.1
- **Node.js**: >=22.19.0
- **License**: MIT
## 🧭 Architecture Diagrams
### Authentication flows (PAT vs GitHub App)
```mermaid
flowchart LR
subgraph PAT[ PAT Mode ]
P1[Env: GITHUB_TOKEN] --> P2[Octokit: users.getAuthenticated]
P2 --> P3{200 OK?}
P3 -- Yes --> P4[authOk=true, login=user]
P3 -- No --> P5[authOk=false, error]
end
subgraph APP[ GitHub App Mode ]
A1[Env: APP_ID, INSTALLATION_ID, PRIVATE_KEY] --> A2[App JWT Client]
A1 --> A3[Installation Client]
A3 --> A4[GET /installation/repositories]
A4 --> A5{200 OK?}
A5 -- Yes --> A6[apps.getInstallation]
A6 --> A7[authOk=true, login=installation.account.login]
A5 -- No --> A8[authOk=false, error]
end
```
### Tool categorization
```mermaid
flowchart TB
A[Tools] --> B[Repository Management]
A --> C[File Operations]
A --> D[Branch Management]
A --> E[Pull Requests]
A --> F[Issues]
A --> G[Advanced Repository Management]
A --> H[GitHub Actions & CI/CD]
A --> I[Repository Security]
A --> J[Natural Language Workflows]
```
### MCP client integration (stdio)
```mermaid
sequenceDiagram
participant Client as MCP Client
participant Server as jaegis-github-mcp-server
Client->>Server: initialize (stdio)
Server-->>Client: tool list / capabilities
Client->>Server: callTool(create_repository, params)
Server-->>Client: result / error
```
### Configuration loading hierarchy
```mermaid
flowchart TD
Z[Configuration Sources] -->|highest| A[%USERPROFILE%/.mcp/.env]
Z --> B[%APPDATA%/github-mcp-server/.env]
Z --> C[%USERPROFILE%/.config/github-mcp-server/.env]
Z --> D[package .env]
Z -->|lowest| E[cwd .env]
A & B & C & D & E --> F[Resolved config]
F --> G[Auth mode: PAT or App]
```
## 🤝 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)