github-cicd-mcp 0.0.0-stage → 1.2.0

package/dist/tools/billing.js

@@ -0,0 +1,58 @@
+import { z } from "zod";
+import { getOctokit } from "../lib/github.js";
+import { errorResult, jsonResult } from "../lib/response.js";
+const org = z.string().describe("Organization login");
+export function registerBillingTools(server) {
+    server.tool("github_get_user_billing_actions", "Get GitHub Actions billing summary for the authenticated user (minutes, included vs paid).", {}, async () => {
+        try {
+            const octokit = getOctokit();
+            const { data: me } = await octokit.rest.users.getAuthenticated();
+            const { data } = await octokit.rest.billing.getGithubActionsBillingUser({
+                username: me.login,
+            });
+            return jsonResult(data);
+        }
+        catch (e) {
+            return errorResult(e);
+        }
+    });
+    server.tool("github_get_org_billing_actions", "Get GitHub Actions billing for an organization.", { org }, async ({ org }) => {
+        try {
+            const { data } = await getOctokit().rest.billing.getGithubActionsBillingOrg({
+                org,
+            });
+            return jsonResult(data);
+        }
+        catch (e) {
+            return errorResult(e);
+        }
+    });
+    server.tool("github_get_org_billing_overview", "Get combined billing overview for an org (Actions, Packages, shared storage).", { org }, async ({ org }) => {
+        try {
+            const octokit = getOctokit();
+            const [actions, packages, storage] = await Promise.allSettled([
+                octokit.rest.billing.getGithubActionsBillingOrg({ org }),
+                octokit.rest.billing.getGithubPackagesBillingOrg({ org }),
+                octokit.rest.billing.getSharedStorageBillingOrg({ org }),
+            ]);
+            return jsonResult({
+                actions: actions.status === "fulfilled" ? actions.value.data : { error: String(actions.reason) },
+                packages: packages.status === "fulfilled" ? packages.value.data : { error: String(packages.reason) },
+                shared_storage: storage.status === "fulfilled" ? storage.value.data : { error: String(storage.reason) },
+            });
+        }
+        catch (e) {
+            return errorResult(e);
+        }
+    });
+    server.tool("github_get_org_billing_usage_report", "Request billing usage export metadata (org plans — requires billing admin).", { org }, async ({ org }) => {
+        try {
+            const octokit = getOctokit();
+            const { data: usage } = await octokit.request("GET /orgs/{org}/settings/billing/usage", { org });
+            return jsonResult(usage);
+        }
+        catch (e) {
+            return errorResult(e);
+        }
+    });
+}

package/dist/tools/branch-protection.d.ts

@@ -0,0 +1,2 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+export declare function registerBranchProtectionTools(server: McpServer): void;

package/dist/tools/branch-protection.js

@@ -0,0 +1,125 @@
+import { z } from "zod";
+import { owner, repo } from "../lib/fields.js";
+import { getOctokit } from "../lib/github.js";
+import { errorResult, jsonResult } from "../lib/response.js";
+export function registerBranchProtectionTools(server) {
+    server.tool("github_get_branch", "Get branch metadata including protection status.", {
+        owner,
+        repo,
+        branch: z.string(),
+    }, async ({ owner, repo, branch }) => {
+        try {
+            const { data } = await getOctokit().rest.repos.getBranch({
+                owner,
+                repo,
+                branch,
+            });
+            return jsonResult({
+                name: data.name,
+                protected: data.protected,
+                commit_sha: data.commit.sha,
+                protection: data.protection,
+            });
+        }
+        catch (e) {
+            return errorResult(e);
+        }
+    });
+    server.tool("github_get_branch_protection", "Get branch protection rules for a branch.", {
+        owner,
+        repo,
+        branch: z.string(),
+    }, async ({ owner, repo, branch }) => {
+        try {
+            const { data } = await getOctokit().rest.repos.getBranchProtection({
+                owner,
+                repo,
+                branch,
+            });
+            return jsonResult(data);
+        }
+        catch (e) {
+            return errorResult(e);
+        }
+    });
+    server.tool("github_update_branch_protection", "Update branch protection (require PR reviews, status checks, admins).", {
+        owner,
+        repo,
+        branch: z.string(),
+        required_status_checks: z
+            .string()
+            .optional()
+            .describe('JSON: { "strict": true, "contexts": ["ci/build"] }'),
+        enforce_admins: z.boolean().optional(),
+        required_pull_request_reviews: z
+            .string()
+            .optional()
+            .describe('JSON: { "required_approving_review_count": 1 }'),
+        restrictions: z
+            .string()
+            .optional()
+            .describe('JSON: { "users": [], "teams": [], "apps": [] } or null to disable'),
+        allow_force_pushes: z.boolean().optional(),
+        allow_deletions: z.boolean().optional(),
+    }, async ({ owner, repo, branch, required_status_checks, enforce_admins, required_pull_request_reviews, restrictions, allow_force_pushes, allow_deletions, }) => {
+        try {
+            const { data } = await getOctokit().rest.repos.updateBranchProtection({
+                owner,
+                repo,
+                branch,
+                required_status_checks: required_status_checks
+                    ? JSON.parse(required_status_checks)
+                    : null,
+                enforce_admins: enforce_admins ?? null,
+                required_pull_request_reviews: required_pull_request_reviews
+                    ? JSON.parse(required_pull_request_reviews)
+                    : null,
+                restrictions: restrictions ? JSON.parse(restrictions) : null,
+                allow_force_pushes: allow_force_pushes ?? false,
+                allow_deletions: allow_deletions ?? false,
+            });
+            return jsonResult(data);
+        }
+        catch (e) {
+            return errorResult(e);
+        }
+    });
+    server.tool("github_delete_branch_protection", "Remove branch protection from a branch.", {
+        owner,
+        repo,
+        branch: z.string(),
+    }, async ({ owner, repo, branch }) => {
+        try {
+            await getOctokit().rest.repos.deleteBranchProtection({
+                owner,
+                repo,
+                branch,
+            });
+            return jsonResult({ ok: true, branch, message: "Branch protection removed" });
+        }
+        catch (e) {
+            return errorResult(e);
+        }
+    });
+    server.tool("github_list_branches", "List branches in a repository.", {
+        owner,
+        repo,
+        per_page: z.number().optional(),
+    }, async ({ owner, repo, per_page }) => {
+        try {
+            const { data } = await getOctokit().rest.repos.listBranches({
+                owner,
+                repo,
+                per_page: per_page ?? 100,
+            });
+            return jsonResult(data.map((b) => ({
+                name: b.name,
+                protected: b.protected,
+                sha: b.commit.sha,
+            })));
+        }
+        catch (e) {
+            return errorResult(e);
+        }
+    });
+}

package/dist/tools/commits.d.ts

@@ -0,0 +1,2 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+export declare function registerCommitTools(server: McpServer): void;

package/dist/tools/commits.js

@@ -0,0 +1,203 @@
+import { z } from "zod";
+import { owner, perPage, repo } from "../lib/fields.js";
+import { getOctokit } from "../lib/github.js";
+import { errorResult, jsonResult } from "../lib/response.js";
+export function registerCommitTools(server) {
+    server.tool("github_list_commits", "List commits on a branch or for the whole repo.", {
+        owner,
+        repo,
+        sha: z.string().optional().describe("Branch or commit SHA to start from"),
+        per_page: perPage,
+    }, async ({ owner, repo, sha, per_page }) => {
+        try {
+            const { data } = await getOctokit().rest.repos.listCommits({
+                owner,
+                repo,
+                sha: sha ?? undefined,
+                per_page: per_page ?? 30,
+            });
+            return jsonResult(data.map((c) => ({
+                sha: c.sha,
+                message: c.commit.message,
+                author: c.commit.author?.name,
+                date: c.commit.author?.date,
+                html_url: c.html_url,
+            })));
+        }
+        catch (e) {
+            return errorResult(e);
+        }
+    });
+    server.tool("github_get_commit", "Get a single commit with files changed.", {
+        owner,
+        repo,
+        ref: z.string().describe("Commit SHA"),
+    }, async ({ owner, repo, ref }) => {
+        try {
+            const { data } = await getOctokit().rest.repos.getCommit({
+                owner,
+                repo,
+                ref,
+            });
+            return jsonResult({
+                sha: data.sha,
+                message: data.commit.message,
+                author: data.commit.author,
+                stats: data.stats,
+                files: data.files?.map((f) => ({
+                    filename: f.filename,
+                    status: f.status,
+                    additions: f.additions,
+                    deletions: f.deletions,
+                })),
+                html_url: data.html_url,
+            });
+        }
+        catch (e) {
+            return errorResult(e);
+        }
+    });
+    server.tool("github_compare_commits", "Compare two commits (base...head) — useful for release notes and PR scope.", {
+        owner,
+        repo,
+        base: z.string().describe("Base ref or SHA"),
+        head: z.string().describe("Head ref or SHA"),
+    }, async ({ owner, repo, base, head }) => {
+        try {
+            const { data } = await getOctokit().rest.repos.compareCommitsWithBasehead({
+                owner,
+                repo,
+                basehead: `${base}...${head}`,
+            });
+            return jsonResult({
+                status: data.status,
+                ahead_by: data.ahead_by,
+                behind_by: data.behind_by,
+                total_commits: data.total_commits,
+                commits: data.commits?.map((c) => ({
+                    sha: c.sha,
+                    message: c.commit.message,
+                })),
+                files: data.files?.map((f) => f.filename),
+            });
+        }
+        catch (e) {
+            return errorResult(e);
+        }
+    });
+    server.tool("github_create_commit", "Create a commit on a branch by updating one or more files (GitHub Git API — no local clone required).", {
+        owner,
+        repo,
+        branch: z.string().describe("Branch to commit to"),
+        message: z.string().describe("Commit message"),
+        files: z
+            .string()
+            .describe('JSON array of { "path": "src/a.ts", "content": "...", "encoding": "utf-8" | "base64" }'),
+    }, async ({ owner, repo, branch, message, files }) => {
+        try {
+            const fileList = JSON.parse(files);
+            if (!Array.isArray(fileList) || fileList.length === 0) {
+                throw new Error("files must be a non-empty JSON array");
+            }
+            const octokit = getOctokit();
+            const refRes = await octokit.rest.git.getRef({
+                owner,
+                repo,
+                ref: `heads/${branch}`,
+            });
+            const parentSha = refRes.data.object.sha;
+            const { data: parentCommit } = await octokit.rest.git.getCommit({
+                owner,
+                repo,
+                commit_sha: parentSha,
+            });
+            const treeItems = [];
+            for (const file of fileList) {
+                const encoding = file.encoding ?? "utf-8";
+                const { data: blob } = await octokit.rest.git.createBlob({
+                    owner,
+                    repo,
+                    content: file.content,
+                    encoding: encoding === "base64" ? "base64" : "utf-8",
+                });
+                treeItems.push({
+                    path: file.path,
+                    mode: "100644",
+                    type: "blob",
+                    sha: blob.sha,
+                });
+            }
+            const { data: tree } = await octokit.rest.git.createTree({
+                owner,
+                repo,
+                base_tree: parentCommit.tree.sha,
+                tree: treeItems,
+            });
+            const { data: commit } = await octokit.rest.git.createCommit({
+                owner,
+                repo,
+                message,
+                tree: tree.sha,
+                parents: [parentSha],
+            });
+            await octokit.rest.git.updateRef({
+                owner,
+                repo,
+                ref: `heads/${branch}`,
+                sha: commit.sha,
+            });
+            return jsonResult({
+                sha: commit.sha,
+                message: commit.message,
+                branch,
+                html_url: `https://github.com/${owner}/${repo}/commit/${commit.sha}`,
+            });
+        }
+        catch (e) {
+            return errorResult(e);
+        }
+    });
+    server.tool("github_get_combined_status", "Get combined commit status (legacy statuses + check runs summary) for CI/CD gates.", {
+        owner,
+        repo,
+        ref: z.string().describe("Commit SHA or ref"),
+    }, async ({ owner, repo, ref }) => {
+        try {
+            const { data } = await getOctokit().rest.repos.getCombinedStatusForRef({
+                owner,
+                repo,
+                ref,
+            });
+            return jsonResult(data);
+        }
+        catch (e) {
+            return errorResult(e);
+        }
+    });
+    server.tool("github_list_check_runs_for_ref", "List GitHub Actions check runs for a commit ref.", {
+        owner,
+        repo,
+        ref: z.string().describe("Commit SHA"),
+    }, async ({ owner, repo, ref }) => {
+        try {
+            const { data } = await getOctokit().rest.checks.listForRef({
+                owner,
+                repo,
+                ref,
+                per_page: 100,
+            });
+            return jsonResult(data.check_runs.map((c) => ({
+                id: c.id,
+                name: c.name,
+                status: c.status,
+                conclusion: c.conclusion,
+                html_url: c.html_url,
+                started_at: c.started_at,
+                completed_at: c.completed_at,
+            })));
+        }
+        catch (e) {
+            return errorResult(e);
+        }
+    });
+}

package/dist/tools/deployments.d.ts

@@ -0,0 +1,2 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+export declare function registerDeploymentTools(server: McpServer): void;

package/dist/tools/deployments.js

@@ -0,0 +1,98 @@
+import { z } from "zod";
+import { owner, perPage, repo } from "../lib/fields.js";
+import { getOctokit } from "../lib/github.js";
+import { errorResult, jsonResult } from "../lib/response.js";
+export function registerDeploymentTools(server) {
+    server.tool("github_list_deployments", "List deployments for a repository (CD history).", {
+        owner,
+        repo,
+        environment: z.string().optional().describe("Filter by environment name"),
+        per_page: perPage,
+    }, async ({ owner, repo, environment, per_page }) => {
+        try {
+            const { data } = await getOctokit().rest.repos.listDeployments({
+                owner,
+                repo,
+                environment: environment ?? undefined,
+                per_page: per_page ?? 30,
+            });
+            return jsonResult(data.map((d) => ({
+                id: d.id,
+                ref: d.ref,
+                sha: d.sha,
+                environment: d.environment,
+                description: d.description,
+                created_at: d.created_at,
+            })));
+        }
+        catch (e) {
+            return errorResult(e);
+        }
+    });
+    server.tool("github_create_deployment", "Create a deployment for a ref (triggers deployment workflows / environments).", {
+        owner,
+        repo,
+        ref: z.string().describe("Branch, tag, or SHA"),
+        environment: z.string().optional().describe("e.g. production, staging"),
+        description: z.string().optional(),
+        auto_merge: z.boolean().optional().describe("Merge default branch into ref"),
+        required_contexts: z
+            .string()
+            .optional()
+            .describe('JSON array of status check names, or "[]" for none'),
+    }, async ({ owner, repo, ref, environment, description, auto_merge, required_contexts }) => {
+        try {
+            const contexts = required_contexts ? JSON.parse(required_contexts) : undefined;
+            const { data } = await getOctokit().rest.repos.createDeployment({
+                owner,
+                repo,
+                ref,
+                environment: environment ?? "production",
+                description: description ?? undefined,
+                auto_merge: auto_merge ?? false,
+                required_contexts: contexts,
+            });
+            return jsonResult(data);
+        }
+        catch (e) {
+            return errorResult(e);
+        }
+    });
+    server.tool("github_create_deployment_status", "Update deployment status (success, failure, in_progress) for CD observability.", {
+        owner,
+        repo,
+        deployment_id: z.number(),
+        state: z
+            .string()
+            .describe("error | failure | inactive | in_progress | queued | pending | success"),
+        environment_url: z.string().optional().describe("Live site URL"),
+        description: z.string().optional(),
+    }, async ({ owner, repo, deployment_id, state, environment_url, description }) => {
+        try {
+            const { data } = await getOctokit().rest.repos.createDeploymentStatus({
+                owner,
+                repo,
+                deployment_id,
+                state: state,
+                environment_url: environment_url ?? undefined,
+                description: description ?? undefined,
+            });
+            return jsonResult(data);
+        }
+        catch (e) {
+            return errorResult(e);
+        }
+    });
+    server.tool("github_list_environments", "List deployment environments and protection rules.", { owner, repo }, async ({ owner, repo }) => {
+        try {
+            const { data } = await getOctokit().rest.repos.getAllEnvironments({
+                owner,
+                repo,
+            });
+            return jsonResult(data.environments);
+        }
+        catch (e) {
+            return errorResult(e);
+        }
+    });
+}

package/dist/tools/graphql.d.ts

@@ -0,0 +1,2 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+export declare function registerGraphqlTools(server: McpServer): void;

package/dist/tools/graphql.js

@@ -0,0 +1,73 @@
+import { graphql } from "@octokit/graphql";
+import { z } from "zod";
+import { getToken } from "../lib/github.js";
+import { errorResult, jsonResult } from "../lib/response.js";
+function graphqlClient() {
+    const baseUrl = process.env.GITHUB_GRAPHQL_URL ??
+        (process.env.GITHUB_HOST && process.env.GITHUB_HOST !== "github.com"
+            ? `https://${process.env.GITHUB_HOST}/api/graphql`
+            : undefined);
+    return graphql.defaults({
+        headers: {
+            authorization: `token ${getToken()}`,
+        },
+        ...(baseUrl ? { baseUrl } : {}),
+    });
+}
+export function registerGraphqlTools(server) {
+    server.tool("github_graphql_query", "Run a read-only GitHub GraphQL query (https://docs.github.com/en/graphql). Variables optional.", {
+        query: z.string().describe("GraphQL query string"),
+        variables: z.string().optional().describe("JSON object of GraphQL variables"),
+    }, async ({ query, variables }) => {
+        try {
+            const trimmed = query.trim();
+            if (/^\s*mutation\b/i.test(trimmed)) {
+                throw new Error("Mutations are blocked in this tool. Use REST tools or github_graphql_mutation explicitly.");
+            }
+            const vars = variables ? JSON.parse(variables) : undefined;
+            const data = await graphqlClient()(query, vars);
+            return jsonResult(data);
+        }
+        catch (e) {
+            return errorResult(e);
+        }
+    });
+    server.tool("github_graphql_mutation", "Run a GitHub GraphQL mutation (create/update via GraphQL API). Use with care.", {
+        query: z.string().describe("GraphQL mutation string"),
+        variables: z.string().optional().describe("JSON object of GraphQL variables"),
+    }, async ({ query, variables }) => {
+        try {
+            const vars = variables ? JSON.parse(variables) : undefined;
+            const data = await graphqlClient()(query, vars);
+            return jsonResult(data);
+        }
+        catch (e) {
+            return errorResult(e);
+        }
+    });
+    server.tool("github_graphql_repository_overview", "Quick GraphQL snapshot: repo, default branch, latest commit, open PR count.", {
+        owner: z.string(),
+        name: z.string().describe("Repository name"),
+    }, async ({ owner, name }) => {
+        try {
+            const data = await graphqlClient()(`
+          query RepoOverview($owner: String!, $name: String!) {
+            repository(owner: $owner, name: $name) {
+              nameWithOwner
+              description
+              isPrivate
+              defaultBranchRef { name }
+              pushedAt
+              openPullRequests: pullRequests(states: OPEN) { totalCount }
+              openIssues: issues(states: OPEN) { totalCount }
+              primaryLanguage { name }
+            }
+          }
+        `, { owner, name });
+            return jsonResult(data);
+        }
+        catch (e) {
+            return errorResult(e);
+        }
+    });
+}

package/dist/tools/issues.d.ts

@@ -0,0 +1,2 @@
+import type { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+export declare function registerIssueTools(server: McpServer): void;