@nimbus-dev/connectors 0.2.1 → 0.2.3

package/connectors/github/src/tools.ts

@@ -0,0 +1,311 @@
+import { z } from "zod";
+import {
+  type ConsentServer,
+  createWriteToolRegistrar,
+  type WriteToolConfig,
+} from "../../../shared/consent-kit.ts";
+import { ghFetch, ghQueryPath, ghRepoPath, setGhPaging } from "../../../shared/github-rest.ts";
+import {
+  createRegisterSimpleTool,
+  createZodToolRegistrar,
+  mcpJsonResult as jsonResult,
+  requireProcessEnv,
+  type ZodObjectSchema,
+} from "../../../shared/mcp-tool-kit.ts";
+import {
+  makeRestToolRegistrar,
+  makeRestWriteToolRegistrar,
+} from "../../../shared/rest-tool-kit.ts";
+
+/** Tool names exposed by this connector — for contract/introspection tests. */
+export const GITHUB_TOOL_NAMES = [
+  "github_repo_list",
+  "github_repo_get",
+  "github_pr_list",
+  "github_pr_get",
+  "github_pr_merge",
+  "github_pr_close",
+  "github_issue_list",
+  "github_issue_get",
+  "github_issue_create",
+  "github_ci_runs",
+  "github_ci_run_get",
+  "github_branch_delete",
+  "github_tag_create",
+  "github_commit_push",
+] as const;
+
+export function registerGithubTools(
+  server: ConsentServer & { tool: (...args: never) => unknown },
+): void {
+  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"],
+  });
+
+  /** Standard GitHub tool, read or write: token → ghFetch(buildPath[, buildInit]) → mcpJsonResultIfOk("GitHub"). */
+  const githubRest = { tokenEnv: "GITHUB_PAT", serviceLabel: "GitHub", fetch: ghFetch } as const;
+  const registerGithubTool = makeRestToolRegistrar({ registrar: reg, ...githubRest });
+  const registerRestWriteTool = makeRestWriteToolRegistrar({ registerWriteTool, ...githubRest });
+
+  /**
+   * The write-tool equivalent of `registerGithubTool`, 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 {
+    registerRestWriteTool(
+      name,
+      { ...cfg, scopeTargetOf: (p) => ({ kind: "repo", value: `${p.owner}/${p.repo}` }) },
+      description,
+      schema,
+      buildPath,
+      buildInit,
+    );
+  }
+
+  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) =>
+      ghQueryPath("/user/repos", (q) => {
+        setGhPaging(q, parsed);
+        q.set("sort", "updated");
+        q.set("affiliation", "owner,collaborator,organization_member");
+      }),
+  );
+
+  registerGithubTool(
+    "github_repo_get",
+    "Get repository metadata (owner/repo).",
+    repoSlugArgs,
+    (parsed) => ghRepoPath(parsed.owner, parsed.repo),
+  );
+
+  /** Pulls and issues take one list query: a state filter, paging, newest activity first. */
+  const githubStateListSchema = 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(),
+  });
+  const stateListPath =
+    (collection: "pulls" | "issues") =>
+    (parsed: z.infer<typeof githubStateListSchema>): string =>
+      ghQueryPath(`${ghRepoPath(parsed.owner, parsed.repo)}/${collection}`, (q) => {
+        q.set("state", parsed.state ?? "open");
+        setGhPaging(q, parsed);
+        q.set("sort", "updated");
+        q.set("direction", "desc");
+      });
+
+  registerGithubTool(
+    "github_pr_list",
+    "List pull requests for a repository.",
+    githubStateListSchema,
+    stateListPath("pulls"),
+  );
+
+  const githubPrNumberSchema = repoSlugArgs.extend({
+    pullNumber: z.number().int().min(1),
+  });
+
+  registerGithubTool(
+    "github_pr_get",
+    "Get a single pull request by number.",
+    githubPrNumberSchema,
+    (parsed) => `${ghRepoPath(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) => `${ghRepoPath(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) => `${ghRepoPath(parsed.owner, parsed.repo)}/pulls/${String(parsed.pullNumber)}`,
+    () => jsonInit("PATCH", { state: "closed" }),
+  );
+
+  registerGithubTool(
+    "github_issue_list",
+    "List issues for a repository.",
+    githubStateListSchema,
+    stateListPath("issues"),
+  );
+
+  const githubIssueGetSchema = repoSlugArgs.extend({
+    issueNumber: z.number().int().min(1),
+  });
+
+  registerGithubTool(
+    "github_issue_get",
+    "Get a single issue by number.",
+    githubIssueGetSchema,
+    (parsed) => `${ghRepoPath(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) => `${ghRepoPath(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) =>
+      ghQueryPath(`${ghRepoPath(parsed.owner, parsed.repo)}/actions/runs`, (q) => {
+        setGhPaging(q, parsed);
+      }),
+  );
+
+  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) => `${ghRepoPath(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,
+          `${ghRepoPath(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 = `${ghRepoPath(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) => `${ghRepoPath(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,
+    () =>
+      Promise.resolve(
+        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.",
+        }),
+      ),
+  );
+}

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

@@ -1,213 +1,10 @@
 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);
-}
+import { registerGithubActionsTools } from "./tools.ts";
 
 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 });
-  },
-);
+registerGithubActionsTools(mcp);
 
 const transport = new StdioServerTransport();
 await mcp.connect(transport);