{"id":50728680,"url":"https://github.com/onamfc/mcp-github-integration","last_synced_at":"2026-06-10T06:45:52.876Z","repository":{"id":325360932,"uuid":"1100770798","full_name":"onamfc/mcp-github-integration","owner":"onamfc","description":"A TypeScript package for interacting with the GitHub API through an MCP (Model Context Protocol) server integration.","archived":false,"fork":false,"pushed_at":"2025-11-20T22:45:14.000Z","size":80,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-11-21T00:14:58.379Z","etag":null,"topics":["developer-tools","github-api","mcp","model-context-protocol","octokit","typescript"],"latest_commit_sha":null,"homepage":"https://thebrandonestrella.com","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/onamfc.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-11-20T18:25:10.000Z","updated_at":"2025-11-20T23:33:09.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/onamfc/mcp-github-integration","commit_stats":null,"previous_names":["onamfc/mcp-github-integration"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/onamfc/mcp-github-integration","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/onamfc%2Fmcp-github-integration","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/onamfc%2Fmcp-github-integration/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/onamfc%2Fmcp-github-integration/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/onamfc%2Fmcp-github-integration/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/onamfc","download_url":"https://codeload.github.com/onamfc/mcp-github-integration/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/onamfc%2Fmcp-github-integration/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":34140774,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-06-10T02:00:07.152Z","response_time":89,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["developer-tools","github-api","mcp","model-context-protocol","octokit","typescript"],"created_at":"2026-06-10T06:45:52.105Z","updated_at":"2026-06-10T06:45:52.863Z","avatar_url":"https://github.com/onamfc.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# GitHub MCP API Client\n\nA TypeScript package for interacting with the GitHub API through an MCP (Model Context Protocol) server integration.\n\n## Features\n\n- Full TypeScript support with type definitions\n- **129 MCP tools** covering all major GitHub API operations:\n  - Repository management (create, update, delete, search, settings, administration)\n  - Issue tracking (create, update, close, comments, search)\n  - Pull request management (create, merge, review, comments)\n  - Branch operations (create, delete, list, protect)\n  - Commit operations (list, get, compare)\n  - Release management (create, update, delete, assets)\n  - Content operations (read, write, delete files)\n  - GitHub Actions (workflows, runs, artifacts)\n  - Webhooks (create, update, delete, deliveries, redelivery)\n  - Collaborators and teams (add, remove, permissions)\n  - Repository statistics and insights\n  - Security settings (Dependabot, vulnerability alerts)\n  - Advanced search across repositories, issues, PRs, code, commits, users, topics, and labels\n- Built-in logging with `@onamfc/developer-log`\n- Package inspection with `@onamfc/pkg-inspect`\n- Robust error handling\n\n## Installation\n\n### From NPM\n\n```bash\nnpm install @onamfc/mcp-github-integration\n```\n\n### From Source\n\n```bash\ngit clone https://github.com/onamfc/mcp-github-integration.git\ncd mcp-github-integration\nnpm install\nnpm run build\n```\n\n## Configuration\n\nSet your GitHub personal access token as an environment variable:\n\n```bash\nexport GITHUB_TOKEN=your_github_token_here\n```\n\n## Usage\n\n### Using the MCP Server\n\n```typescript\nimport { MCPServer } from '@onamfc/mcp-github-integration';\n\nconst server = new MCPServer(process.env.GITHUB_TOKEN);\n\n// Get authenticated user\nconst response = await server.handleRequest({\n  method: 'github_get_authenticated_user',\n  params: {},\n});\n\nif (response.success) {\n  console.log('User:', response.data);\n}\n\n// Search repositories\nconst searchResponse = await server.handleRequest({\n  method: 'github_search_repositories',\n  params: {\n    q: 'typescript',\n    per_page: 10,\n  },\n});\n```\n\n### Using the GitHub Client Directly\n\n```typescript\nimport { GitHubClient } from '@onamfc/mcp-github-integration';\n\nconst client = new GitHubClient({\n  token: process.env.GITHUB_TOKEN,\n});\n\n// Create a new repository\nconst newRepo = await client.createRepository({\n  name: 'my-awesome-project',\n  description: 'My awesome project description',\n  private: false,\n  auto_init: true,\n});\n\n// Get repository information\nconst repo = await client.getRepository('owner', 'repo-name');\nconsole.log(repo);\n\n// Create an issue\nconst issue = await client.createIssue({\n  owner: 'owner',\n  repo: 'repo-name',\n  title: 'Bug Report',\n  body: 'Description of the bug',\n  labels: ['bug'],\n});\n\n// List pull requests\nconst prs = await client.listPullRequests({\n  owner: 'owner',\n  repo: 'repo-name',\n  state: 'open',\n});\n```\n\n## Available GitHub API Operations\n\n### Repository Operations (25 endpoints)\n\n- `github_get_repository` - Get repository information\n- `github_list_repositories` - List user's public repositories\n- `github_create_repository` - Create a new repository\n- `github_delete_repository` - Delete a repository\n- `github_update_repository` - Update repository settings and configuration\n- `github_get_repository_topics` - Get repository topics/tags\n- `github_replace_repository_topics` - Set repository topics for discoverability\n- `github_get_repository_languages` - Get programming languages used\n- `github_get_code_frequency_stats` - Get weekly addition/deletion statistics\n- `github_get_contributors_stats` - Get contributor activity statistics\n- `github_get_participation_stats` - Get weekly commit count statistics\n- `github_transfer_repository` - Transfer repository to new owner\n- `github_list_repository_teams` - List teams with access to repository\n- `github_check_team_permission` - Check team permission for repository\n- `github_add_repository_team` - Add or update team access to repository\n- `github_remove_repository_team` - Remove team access from repository\n- `github_enable_automated_security_fixes` - Enable Dependabot automated security fixes\n- `github_disable_automated_security_fixes` - Disable automated security fixes\n- `github_enable_vulnerability_alerts` - Enable Dependabot vulnerability alerts\n- `github_disable_vulnerability_alerts` - Disable vulnerability alerts\n\n### Collaborator Management (7 endpoints)\n\n- `github_list_collaborators` - List repository collaborators\n- `github_check_collaborator` - Check if user is a collaborator\n- `github_add_collaborator` - Add collaborator to repository\n- `github_remove_collaborator` - Remove collaborator from repository\n- `github_get_collaborator_permission` - Get collaborator permission level\n- `github_list_repository_invitations` - List pending repository invitations\n- `github_delete_repository_invitation` - Delete/cancel a repository invitation\n\n### Issue Operations (9 endpoints)\n\n- `github_create_issue` - Create a new issue\n- `github_list_issues` - List issues in a repository\n- `github_get_issue` - Get a specific issue\n- `github_update_issue` - Update an existing issue\n- `github_close_issue` - Close an issue\n- `github_create_issue_comment` - Add a comment to an issue\n- `github_list_issue_comments` - List comments on an issue\n- `github_update_issue_comment` - Update an issue comment\n- `github_delete_issue_comment` - Delete an issue comment\n\n### Pull Request Operations (4 endpoints)\n\n- `github_create_pull_request` - Create a new pull request\n- `github_list_pull_requests` - List pull requests in a repository\n- `github_get_pull_request` - Get a specific pull request\n- `github_merge_pull_request` - Merge a pull request\n\n### Branch Operations (5 endpoints)\n\n- `github_list_branches` - List all branches in a repository\n- `github_get_branch` - Get information about a specific branch\n- `github_create_branch` - Create a new branch\n- `github_delete_branch` - Delete a branch\n- `github_get_branch_protection` - Get branch protection rules\n\n### Commit Operations (3 endpoints)\n\n- `github_list_commits` - List commits in a repository\n- `github_get_commit` - Get a specific commit\n- `github_compare_commits` - Compare two commits or branches\n\n### Release Operations (6 endpoints)\n\n- `github_list_releases` - List all releases\n- `github_get_latest_release` - Get the latest release\n- `github_get_release` - Get a specific release by ID\n- `github_create_release` - Create a new release\n- `github_update_release` - Update a release\n- `github_delete_release` - Delete a release\n\n### Content Operations (5 endpoints)\n\n- `github_get_file_content` - Get contents of a file\n- `github_create_file` - Create a file\n- `github_update_file` - Update a file\n- `github_delete_file` - Delete a file\n- `github_get_directory_content` - Get contents of a directory\n\n### GitHub Actions (9 endpoints)\n\n- `github_list_workflows` - List all workflows\n- `github_get_workflow` - Get a specific workflow\n- `github_list_workflow_runs` - List workflow runs\n- `github_get_workflow_run` - Get a specific workflow run\n- `github_cancel_workflow_run` - Cancel a workflow run\n- `github_rerun_workflow` - Re-run a workflow\n- `github_delete_workflow_run` - Delete a workflow run\n- `github_list_workflow_run_artifacts` - List artifacts for a workflow run\n- `github_download_artifact` - Download a workflow artifact\n\n### Webhook Operations (11 endpoints)\n\n- `github_list_webhooks` - List all webhooks for a repository\n- `github_get_webhook` - Get a specific webhook by ID\n- `github_create_webhook` - Create a new webhook\n- `github_update_webhook` - Update an existing webhook\n- `github_delete_webhook` - Delete a webhook\n- `github_ping_webhook` - Trigger a ping event to webhook\n- `github_test_webhook` - Trigger a test push event to webhook\n- `github_list_webhook_deliveries` - List deliveries for a webhook\n- `github_get_webhook_delivery` - Get a specific webhook delivery\n- `github_redeliver_webhook` - Redeliver a webhook delivery\n\n### Search Operations (8 endpoints)\n\n- `github_search_repositories` - Search for repositories\n- `github_search_issues` - Search for issues and pull requests\n- `github_search_code` - Search code across repositories\n- `github_search_commits` - Search commits\n- `github_search_users` - Search for users\n- `github_search_topics` - Search for topics\n- `github_search_labels` - Search for labels in a repository\n\n### User Operations (1 endpoint)\n\n- `github_get_authenticated_user` - Get authenticated user information\n\n## Common Use Cases\n\n### Repository Automation\n\nCreate and configure repositories programmatically:\n\n```typescript\n// Create repository with full configuration\nawait server.handleRequest({\n  method: 'github_create_repository',\n  params: {\n    name: 'my-project',\n    description: 'My awesome project',\n    private: false,\n    auto_init: true,\n    gitignore_template: 'Node',\n    license_template: 'mit',\n  },\n});\n\n// Update repository settings\nawait server.handleRequest({\n  method: 'github_update_repository',\n  params: {\n    owner: 'myorg',\n    repo: 'my-project',\n    has_issues: true,\n    has_wiki: false,\n    allow_squash_merge: true,\n    delete_branch_on_merge: true,\n  },\n});\n\n// Add topics for discoverability\nawait server.handleRequest({\n  method: 'github_replace_repository_topics',\n  params: {\n    owner: 'myorg',\n    repo: 'my-project',\n    topics: ['javascript', 'api', 'automation'],\n  },\n});\n```\n\n### Team \u0026 Access Management\n\nManage collaborators and permissions:\n\n```typescript\n// Add collaborator\nawait server.handleRequest({\n  method: 'github_add_collaborator',\n  params: {\n    owner: 'myorg',\n    repo: 'my-project',\n    username: 'developer123',\n    permission: 'push',\n  },\n});\n\n// Add team access\nawait server.handleRequest({\n  method: 'github_add_repository_team',\n  params: {\n    owner: 'myorg',\n    repo: 'my-project',\n    team_slug: 'backend-team',\n    permission: 'admin',\n  },\n});\n```\n\n### CI/CD Integration\n\nAutomate workflows and deployments:\n\n```typescript\n// List workflow runs\nawait server.handleRequest({\n  method: 'github_list_workflow_runs',\n  params: {\n    owner: 'myorg',\n    repo: 'my-project',\n    workflow_id: 'deploy.yml',\n  },\n});\n\n// Re-run failed workflow\nawait server.handleRequest({\n  method: 'github_rerun_workflow',\n  params: {\n    owner: 'myorg',\n    repo: 'my-project',\n    run_id: 123456,\n  },\n});\n\n// Download build artifacts\nawait server.handleRequest({\n  method: 'github_download_artifact',\n  params: {\n    owner: 'myorg',\n    repo: 'my-project',\n    artifact_id: 789012,\n  },\n});\n```\n\n### Webhook Management\n\nSet up event-driven integrations:\n\n```typescript\n// Create webhook\nawait server.handleRequest({\n  method: 'github_create_webhook',\n  params: {\n    owner: 'myorg',\n    repo: 'my-project',\n    config: {\n      url: 'https://myapp.com/webhooks',\n      content_type: 'json',\n      secret: 'my-secret-key',\n    },\n    events: ['push', 'pull_request', 'issues'],\n    active: true,\n  },\n});\n\n// List webhook deliveries\nawait server.handleRequest({\n  method: 'github_list_webhook_deliveries',\n  params: {\n    owner: 'myorg',\n    repo: 'my-project',\n    hook_id: 12345,\n  },\n});\n\n// Redeliver failed webhook\nawait server.handleRequest({\n  method: 'github_redeliver_webhook',\n  params: {\n    owner: 'myorg',\n    repo: 'my-project',\n    hook_id: 12345,\n    delivery_id: 67890,\n  },\n});\n```\n\n### Release Management\n\nAutomate release workflows:\n\n```typescript\n// Create release\nawait server.handleRequest({\n  method: 'github_create_release',\n  params: {\n    owner: 'myorg',\n    repo: 'my-project',\n    tag_name: 'v1.0.0',\n    name: 'Version 1.0.0',\n    body: 'Release notes here',\n    draft: false,\n    prerelease: false,\n  },\n});\n\n// Get latest release\nawait server.handleRequest({\n  method: 'github_get_latest_release',\n  params: {\n    owner: 'myorg',\n    repo: 'my-project',\n  },\n});\n```\n\n## Examples\n\nA working example demonstrating the client's capabilities is provided in `examples/basic-usage.ts`:\n\n### Basic Usage Example\n\nDemonstrates all core operations:\n- Getting repository information\n- Listing issues and pull requests\n- Listing branches and commits\n- Getting authenticated user information\n\n**Run the example:**\n```bash\n# Using default repository (octocat/Hello-World)\nGITHUB_TOKEN=your_token npm run example:basic\n\n# Using your own repository\nGITHUB_TOKEN=your_token REPO_OWNER=owner REPO_NAME=repo npm run example:basic\n```\n\n**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.\n\n## MCP Request/Response Format\n\n### Request Format\n\n```typescript\n{\n  method: string,        // The tool/method name\n  params: {              // Parameters for the method\n    [key: string]: any\n  }\n}\n```\n\n### Response Format\n\n```typescript\n{\n  success: boolean,      // Whether the request succeeded\n  data?: any,            // Response data (if successful)\n  error?: {              // Error information (if failed)\n    code: string,\n    message: string,\n    details?: any\n  }\n}\n```\n\n## Important Notes\n\n### GitHub Token Requirements\n\n- A GitHub personal access token is required\n- Generate one at: https://github.com/settings/tokens\n- Required scopes depend on operations:\n  - `repo` - Full repository access (for private repos)\n  - `public_repo` - Public repository access only\n  - `read:user` - Read user profile data\n  - `user:email` - Read user email addresses\n  - `admin:repo_hook` - Full control of repository hooks (webhooks)\n  - `admin:org` - Full control of organization settings (for team operations)\n  - `workflow` - Update GitHub Actions workflows\n\n### Rate Limiting\n\nGitHub API has rate limits:\n\n- **Authenticated requests**: 5,000 requests per hour\n- **Unauthenticated requests**: 60 requests per hour\n- Check rate limit status in response headers\n- The client will throw an error if rate limited\n\n### Error Handling\n\nAll methods throw `GitHubAPIError` on failure:\n\n```typescript\ntry {\n  const repo = await client.getRepository('owner', 'repo');\n} catch (error) {\n  if (error instanceof GitHubAPIError) {\n    console.error(`Error ${error.code}: ${error.message}`);\n    console.error('Status:', error.statusCode);\n  }\n}\n```\n\n### Security Best Practices\n\n- Never commit your GitHub token to version control\n- Use environment variables for tokens\n- Rotate tokens regularly\n- Use minimal required scopes for your token\n- Consider using GitHub Apps for production applications\n- Always use webhook secrets for signature verification\n- Enable Dependabot security alerts on repositories\n\n## API Documentation\n\nFor detailed GitHub API documentation, visit:\n\n- [GitHub REST API Documentation](https://docs.github.com/en/rest)\n- [Octokit.js Documentation](https://octokit.github.io/rest.js/)\n\n## License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n\n## Contributing\n\nContributions 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.\n\nPlease make sure to update tests as appropriate.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fonamfc%2Fmcp-github-integration","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fonamfc%2Fmcp-github-integration","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fonamfc%2Fmcp-github-integration/lists"}