@nimbus-dev/connectors 0.1.0

package/connectors/gitlab/src/server.ts

@@ -0,0 +1,392 @@
+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 { stripTrailingSlashes } from "../../../shared/strip-trailing-slashes.ts";
+
+function apiBase(): string {
+  const b = process.env["GITLAB_API_BASE_URL"];
+  if (b !== undefined && b.trim() !== "") {
+    return stripTrailingSlashes(b);
+  }
+  return "https://gitlab.com/api/v4";
+}
+
+async function glFetch(
+  token: string,
+  path: string,
+  init?: RequestInit,
+): Promise<{ ok: boolean; status: number; json: unknown; text: string }> {
+  const base = apiBase();
+  const relativePath = path.startsWith("/") ? path : `/${path}`;
+  const url = path.startsWith("http") ? path : `${base}${relativePath}`;
+  const baseHeaders: Record<string, string> = { "PRIVATE-TOKEN": token };
+  const mergedHeaders =
+    init?.headers === undefined
+      ? baseHeaders
+      : { ...baseHeaders, ...(init.headers as Record<string, string>) };
+  const res = await fetch(url, {
+    ...init,
+    headers: mergedHeaders,
+  });
+  const text = await res.text();
+  let json: unknown;
+  try {
+    json = JSON.parse(text) as unknown;
+  } catch {
+    json = null;
+  }
+  return { ok: res.ok, status: res.status, json, text };
+}
+
+const server = new McpServer({ name: "nimbus-gitlab", version: "0.1.0" });
+
+const registerSimpleTool = createRegisterSimpleTool(server);
+const reg = createZodToolRegistrar(registerSimpleTool);
+
+/**
+ * Register a standard GitLab read/write tool whose body is the repeated shape
+ * `token → glFetch(buildUrl[, buildInit]) → mcpJsonResultIfOk("GitLab", res)`.
+ * `buildUrl` returns the relative path (or absolute URL) and `buildInit` the
+ * optional fetch init (method/body). Tools with a non-standard tail (raw text
+ * trace, custom error text) stay hand-written below.
+ */
+/**
+ * Every MUTATING gitlab 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: "gitlab",
+  scopeEnv: "NIMBUS_MCP_GITLAB_WRITE_SCOPE",
+  scopeKinds: ["repo"],
+});
+
+/**
+ * The write-tool equivalent of `registerGitlabTool`: identical fetch and result handling, routed
+ * through the write registrar. `scopeTargetOf` is supplied here rather than per tool — every
+ * GitLab mutation is scoped to one project — so a new write tool cannot forget it.
+ */
+function registerGitlabWriteTool<T extends { projectPath: string }>(
+  name: string,
+  cfg: Omit<WriteToolConfig<T>, "scopeTargetOf">,
+  description: string,
+  schema: ZodObjectSchema<T>,
+  buildUrl: (p: T) => string,
+  buildInit?: (p: T) => RequestInit,
+): void {
+  registerWriteTool(
+    name,
+    { ...cfg, scopeTargetOf: (p) => ({ kind: "repo", value: p.projectPath }) },
+    description,
+    schema,
+    async (parsed) => {
+      const token = requireProcessEnv("GITLAB_PAT");
+      const res = await glFetch(token, buildUrl(parsed), buildInit?.(parsed));
+      return mcpJsonResultIfOk("GitLab", res);
+    },
+  );
+}
+
+function registerGitlabTool<T>(
+  name: string,
+  description: string,
+  schema: ZodObjectSchema<T>,
+  buildUrl: (p: T) => string,
+  buildInit?: (p: T) => RequestInit,
+): void {
+  reg(name, description, schema, async (parsed) => {
+    const token = requireProcessEnv("GITLAB_PAT");
+    const res = await glFetch(token, buildUrl(parsed), buildInit?.(parsed));
+    return mcpJsonResultIfOk("GitLab", res);
+  });
+}
+
+const projectPathArg = z.object({
+  projectPath: z
+    .string()
+    .min(1)
+    .describe("URL-encoded path or numeric project id, e.g. group/repo"),
+});
+
+const gitlabProjectListSchema = z.object({
+  perPage: z.number().int().min(1).max(100).optional(),
+  page: z.number().int().min(1).optional(),
+});
+
+registerGitlabTool(
+  "gitlab_project_list",
+  "List projects visible to the authenticated user (membership).",
+  gitlabProjectListSchema,
+  (parsed) => {
+    const u = new URL(`${apiBase()}/projects`);
+    u.searchParams.set("membership", "true");
+    u.searchParams.set("order_by", "last_activity_at");
+    u.searchParams.set("sort", "desc");
+    u.searchParams.set("per_page", String(parsed.perPage ?? 30));
+    if (parsed.page !== undefined) {
+      u.searchParams.set("page", String(parsed.page));
+    }
+    // Absolute URL: u already includes apiBase()'s `/api/v4`; returning a
+    // relative path would let glFetch re-prefix apiBase() → `/api/v4/api/v4/…`.
+    return u.toString();
+  },
+);
+
+const gitlabMrListSchema = projectPathArg.extend({
+  state: z.enum(["opened", "closed", "locked", "merged", "all"]).optional(),
+  perPage: z.number().int().min(1).max(100).optional(),
+  page: z.number().int().min(1).optional(),
+});
+
+registerGitlabTool(
+  "gitlab_mr_list",
+  "List merge requests for a project.",
+  gitlabMrListSchema,
+  (parsed) => {
+    const enc = encodeURIComponent(parsed.projectPath);
+    const u = new URL(`${apiBase()}/projects/${enc}/merge_requests`);
+    u.searchParams.set("state", parsed.state ?? "opened");
+    u.searchParams.set("per_page", String(parsed.perPage ?? 30));
+    if (parsed.page !== undefined) {
+      u.searchParams.set("page", String(parsed.page));
+    }
+    // Absolute URL: u already includes apiBase()'s `/api/v4`; returning a
+    // relative path would let glFetch re-prefix apiBase() → `/api/v4/api/v4/…`.
+    return u.toString();
+  },
+);
+
+const gitlabMrGetSchema = projectPathArg.extend({
+  mergeRequestIid: z.number().int().min(1),
+});
+
+registerGitlabTool(
+  "gitlab_mr_get",
+  "Get a single merge request by IID.",
+  gitlabMrGetSchema,
+  (parsed) =>
+    `/projects/${encodeURIComponent(parsed.projectPath)}/merge_requests/${String(parsed.mergeRequestIid)}`,
+);
+
+const gitlabMrMergeSchema = projectPathArg.extend({
+  mergeRequestIid: z.number().int().min(1),
+  mergeCommitMessage: z.string().max(10_000).optional(),
+  squash: z.boolean().optional(),
+  shouldRemoveSourceBranch: z.boolean().optional(),
+});
+
+registerGitlabWriteTool(
+  "gitlab_mr_merge",
+  {
+    mutates: "gitlab.mr.merge",
+    recoverable: true,
+  },
+  "Merge a merge request.",
+  gitlabMrMergeSchema,
+  (parsed) =>
+    `/projects/${encodeURIComponent(parsed.projectPath)}/merge_requests/${String(parsed.mergeRequestIid)}/merge`,
+  (parsed) => {
+    const body: Record<string, unknown> = {};
+    if (parsed.mergeCommitMessage !== undefined) {
+      body["merge_commit_message"] = parsed.mergeCommitMessage;
+    }
+    if (parsed.squash !== undefined) {
+      body["squash"] = parsed.squash;
+    }
+    if (parsed.shouldRemoveSourceBranch !== undefined) {
+      body["should_remove_source_branch"] = parsed.shouldRemoveSourceBranch;
+    }
+    return {
+      method: "PUT",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify(body),
+    };
+  },
+);
+
+const gitlabIssueListSchema = projectPathArg.extend({
+  state: z.enum(["opened", "closed", "all"]).optional(),
+  perPage: z.number().int().min(1).max(100).optional(),
+  page: z.number().int().min(1).optional(),
+});
+
+registerGitlabTool(
+  "gitlab_issue_list",
+  "List issues for a project.",
+  gitlabIssueListSchema,
+  (parsed) => {
+    const enc = encodeURIComponent(parsed.projectPath);
+    const u = new URL(`${apiBase()}/projects/${enc}/issues`);
+    u.searchParams.set("state", parsed.state ?? "opened");
+    u.searchParams.set("per_page", String(parsed.perPage ?? 30));
+    if (parsed.page !== undefined) {
+      u.searchParams.set("page", String(parsed.page));
+    }
+    // Absolute URL: u already includes apiBase()'s `/api/v4`; returning a
+    // relative path would let glFetch re-prefix apiBase() → `/api/v4/api/v4/…`.
+    return u.toString();
+  },
+);
+
+const gitlabIssueGetSchema = projectPathArg.extend({
+  issueIid: z.number().int().min(1),
+});
+
+registerGitlabTool(
+  "gitlab_issue_get",
+  "Get a single issue by IID.",
+  gitlabIssueGetSchema,
+  (parsed) =>
+    `/projects/${encodeURIComponent(parsed.projectPath)}/issues/${String(parsed.issueIid)}`,
+);
+
+const gitlabPipelineListSchema = projectPathArg.extend({
+  ref: z.string().max(500).optional(),
+  status: z.string().max(64).optional(),
+  perPage: z.number().int().min(1).max(100).optional(),
+  page: z.number().int().min(1).optional(),
+});
+
+registerGitlabTool(
+  "gitlab_pipeline_list",
+  "List CI pipelines for a project.",
+  gitlabPipelineListSchema,
+  (parsed) => {
+    const enc = encodeURIComponent(parsed.projectPath);
+    const u = new URL(`${apiBase()}/projects/${enc}/pipelines`);
+    u.searchParams.set("per_page", String(parsed.perPage ?? 30));
+    if (parsed.page !== undefined) {
+      u.searchParams.set("page", String(parsed.page));
+    }
+    if (parsed.ref !== undefined) {
+      u.searchParams.set("ref", parsed.ref);
+    }
+    if (parsed.status !== undefined) {
+      u.searchParams.set("status", parsed.status);
+    }
+    // Absolute URL: u already includes apiBase()'s `/api/v4`; returning a
+    // relative path would let glFetch re-prefix apiBase() → `/api/v4/api/v4/…`.
+    return u.toString();
+  },
+);
+
+const gitlabPipelineGetSchema = projectPathArg.extend({
+  pipelineId: z.number().int().min(1),
+});
+
+registerGitlabTool(
+  "gitlab_pipeline_get",
+  "Get a single pipeline by id.",
+  gitlabPipelineGetSchema,
+  (parsed) =>
+    `/projects/${encodeURIComponent(parsed.projectPath)}/pipelines/${String(parsed.pipelineId)}`,
+);
+
+registerGitlabTool(
+  "gitlab_pipeline_jobs_get",
+  "List jobs for a CI pipeline (by pipeline id).",
+  gitlabPipelineGetSchema,
+  (parsed) =>
+    `/projects/${encodeURIComponent(parsed.projectPath)}/pipelines/${String(parsed.pipelineId)}/jobs`,
+);
+
+const gitlabJobTraceSchema = projectPathArg.extend({
+  jobId: z.number().int().min(1),
+});
+
+reg(
+  "gitlab_job_trace",
+  "Download plain-text trace for a CI job (by job id).",
+  gitlabJobTraceSchema,
+  async (parsed) => {
+    const token = requireProcessEnv("GITLAB_PAT");
+    const enc = encodeURIComponent(parsed.projectPath);
+    const url = `${apiBase()}/projects/${enc}/jobs/${String(parsed.jobId)}/trace`;
+    const res = await fetch(url, { headers: { "PRIVATE-TOKEN": token } });
+    const text = await res.text();
+    if (!res.ok) {
+      throw new Error(`GitLab ${String(res.status)}: ${text.slice(0, 300)}`);
+    }
+    return jsonResult({ trace: text });
+  },
+);
+
+reg(
+  "gitlab_job_log_tail",
+  "Download job trace text, optionally keeping only the last N characters (tail).",
+  gitlabJobTraceSchema.extend({
+    maxChars: z.number().int().min(1000).max(500_000).optional(),
+  }),
+  async (parsed) => {
+    const token = requireProcessEnv("GITLAB_PAT");
+    const enc = encodeURIComponent(parsed.projectPath);
+    const url = `${apiBase()}/projects/${enc}/jobs/${String(parsed.jobId)}/trace`;
+    const res = await fetch(url, { headers: { "PRIVATE-TOKEN": token } });
+    const text = await res.text();
+    if (!res.ok) {
+      throw new Error(`GitLab ${String(res.status)}: ${text.slice(0, 300)}`);
+    }
+    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,
+      trace: tail,
+    });
+  },
+);
+
+registerWriteTool(
+  "gitlab_pipeline_retry",
+  {
+    mutates: "gitlab.pipeline.retry",
+    recoverable: true,
+    scopeTargetOf: (p) => ({ kind: "repo", value: p.projectPath }),
+  },
+  "Retry failed jobs in a pipeline.",
+  gitlabPipelineGetSchema,
+  async (parsed) => {
+    const token = requireProcessEnv("GITLAB_PAT");
+    const enc = encodeURIComponent(parsed.projectPath);
+    const path = `/projects/${enc}/pipelines/${String(parsed.pipelineId)}/retry`;
+    const res = await glFetch(token, path, { method: "POST" });
+    if (!res.ok) {
+      throw new Error(`GitLab pipeline retry ${String(res.status)}: ${res.text.slice(0, 400)}`);
+    }
+    return mcpJsonResultIfOk("GitLab", res);
+  },
+);
+
+registerWriteTool(
+  "gitlab_pipeline_cancel",
+  {
+    mutates: "gitlab.pipeline.cancel",
+    recoverable: true,
+    scopeTargetOf: (p) => ({ kind: "repo", value: p.projectPath }),
+  },
+  "Cancel a pipeline.",
+  gitlabPipelineGetSchema,
+  async (parsed) => {
+    const token = requireProcessEnv("GITLAB_PAT");
+    const enc = encodeURIComponent(parsed.projectPath);
+    const path = `/projects/${enc}/pipelines/${String(parsed.pipelineId)}/cancel`;
+    const res = await glFetch(token, path, { method: "POST" });
+    if (!res.ok) {
+      throw new Error(`GitLab pipeline cancel ${String(res.status)}: ${res.text.slice(0, 400)}`);
+    }
+    return mcpJsonResultIfOk("GitLab", res);
+  },
+);
+
+const transport = new StdioServerTransport();
+await server.connect(transport);

package/connectors/gmail/nimbus.extension.json

@@ -0,0 +1,15 @@
+{
+  "id": "com.nimbus.gmail",
+  "displayName": "Gmail",
+  "version": "0.1.0",
+  "description": "Gmail REST connector (messages, threads, labels, search). Mutations require Gateway HITL.",
+  "author": "Nimbus",
+  "entrypoint": "dist/server.js",
+  "runtime": "bun",
+  "permissions": {
+    "network": ["www.googleapis.com", "gmail.googleapis.com", "oauth2.googleapis.com"]
+  },
+  "hitlRequired": ["write", "delete"],
+  "syncInterval": 120,
+  "minNimbusVersion": "0.2.0"
+}

package/connectors/gmail/src/server.ts

@@ -0,0 +1,277 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { z } from "zod";
+import { headerLine } from "../../../shared/header-safe.ts";
+import {
+  createRegisterSimpleTool,
+  createZodToolRegistrar,
+  mcpJsonResultIfOk,
+  requireProcessEnv,
+  type ZodObjectSchema,
+} from "../../../shared/mcp-tool-kit.ts";
+import { makeRestFetcher, makeRestToolRegistrar } from "../../../shared/rest-tool-kit.ts";
+
+const GMAIL_BASE = "https://gmail.googleapis.com/gmail/v1/users/me";
+
+function gmailFetch(
+  token: string,
+  path: string,
+  init?: RequestInit,
+): Promise<{ ok: boolean; status: number; json: unknown; text: string }> {
+  return makeRestFetcher({ apiBase: GMAIL_BASE, token })(path, init);
+}
+
+function buildRfc822Message(params: {
+  to: string;
+  subject: string;
+  body: string;
+  cc?: string;
+  bcc?: string;
+}): string {
+  const lines: string[] = [
+    `To: ${params.to}`,
+    ...(params.cc !== undefined && params.cc !== "" ? [`Cc: ${params.cc}`] : []),
+    ...(params.bcc !== undefined && params.bcc !== "" ? [`Bcc: ${params.bcc}`] : []),
+    `Subject: ${params.subject}`,
+    "Content-Type: text/plain; charset=UTF-8",
+    "",
+    params.body,
+  ];
+  return lines.join("\r\n");
+}
+
+function toRawBase64Url(rfc822: string): string {
+  return Buffer.from(rfc822, "utf-8").toString("base64url");
+}
+
+const server = new McpServer({ name: "nimbus-gmail", version: "0.1.0" });
+
+const reg = createZodToolRegistrar(createRegisterSimpleTool(server));
+
+/** Standard Gmail tool: token → gmailFetch(buildPath[, buildInit]) → mcpJsonResultIfOk("Gmail API", …, 200). */
+import { createWriteToolRegistrar, type WriteToolConfig } from "../../../shared/consent-kit.ts";
+
+/**
+ * Every MUTATING gmail 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: "gmail",
+  scopeEnv: "NIMBUS_MCP_GMAIL_WRITE_SCOPE",
+  scopeKinds: ["recipient", "draft"],
+});
+
+/**
+ * The write-tool equivalent of `registerGmailTool`: identical fetch and result handling, routed
+ * through the write registrar.
+ */
+function registerGmailWriteTool<T>(
+  name: string,
+  cfg: WriteToolConfig<T>,
+  description: string,
+  schema: ZodObjectSchema<T>,
+  buildPath: (p: T) => string,
+  buildInit?: (p: T) => RequestInit,
+): void {
+  registerWriteTool(name, cfg, description, schema, async (parsed) => {
+    const token = requireProcessEnv("GOOGLE_OAUTH_ACCESS_TOKEN");
+    const res = await gmailFetch(token, buildPath(parsed), buildInit?.(parsed));
+    return mcpJsonResultIfOk("Gmail API", res, 200);
+  });
+}
+
+const registerGmailTool = makeRestToolRegistrar({
+  registrar: reg,
+  tokenEnv: "GOOGLE_OAUTH_ACCESS_TOKEN",
+  serviceLabel: "Gmail API",
+  fetch: gmailFetch,
+  snippetMax: 200,
+});
+
+const gmailMessageListArgs = z.object({
+  maxResults: z.number().int().min(1).max(100).optional(),
+  pageToken: z.string().optional(),
+  q: z.string().max(500).optional(),
+  labelIds: z.array(z.string()).optional(),
+  includeSpamTrash: z.boolean().optional(),
+});
+
+registerGmailTool(
+  "gmail_message_list",
+  "List Gmail message ids (metadata). Optional Gmail search query `q` (same syntax as Gmail UI).",
+  gmailMessageListArgs,
+  (data) => {
+    const u = new URL(`${GMAIL_BASE}/messages`);
+    u.searchParams.set("maxResults", String(data.maxResults ?? 25));
+    if (data.pageToken !== undefined && data.pageToken !== "") {
+      u.searchParams.set("pageToken", data.pageToken);
+    }
+    if (data.q !== undefined && data.q !== "") {
+      u.searchParams.set("q", data.q);
+    }
+    if (data.labelIds !== undefined) {
+      for (const lid of data.labelIds) {
+        u.searchParams.append("labelIds", lid);
+      }
+    }
+    if (data.includeSpamTrash === true) {
+      u.searchParams.set("includeSpamTrash", "true");
+    }
+    return u.toString();
+  },
+);
+
+const gmailMessageReadArgs = z.object({
+  messageId: z.string().min(1),
+  format: z.enum(["minimal", "full", "metadata", "raw"]).optional(),
+});
+
+registerGmailTool(
+  "gmail_message_read",
+  "Read a single Gmail message (format minimal | metadata | full | raw).",
+  gmailMessageReadArgs,
+  (data) => {
+    const fmt = data.format ?? "metadata";
+    const u = new URL(`${GMAIL_BASE}/messages/${encodeURIComponent(data.messageId)}`);
+    u.searchParams.set("format", fmt);
+    if (fmt === "metadata") {
+      u.searchParams.append("metadataHeaders", "Subject");
+      u.searchParams.append("metadataHeaders", "From");
+      u.searchParams.append("metadataHeaders", "To");
+      u.searchParams.append("metadataHeaders", "Date");
+    }
+    return u.toString();
+  },
+);
+
+const gmailThreadReadArgs = z.object({
+  threadId: z.string().min(1),
+  format: z.enum(["minimal", "full", "metadata"]).optional(),
+});
+
+registerGmailTool(
+  "gmail_thread_read",
+  "Read a Gmail thread and its messages.",
+  gmailThreadReadArgs,
+  (data) => {
+    const fmt = data.format ?? "metadata";
+    const u = new URL(`${GMAIL_BASE}/threads/${encodeURIComponent(data.threadId)}`);
+    u.searchParams.set("format", fmt);
+    return u.toString();
+  },
+);
+
+const gmailLabelListArgs = z.object({});
+
+registerGmailTool(
+  "gmail_label_list",
+  "List all Gmail labels.",
+  gmailLabelListArgs,
+  () => `${GMAIL_BASE}/labels`,
+);
+
+const gmailDraftCreateArgs = z.object({
+  to: headerLine({ min: 1 }),
+  subject: headerLine({ min: 1, max: 998 }),
+  body: z.string().max(1_000_000),
+  cc: headerLine().optional(),
+  bcc: headerLine().optional(),
+});
+
+registerGmailWriteTool(
+  "gmail_draft_create",
+  {
+    mutates: "gmail.draft.create",
+    recoverable: true,
+    scopeTargetOf: (p) => ({ kind: "recipient", value: p.to }),
+  },
+  "Create a Gmail draft. Requires Gateway HITL email.draft.create.",
+  gmailDraftCreateArgs,
+  () => `${GMAIL_BASE}/drafts`,
+  (data) => {
+    const msgParams: { to: string; subject: string; body: string; cc?: string; bcc?: string } = {
+      to: data.to,
+      subject: data.subject,
+      body: data.body,
+    };
+    if (data.cc !== undefined && data.cc !== "") {
+      msgParams.cc = data.cc;
+    }
+    if (data.bcc !== undefined && data.bcc !== "") {
+      msgParams.bcc = data.bcc;
+    }
+    const raw = toRawBase64Url(buildRfc822Message(msgParams));
+    return {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({ message: { raw } }),
+    };
+  },
+);
+
+const gmailDraftSendArgs = z.object({
+  draftId: z.string().min(1),
+});
+
+registerGmailWriteTool(
+  "gmail_draft_send",
+  {
+    mutates: "gmail.draft.send",
+    recoverable: false,
+    capturePreState: (p) => Promise.resolve({ draftId: p.draftId }),
+    scopeTargetOf: (p) => ({ kind: "draft", value: p.draftId }),
+  },
+  "Send an existing Gmail draft by id. Requires Gateway HITL email.draft.send.",
+  gmailDraftSendArgs,
+  () => `${GMAIL_BASE}/drafts/send`,
+  (data) => ({
+    method: "POST",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify({ id: data.draftId }),
+  }),
+);
+
+const gmailMessageSendArgs = z.object({
+  to: headerLine({ min: 1 }),
+  subject: headerLine({ min: 1, max: 998 }),
+  body: z.string().max(1_000_000),
+  cc: headerLine().optional(),
+  bcc: headerLine().optional(),
+});
+
+registerGmailWriteTool(
+  "gmail_message_send",
+  {
+    mutates: "gmail.message.send",
+    recoverable: false,
+    // A sent mail cannot be recalled and nothing remains to query, so the recipient and subject
+    // ARE the pre-state.
+    capturePreState: (p) => Promise.resolve({ to: p.to, subject: p.subject }),
+    scopeTargetOf: (p) => ({ kind: "recipient", value: p.to }),
+  },
+  "Send a new Gmail message (not a draft). Requires Gateway HITL email.send.",
+  gmailMessageSendArgs,
+  () => `${GMAIL_BASE}/messages/send`,
+  (data) => {
+    const sendParams: { to: string; subject: string; body: string; cc?: string; bcc?: string } = {
+      to: data.to,
+      subject: data.subject,
+      body: data.body,
+    };
+    if (data.cc !== undefined && data.cc !== "") {
+      sendParams.cc = data.cc;
+    }
+    if (data.bcc !== undefined && data.bcc !== "") {
+      sendParams.bcc = data.bcc;
+    }
+    const raw = toRawBase64Url(buildRfc822Message(sendParams));
+    return {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({ raw }),
+    };
+  },
+);
+
+await server.connect(new StdioServerTransport());

package/connectors/google-drive/nimbus.extension.json

@@ -0,0 +1,15 @@
+{
+  "id": "com.nimbus.google-drive",
+  "displayName": "Google Drive",
+  "version": "0.1.0",
+  "description": "Google Drive v3 connector (files, folders, search). Mutations require Gateway HITL.",
+  "author": "Nimbus",
+  "entrypoint": "dist/server.js",
+  "runtime": "bun",
+  "permissions": {
+    "network": ["www.googleapis.com", "oauth2.googleapis.com", "accounts.google.com"]
+  },
+  "hitlRequired": ["write", "delete"],
+  "syncInterval": 300,
+  "minNimbusVersion": "0.2.0"
+}

package/connectors/google-drive/src/drive-query.ts

@@ -0,0 +1,3 @@
+export function escapeDriveQueryLiteral(value: string): string {
+  return value.replaceAll("\u005c", "\u005c\u005c").replaceAll("'", "\u005c'");
+}