@nimbus-dev/connectors 0.1.0

package/connectors/github/src/server.ts

@@ -0,0 +1,347 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { z } from "zod";
+
+import { createWriteToolRegistrar, type WriteToolConfig } from "../../../shared/consent-kit.ts";
+import {
+  createRegisterSimpleTool,
+  createZodToolRegistrar,
+  mcpJsonResult as jsonResult,
+  mcpJsonResultIfOk,
+  requireProcessEnv,
+  type ZodObjectSchema,
+} from "../../../shared/mcp-tool-kit.ts";
+import { makeRestFetcher, makeRestToolRegistrar } from "../../../shared/rest-tool-kit.ts";
+
+const GH_API = "https://api.github.com";
+const GH_HEADERS: Record<string, string> = {
+  Accept: "application/vnd.github+json",
+  "X-GitHub-Api-Version": "2022-11-28",
+};
+
+function ghFetch(
+  token: string,
+  path: string,
+  init?: RequestInit,
+): Promise<{ ok: boolean; status: number; json: unknown; text: string }> {
+  return makeRestFetcher({ apiBase: GH_API, token, defaultHeaders: GH_HEADERS })(path, init);
+}
+
+const server = new McpServer(
+  { name: "nimbus-github", version: "0.1.0" },
+  {
+    // Machine-readable security tiering, so a client can surface it rather than relying on a
+    // human having read the NOTICE file.
+    instructions:
+      "Nimbus GitHub connector. Standalone: mutating tools require MCP elicitation consent and " +
+      "are limited by NIMBUS_MCP_GITHUB_WRITE_SCOPE; they are not registered at all if this " +
+      "client does not support elicitation. No sandbox, no OS keychain and no egress ledger " +
+      "outside the Nimbus gateway. See NOTICE.",
+  },
+);
+
+const registerSimpleTool = createRegisterSimpleTool(server);
+const reg = createZodToolRegistrar(registerSimpleTool);
+
+/**
+ * Every MUTATING GitHub tool goes through here. Outside the gateway this adds the consent gate,
+ * the write-scope allow-list, the mutation budget and the audit record; inside the gateway it is a
+ * pass-through, because executor.ts (I2) is the gate there.
+ */
+const registerWriteTool = createWriteToolRegistrar(server, {
+  connector: "github",
+  scopeEnv: "NIMBUS_MCP_GITHUB_WRITE_SCOPE",
+  scopeKinds: ["repo"],
+});
+
+/**
+ * The write-tool equivalent of `registerGithubTool`: same buildPath/buildInit shape, same fetch and
+ * result handling, routed through the write registrar. `scopeTargetOf` is supplied here rather
+ * than per tool — every GitHub mutation is scoped to one `owner/repo`, and deriving it centrally
+ * means a new write tool cannot forget it.
+ */
+function registerGithubWriteTool<T extends { owner: string; repo: string }>(
+  name: string,
+  cfg: Omit<WriteToolConfig<T>, "scopeTargetOf">,
+  description: string,
+  schema: ZodObjectSchema<T>,
+  buildPath: (parsed: T) => string,
+  buildInit?: (parsed: T) => RequestInit,
+): void {
+  registerWriteTool(
+    name,
+    { ...cfg, scopeTargetOf: (p) => ({ kind: "repo", value: `${p.owner}/${p.repo}` }) },
+    description,
+    schema,
+    async (parsed) => {
+      const token = requireProcessEnv("GITHUB_PAT");
+      const res = await ghFetch(token, buildPath(parsed), buildInit?.(parsed));
+      return mcpJsonResultIfOk("GitHub", res);
+    },
+  );
+}
+
+/** Standard GitHub tool: token → ghFetch(buildPath[, buildInit]) → mcpJsonResultIfOk("GitHub"). */
+const registerGithubTool = makeRestToolRegistrar({
+  registrar: reg,
+  tokenEnv: "GITHUB_PAT",
+  serviceLabel: "GitHub",
+  fetch: ghFetch,
+});
+
+const slug = (owner: string, repo: string): string =>
+  `/repos/${encodeURIComponent(owner)}/${encodeURIComponent(repo)}`;
+
+const jsonInit = (method: string, body: unknown): RequestInit => ({
+  method,
+  headers: { "Content-Type": "application/json" },
+  body: JSON.stringify(body),
+});
+
+const repoSlugArgs = z.object({
+  owner: z.string().min(1),
+  repo: z.string().min(1),
+});
+
+const githubRepoListSchema = z.object({
+  perPage: z.number().int().min(1).max(100).optional(),
+  page: z.number().int().min(1).optional(),
+});
+
+registerGithubTool(
+  "github_repo_list",
+  "List repositories for the authenticated user (affiliation: owner, collaborator, organization_member).",
+  githubRepoListSchema,
+  (parsed) => {
+    const u = new URL(`${GH_API}/user/repos`);
+    u.searchParams.set("per_page", String(parsed.perPage ?? 30));
+    if (parsed.page !== undefined) {
+      u.searchParams.set("page", String(parsed.page));
+    }
+    u.searchParams.set("sort", "updated");
+    u.searchParams.set("affiliation", "owner,collaborator,organization_member");
+    return `${u.pathname}${u.search}`;
+  },
+);
+
+registerGithubTool(
+  "github_repo_get",
+  "Get repository metadata (owner/repo).",
+  repoSlugArgs,
+  (parsed) => slug(parsed.owner, parsed.repo),
+);
+
+const githubPrListSchema = repoSlugArgs.extend({
+  state: z.enum(["open", "closed", "all"]).optional(),
+  perPage: z.number().int().min(1).max(100).optional(),
+  page: z.number().int().min(1).optional(),
+});
+
+registerGithubTool(
+  "github_pr_list",
+  "List pull requests for a repository.",
+  githubPrListSchema,
+  (parsed) => {
+    const u = new URL(`${GH_API}${slug(parsed.owner, parsed.repo)}/pulls`);
+    u.searchParams.set("state", parsed.state ?? "open");
+    u.searchParams.set("per_page", String(parsed.perPage ?? 30));
+    if (parsed.page !== undefined) {
+      u.searchParams.set("page", String(parsed.page));
+    }
+    u.searchParams.set("sort", "updated");
+    u.searchParams.set("direction", "desc");
+    return `${u.pathname}${u.search}`;
+  },
+);
+
+const githubPrNumberSchema = repoSlugArgs.extend({
+  pullNumber: z.number().int().min(1),
+});
+
+registerGithubTool(
+  "github_pr_get",
+  "Get a single pull request by number.",
+  githubPrNumberSchema,
+  (parsed) => `${slug(parsed.owner, parsed.repo)}/pulls/${String(parsed.pullNumber)}`,
+);
+
+const githubPrMergeSchema = repoSlugArgs.extend({
+  pullNumber: z.number().int().min(1),
+  mergeMethod: z.enum(["merge", "squash", "rebase"]).optional(),
+  commitTitle: z.string().max(500).optional(),
+});
+
+registerGithubWriteTool(
+  "github_pr_merge",
+  { mutates: "github.pr.merge", recoverable: true },
+  "Merge a pull request.",
+  githubPrMergeSchema,
+  (parsed) => `${slug(parsed.owner, parsed.repo)}/pulls/${String(parsed.pullNumber)}/merge`,
+  (parsed) => {
+    const body: Record<string, string> = {};
+    if (parsed.mergeMethod !== undefined) {
+      body["merge_method"] = parsed.mergeMethod;
+    }
+    if (parsed.commitTitle !== undefined && parsed.commitTitle !== "") {
+      body["commit_title"] = parsed.commitTitle;
+    }
+    return jsonInit("PUT", body);
+  },
+);
+
+registerGithubWriteTool(
+  "github_pr_close",
+  { mutates: "github.pr.close", recoverable: true },
+  "Close a pull request without merging.",
+  githubPrNumberSchema,
+  (parsed) => `${slug(parsed.owner, parsed.repo)}/pulls/${String(parsed.pullNumber)}`,
+  () => jsonInit("PATCH", { state: "closed" }),
+);
+
+const githubIssueListSchema = repoSlugArgs.extend({
+  state: z.enum(["open", "closed", "all"]).optional(),
+  perPage: z.number().int().min(1).max(100).optional(),
+  page: z.number().int().min(1).optional(),
+});
+
+registerGithubTool(
+  "github_issue_list",
+  "List issues for a repository.",
+  githubIssueListSchema,
+  (parsed) => {
+    const u = new URL(`${GH_API}${slug(parsed.owner, parsed.repo)}/issues`);
+    u.searchParams.set("state", parsed.state ?? "open");
+    u.searchParams.set("per_page", String(parsed.perPage ?? 30));
+    if (parsed.page !== undefined) {
+      u.searchParams.set("page", String(parsed.page));
+    }
+    u.searchParams.set("sort", "updated");
+    u.searchParams.set("direction", "desc");
+    return `${u.pathname}${u.search}`;
+  },
+);
+
+const githubIssueGetSchema = repoSlugArgs.extend({
+  issueNumber: z.number().int().min(1),
+});
+
+registerGithubTool(
+  "github_issue_get",
+  "Get a single issue by number.",
+  githubIssueGetSchema,
+  (parsed) => `${slug(parsed.owner, parsed.repo)}/issues/${String(parsed.issueNumber)}`,
+);
+
+const githubIssueCreateSchema = repoSlugArgs.extend({
+  title: z.string().min(1).max(500),
+  body: z.string().max(65_000).optional(),
+});
+
+registerGithubWriteTool(
+  "github_issue_create",
+  { mutates: "github.issue.create", recoverable: true },
+  "Create a new issue in a repository.",
+  githubIssueCreateSchema,
+  (parsed) => `${slug(parsed.owner, parsed.repo)}/issues`,
+  (parsed) => jsonInit("POST", { title: parsed.title, body: parsed.body }),
+);
+
+const githubCiRunsSchema = repoSlugArgs.extend({
+  perPage: z.number().int().min(1).max(100).optional(),
+  page: z.number().int().min(1).optional(),
+});
+
+registerGithubTool(
+  "github_ci_runs",
+  "List GitHub Actions workflow runs for a repository.",
+  githubCiRunsSchema,
+  (parsed) => {
+    const u = new URL(`${GH_API}${slug(parsed.owner, parsed.repo)}/actions/runs`);
+    u.searchParams.set("per_page", String(parsed.perPage ?? 30));
+    if (parsed.page !== undefined) {
+      u.searchParams.set("page", String(parsed.page));
+    }
+    return `${u.pathname}${u.search}`;
+  },
+);
+
+const githubCiRunGetSchema = repoSlugArgs.extend({
+  runId: z.number().int().min(1),
+});
+
+registerGithubTool(
+  "github_ci_run_get",
+  "Get a single workflow run including jobs URL reference.",
+  githubCiRunGetSchema,
+  (parsed) => `${slug(parsed.owner, parsed.repo)}/actions/runs/${String(parsed.runId)}`,
+);
+
+const githubBranchDeleteSchema = repoSlugArgs.extend({
+  branch: z.string().min(1).max(255),
+});
+
+registerWriteTool(
+  "github_branch_delete",
+  {
+    mutates: "github.branch.delete",
+    // The only GitHub mutation here that cannot be undone from its own result, so the ref's SHA is
+    // captured BEFORE the delete. With it the branch can be recreated; without it the commit is
+    // only reachable by reflog on someone's clone.
+    recoverable: false,
+    capturePreState: async (parsed) => {
+      const token = requireProcessEnv("GITHUB_PAT");
+      const ref = `heads/${parsed.branch}`;
+      const res = await ghFetch(
+        token,
+        `${slug(parsed.owner, parsed.repo)}/git/ref/${encodeURIComponent(ref)}`,
+      );
+      return { ref, resolved: res.ok, sha: res.json };
+    },
+    scopeTargetOf: (parsed) => ({ kind: "repo", value: `${parsed.owner}/${parsed.repo}` }),
+  },
+  "Delete a branch by ref name.",
+  githubBranchDeleteSchema,
+  async (parsed) => {
+    const token = requireProcessEnv("GITHUB_PAT");
+    const ref = `heads/${parsed.branch}`;
+    const path = `${slug(parsed.owner, parsed.repo)}/git/refs/${encodeURIComponent(ref)}`;
+    const res = await ghFetch(token, path, { method: "DELETE" });
+    if (!res.ok && res.status !== 204) {
+      throw new Error(`GitHub ${String(res.status)}: ${res.text.slice(0, 300)}`);
+    }
+    return jsonResult({ ok: true, deleted: ref });
+  },
+);
+
+const githubTagCreateSchema = repoSlugArgs.extend({
+  tag: z.string().min(1).max(255),
+  sha: z.string().min(7).max(40),
+});
+
+registerGithubWriteTool(
+  "github_tag_create",
+  { mutates: "github.tag.create", recoverable: true },
+  "Create a lightweight tag pointing at a commit SHA.",
+  githubTagCreateSchema,
+  (parsed) => `${slug(parsed.owner, parsed.repo)}/git/refs`,
+  (parsed) => jsonInit("POST", { ref: `refs/tags/${parsed.tag}`, sha: parsed.sha }),
+);
+
+const githubCommitPushSchema = repoSlugArgs.extend({
+  branch: z.string().min(1).optional(),
+});
+
+reg(
+  "github_commit_push",
+  "Push commits is not available via this tool — use local git with your own remote credentials (requires HITL repo.commit.push if ever implemented).",
+  githubCommitPushSchema,
+  async () =>
+    jsonResult({
+      code: "NOT_IMPLEMENTED",
+      message:
+        "Pushing commits requires local git and is not executed by this MCP server. Clone the repo and push with git.",
+    }),
+);
+
+const transport = new StdioServerTransport();
+await server.connect(transport);

package/connectors/github-actions/nimbus.extension.json

@@ -0,0 +1,15 @@
+{
+  "id": "com.nimbus.github-actions",
+  "displayName": "GitHub Actions",
+  "version": "0.1.0",
+  "description": "GitHub Actions workflows / runs / artifacts via the GitHub REST API. Mutations require Gateway HITL.",
+  "author": "Nimbus",
+  "entrypoint": "dist/server.js",
+  "runtime": "bun",
+  "permissions": {
+    "network": ["api.github.com"]
+  },
+  "hitlRequired": ["write", "delete"],
+  "syncInterval": 300,
+  "minNimbusVersion": "0.2.0"
+}

package/connectors/github-actions/src/server.ts

@@ -0,0 +1,213 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { z } from "zod";
+import { createWriteToolRegistrar } from "../../../shared/consent-kit.ts";
+import {
+  createRegisterSimpleTool,
+  createZodToolRegistrar,
+  mcpJsonResult as jsonResult,
+  requireProcessEnv,
+} from "../../../shared/mcp-tool-kit.ts";
+import { makeRestFetcher, makeRestToolRegistrar } from "../../../shared/rest-tool-kit.ts";
+
+const GH_API = "https://api.github.com";
+const GH_HEADERS: Record<string, string> = {
+  Accept: "application/vnd.github+json",
+  "X-GitHub-Api-Version": "2022-11-28",
+};
+
+function ghFetch(
+  token: string,
+  path: string,
+  init?: RequestInit,
+): Promise<{ ok: boolean; status: number; json: unknown; text: string }> {
+  return makeRestFetcher({ apiBase: GH_API, token, defaultHeaders: GH_HEADERS })(path, init);
+}
+
+const mcp = new McpServer({ name: "nimbus-github-actions", version: "0.1.0" });
+const reg = createZodToolRegistrar(createRegisterSimpleTool(mcp));
+
+/**
+ * Every MUTATING github-actions tool goes through here. Outside the gateway this adds the
+ * consent gate, the write-scope allow-list, the mutation budget and the audit record; inside
+ * the gateway it is a pass-through, because executor.ts (I2) is the gate there.
+ */
+const registerWriteTool = createWriteToolRegistrar(mcp, {
+  connector: "github-actions",
+  scopeEnv: "NIMBUS_MCP_GITHUB_ACTIONS_WRITE_SCOPE",
+  scopeKinds: ["repo"],
+});
+
+/** Standard GitHub Actions tool: token → ghFetch(buildPath) → mcpJsonResultIfOk("GitHub Actions"). */
+const registerGhaTool = makeRestToolRegistrar({
+  registrar: reg,
+  tokenEnv: "GITHUB_PAT",
+  serviceLabel: "GitHub Actions",
+  fetch: ghFetch,
+});
+
+const slug = (owner: string, repo: string): string =>
+  `/repos/${encodeURIComponent(owner)}/${encodeURIComponent(repo)}`;
+
+const repoSlugArgs = z.object({
+  owner: z.string().min(1),
+  repo: z.string().min(1),
+});
+
+const runListSchema = repoSlugArgs.extend({
+  perPage: z.number().int().min(1).max(100).optional(),
+  page: z.number().int().min(1).optional(),
+  branch: z.string().optional(),
+  event: z.string().optional(),
+  status: z.string().optional(),
+});
+
+registerGhaTool(
+  "gha_workflow_list",
+  "List GitHub Actions workflows for a repository.",
+  repoSlugArgs.extend({
+    perPage: z.number().int().min(1).max(100).optional(),
+    page: z.number().int().min(1).optional(),
+  }),
+  (parsed) => {
+    const u = new URL(`${GH_API}${slug(parsed.owner, parsed.repo)}/actions/workflows`);
+    u.searchParams.set("per_page", String(parsed.perPage ?? 30));
+    if (parsed.page !== undefined) {
+      u.searchParams.set("page", String(parsed.page));
+    }
+    return `${u.pathname}${u.search}`;
+  },
+);
+
+registerGhaTool("gha_run_list", "List workflow runs for a repository.", runListSchema, (parsed) => {
+  const u = new URL(`${GH_API}${slug(parsed.owner, parsed.repo)}/actions/runs`);
+  u.searchParams.set("per_page", String(parsed.perPage ?? 30));
+  if (parsed.page !== undefined) {
+    u.searchParams.set("page", String(parsed.page));
+  }
+  if (parsed.branch !== undefined) {
+    u.searchParams.set("branch", parsed.branch);
+  }
+  if (parsed.event !== undefined) {
+    u.searchParams.set("event", parsed.event);
+  }
+  if (parsed.status !== undefined) {
+    u.searchParams.set("status", parsed.status);
+  }
+  return `${u.pathname}${u.search}`;
+});
+
+const runIdSchema = repoSlugArgs.extend({
+  runId: z.number().int().min(1),
+});
+
+registerGhaTool(
+  "gha_run_get",
+  "Get a single workflow run by id.",
+  runIdSchema,
+  (parsed) => `${slug(parsed.owner, parsed.repo)}/actions/runs/${String(parsed.runId)}`,
+);
+
+registerGhaTool(
+  "gha_run_jobs",
+  "List jobs for a workflow run.",
+  runIdSchema,
+  (parsed) => `${slug(parsed.owner, parsed.repo)}/actions/runs/${String(parsed.runId)}/jobs`,
+);
+
+reg(
+  "gha_run_log",
+  "Download console log text for a job (truncated).",
+  repoSlugArgs.extend({
+    jobId: z.number().int().min(1),
+    maxChars: z.number().int().min(1000).max(500_000).optional(),
+  }),
+  async (parsed) => {
+    const token = requireProcessEnv("GITHUB_PAT");
+    const url = `${GH_API}/repos/${encodeURIComponent(parsed.owner)}/${encodeURIComponent(parsed.repo)}/actions/jobs/${String(parsed.jobId)}/logs`;
+    const res = await fetch(url, {
+      headers: {
+        Accept: "application/vnd.github+json",
+        Authorization: `Bearer ${token}`,
+        "X-GitHub-Api-Version": "2022-11-28",
+      },
+      redirect: "follow",
+    });
+    const text = await res.text();
+    if (!res.ok) {
+      throw new Error(`GitHub Actions logs ${String(res.status)}: ${text.slice(0, 400)}`);
+    }
+    const max = parsed.maxChars ?? 64_000;
+    const tail = text.length > max ? text.slice(-max) : text;
+    return jsonResult({
+      jobId: parsed.jobId,
+      truncated: text.length > max,
+      totalChars: text.length,
+      text: tail,
+    });
+  },
+);
+
+registerWriteTool(
+  "gha_run_trigger",
+  {
+    mutates: "github_actions.run.trigger",
+    recoverable: true,
+    scopeTargetOf: (p) => ({ kind: "repo", value: `${p.owner}/${p.repo}` }),
+  },
+  "Dispatch a workflow (workflow_dispatch).",
+  repoSlugArgs.extend({
+    workflowId: z
+      .string()
+      .min(1)
+      .describe("Numeric workflow id or workflow file name (e.g. ci.yml)"),
+    ref: z.string().min(1).optional(),
+    inputs: z.record(z.string(), z.string()).optional(),
+  }),
+  async (parsed) => {
+    const token = requireProcessEnv("GITHUB_PAT");
+    const encWf = encodeURIComponent(parsed.workflowId);
+    const path = `${slug(parsed.owner, parsed.repo)}/actions/workflows/${encWf}/dispatches`;
+    const ref = parsed.ref ?? "main";
+    const res = await ghFetch(token, path, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({
+        ref,
+        inputs: parsed.inputs ?? {},
+      }),
+    });
+    if (!res.ok) {
+      throw new Error(`GitHub Actions dispatch ${String(res.status)}: ${res.text.slice(0, 400)}`);
+    }
+    return jsonResult({
+      ok: true,
+      owner: parsed.owner,
+      repo: parsed.repo,
+      workflowId: parsed.workflowId,
+    });
+  },
+);
+
+registerWriteTool(
+  "gha_run_cancel",
+  {
+    mutates: "github_actions.run.cancel",
+    recoverable: true,
+    scopeTargetOf: (p) => ({ kind: "repo", value: `${p.owner}/${p.repo}` }),
+  },
+  "Cancel a workflow run.",
+  runIdSchema,
+  async (parsed) => {
+    const token = requireProcessEnv("GITHUB_PAT");
+    const path = `${slug(parsed.owner, parsed.repo)}/actions/runs/${String(parsed.runId)}/cancel`;
+    const res = await ghFetch(token, path, { method: "POST" });
+    if (!res.ok) {
+      throw new Error(`GitHub Actions cancel ${String(res.status)}: ${res.text.slice(0, 400)}`);
+    }
+    return jsonResult({ ok: true, runId: parsed.runId });
+  },
+);
+
+const transport = new StdioServerTransport();
+await mcp.connect(transport);

package/connectors/gitlab/nimbus.extension.json

@@ -0,0 +1,15 @@
+{
+  "id": "com.nimbus.gitlab",
+  "displayName": "GitLab",
+  "version": "0.1.0",
+  "description": "GitLab REST connector (projects, merge requests, pipelines). Self-hosted hosts come from gitlab.api_base. Mutations require Gateway HITL.",
+  "author": "Nimbus",
+  "entrypoint": "dist/server.js",
+  "runtime": "bun",
+  "permissions": {
+    "network": ["gitlab.com"]
+  },
+  "hitlRequired": ["write", "delete"],
+  "syncInterval": 300,
+  "minNimbusVersion": "0.2.0"
+}