npm package: @onamfc/mcp-github-integration
Description: GitHub API client for MCP server integration
Latest version: 1.0.0

# GitHub MCP API Client

A TypeScript package for interacting with the GitHub API through an MCP (Model Context Protocol) server integration.

## Features

- Full TypeScript support with type definitions
- **129 MCP tools** covering all major GitHub API operations:
  - Repository management (create, update, delete, search, settings, administration)
  - Issue tracking (create, update, close, comments, search)
  - Pull request management (create, merge, review, comments)
  - Branch operations (create, delete, list, protect)
  - Commit operations (list, get, compare)
  - Release management (create, update, delete, assets)
  - Content operations (read, write, delete files)
  - GitHub Actions (workflows, runs, artifacts)
  - Webhooks (create, update, delete, deliveries, redelivery)
  - Collaborators and teams (add, remove, permissions)
  - Repository statistics and insights
  - Security settings (Dependabot, vulnerability alerts)
  - Advanced search across repositories, issues, PRs, code, commits, users, topics, and labels
- Built-in logging with `@onamfc/developer-log`
- Package inspection with `@onamfc/pkg-inspect`
- Robust error handling

## Installation

### From NPM

```bash
npm install @onamfc/mcp-github-integration
```

### From Source

```bash
git clone https://github.com/onamfc/mcp-github-integration.git
cd mcp-github-integration
npm install
npm run build
```

## Configuration

Set your GitHub personal access token as an environment variable:

```bash
export GITHUB_TOKEN=your_github_token_here
```

## Usage

### Using the MCP Server

```typescript
import { MCPServer } from '@onamfc/mcp-github-integration';

const server = new MCPServer(process.env.GITHUB_TOKEN);

// Get authenticated user
const response = await server.handleRequest({
  method: 'github_get_authenticated_user',
  params: {},
});

if (response.success) {
  console.log('User:', response.data);
}

// Search repositories
const searchResponse = await server.handleRequest({
  method: 'github_search_repositories',
  params: {
    q: 'typescript',
    per_page: 10,
  },
});
```

### Using the GitHub Client Directly

```typescript
import { GitHubClient } from '@onamfc/mcp-github-integration';

const client = new GitHubClient({
  token: process.env.GITHUB_TOKEN,
});

// Create a new repository
const newRepo = await client.createRepository({
  name: 'my-awesome-project',
  description: 'My awesome project description',
  private: false,
  auto_init: true,
});

// Get repository information
const repo = await client.getRepository('owner', 'repo-name');
console.log(repo);

// Create an issue
const issue = await client.createIssue({
  owner: 'owner',
  repo: 'repo-name',
  title: 'Bug Report',
  body: 'Description of the bug',
  labels: ['bug'],
});

// List pull requests
const prs = await client.listPullRequests({
  owner: 'owner',
  repo: 'repo-name',
  state: 'open',
});
```

## Available GitHub API Operations

### Repository Operations (25 endpoints)

- `github_get_repository` - Get repository information
- `github_list_repositories` - List user's public repositories
- `github_create_repository` - Create a new repository
- `github_delete_repository` - Delete a repository
- `github_update_repository` - Update repository settings and configuration
- `github_get_repository_topics` - Get repository topics/tags
- `github_replace_repository_topics` - Set repository topics for discoverability
- `github_get_repository_languages` - Get programming languages used
- `github_get_code_frequency_stats` - Get weekly addition/deletion statistics
- `github_get_contributors_stats` - Get contributor activity statistics
- `github_get_participation_stats` - Get weekly commit count statistics
- `github_transfer_repository` - Transfer repository to new owner
- `github_list_repository_teams` - List teams with access to repository
- `github_check_team_permission` - Check team permission for repository
- `github_add_repository_team` - Add or update team access to repository
- `github_remove_repository_team` - Remove team access from repository
- `github_enable_automated_security_fixes` - Enable Dependabot automated security fixes
- `github_disable_automated_security_fixes` - Disable automated security fixes
- `github_enable_vulnerability_alerts` - Enable Dependabot vulnerability alerts
- `github_disable_vulnerability_alerts` - Disable vulnerability alerts

### Collaborator Management (7 endpoints)

- `github_list_collaborators` - List repository collaborators
- `github_check_collaborator` - Check if user is a collaborator
- `github_add_collaborator` - Add collaborator to repository
- `github_remove_collaborator` - Remove collaborator from repository
- `github_get_collaborator_permission` - Get collaborator permission level
- `github_list_repository_invitations` - List pending repository invitations
- `github_delete_repository_invitation` - Delete/cancel a repository invitation

### Issue Operations (9 endpoints)

- `github_create_issue` - Create a new issue
- `github_list_issues` - List issues in a repository
- `github_get_issue` - Get a specific issue
- `github_update_issue` - Update an existing issue
- `github_close_issue` - Close an issue
- `github_create_issue_comment` - Add a comment to an issue
- `github_list_issue_comments` - List comments on an issue
- `github_update_issue_comment` - Update an issue comment
- `github_delete_issue_comment` - Delete an issue comment

### Pull Request Operations (4 endpoints)

- `github_create_pull_request` - Create a new pull request
- `github_list_pull_requests` - List pull requests in a repository
- `github_get_pull_request` - Get a specific pull request
- `github_merge_pull_request` - Merge a pull request

### Branch Operations (5 endpoints)

- `github_list_branches` - List all branches in a repository
- `github_get_branch` - Get information about a specific branch
- `github_create_branch` - Create a new branch
- `github_delete_branch` - Delete a branch
- `github_get_branch_protection` - Get branch protection rules

### Commit Operations (3 endpoints)

- `github_list_commits` - List commits in a repository
- `github_get_commit` - Get a specific commit
- `github_compare_commits` - Compare two commits or branches

### Release Operations (6 endpoints)

- `github_list_releases` - List all releases
- `github_get_latest_release` - Get the latest release
- `github_get_release` - Get a specific release by ID
- `github_create_release` - Create a new release
- `github_update_release` - Update a release
- `github_delete_release` - Delete a release

### Content Operations (5 endpoints)

- `github_get_file_content` - Get contents of a file
- `github_create_file` - Create a file
- `github_update_file` - Update a file
- `github_delete_file` - Delete a file
- `github_get_directory_content` - Get contents of a directory

### GitHub Actions (9 endpoints)

- `github_list_workflows` - List all workflows
- `github_get_workflow` - Get a specific workflow
- `github_list_workflow_runs` - List workflow runs
- `github_get_workflow_run` - Get a specific workflow run
- `github_cancel_workflow_run` - Cancel a workflow run
- `github_rerun_workflow` - Re-run a workflow
- `github_delete_workflow_run` - Delete a workflow run
- `github_list_workflow_run_artifacts` - List artifacts for a workflow run
- `github_download_artifact` - Download a workflow artifact

### Webhook Operations (11 endpoints)

- `github_list_webhooks` - List all webhooks for a repository
- `github_get_webhook` - Get a specific webhook by ID
- `github_create_webhook` - Create a new webhook
- `github_update_webhook` - Update an existing webhook
- `github_delete_webhook` - Delete a webhook
- `github_ping_webhook` - Trigger a ping event to webhook
- `github_test_webhook` - Trigger a test push event to webhook
- `github_list_webhook_deliveries` - List deliveries for a webhook
- `github_get_webhook_delivery` - Get a specific webhook delivery
- `github_redeliver_webhook` - Redeliver a webhook delivery

### Search Operations (8 endpoints)

- `github_search_repositories` - Search for repositories
- `github_search_issues` - Search for issues and pull requests
- `github_search_code` - Search code across repositories
- `github_search_commits` - Search commits
- `github_search_users` - Search for users
- `github_search_topics` - Search for topics
- `github_search_labels` - Search for labels in a repository

### User Operations (1 endpoint)

- `github_get_authenticated_user` - Get authenticated user information

## Common Use Cases

### Repository Automation

Create and configure repositories programmatically:

```typescript
// Create repository with full configuration
await server.handleRequest({
  method: 'github_create_repository',
  params: {
    name: 'my-project',
    description: 'My awesome project',
    private: false,
    auto_init: true,
    gitignore_template: 'Node',
    license_template: 'mit',
  },
});

// Update repository settings
await server.handleRequest({
  method: 'github_update_repository',
  params: {
    owner: 'myorg',
    repo: 'my-project',
    has_issues: true,
    has_wiki: false,
    allow_squash_merge: true,
    delete_branch_on_merge: true,
  },
});

// Add topics for discoverability
await server.handleRequest({
  method: 'github_replace_repository_topics',
  params: {
    owner: 'myorg',
    repo: 'my-project',
    topics: ['javascript', 'api', 'automation'],
  },
});
```

### Team & Access Management

Manage collaborators and permissions:

```typescript
// Add collaborator
await server.handleRequest({
  method: 'github_add_collaborator',
  params: {
    owner: 'myorg',
    repo: 'my-project',
    username: 'developer123',
    permission: 'push',
  },
});

// Add team access
await server.handleRequest({
  method: 'github_add_repository_team',
  params: {
    owner: 'myorg',
    repo: 'my-project',
    team_slug: 'backend-team',
    permission: 'admin',
  },
});
```

### CI/CD Integration

Automate workflows and deployments:

```typescript
// List workflow runs
await server.handleRequest({
  method: 'github_list_workflow_runs',
  params: {
    owner: 'myorg',
    repo: 'my-project',
    workflow_id: 'deploy.yml',
  },
});

// Re-run failed workflow
await server.handleRequest({
  method: 'github_rerun_workflow',
  params: {
    owner: 'myorg',
    repo: 'my-project',
    run_id: 123456,
  },
});

// Download build artifacts
await server.handleRequest({
  method: 'github_download_artifact',
  params: {
    owner: 'myorg',
    repo: 'my-project',
    artifact_id: 789012,
  },
});
```

### Webhook Management

Set up event-driven integrations:

```typescript
// Create webhook
await server.handleRequest({
  method: 'github_create_webhook',
  params: {
    owner: 'myorg',
    repo: 'my-project',
    config: {
      url: 'https://myapp.com/webhooks',
      content_type: 'json',
      secret: 'my-secret-key',
    },
    events: ['push', 'pull_request', 'issues'],
    active: true,
  },
});

// List webhook deliveries
await server.handleRequest({
  method: 'github_list_webhook_deliveries',
  params: {
    owner: 'myorg',
    repo: 'my-project',
    hook_id: 12345,
  },
});

// Redeliver failed webhook
await server.handleRequest({
  method: 'github_redeliver_webhook',
  params: {
    owner: 'myorg',
    repo: 'my-project',
    hook_id: 12345,
    delivery_id: 67890,
  },
});
```

### Release Management

Automate release workflows:

```typescript
// Create release
await server.handleRequest({
  method: 'github_create_release',
  params: {
    owner: 'myorg',
    repo: 'my-project',
    tag_name: 'v1.0.0',
    name: 'Version 1.0.0',
    body: 'Release notes here',
    draft: false,
    prerelease: false,
  },
});

// Get latest release
await server.handleRequest({
  method: 'github_get_latest_release',
  params: {
    owner: 'myorg',
    repo: 'my-project',
  },
});
```

## Examples

A working example demonstrating the client's capabilities is provided in `examples/basic-usage.ts`:

### Basic Usage Example

Demonstrates all core operations:
- Getting repository information
- Listing issues and pull requests
- Listing branches and commits
- Getting authenticated user information

**Run the example:**
```bash
# Using default repository (octocat/Hello-World)
GITHUB_TOKEN=your_token npm run example:basic

# Using your own repository
GITHUB_TOKEN=your_token REPO_OWNER=owner REPO_NAME=repo npm run example:basic
```

**Note:** The `examples/` directory contains additional working examples including `setup-new-repo.ts` which demonstrates repository setup automation. See [`examples/README.md`](./examples/README.md) for details.

## MCP Request/Response Format

### Request Format

```typescript
{
  method: string,        // The tool/method name
  params: {              // Parameters for the method
    [key: string]: any
  }
}
```

### Response Format

```typescript
{
  success: boolean,      // Whether the request succeeded
  data?: any,            // Response data (if successful)
  error?: {              // Error information (if failed)
    code: string,
    message: string,
    details?: any
  }
}
```

## Important Notes

### GitHub Token Requirements

- A GitHub personal access token is required
- Generate one at: https://github.com/settings/tokens
- Required scopes depend on operations:
  - `repo` - Full repository access (for private repos)
  - `public_repo` - Public repository access only
  - `read:user` - Read user profile data
  - `user:email` - Read user email addresses
  - `admin:repo_hook` - Full control of repository hooks (webhooks)
  - `admin:org` - Full control of organization settings (for team operations)
  - `workflow` - Update GitHub Actions workflows

### Rate Limiting

GitHub API has rate limits:

- **Authenticated requests**: 5,000 requests per hour
- **Unauthenticated requests**: 60 requests per hour
- Check rate limit status in response headers
- The client will throw an error if rate limited

### Error Handling

All methods throw `GitHubAPIError` on failure:

```typescript
try {
  const repo = await client.getRepository('owner', 'repo');
} catch (error) {
  if (error instanceof GitHubAPIError) {
    console.error(`Error ${error.code}: ${error.message}`);
    console.error('Status:', error.statusCode);
  }
}
```

### Security Best Practices

- Never commit your GitHub token to version control
- Use environment variables for tokens
- Rotate tokens regularly
- Use minimal required scopes for your token
- Consider using GitHub Apps for production applications
- Always use webhook secrets for signature verification
- Enable Dependabot security alerts on repositories

## API Documentation

For detailed GitHub API documentation, visit:

- [GitHub REST API Documentation](https://docs.github.com/en/rest)
- [Octokit.js Documentation](https://octokit.github.io/rest.js/)

## License

This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.

## Contributing

Contributions are welcome! Please feel free to submit a Pull Request. For major changes, please open an issue first to discuss what you would like to change.

Please make sure to update tests as appropriate.