github-cicd-mcp 0.0.0-stage → 1.2.0

package/CHANGELOG.md

@@ -0,0 +1,43 @@
+# Changelog
+
+All notable changes to this project will be documented in this file.
+
+## [1.2.0] - 2026-10-13
+
+### Added
+
+- SECURITY.md for responsible vulnerability disclosure
+- Security policy and best practices documentation
+- CI/CD verification script that counts registered tools (70 tools)
+- Enhanced documentation for public release
+
+### Changed
+
+- Updated package.json with correct repository URLs
+- Improved README with installation instructions for npm and source
+- Added npm publish configuration for public access
+
+### Security
+
+- Added security checklist and token scope recommendations
+- Documented safe authentication practices
+- Added dependency audit information
+
+## [1.1.0] - 2026-03-23
+
+### Added
+
+- Issues: create, list, get, update, comments
+- Releases and tags
+- Branch protection and branch listing
+- Webhooks and collaborators / org teams
+- GraphQL query, mutation, and repository overview helper
+- Workflow run artifacts
+- Fork repository
+- Public release docs (`RELEASING.md`), CI workflow, MIT `LICENSE`
+
+## [1.0.0] - 2026-03-23
+
+### Added
+
+- Initial MCP: repos, commits, PRs, Actions, deployments, billing, local git

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 github-cicd-mcp contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,146 @@
-# Temporary Holding Version
-
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+# github-cicd-mcp
+
+GitHub CI/CD MCP server for Model Context Protocol.
+
+[![CI](https://github.com/devstephenke-sys/Github-Free-MCPs/actions/workflows/ci.yml/badge.svg)](https://github.com/devstephenke-sys/Github-Free-MCPs/actions/workflows/ci.yml)
+[![npm version](https://img.shields.io/npm/v/github-cicd-mcp.svg)](https://www.npmjs.com/package/github-cicd-mcp)
+[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
+
+**Model Context Protocol (MCP) server** for [GitHub REST](https://docs.github.com/en/rest) and [GraphQL](https://docs.github.com/en/graphql) — built for **CI/CD and DevOps** workflows in Cursor, Claude Desktop, and other MCP clients.
+
+Give your AI agent tools to manage repos, commits, pull requests, issues, GitHub Actions, deployments, billing, releases, branch protection, webhooks, and local `git` — without leaving the editor.
+
+---
+
+## Install
+
+### npm / npx (recommended)
+
+```json
+{
+  "mcpServers": {
+    "github-cicd": {
+      "command": "npx",
+      "args": ["-y", "github-cicd-mcp"],
+      "env": {
+        "GITHUB_TOKEN": "${env:GITHUB_TOKEN}"
+      }
+    }
+  }
+}
+```
+
+Set `GITHUB_TOKEN` (or `GH_TOKEN`) in your system environment, or replace `${env:GITHUB_TOKEN}` with a secret reference your client supports.
+
+### From source
+
+```bash
+git clone https://github.com/devstephenke-sys/Github-Free-MCPs.git
+cd Github-Free-MCPs
+npm install
+npm run build
+```
+
+Point MCP at `node /absolute/path/to/github-cicd-mcp/dist/index.js`.
+
+---
+
+## Authentication
+
+Create a [personal access token](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens):
+
+| Need | Scopes / permissions |
+|------|----------------------|
+| Repos, PRs, commits, issues | `repo` or fine-grained **Contents**, **Pull requests**, **Issues** |
+| Actions | `workflow` |
+| Org billing | `read:org` + org billing role |
+| Admin (branch protection, webhooks) | Admin access on the repo/org |
+
+Never commit tokens. Use environment variables only.
+
+⚠️ **Security**: See [SECURITY.md](SECURITY.md) for security policies and best practices.
+
+---
+
+## Tool reference
+
+### Core & repos
+
+`github_get_authenticated_user`, `github_get_rate_limit`, `github_create_repository`, `github_get_repository`, `github_list_repositories`, `github_create_branch`, `github_fork_repository`
+
+### Commits & CI status
+
+`github_list_commits`, `github_get_commit`, `github_compare_commits`, `github_create_commit`, `github_get_combined_status`, `github_list_check_runs_for_ref`
+
+### Pull requests
+
+`github_create_pull_request`, `github_list_pull_requests`, `github_get_pull_request`, `github_merge_pull_request`, `github_update_pull_request`, `github_list_pull_request_files`, `github_create_pull_request_review`
+
+### Issues
+
+`github_create_issue`, `github_list_issues`, `github_get_issue`, `github_update_issue`, `github_add_issue_comment`, `github_list_issue_comments`
+
+### Releases & tags
+
+`github_list_releases`, `github_get_release_by_tag`, `github_create_release`, `github_list_tags`, `github_create_tag`
+
+### Branches & protection
+
+`github_list_branches`, `github_get_branch`, `github_get_branch_protection`, `github_update_branch_protection`, `github_delete_branch_protection`
+
+### GitHub Actions
+
+`github_list_workflows`, `github_list_workflow_runs`, `github_get_workflow_run`, `github_list_workflow_jobs`, `github_rerun_workflow`, `github_cancel_workflow_run`, `github_dispatch_workflow`, `github_list_actions_secrets`, `github_list_actions_variables`, `github_list_workflow_run_artifacts`, `github_download_workflow_artifact`
+
+### Deployments (CD)
+
+`github_list_deployments`, `github_create_deployment`, `github_create_deployment_status`, `github_list_environments`
+
+### Billing
+
+`github_get_user_billing_actions`, `github_get_org_billing_actions`, `github_get_org_billing_overview`, `github_get_org_billing_usage_report`
+
+### Webhooks & access
+
+`github_list_webhooks`, `github_create_webhook`, `github_delete_webhook`, `github_list_collaborators`, `github_add_collaborator`, `github_list_teams`
+
+### GraphQL
+
+`github_graphql_query`, `github_graphql_mutation`, `github_graphql_repository_overview`
+
+### Local git
+
+`git_status`, `git_commit`, `git_push`, `git_pull`, `git_log`, `git_clone`
+
+---
+
+## GitHub Enterprise
+
+- `GITHUB_HOST` — hostname (when not `github.com`)
+- `GITHUB_API_URL` — REST base, e.g. `https://github.example.com/api/v3`
+- `GITHUB_GRAPHQL_URL` — GraphQL endpoint override
+
+---
+
+## Development
+
+```bash
+npm install
+npm run build
+npm run verify
+```
+
+---
+
+## Publish your own fork
+
+See **[RELEASING.md](RELEASING.md)** for:
+- Public GitHub repo setup
+- npm publish (`npm publish --access public`)
+- GitHub Releases and optional MCP directory listings
+
+---
+
+## License
+
+[MIT](LICENSE)

package/dist/index.d.ts

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

package/dist/index.js

@@ -0,0 +1,45 @@
+#!/usr/bin/env node
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { registerActionsTools } from "./tools/actions.js";
+import { registerBillingTools } from "./tools/billing.js";
+import { registerBranchProtectionTools } from "./tools/branch-protection.js";
+import { registerCommitTools } from "./tools/commits.js";
+import { registerDeploymentTools } from "./tools/deployments.js";
+import { registerGraphqlTools } from "./tools/graphql.js";
+import { registerIssueTools } from "./tools/issues.js";
+import { registerLocalGitTools } from "./tools/local-git.js";
+import { registerPullRequestTools } from "./tools/pull-requests.js";
+import { registerReleaseTools } from "./tools/releases.js";
+import { registerRepoTools } from "./tools/repos.js";
+import { registerCollaboratorTools, registerWebhookTools, } from "./tools/webhooks-collaborators.js";
+const server = new McpServer({
+    name: "github-cicd-mcp",
+    version: "1.1.0",
+}, {
+    instructions: `GitHub CI/CD assistant (REST + GraphQL): https://docs.github.com/en/rest and /en/graphql.
+github_* — remote API (repos, commits, PRs, issues, releases, branch protection, Actions, deployments, billing, webhooks).
+git_* — local clone/commit/push/pull.
+Requires GITHUB_TOKEN or GH_TOKEN (repo, workflow; read:org for org billing).`,
+});
+registerRepoTools(server);
+registerCommitTools(server);
+registerPullRequestTools(server);
+registerActionsTools(server);
+registerDeploymentTools(server);
+registerBillingTools(server);
+registerIssueTools(server);
+registerReleaseTools(server);
+registerBranchProtectionTools(server);
+registerWebhookTools(server);
+registerCollaboratorTools(server);
+registerGraphqlTools(server);
+registerLocalGitTools(server);
+async function main() {
+    const transport = new StdioServerTransport();
+    await server.connect(transport);
+}
+main().catch((err) => {
+    console.error(err);
+    process.exit(1);
+});

package/dist/lib/fields.d.ts

@@ -0,0 +1,4 @@
+import { z } from "zod";
+export declare const owner: z.ZodString;
+export declare const repo: z.ZodString;
+export declare const perPage: z.ZodOptional<z.ZodNumber>;

package/dist/lib/fields.js

@@ -0,0 +1,4 @@
+import { z } from "zod";
+export const owner = z.string().describe("Repository owner (user or org login)");
+export const repo = z.string().describe("Repository name");
+export const perPage = z.number().optional().describe("Results per page (max 100)");

package/dist/lib/github.d.ts

@@ -0,0 +1,13 @@
+import { Octokit } from "@octokit/rest";
+export declare function getToken(): string;
+export declare function getOctokit(): Octokit;
+export declare const ownerRepoSchema: {
+    owner: {
+        type: "string";
+        description: string;
+    };
+    repo: {
+        type: "string";
+        description: string;
+    };
+};

package/dist/lib/github.js

@@ -0,0 +1,27 @@
+import { Octokit } from "@octokit/rest";
+let octokitInstance = null;
+export function getToken() {
+    const token = process.env.GITHUB_TOKEN ?? process.env.GH_TOKEN ?? "";
+    if (!token) {
+        throw new Error("Missing GITHUB_TOKEN (or GH_TOKEN). Create a PAT: https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens");
+    }
+    return token;
+}
+export function getOctokit() {
+    if (!octokitInstance) {
+        const baseUrl = process.env.GITHUB_API_URL ??
+            (process.env.GITHUB_HOST && process.env.GITHUB_HOST !== "github.com"
+                ? `https://${process.env.GITHUB_HOST}/api/v3`
+                : undefined);
+        octokitInstance = new Octokit({
+            auth: getToken(),
+            userAgent: "github-cicd-mcp/1.1.0",
+            ...(baseUrl ? { baseUrl } : {}),
+        });
+    }
+    return octokitInstance;
+}
+export const ownerRepoSchema = {
+    owner: { type: "string", description: "Repository owner (user or org login)" },
+    repo: { type: "string", description: "Repository name" },
+};

package/dist/lib/response.d.ts

@@ -0,0 +1,4 @@
+import type { CallToolResult } from "@modelcontextprotocol/sdk/types.js";
+export declare function jsonResult(data: unknown): CallToolResult;
+export declare function textResult(message: string): CallToolResult;
+export declare function errorResult(err: unknown): CallToolResult;

package/dist/lib/response.js

@@ -0,0 +1,48 @@
+import { RequestError } from "@octokit/request-error";
+function formatUnknownError(err) {
+    if (err instanceof RequestError) {
+        const detail = err.response?.data !== undefined
+            ? typeof err.response.data === "string"
+                ? err.response.data
+                : JSON.stringify(err.response.data, null, 2)
+            : "";
+        const requestId = err.response?.headers && "x-github-request-id" in err.response.headers
+            ? String(err.response.headers["x-github-request-id"])
+            : undefined;
+        return [
+            `GitHub API ${err.status}: ${err.message}`,
+            requestId ? `request-id: ${requestId}` : "",
+            detail ? detail : "",
+        ]
+            .filter(Boolean)
+            .join("\n");
+    }
+    if (err instanceof Error) {
+        return err.message;
+    }
+    if (typeof err === "object" && err !== null && "message" in err) {
+        return String(err.message);
+    }
+    return String(err);
+}
+export function jsonResult(data) {
+    return {
+        content: [
+            {
+                type: "text",
+                text: JSON.stringify(data, null, 2),
+            },
+        ],
+    };
+}
+export function textResult(message) {
+    return {
+        content: [{ type: "text", text: message }],
+    };
+}
+export function errorResult(err) {
+    return {
+        content: [{ type: "text", text: `Error: ${formatUnknownError(err)}` }],
+        isError: true,
+    };
+}

package/dist/tools/actions.d.ts

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

package/dist/tools/actions.js

@@ -0,0 +1,257 @@
+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";
+const workflowStatus = z
+    .string()
+    .optional()
+    .describe("queued | in_progress | completed | failure | success | etc.");
+export function registerActionsTools(server) {
+    server.tool("github_list_workflows", "List GitHub Actions workflows in a repository.", { owner, repo }, async ({ owner, repo }) => {
+        try {
+            const { data } = await getOctokit().rest.actions.listRepoWorkflows({
+                owner,
+                repo,
+            });
+            return jsonResult(data.workflows.map((w) => ({
+                id: w.id,
+                name: w.name,
+                path: w.path,
+                state: w.state,
+                html_url: w.html_url,
+            })));
+        }
+        catch (e) {
+            return errorResult(e);
+        }
+    });
+    server.tool("github_list_workflow_runs", "List workflow runs (filter by workflow id, branch, or status).", {
+        owner,
+        repo,
+        workflow_id: z.number().optional().describe("Workflow ID"),
+        branch: z.string().optional(),
+        status: workflowStatus,
+        per_page: perPage,
+    }, async ({ owner, repo, workflow_id, branch, status, per_page }) => {
+        try {
+            const octokit = getOctokit();
+            const common = {
+                owner,
+                repo,
+                branch: branch ?? undefined,
+                status: status,
+                per_page: per_page ?? 20,
+            };
+            const { data } = workflow_id
+                ? await octokit.rest.actions.listWorkflowRuns({
+                    ...common,
+                    workflow_id,
+                })
+                : await octokit.rest.actions.listWorkflowRunsForRepo(common);
+            return jsonResult(data.workflow_runs.map((r) => ({
+                id: r.id,
+                name: r.name,
+                status: r.status,
+                conclusion: r.conclusion,
+                head_branch: r.head_branch,
+                head_sha: r.head_sha,
+                event: r.event,
+                html_url: r.html_url,
+                created_at: r.created_at,
+                updated_at: r.updated_at,
+            })));
+        }
+        catch (e) {
+            return errorResult(e);
+        }
+    });
+    server.tool("github_get_workflow_run", "Get details for a single workflow run.", {
+        owner,
+        repo,
+        run_id: z.number(),
+    }, async ({ owner, repo, run_id }) => {
+        try {
+            const { data } = await getOctokit().rest.actions.getWorkflowRun({
+                owner,
+                repo,
+                run_id,
+            });
+            return jsonResult({
+                id: data.id,
+                name: data.name,
+                status: data.status,
+                conclusion: data.conclusion,
+                head_branch: data.head_branch,
+                head_sha: data.head_sha,
+                html_url: data.html_url,
+                jobs_url: data.jobs_url,
+                run_attempt: data.run_attempt,
+            });
+        }
+        catch (e) {
+            return errorResult(e);
+        }
+    });
+    server.tool("github_list_workflow_jobs", "List jobs for a workflow run (steps, conclusions).", {
+        owner,
+        repo,
+        run_id: z.number(),
+    }, async ({ owner, repo, run_id }) => {
+        try {
+            const { data } = await getOctokit().rest.actions.listJobsForWorkflowRun({
+                owner,
+                repo,
+                run_id,
+                per_page: 100,
+            });
+            return jsonResult(data.jobs.map((j) => ({
+                id: j.id,
+                name: j.name,
+                status: j.status,
+                conclusion: j.conclusion,
+                started_at: j.started_at,
+                completed_at: j.completed_at,
+                html_url: j.html_url,
+                steps: j.steps?.map((s) => ({
+                    name: s.name,
+                    status: s.status,
+                    conclusion: s.conclusion,
+                })),
+            })));
+        }
+        catch (e) {
+            return errorResult(e);
+        }
+    });
+    server.tool("github_rerun_workflow", "Re-run a failed or cancelled workflow run.", {
+        owner,
+        repo,
+        run_id: z.number(),
+    }, async ({ owner, repo, run_id }) => {
+        try {
+            await getOctokit().rest.actions.reRunWorkflow({
+                owner,
+                repo,
+                run_id,
+            });
+            return jsonResult({ ok: true, run_id, message: "Workflow re-run requested" });
+        }
+        catch (e) {
+            return errorResult(e);
+        }
+    });
+    server.tool("github_cancel_workflow_run", "Cancel an in-progress workflow run.", {
+        owner,
+        repo,
+        run_id: z.number(),
+    }, async ({ owner, repo, run_id }) => {
+        try {
+            await getOctokit().rest.actions.cancelWorkflowRun({
+                owner,
+                repo,
+                run_id,
+            });
+            return jsonResult({ ok: true, run_id, message: "Workflow cancel requested" });
+        }
+        catch (e) {
+            return errorResult(e);
+        }
+    });
+    server.tool("github_dispatch_workflow", "Trigger a workflow_dispatch event (manual CI run).", {
+        owner,
+        repo,
+        workflow_id: z.string().describe("Workflow ID or filename e.g. deploy.yml"),
+        ref: z.string().describe("Branch or tag to run on"),
+        inputs: z
+            .string()
+            .optional()
+            .describe("JSON object of workflow input key/value pairs"),
+    }, async ({ owner, repo, workflow_id, ref, inputs }) => {
+        try {
+            const parsedInputs = inputs ? JSON.parse(inputs) : undefined;
+            await getOctokit().rest.actions.createWorkflowDispatch({
+                owner,
+                repo,
+                workflow_id,
+                ref,
+                inputs: parsedInputs,
+            });
+            return jsonResult({ ok: true, workflow_id, ref, message: "workflow_dispatch sent" });
+        }
+        catch (e) {
+            return errorResult(e);
+        }
+    });
+    server.tool("github_list_actions_secrets", "List Actions secret names (values are never returned).", { owner, repo }, async ({ owner, repo }) => {
+        try {
+            const { data } = await getOctokit().rest.actions.listRepoSecrets({
+                owner,
+                repo,
+                per_page: 100,
+            });
+            return jsonResult(data.secrets.map((s) => ({
+                name: s.name,
+                updated_at: s.updated_at,
+            })));
+        }
+        catch (e) {
+            return errorResult(e);
+        }
+    });
+    server.tool("github_list_actions_variables", "List Actions variables for a repository (non-secret config).", { owner, repo }, async ({ owner, repo }) => {
+        try {
+            const { data } = await getOctokit().rest.actions.listRepoVariables({
+                owner,
+                repo,
+                per_page: 100,
+            });
+            return jsonResult(data.variables);
+        }
+        catch (e) {
+            return errorResult(e);
+        }
+    });
+    server.tool("github_list_workflow_run_artifacts", "List CI build artifacts for a workflow run.", {
+        owner,
+        repo,
+        run_id: z.number(),
+    }, async ({ owner, repo, run_id }) => {
+        try {
+            const { data } = await getOctokit().rest.actions.listWorkflowRunArtifacts({
+                owner,
+                repo,
+                run_id,
+                per_page: 100,
+            });
+            return jsonResult(data.artifacts.map((a) => ({
+                id: a.id,
+                name: a.name,
+                size_in_bytes: a.size_in_bytes,
+                expired: a.expired,
+                expires_at: a.expires_at,
+                archive_download_url: a.archive_download_url,
+            })));
+        }
+        catch (e) {
+            return errorResult(e);
+        }
+    });
+    server.tool("github_download_workflow_artifact", "Get download URL metadata for a workflow artifact (follow URL with auth to download zip).", {
+        owner,
+        repo,
+        artifact_id: z.number(),
+    }, async ({ owner, repo, artifact_id }) => {
+        try {
+            const { data } = await getOctokit().rest.actions.downloadArtifact({
+                owner,
+                repo,
+                artifact_id,
+                archive_format: "zip",
+            });
+            return jsonResult(data);
+        }
+        catch (e) {
+            return errorResult(e);
+        }
+    });
+}

package/dist/tools/billing.d.ts

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