github-pro-mcp 0.0.2 → 0.0.4

package/dist/utils/errors.js

@@ -1,107 +0,0 @@
-import { RequestError } from "@octokit/request-error";
-import { categorizeError, incrementMetric } from "./metrics.js";
-/**
- * Convert any GitHub API error (REST or GraphQL) into a structured
- * MCP error response with actionable guidance.
- *
- * Automatically increments the metrics counter for the error category.
- */
-export function handleGitHubError(err) {
-    incrementMetric(categorizeError(err));
-    const gqlErrors = err?.errors;
-    if (gqlErrors && Array.isArray(gqlErrors) && gqlErrors.length > 0) {
-        const gqlErr = gqlErrors[0];
-        let hint = "";
-        const msg = gqlErr.message ?? "";
-        const type = gqlErr.type ?? "";
-        if (type === "FORBIDDEN" || msg.includes("not accessible")) {
-            hint = `\n• Your token lacks the required permissions. For Projects, ensure it has the 'project' scope (classic PAT) or 'Projects' permission (fine-grained PAT).`;
-        }
-        else if (type === "NOT_FOUND") {
-            hint = `\n• The resource was not found. Check the owner/repo name or item ID.`;
-        }
-        return {
-            content: [{ type: "text", text: `GraphQL error: ${msg}\n` +
-                        `• Type: ${type || "unknown"}\n` +
-                        `• Path: ${(gqlErr.path ?? []).join(".")}${hint}`
-                }],
-            isError: true,
-        };
-    }
-    if (err instanceof RequestError) {
-        const status = err.status;
-        const resource = err.response?.url ?? "unknown";
-        switch (status) {
-            case 401:
-                return {
-                    content: [{ type: "text", text: `Authentication failed (401). GitHub returned: "${err.message}".\n` +
-                                `Your GITHUB_PERSONAL_ACCESS_TOKEN may be expired, revoked, or invalid.\n` +
-                                `• Generate a new token at: https://github.com/settings/tokens\n` +
-                                `• Ensure the token has the required scopes (repo, read:org, etc.)\n` +
-                                `• Set it as the GITHUB_PERSONAL_ACCESS_TOKEN environment variable.`
-                        }],
-                    isError: true,
-                };
-            case 403: {
-                const scopes = err.response?.headers?.["x-accepted-oauth-scopes"];
-                return {
-                    content: [{ type: "text", text: `Permission denied (403). ${err.message}.\n` +
-                                `• Required OAuth scopes: ${scopes ?? "unknown"}\n` +
-                                `• For Projects v2, ensure the token has the 'project' scope (classic PAT) or 'Projects' permission (fine-grained PAT).\n` +
-                                `• Update your token at: https://github.com/settings/tokens\n` +
-                                `• If this is an organization resource, ensure SSO is authorized.`
-                        }],
-                    isError: true,
-                };
-            }
-            case 404:
-                return {
-                    content: [{ type: "text", text: `Resource not found (404) at ${resource}.\n` +
-                                `• The resource may not exist, or your token may lack access.\n` +
-                                `• For private repos, verify the token has the 'repo' scope.\n` +
-                                `• Check if the owner/repo name is spelled correctly.`
-                        }],
-                    isError: true,
-                };
-            case 429: {
-                const resetEpoch = err.response?.headers?.["x-ratelimit-reset"];
-                const resetTime = resetEpoch
-                    ? new Date(Number(resetEpoch) * 1000).toISOString()
-                    : "unknown";
-                return {
-                    content: [{ type: "text", text: `Rate limit exceeded (429). Resets at ${resetTime}.\n` +
-                                `• Limit: ${err.response?.headers?.["x-ratelimit-limit"] ?? "?"} requests/hr\n` +
-                                `• Wait until the reset time before retrying.`
-                        }],
-                    isError: true,
-                };
-            }
-            default:
-                return {
-                    content: [{ type: "text", text: `GitHub API error (${status}): ${err.message}`
-                        }],
-                    isError: true,
-                };
-        }
-    }
-    if (err instanceof Error) {
-        return {
-            content: [{ type: "text", text: `Unexpected error: ${err.message}` }],
-            isError: true,
-        };
-    }
-    return {
-        content: [{ type: "text", text: `Unknown error: ${String(err)}` }],
-        isError: true,
-    };
-}
-export function formatZodErrors(err) {
-    const issues = err?.issues;
-    if (!issues || !Array.isArray(issues))
-        return null;
-    const parts = issues.map((issue) => {
-        const field = issue.path.length > 0 ? `"${issue.path.join(".")}"` : "input";
-        return `• ${field}: ${issue.message}`;
-    });
-    return `Validation error:\n${parts.join("\n")}`;
-}

package/dist/utils/logger.d.ts

@@ -1,14 +0,0 @@
-type LogLevel = "error" | "warn" | "info" | "debug";
-type LogSink = (level: LogLevel, message: string) => void;
-export interface Logger {
-    error: (message: string) => void;
-    warn: (message: string) => void;
-    info: (message: string) => void;
-    debug: (message: string) => void;
-}
-export declare function createLogger(component: string): Logger;
-export declare function configureLogger(opts: {
-    sink?: LogSink;
-    minLevel?: LogLevel;
-}): void;
-export {};

package/dist/utils/logger.js

@@ -1,40 +0,0 @@
-const LEVEL_ORDER = {
-    error: 0,
-    warn: 1,
-    info: 2,
-    debug: 3,
-};
-function resolveMinLevel() {
-    const env = process.env.GITHUB_LOG_LEVEL?.toLowerCase();
-    if (env === "debug")
-        return "debug";
-    if (env === "info")
-        return "info";
-    if (env === "warn")
-        return "warn";
-    return "error";
-}
-function defaultSink(level, message) {
-    process.stderr.write(`[${new Date().toISOString()}] [${level.toUpperCase()}] ${message}\n`);
-}
-let globalSink = defaultSink;
-let globalMinLevel = resolveMinLevel();
-export function createLogger(component) {
-    const log = (level, message) => {
-        if (LEVEL_ORDER[level] <= LEVEL_ORDER[globalMinLevel]) {
-            globalSink(level, `[${component}] ${message}`);
-        }
-    };
-    return {
-        error: (msg) => log("error", msg),
-        warn: (msg) => log("warn", msg),
-        info: (msg) => log("info", msg),
-        debug: (msg) => log("debug", msg),
-    };
-}
-export function configureLogger(opts) {
-    if (opts.sink)
-        globalSink = opts.sink;
-    if (opts.minLevel)
-        globalMinLevel = opts.minLevel;
-}

package/dist/utils/metrics.d.ts

@@ -1,11 +0,0 @@
-type ErrorCategory = "auth_401" | "permission_403" | "not_found_404" | "rate_limit_429" | "server_5xx" | "network" | "validation" | "circuit_breaker" | "unknown";
-interface MetricSnapshot {
-    startedAt: number;
-    counters: Record<ErrorCategory, number>;
-    total: number;
-}
-export declare function incrementMetric(category: ErrorCategory): void;
-export declare function categorizeError(error: unknown): ErrorCategory;
-export declare function getMetricsSnapshot(): MetricSnapshot;
-export declare function getMetricsSummary(): string;
-export {};

package/dist/utils/metrics.js

@@ -1,70 +0,0 @@
-import { createLogger } from "./logger.js";
-const log = createLogger("metrics");
-const counters = {
-    auth_401: 0,
-    permission_403: 0,
-    not_found_404: 0,
-    rate_limit_429: 0,
-    server_5xx: 0,
-    network: 0,
-    validation: 0,
-    circuit_breaker: 0,
-    unknown: 0,
-};
-const startedAt = Date.now();
-export function incrementMetric(category) {
-    counters[category]++;
-    log.debug(`Metric ${category} = ${counters[category]}`);
-}
-export function categorizeError(error) {
-    if (error instanceof Error && error.name === "CircuitBreakerError") {
-        return "circuit_breaker";
-    }
-    const status = error?.status;
-    if (status === 401)
-        return "auth_401";
-    if (status === 403)
-        return "permission_403";
-    if (status === 404)
-        return "not_found_404";
-    if (status === 429)
-        return "rate_limit_429";
-    if (typeof status === "number" && status >= 500)
-        return "server_5xx";
-    const code = error?.code;
-    if (code && ["ECONNRESET", "ECONNREFUSED", "ETIMEDOUT", "ENOTFOUND", "EPIPE"].includes(code)) {
-        return "network";
-    }
-    const message = error instanceof Error ? error.message.toLowerCase() : "";
-    if (message.includes("validation") || message.includes("invalid") || message.includes("zod")) {
-        return "validation";
-    }
-    return "unknown";
-}
-export function getMetricsSnapshot() {
-    let total = 0;
-    for (const v of Object.values(counters))
-        total += v;
-    return {
-        startedAt,
-        counters: { ...counters },
-        total,
-    };
-}
-export function getMetricsSummary() {
-    const snap = getMetricsSnapshot();
-    const uptime = Math.round((Date.now() - snap.startedAt) / 1000);
-    const lines = [
-        `Metrics (uptime: ${uptime}s, total errors: ${snap.total})`,
-        `  401 (auth):       ${snap.counters.auth_401}`,
-        `  403 (permission):  ${snap.counters.permission_403}`,
-        `  404 (not found):   ${snap.counters.not_found_404}`,
-        `  429 (rate limit):  ${snap.counters.rate_limit_429}`,
-        `  5xx (server):      ${snap.counters.server_5xx}`,
-        `  network:           ${snap.counters.network}`,
-        `  validation:        ${snap.counters.validation}`,
-        `  circuit_breaker:   ${snap.counters.circuit_breaker}`,
-        `  unknown:           ${snap.counters.unknown}`,
-    ];
-    return lines.join("\n");
-}

package/dist/utils/rateLimit.d.ts

@@ -1,21 +0,0 @@
-interface RateLimitState {
-    core: {
-        limit: number;
-        remaining: number;
-        reset: number;
-    };
-    search: {
-        limit: number;
-        remaining: number;
-        reset: number;
-    };
-    graphql: {
-        limit: number;
-        remaining: number;
-        reset: number;
-    };
-}
-export declare function updateRateLimits(headers: Record<string, string | undefined>): void;
-export declare function getRateLimitState(): RateLimitState;
-export declare function getRateLimitSummary(): string;
-export {};

package/dist/utils/rateLimit.js

@@ -1,40 +0,0 @@
-const state = {
-    core: { limit: 5000, remaining: 5000, reset: 0 },
-    search: { limit: 30, remaining: 30, reset: 0 },
-    graphql: { limit: 5000, remaining: 5000, reset: 0 },
-};
-export function updateRateLimits(headers) {
-    const limit = parseInt(headers["x-ratelimit-limit"] ?? "5000", 10);
-    const remaining = parseInt(headers["x-ratelimit-remaining"] ?? String(limit), 10);
-    const reset = parseInt(headers["x-ratelimit-reset"] ?? "0", 10);
-    const resource = headers["x-ratelimit-resource"] ?? "core";
-    if (resource === "search") {
-        state.search = { limit, remaining, reset };
-    }
-    else if (resource === "graphql") {
-        state.graphql = { limit, remaining, reset };
-    }
-    else {
-        state.core = { limit, remaining, reset };
-    }
-}
-export function getRateLimitState() {
-    return {
-        core: { ...state.core },
-        search: { ...state.search },
-        graphql: { ...state.graphql },
-    };
-}
-export function getRateLimitSummary() {
-    const s = getRateLimitState();
-    const formatCategory = (label, r) => {
-        const pct = r.limit > 0 ? Math.round((r.remaining / r.limit) * 100) : 100;
-        const resetStr = r.reset > 0 ? ` (resets ${new Date(r.reset * 1000).toISOString()})` : "";
-        return `${label}: ${r.remaining}/${r.limit} (${pct}%)${resetStr}`;
-    };
-    return [
-        formatCategory("Core", s.core),
-        formatCategory("Search", s.search),
-        formatCategory("GraphQL", s.graphql),
-    ].join("\n");
-}

package/dist/utils/retry.d.ts

@@ -1,9 +0,0 @@
-export interface RetryConfig {
-    maxAttempts: number;
-    initialDelayMs: number;
-    backoffFactor: number;
-    maxDelayMs: number;
-    retryableStatusCodes: number[];
-    retryableErrors: string[];
-}
-export declare function withRetry<T>(fn: () => Promise<T>, label: string, overrides?: Partial<RetryConfig>): Promise<T>;

package/dist/utils/retry.js

@@ -1,76 +0,0 @@
-import { createLogger } from "./logger.js";
-const log = createLogger("retry");
-function defaultConfig() {
-    return {
-        maxAttempts: parseInt(process.env.GITHUB_RETRY_MAX_ATTEMPTS ?? "3", 10),
-        initialDelayMs: parseInt(process.env.GITHUB_RETRY_BACKOFF_MS ?? "1000", 10),
-        backoffFactor: parseFloat(process.env.GITHUB_RETRY_BACKOFF_FACTOR ?? "2"),
-        maxDelayMs: 30000,
-        retryableStatusCodes: [429, 500, 502, 503, 504],
-        retryableErrors: [
-            "ETIMEDOUT",
-            "ECONNRESET",
-            "ECONNREFUSED",
-            "ENOTFOUND",
-            "EPIPE",
-        ],
-    };
-}
-function delay(ms) {
-    return new Promise((resolve) => setTimeout(resolve, ms));
-}
-function isRetryableError(error, config) {
-    if (error instanceof Error) {
-        const code = error.code;
-        if (code && config.retryableErrors.includes(code))
-            return true;
-        const status = error.status;
-        if (typeof status === "number" && config.retryableStatusCodes.includes(status))
-            return true;
-        const message = error.message.toLowerCase();
-        if (message.includes("socket hang up") ||
-            message.includes("request aborted") ||
-            message.includes("network error") ||
-            message.includes("rate limit")) {
-            return true;
-        }
-    }
-    return false;
-}
-function calcDelay(attempt, config) {
-    const computed = config.initialDelayMs * Math.pow(config.backoffFactor, attempt - 1);
-    const jitter = Math.random() * 0.3 * computed;
-    return Math.min(computed + jitter, config.maxDelayMs);
-}
-export async function withRetry(fn, label, overrides) {
-    const config = { ...defaultConfig(), ...overrides };
-    for (let attempt = 1; attempt <= config.maxAttempts; attempt++) {
-        try {
-            return await fn();
-        }
-        catch (error) {
-            if (attempt === config.maxAttempts || !isRetryableError(error, config)) {
-                throw error;
-            }
-            const waitMs = calcDelay(attempt, config);
-            log.warn(`Retry attempt ${attempt}/${config.maxAttempts} for "${label}" ` +
-                `after ${Math.round(waitMs)}ms: ${extractErrorSummary(error)}`);
-            await delay(waitMs);
-        }
-    }
-    throw new Error(`Unexpected: retry loop exhausted for "${label}"`);
-}
-function extractErrorSummary(error) {
-    if (error instanceof Error) {
-        const status = error.status;
-        const code = error.code;
-        const parts = [];
-        if (typeof status === "number")
-            parts.push(`${status}`);
-        if (code)
-            parts.push(code);
-        parts.push(error.message.split("\n")[0]);
-        return parts.join(" ");
-    }
-    return String(error);
-}

package/dist/utils/types.d.ts

@@ -1,33 +0,0 @@
-import * as z from "zod/v4";
-export declare const OwnerRepoSchema: z.ZodObject<{
-    owner: z.ZodString;
-    repo: z.ZodString;
-}, z.core.$strip>;
-export declare const PaginationSchema: z.ZodObject<{
-    page: z.ZodDefault<z.ZodOptional<z.ZodNumber>>;
-    per_page: z.ZodDefault<z.ZodOptional<z.ZodNumber>>;
-}, z.core.$strip>;
-export declare const IssueNumberSchema: z.ZodNumber;
-export declare const PullNumberSchema: z.ZodNumber;
-export declare const IncludeFlagsSchema: z.ZodObject<{
-    include_comments: z.ZodDefault<z.ZodOptional<z.ZodBoolean>>;
-    include_labels: z.ZodDefault<z.ZodOptional<z.ZodBoolean>>;
-    include_fields: z.ZodDefault<z.ZodOptional<z.ZodBoolean>>;
-    include_sub_issues: z.ZodDefault<z.ZodOptional<z.ZodBoolean>>;
-}, z.core.$strip>;
-export declare const PrIncludeFlagsSchema: z.ZodObject<{
-    include_commits: z.ZodDefault<z.ZodOptional<z.ZodBoolean>>;
-    include_reviews: z.ZodDefault<z.ZodOptional<z.ZodBoolean>>;
-}, z.core.$strip>;
-interface RepoShape {
-    full_name: string;
-    description: string | null;
-    private: boolean;
-    language: string | null;
-    default_branch: string;
-    updated_at: string;
-    stars: number;
-    forks: number;
-}
-export declare function formatRepo(r: Record<string, unknown>): RepoShape;
-export {};

package/dist/utils/types.js

@@ -1,33 +0,0 @@
-import * as z from "zod/v4";
-export const OwnerRepoSchema = z.object({
-    owner: z.string().min(1).describe("Repository owner (user or organization)"),
-    repo: z.string().min(1).describe("Repository name"),
-});
-export const PaginationSchema = z.object({
-    page: z.number().int().min(1).optional().default(1).describe("Page number (starts at 1)"),
-    per_page: z.number().int().min(1).max(100).optional().default(30).describe("Results per page (max 100)"),
-});
-export const IssueNumberSchema = z.number().int().positive().describe("Issue number");
-export const PullNumberSchema = z.number().int().positive().describe("Pull request number");
-export const IncludeFlagsSchema = z.object({
-    include_comments: z.boolean().optional().default(false).describe("Include issue comments"),
-    include_labels: z.boolean().optional().default(false).describe("Include labels"),
-    include_fields: z.boolean().optional().default(false).describe("Include issue field values (Priority, Effort, dates)"),
-    include_sub_issues: z.boolean().optional().default(false).describe("Include sub-issues"),
-});
-export const PrIncludeFlagsSchema = z.object({
-    include_commits: z.boolean().optional().default(false).describe("Include commit list"),
-    include_reviews: z.boolean().optional().default(false).describe("Include review list"),
-});
-export function formatRepo(r) {
-    return {
-        full_name: String(r.full_name ?? ""),
-        description: r.description ?? null,
-        private: Boolean(r.private),
-        language: r.language ?? null,
-        default_branch: String(r.default_branch ?? ""),
-        updated_at: String(r.updated_at ?? ""),
-        stars: Number(r.stargazers_count ?? 0),
-        forks: Number(r.forks_count ?? 0),
-    };
-}

package/dist/utils/validation.d.ts

@@ -1,13 +0,0 @@
-interface ErrorResponse {
-    content: [{
-        type: "text";
-        text: string;
-    }];
-    isError: true;
-    [x: string]: unknown;
-}
-export declare function validatePinnedOwnerRepo(owner?: string, repo?: string): ErrorResponse | null;
-export declare function requireOrg(owner: string): Promise<ErrorResponse | null>;
-export declare function requireUser(owner: string): Promise<ErrorResponse | null>;
-export declare function requireIssueOpen(owner: string, repo: string, issue_number: number): Promise<ErrorResponse | null>;
-export {};

package/dist/utils/validation.js

@@ -1,88 +0,0 @@
-import { createClient } from "../client.js";
-export function validatePinnedOwnerRepo(owner, repo) {
-    const pinnedOwner = process.env.GITHUB_OWNER;
-    const pinnedRepo = process.env.GITHUB_REPO;
-    const errors = [];
-    if (pinnedOwner && owner && pinnedOwner.toLowerCase() !== owner.toLowerCase()) {
-        errors.push(`FATAL: This MCP server is pinned to a specific owner. ` +
-            `The provided owner "${owner}" is not permitted. This operation cannot proceed.`);
-    }
-    if (pinnedRepo && repo && pinnedRepo.toLowerCase() !== repo.toLowerCase()) {
-        errors.push(`FATAL: This MCP server is pinned to a specific repository. ` +
-            `The provided repo "${repo}" is not permitted. This operation cannot proceed.`);
-    }
-    if (errors.length > 0) {
-        return {
-            content: [{ type: "text", text: errors.join("\n") }],
-            isError: true,
-        };
-    }
-    return null;
-}
-const ownerTypeCache = new Map();
-const OWNER_TYPE_CACHE_TTL_MS = parseInt(process.env.GITHUB_OWNER_TYPE_CACHE_MS ?? "300000", 10);
-function getCachedOwnerType(owner) {
-    const entry = ownerTypeCache.get(owner.toLowerCase());
-    if (!entry)
-        return null;
-    if (Date.now() > entry.expiresAt) {
-        ownerTypeCache.delete(owner.toLowerCase());
-        return null;
-    }
-    return entry.type;
-}
-function setCachedOwnerType(owner, type) {
-    ownerTypeCache.set(owner.toLowerCase(), {
-        type,
-        expiresAt: Date.now() + OWNER_TYPE_CACHE_TTL_MS,
-    });
-}
-async function resolveOwnerType(owner) {
-    const cached = getCachedOwnerType(owner);
-    if (cached)
-        return cached;
-    const octokit = createClient();
-    const { data: user } = await octokit.rest.users.getByUsername({ username: owner });
-    const type = user.type;
-    setCachedOwnerType(owner, type);
-    return type;
-}
-export async function requireOrg(owner) {
-    const type = await resolveOwnerType(owner);
-    if (type !== "Organization") {
-        return {
-            content: [{ type: "text", text: `"${owner}" is a user account, not an organization. ` +
-                        `This tool only works for organizations. ` +
-                        `Tip: Use owner_list_organization to find organizations for a user.`
-                }],
-            isError: true,
-        };
-    }
-    return null;
-}
-export async function requireUser(owner) {
-    const type = await resolveOwnerType(owner);
-    if (type !== "User") {
-        return {
-            content: [{ type: "text", text: `"${owner}" is an organization, not a user account. ` +
-                        `This tool lists organizations that a user belongs to; provide a username instead. ` +
-                        `Tip: To find user accounts, use organization_search with a name query.`
-                }],
-            isError: true,
-        };
-    }
-    return null;
-}
-export async function requireIssueOpen(owner, repo, issue_number) {
-    const octokit = createClient();
-    const { data } = await octokit.rest.issues.get({ owner, repo, issue_number });
-    if (data.state === "closed") {
-        return {
-            content: [{ type: "text", text: `Issue #${issue_number} in ${owner}/${repo} is closed. ` +
-                        `Reopen it first before modifying the title or body.`
-                }],
-            isError: true,
-        };
-    }
-    return null;
-}