{"_id":"@onamfc/mcp-github-integration","name":"@onamfc/mcp-github-integration","dist-tags":{"latest":"1.0.0"},"versions":{"1.0.0":{"name":"@onamfc/mcp-github-integration","version":"1.0.0","description":"GitHub API client for MCP server integration","license":"MIT","type":"module","repository":{"type":"git","url":"git+https://github.com/onamfc/mcp-github-integration.git"},"main":"./dist/index.js","types":"./dist/index.d.ts","scripts":{"build":"npx -p typescript tsc","dev":"npx -p typescript tsc --watch","test":"NODE_OPTIONS='--experimental-vm-modules' npx vitest run","test:watch":"NODE_OPTIONS='--experimental-vm-modules' npx vitest","test:ui":"NODE_OPTIONS='--experimental-vm-modules' npx vitest --ui","test:coverage":"NODE_OPTIONS='--experimental-vm-modules' npx vitest run --coverage","example:basic":"node dist/examples/basic-usage.js","example:setup-repo":"node dist/examples/setup-new-repo.js"},"dependencies":{"@octokit/rest":"^20.0.2","@octokit/types":"^12.4.0","@onamfc/developer-log":"^1.0.0","@onamfc/pkg-inspect":"^1.0.0"},"devDependencies":{"@types/node":"^20.19.25","@vitest/ui":"^4.0.10","typescript":"^5.9.3","vitest":"^4.0.10"},"_id":"@onamfc/mcp-github-integration@1.0.0","gitHead":"84398821bda93e51730cff9a61c8e9826022d64a","bugs":{"url":"https://github.com/onamfc/mcp-github-integration/issues"},"homepage":"https://github.com/onamfc/mcp-github-integration#readme","_nodeVersion":"22.14.0","_npmVersion":"10.9.2","dist":{"integrity":"sha512-wHia2DJgJxfelKf6tsk+pAfJCTxlN4nmcgKq3GoA4PtT0ErQZ71sN3ejOmql5BdsftAoLBJBt3BRnBBjjBWC/A==","shasum":"396f304c646ea8b642813f93bcf70bf0dffd2de6","tarball":"https://registry.npmjs.org/@onamfc/mcp-github-integration/-/mcp-github-integration-1.0.0.tgz","fileCount":25,"unpackedSize":286064,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIQCPfQvrvSBS4leGXCXNvOo9e1MlVYzU2i8eYcLThiF+BQIgG04f4IuyQ41XxhM0yAlXehBIU7nCLmUG5Ycr+MhnDDE="}]},"_npmUser":{"name":"onamfc","email":"onamfc@gmail.com"},"directories":{},"maintainers":[{"name":"onamfc","email":"onamfc@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/mcp-github-integration_1.0.0_1763679136725_0.893460797685985"},"_hasShrinkwrap":false}},"time":{"created":"2025-11-20T22:52:16.661Z","1.0.0":"2025-11-20T22:52:16.961Z","modified":"2025-11-20T22:52:17.221Z"},"maintainers":[{"name":"onamfc","email":"onamfc@gmail.com"}],"description":"GitHub API client for MCP server integration","homepage":"https://github.com/onamfc/mcp-github-integration#readme","repository":{"type":"git","url":"git+https://github.com/onamfc/mcp-github-integration.git"},"bugs":{"url":"https://github.com/onamfc/mcp-github-integration/issues"},"license":"MIT","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 & 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","readmeFilename":"README.md","_rev":"1-755881acdcb2c5bca21e08d91e6612ed"}