GitHub Repos Manager MCP Server

Implements the Model Context Protocol (MCP) specification using stdio (standard input/output) as the transport layer, enabling direct communication between MCP clients (Claude Desktop, Cline, Cursor, Roo Code) and a Node.js server that proxies all requests to GitHub's REST and GraphQL APIs. The server maintains a persistent connection, marshals JSON-RPC 2.0 messages, and routes tool invocations through a handler-based architecture without requiring Docker or the GitHub CLI.

Implements GitHub Personal Access Token (PAT) authentication at the GitHubAPIService layer, handling token validation, request signing, and rate-limit tracking across both REST and GraphQL APIs. The system manages authentication state without OAuth flows, stores tokens securely via environment variables or configuration files, and implements exponential backoff and rate-limit headers inspection to prevent API quota exhaustion.

Implements 4 label tools and 4 milestone tools for managing issue/PR metadata. Labels are created via /repos/{owner}/{repo}/labels with name, color, and description. Milestones are created via /repos/{owner}/{repo}/milestones with title, description, and due date. Both support listing, updating, and deletion. Labels can be applied to issues/PRs via /repos/{owner}/{repo}/issues/{issue_number}/labels. Milestones track progress through open/closed issue counts. The handler supports bulk label operations and milestone filtering by state.

Implements 9 security tools covering deploy key management, webhook configuration, and repository secrets. Deploy keys are managed via /repos/{owner}/{repo}/keys, enabling SSH-based authentication for CI/CD systems. Webhooks are configured via /repos/{owner}/{repo}/hooks with event filtering (push, pull_request, issues, etc.) and payload URL specification. Secrets are managed via /repos/{owner}/{repo}/actions/secrets for GitHub Actions integration. The handler supports webhook testing via /repos/{owner}/{repo}/hooks/{hook_id}/tests and secret encryption/decryption for secure storage.

Implements workflow management tools that trigger GitHub Actions workflows, retrieve workflow runs, and access artifacts. Workflows are triggered via /repos/{owner}/{repo}/actions/workflows/{workflow_id}/dispatches with input parameters. Workflow runs are retrieved via /repos/{owner}/{repo}/actions/runs with filtering by status (success, failure, in_progress). Artifacts are accessed via /repos/{owner}/{repo}/actions/runs/{run_id}/artifacts, enabling download of build outputs, test reports, and other artifacts. The handler supports workflow re-runs and cancellation for workflow management.

Implements search tools that query repositories across GitHub using the /search/repositories endpoint with advanced filtering syntax. Search supports language filters (language:python), star counts (stars:>1000), date ranges (created:>2023-01-01), and topic filters (topic:machine-learning). Results are paginated and include repository metadata (stars, forks, language, topics). The handler normalizes search results and formats them for human readability. Search is scoped to public repositories unless the token has access to private repositories.

Implements organization management tools that retrieve organization metadata, list members, manage teams, and configure organization settings. Organization metadata is retrieved via /orgs/{org}, exposing public profile information, repositories count, and member count. Members are listed via /orgs/{org}/members with filtering by role. Teams are managed via /orgs/{org}/teams with member addition/removal. The handler supports team permission configuration (pull, push, admin) and team repository access management.

Implements project management tools that create and manage GitHub Projects (legacy and v2), organize cards on boards, and track project progress. Projects are created via /repos/{owner}/{repo}/projects with name and description. Cards are managed via /projects/{project_id}/columns/{column_id}/cards with support for issue/PR association. The handler supports column management (To Do, In Progress, Done) and card movement between columns. Project progress is tracked through card counts and issue association.

Implements analytics tools that retrieve repository statistics including language distribution, contributor counts, commit frequency, and code metrics. Language statistics are retrieved via /repos/{owner}/{repo}/languages, showing byte counts per language. Contributor statistics are retrieved via /repos/{owner}/{repo}/contributors, showing commit counts and contribution graphs. The handler supports time-based filtering for trend analysis and aggregation of statistics across multiple repositories.

Implements a formatter architecture that converts GitHub API responses (JSON objects) into human-readable markdown format for display in MCP clients. The formatter supports multiple output types: repository metadata, issues, PRs, commits, and analytics. Markdown generation includes tables for structured data (issue lists, contributor stats), code blocks for diffs and logs, and formatted headers for hierarchy. The system maintains consistent formatting across all 89 tools, enabling predictable output for AI assistants and users.

Implements error handling that catches GitHub API errors, normalizes error responses, and provides actionable error messages to users. The system maps GitHub API error codes (404 Not Found, 422 Unprocessable Entity, 403 Forbidden) to human-readable messages with suggestions for remediation. Rate-limit errors are handled with exponential backoff and retry logic. The handler maintains error context (request details, API response) for debugging and logging.

The GitHubAPIService layer implements a hybrid API strategy, routing requests to GitHub's REST API for most operations (82 implemented methods) while maintaining placeholder GraphQL methods (6) for future complex queries. The system automatically selects the optimal API based on operation type: REST for simple CRUD operations, GraphQL for batch queries and complex nested data retrieval. Request marshaling handles API-specific payload formats, response parsing, and error normalization across both protocols.

Organizes 89 distinct GitHub tools into 17 functional handler modules (Repository Operations, Issue Management, Pull Requests, File Management, Branch & Commits, Labels, Milestones, Security, Workflows, Search, Organization, Projects, Analytics, etc.), each implementing a cohesive set of related operations. Each handler module exposes tools via a standardized interface that accepts MCP tool invocation parameters, validates inputs, calls GitHubAPIService methods, and returns formatted results. The tool registry dynamically loads handlers and exposes them to MCP clients as callable tools with JSON schemas.

Implements 5 repository-level tools (list, search, browse, get metadata, get topics) that retrieve repository information, search across repositories by name/description/language, and extract metadata (stars, forks, language distribution, topics). The search handler uses GitHub's REST API search endpoint with query syntax support (language filters, date ranges, star counts), returning paginated results with repository metadata. Metadata retrieval uses the /repos/{owner}/{repo} endpoint to fetch detailed repository information including permissions, visibility, and configuration state.

Implements 8 issue management tools covering creation, retrieval, state transitions (open/closed), locking/unlocking, assignment, and filtering. The system uses GitHub's /repos/{owner}/{repo}/issues endpoint for CRUD operations and /repos/{owner}/{repo}/issues/{issue_number} for state mutations. Issue state is managed through the 'state' parameter (open/closed), while locking prevents further comments via the lock endpoint. Assignment uses the 'assignees' array to manage issue ownership. The handler supports filtering by state, assignee, label, and milestone, returning paginated results with full issue metadata.

Implements 4 issue comment tools (create, list, edit, delete) that manage discussion threads on issues. Comments are created via /repos/{owner}/{repo}/issues/{issue_number}/comments, edited via PATCH to /repos/{owner}/{repo}/issues/comments/{comment_id}, and deleted via DELETE to the same endpoint. The handler maintains comment threading by returning comments in chronological order with author metadata, timestamps, and edit history. Comment bodies support markdown formatting and GitHub mentions (@username), enabling rich discussion threads.

Implements 7 PR management tools covering creation, review management, file analysis, and editing. PRs are created via /repos/{owner}/{repo}/pulls with title, body, head/base branch specification. Reviews are managed through /repos/{owner}/{repo}/pulls/{pull_number}/reviews, supporting APPROVE, REQUEST_CHANGES, and COMMENT review states. File analysis retrieves changed files via /repos/{owner}/{repo}/pulls/{pull_number}/files, showing diff hunks, additions/deletions, and patch content. The handler supports draft PRs, auto-merge configuration, and review request assignment to specific users.

Implements 4 file management tools (create, update, upload, delete) that manipulate repository files through GitHub's /repos/{owner}/{repo}/contents/{path} endpoint. File creation and updates use the PUT endpoint with base64-encoded content and commit messages. The system maintains file history through git commit metadata (author, committer, message). Uploads support binary files through base64 encoding. Deletions use the DELETE endpoint with commit messages. The handler supports branch specification for all operations, enabling file management on non-default branches.

Implements 5 branch/commit tools (create branch, list branches, get commit history, compare commits, get branch protection) that manage repository branches and commit history. Branches are created via /repos/{owner}/{repo}/git/refs with SHA references. Commit history is retrieved via /repos/{owner}/{repo}/commits with filtering by author, date, and path. Commit comparison uses /repos/{owner}/{repo}/compare/{base}...{head} to show diff statistics and changed files. Branch protection rules are retrieved via /repos/{owner}/{repo}/branches/{branch}/protection, exposing required status checks and review requirements.