github-pro-mcp 0.0.1

package/README.md

@@ -0,0 +1,133 @@
+# GitHub Pro MCP
+
+[![npm version](https://img.shields.io/npm/v/github-pro-mcp)](https://www.npmjs.com/package/github-pro-mcp)
+[![Docker image](https://img.shields.io/docker/v/anantanandgupta/github-pro-mcp)](https://hub.docker.com/r/anantanandgupta/github-pro-mcp)
+
+An MCP (Model Context Protocol) server providing comprehensive GitHub API access via hybrid REST + GraphQL — **32 tools across 7 domains**.
+
+## Features
+
+- **32 Tools** — issues, pull requests, repositories, projects v2, labels, organizations, file operations
+- **Hybrid API** — REST for CRUD/search, GraphQL for cursor pagination and composite queries
+- **Resilient by Default** — automatic retry with exponential backoff + jitter, circuit breaker for API outages, proactive rate limit management
+- **Structured Logging** — multi-level (error/warn/info/debug) stderr output
+- **Owner/Repo Pinning** — lock the server to a specific owner or repository as a safety guardrail
+
+## Installation
+
+### npm
+
+```bash
+# Install globally
+npm install -g github-pro-mcp
+
+# Or run directly without installing
+npx github-pro-mcp
+```
+
+### Docker
+
+Multi-arch images for `linux/amd64` and `linux/arm64`:
+
+```bash
+docker pull anantanandgupta/github-pro-mcp
+```
+
+## Quick Start
+
+Set your GitHub token and run:
+
+```bash
+export GITHUB_PERSONAL_ACCESS_TOKEN=ghp_your_token_here
+github-pro-mcp
+```
+
+Or with Docker:
+
+```bash
+docker run -i --rm \
+  -e GITHUB_PERSONAL_ACCESS_TOKEN=ghp_your_token_here \
+  anantanandgupta/github-pro-mcp
+```
+
+## Configuration
+
+### Required
+
+| Variable | Description |
+|----------|-------------|
+| `GITHUB_PERSONAL_ACCESS_TOKEN` | GitHub PAT with appropriate scopes |
+
+### Optional
+
+| Variable | Default | Description |
+|----------|---------|-------------|
+| `GITHUB_HOST` | — | For GHES: `https://{hostname}/api/v3` |
+| `GITHUB_OWNER` | — | Pin server to a single owner (rejects mismatched calls) |
+| `GITHUB_REPO` | — | Pin server to a single repository (rejects mismatched calls) |
+| `GITHUB_RETRY_MAX_ATTEMPTS` | `3` | Max retries for transient errors |
+| `GITHUB_RETRY_BACKOFF_MS` | `1000` | Initial retry backoff (ms) |
+| `GITHUB_CIRCUIT_BREAKER_THRESHOLD` | `5` | Failures before circuit opens |
+| `GITHUB_CIRCUIT_BREAKER_RESET_MS` | `30000` | Circuit recovery timeout (ms) |
+| `GITHUB_LOG_LEVEL` | `error` | Log level: `error`, `warn`, `info`, `debug` |
+
+## Usage with opencode
+
+Add to your `opencode.json`:
+
+```json
+{
+  "mcp": {
+    "github_pro": {
+      "type": "local",
+      "command": ["node", "path/to/github-pro-mcp/dist/index.js"],
+      "environment": {
+        "GITHUB_PERSONAL_ACCESS_TOKEN": "{env:GITHUB_TOKEN}"
+      }
+    }
+  }
+}
+```
+
+For Docker-based usage:
+
+```json
+{
+  "mcp": {
+    "github_pro": {
+      "type": "local",
+      "command": ["docker", "run", "-i", "--rm", "-e", "GITHUB_PERSONAL_ACCESS_TOKEN", "anantanandgupta/github-pro-mcp"],
+      "environment": {
+        "GITHUB_PERSONAL_ACCESS_TOKEN": "{env:GITHUB_TOKEN}"
+      }
+    }
+  }
+}
+```
+
+## Tool Reference
+
+| Domain | Tools | Count |
+|--------|-------|-------|
+| **User & Repos** | `auth_get_current_login`, `file_get_content`, `profile_get`, `owner_list_repository`, `file_create_update`, `code_search`, `repository_search` | 7 |
+| **Issues** | `issue_read`, `issue_list`, `issue_search`, `issue_add_comment`, `sub_issue_write`, `issue_create`, `issue_close`, `issue_reopen`, `issue_update`, `issue_add_label`, `issue_remove_label` | 11 |
+| **Issue Fields** | `owner_list_issue_field`, `issue_get_field_value`, `issue_set_field_value` | 3 |
+| **Pull Requests** | `pull_request_read`, `pull_request_create`, `pull_request_merge` | 3 |
+| **Organizations** | `organization_search`, `owner_list_issue_type`, `owner_list_organization` | 3 |
+| **Projects v2** | `owner_list_project`, `projects_get`, `projects_write` | 3 |
+| **Labels** | `label_list`, `label_write` | 2 |
+| **Total** | | **32** |
+
+## FAQ / Troubleshooting
+
+| Error | Likely Cause |
+|-------|-------------|
+| `401` | Token expired or invalid |
+| `403` | Missing OAuth scopes or SSO |
+| `404` | Resource doesn't exist or no access |
+| `429` | Rate limited — wait and retry |
+| Circuit breaker open | GitHub API returning repeated errors — auto-recovers in 30s |
+
+## License
+
+ISC

package/dist/client.d.ts

@@ -0,0 +1,27 @@
+import { Octokit } from "@octokit/core";
+import type { Api } from "@octokit/plugin-rest-endpoint-methods";
+export type OctokitWithRest = Octokit & {
+    rest: Api["rest"];
+};
+/**
+ * Creates an authenticated Octokit client with all plugins configured.
+ *
+ * The returned client wraps all REST requests through:
+ *   circuit breaker → retry → throttling → GitHub API
+ *
+ * Rate limit headers from responses are automatically tracked
+ * via `updateRateLimits()`.
+ */
+export declare function createClient(): OctokitWithRest;
+/**
+ * Execute a raw GraphQL query against the GitHub API.
+ * The query is wrapped with circuit breaker and retry protection.
+ */
+export declare function gql<T>(query: string, variables?: Record<string, unknown>): Promise<T>;
+/**
+ * Derive the web UI base URL from the GITHUB_HOST env var.
+ * For api.github.com, returns https://github.com.
+ * For GHES, derives from the hostname.
+ */
+export declare function getWebBaseUrl(): string;
+export declare function gqlPaginate<T>(query: string, variables?: Record<string, unknown>): Promise<T[]>;

package/dist/client.js

@@ -0,0 +1,80 @@
+import { Octokit } from "@octokit/core";
+import { restEndpointMethods } from "@octokit/plugin-rest-endpoint-methods";
+import { paginateGraphQL } from "@octokit/plugin-paginate-graphql";
+import { throttling } from "@octokit/plugin-throttling";
+import { withRetry } from "./utils/retry.js";
+import { withCircuitBreaker } from "./utils/circuitBreaker.js";
+import { createLogger } from "./utils/logger.js";
+import { updateRateLimits } from "./utils/rateLimit.js";
+const log = createLogger("client");
+const MyOctokit = Octokit
+    .plugin(restEndpointMethods)
+    .plugin(paginateGraphQL)
+    .plugin(throttling);
+/**
+ * Creates an authenticated Octokit client with all plugins configured.
+ *
+ * The returned client wraps all REST requests through:
+ *   circuit breaker → retry → throttling → GitHub API
+ *
+ * Rate limit headers from responses are automatically tracked
+ * via `updateRateLimits()`.
+ */
+export function createClient() {
+    const token = process.env.GITHUB_PERSONAL_ACCESS_TOKEN;
+    if (!token) {
+        throw new Error("GITHUB_PERSONAL_ACCESS_TOKEN environment variable is not set. " +
+            "Create a token at https://github.com/settings/tokens " +
+            "and set it as GITHUB_PERSONAL_ACCESS_TOKEN in your environment.");
+    }
+    const onRateLimitStrategy = process.env.GITHUB_THROTTLE_ON_RATE_LIMIT !== "queue";
+    const octokit = new MyOctokit({
+        auth: token,
+        baseUrl: process.env.GITHUB_HOST ?? "https://api.github.com",
+        throttle: {
+            onRateLimit: (retryAfter, options) => {
+                log.warn(`Primary rate limit hit. Retrying after ${retryAfter}s. ` +
+                    `Request: ${options.method} ${options.url}`);
+                return onRateLimitStrategy;
+            },
+            onSecondaryRateLimit: (retryAfter, options) => {
+                log.warn(`Secondary rate limit hit. Retrying after ${retryAfter}s. ` +
+                    `Request: ${options.method} ${options.url}`);
+                return process.env.GITHUB_THROTTLE_ON_SECONDARY_RATE_LIMIT !== "queue";
+            },
+        },
+    });
+    octokit.hook.after("request", (response) => {
+        if (response?.headers) {
+            updateRateLimits(response.headers);
+        }
+    });
+    octokit.hook.wrap("request", async (request, options) => {
+        const label = `REST ${options.method} ${options.url}`;
+        return withCircuitBreaker(() => withRetry(() => Promise.resolve(request(options)), label), "github-rest");
+    });
+    return octokit;
+}
+/**
+ * Execute a raw GraphQL query against the GitHub API.
+ * The query is wrapped with circuit breaker and retry protection.
+ */
+export async function gql(query, variables) {
+    const octokit = createClient();
+    return withCircuitBreaker(() => withRetry(() => octokit.graphql(query, variables), `GraphQL ${query.trim().split("\n")[0].slice(0, 60)}`), "github-graphql");
+}
+/**
+ * Derive the web UI base URL from the GITHUB_HOST env var.
+ * For api.github.com, returns https://github.com.
+ * For GHES, derives from the hostname.
+ */
+export function getWebBaseUrl() {
+    const apiUrl = new URL(process.env.GITHUB_HOST ?? "https://api.github.com");
+    if (apiUrl.hostname === "api.github.com")
+        return "https://github.com";
+    return `https://${apiUrl.hostname}`;
+}
+export async function gqlPaginate(query, variables) {
+    const octokit = createClient();
+    return withCircuitBreaker(() => withRetry(() => octokit.graphql.paginate(query, variables), `GraphQL paginate ${query.trim().split("\n")[0].slice(0, 60)}`), "github-graphql");
+}

package/dist/index.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/index.js

@@ -0,0 +1,52 @@
+#!/usr/bin/env node
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { registerAuthGetCurrentLogin, registerFileGetContent, registerProfileGet, registerOwnerListRepository, registerFileCreateUpdate, registerCodeSearch, registerRepositorySearch, } from "./tools/repos.js";
+import { registerOrganizationSearch, registerOwnerListIssueType, registerOwnerListOrganization, } from "./tools/organizations.js";
+import { registerPullRequestRead, registerPullRequestCreate, registerPullRequestMerge, } from "./tools/pull_requests.js";
+import { registerIssueRead, registerIssueList, registerIssueSearch, registerIssueAddComment, registerSubIssueWrite, registerIssueCreate, registerIssueClose, registerIssueReopen, registerIssueUpdate, registerIssueAddLabel, registerIssueRemoveLabel, } from "./tools/issues.js";
+import { registerOwnerListIssueField, registerIssueGetFieldValue, registerIssueSetFieldValue, } from "./tools/issue_fields.js";
+import { registerLabelList, registerLabelWrite, } from "./tools/labels.js";
+import { registerOwnerListProject, registerProjectsGet, registerProjectsWrite, } from "./tools/projects.js";
+const server = new McpServer({ name: "github-pro-mcp", version: "2.0.1" }, { capabilities: { tools: {} } });
+registerAuthGetCurrentLogin(server);
+registerFileGetContent(server);
+registerProfileGet(server);
+registerOwnerListRepository(server);
+registerFileCreateUpdate(server);
+registerCodeSearch(server);
+registerRepositorySearch(server);
+registerOrganizationSearch(server);
+registerOwnerListIssueType(server);
+registerOwnerListOrganization(server);
+registerPullRequestRead(server);
+registerPullRequestCreate(server);
+registerPullRequestMerge(server);
+registerIssueRead(server);
+registerIssueList(server);
+registerIssueSearch(server);
+registerIssueAddComment(server);
+registerSubIssueWrite(server);
+registerIssueCreate(server);
+registerIssueClose(server);
+registerIssueReopen(server);
+registerIssueUpdate(server);
+registerIssueAddLabel(server);
+registerIssueRemoveLabel(server);
+registerOwnerListIssueField(server);
+registerIssueGetFieldValue(server);
+registerIssueSetFieldValue(server);
+registerLabelList(server);
+registerLabelWrite(server);
+registerOwnerListProject(server);
+registerProjectsGet(server);
+registerProjectsWrite(server);
+async function main() {
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+    console.error("github-pro-mcp running on stdio");
+}
+main().catch((err) => {
+    console.error("Fatal error:", err);
+    process.exit(1);
+});

package/dist/tools/issue_fields.d.ts

@@ -0,0 +1,4 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+export declare function registerOwnerListIssueField(server: McpServer): void;
+export declare function registerIssueGetFieldValue(server: McpServer): void;
+export declare function registerIssueSetFieldValue(server: McpServer): void;

package/dist/tools/issue_fields.js

@@ -0,0 +1,104 @@
+import * as z from "zod/v4";
+import { createClient } from "../client.js";
+import { handleGitHubError } from "../utils/errors.js";
+import { requireOrg, validatePinnedOwnerRepo } from "../utils/validation.js";
+import { OwnerRepoSchema, IssueNumberSchema } from "../utils/types.js";
+export function registerOwnerListIssueField(server) {
+    server.registerTool("owner_list_issue_field", {
+        description: "List all issue field definitions for an organization (e.g., Priority, Effort, Start date, Target date). Owner must be an organization.",
+        inputSchema: z.object({
+            owner: z.string().min(1).describe("Organization owner"),
+        }),
+    }, async ({ owner }) => {
+        try {
+            const pinErr = validatePinnedOwnerRepo(owner);
+            if (pinErr)
+                return pinErr;
+            const octokit = createClient();
+            const orgErr = await requireOrg(owner);
+            if (orgErr)
+                return orgErr;
+            const { data } = await octokit.request('GET /orgs/{owner}/issue-fields', { owner });
+            return { content: [{ type: "text", text: JSON.stringify(data, null, 2) }] };
+        }
+        catch (err) {
+            return handleGitHubError(err);
+        }
+    });
+}
+export function registerIssueGetFieldValue(server) {
+    server.registerTool("issue_get_field_value", {
+        description: "Get the current field values (Priority, Effort, dates, etc.) assigned to an issue.",
+        inputSchema: OwnerRepoSchema.extend({
+            issue_number: IssueNumberSchema,
+        }),
+    }, async ({ owner, repo, issue_number }) => {
+        try {
+            const pinErr = validatePinnedOwnerRepo(owner, repo);
+            if (pinErr)
+                return pinErr;
+            const octokit = createClient();
+            const { data } = await octokit.rest.issues.get({ owner, repo, issue_number });
+            const issueData = data;
+            return { content: [{ type: "text", text: JSON.stringify(issueData.issue_field_values ?? [], null, 2) }] };
+        }
+        catch (err) {
+            return handleGitHubError(err);
+        }
+    });
+}
+export function registerIssueSetFieldValue(server) {
+    server.registerTool("issue_set_field_value", {
+        description: "Set field values (Priority, Effort, dates, etc.) on an issue. Accepts either field_id (numeric ID) or field_name (e.g. 'Priority'). For single-select fields, value can be the option name (e.g. 'Medium') or option ID. For dates, use ISO 8601 (e.g. '2026-06-15'). Pass null to clear a field.",
+        inputSchema: OwnerRepoSchema.extend({
+            issue_number: IssueNumberSchema,
+            fields: z.array(z.object({
+                field_id: z.number().int().positive().optional().describe("Field ID from owner_list_issue_field"),
+                field_name: z.string().optional().describe("Field name (e.g. 'Priority') as alternative to field_id"),
+                value: z.union([z.string(), z.number(), z.null()]).describe("Field value: option name/ID for single-select, ISO date for dates, number for numeric fields, or null to clear"),
+            })).min(1).describe("Array of field updates"),
+        }),
+    }, async ({ owner, repo, issue_number, fields }) => {
+        try {
+            const pinErr = validatePinnedOwnerRepo(owner, repo);
+            if (pinErr)
+                return pinErr;
+            const octokit = createClient();
+            const resolvedFields = [];
+            for (const f of fields) {
+                let fieldId = f.field_id;
+                if (!fieldId && f.field_name) {
+                    const fieldName = f.field_name;
+                    const { data: fieldDefs } = await octokit.request('GET /orgs/{owner}/issue-fields', { owner });
+                    const matching = fieldDefs.find((fd) => fd.name.toLowerCase() === fieldName.toLowerCase());
+                    if (!matching) {
+                        return {
+                            content: [{ type: "text", text: `Field "${f.field_name}" not found. Available fields: ${fieldDefs.map((fd) => fd.name).join(", ")}` }],
+                            isError: true,
+                        };
+                    }
+                    fieldId = matching.id;
+                }
+                if (!fieldId) {
+                    return {
+                        content: [{ type: "text", text: "Either field_id or field_name is required for each field update." }],
+                        isError: true,
+                    };
+                }
+                resolvedFields.push({ field_id: fieldId, value: f.value });
+            }
+            const response = await octokit.request('PATCH /repos/{owner}/{repo}/issues/{issue_number}', {
+                owner, repo, issue_number,
+                issue_field_values: resolvedFields,
+            });
+            const data = response.data;
+            return { content: [{ type: "text", text: JSON.stringify({
+                            success: true,
+                            issue_field_values: data.issue_field_values ?? [],
+                        }, null, 2) }] };
+        }
+        catch (err) {
+            return handleGitHubError(err);
+        }
+    });
+}

package/dist/tools/issues.d.ts

@@ -0,0 +1,12 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+export declare function registerIssueRead(server: McpServer): void;
+export declare function registerIssueList(server: McpServer): void;
+export declare function registerIssueSearch(server: McpServer): void;
+export declare function registerIssueAddComment(server: McpServer): void;
+export declare function registerSubIssueWrite(server: McpServer): void;
+export declare function registerIssueCreate(server: McpServer): void;
+export declare function registerIssueClose(server: McpServer): void;
+export declare function registerIssueReopen(server: McpServer): void;
+export declare function registerIssueUpdate(server: McpServer): void;
+export declare function registerIssueAddLabel(server: McpServer): void;
+export declare function registerIssueRemoveLabel(server: McpServer): void;