@nimbus-dev/connectors 0.1.0

package/connectors/bitbucket/src/server.ts

@@ -0,0 +1,252 @@
+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 { joinApiPath } from "../../../shared/join-api-path.ts";
+import {
+  createRegisterSimpleTool,
+  createZodToolRegistrar,
+  mcpJsonResultIfOk,
+} from "../../../shared/mcp-tool-kit.ts";
+
+const BB_API = "https://api.bitbucket.org/2.0";
+
+function requireUsername(): string {
+  const t = process.env["BITBUCKET_USERNAME"];
+  if (t === undefined || t === "") {
+    throw new Error("BITBUCKET_USERNAME is not set");
+  }
+  return t;
+}
+
+function requireAppPassword(): string {
+  const t = process.env["BITBUCKET_APP_PASSWORD"];
+  if (t === undefined || t === "") {
+    throw new Error("BITBUCKET_APP_PASSWORD is not set");
+  }
+  return t;
+}
+
+function basicAuthHeader(): string {
+  const user = requireUsername();
+  const pass = requireAppPassword();
+  const b = Buffer.from(`${user}:${pass}`, "utf8").toString("base64");
+  return `Basic ${b}`;
+}
+
+function splitRepoFull(full: string): { workspace: string; repoSlug: string } {
+  const i = full.indexOf("/");
+  if (i <= 0 || i === full.length - 1) {
+    throw new Error("repoFull must be workspace/repo_slug");
+  }
+  return { workspace: full.slice(0, i), repoSlug: full.slice(i + 1) };
+}
+
+async function bbFetch(
+  path: string,
+  init?: RequestInit,
+): Promise<{ ok: boolean; status: number; json: unknown; text: string }> {
+  const url = joinApiPath(BB_API, path);
+  const baseHeaders: Record<string, string> = {
+    Authorization: basicAuthHeader(),
+    Accept: "application/json",
+  };
+  const extra = init?.headers as Record<string, string> | undefined;
+  const headers = extra === undefined ? baseHeaders : { ...baseHeaders, ...extra };
+  const res = await fetch(url, {
+    ...init,
+    headers,
+  });
+  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-bitbucket", version: "0.1.0" });
+
+const registerSimpleTool = createRegisterSimpleTool(server);
+const reg = createZodToolRegistrar(registerSimpleTool);
+
+/**
+ * Every MUTATING bitbucket 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: "bitbucket",
+  scopeEnv: "NIMBUS_MCP_BITBUCKET_WRITE_SCOPE",
+  scopeKinds: ["repo"],
+});
+
+const repoFullArg = z.object({
+  repoFull: z
+    .string()
+    .min(3)
+    .describe("Repository full name: workspace/repo_slug (e.g. myteam/my-service)"),
+});
+
+const bitbucketRepoListSchema = z.object({
+  pagelen: z.number().int().min(1).max(100).optional(),
+  page: z.string().max(2000).optional().describe("Opaque page URL or token from a prior next link"),
+});
+
+reg(
+  "bitbucket_repo_list",
+  "List repositories where the authenticated user is a member.",
+  bitbucketRepoListSchema,
+  async (parsed) => {
+    if (parsed.page?.startsWith("http")) {
+      const res = await bbFetch(parsed.page);
+      return mcpJsonResultIfOk("Bitbucket", res);
+    }
+    const qs = new URLSearchParams();
+    qs.set("role", "member");
+    qs.set("pagelen", String(parsed.pagelen ?? 30));
+    const res = await bbFetch(`/repositories?${qs.toString()}`);
+    return mcpJsonResultIfOk("Bitbucket", res);
+  },
+);
+
+const bitbucketPrListSchema = repoFullArg.extend({
+  state: z.enum(["OPEN", "MERGED", "DECLINED", "SUPERSEDED"]).optional(),
+  pagelen: z.number().int().min(1).max(100).optional(),
+  page: z.string().max(2000).optional().describe("Opaque next URL from a prior response"),
+});
+
+reg(
+  "bitbucket_pr_list",
+  "List pull requests for a repository.",
+  bitbucketPrListSchema,
+  async (parsed) => {
+    if (parsed.page?.startsWith("http")) {
+      const res = await bbFetch(parsed.page);
+      return mcpJsonResultIfOk("Bitbucket", res);
+    }
+    const { workspace, repoSlug } = splitRepoFull(parsed.repoFull);
+    const base = `/repositories/${encodeURIComponent(workspace)}/${encodeURIComponent(repoSlug)}/pullrequests`;
+    const qs = new URLSearchParams();
+    qs.set("pagelen", String(parsed.pagelen ?? 30));
+    qs.set("sort", "-updated_on");
+    if (parsed.state !== undefined) {
+      qs.set("q", `state="${parsed.state}"`);
+    }
+    const res = await bbFetch(`${base}?${qs.toString()}`);
+    return mcpJsonResultIfOk("Bitbucket", res);
+  },
+);
+
+const bitbucketPrGetSchema = repoFullArg.extend({
+  pullRequestId: z.number().int().min(1),
+});
+
+reg(
+  "bitbucket_pr_get",
+  "Get a single pull request by numeric id.",
+  bitbucketPrGetSchema,
+  async (parsed) => {
+    const { workspace, repoSlug } = splitRepoFull(parsed.repoFull);
+    const path = `/repositories/${encodeURIComponent(workspace)}/${encodeURIComponent(repoSlug)}/pullrequests/${String(parsed.pullRequestId)}`;
+    const res = await bbFetch(path);
+    return mcpJsonResultIfOk("Bitbucket", res);
+  },
+);
+
+const bitbucketPrMergeSchema = repoFullArg.extend({
+  pullRequestId: z.number().int().min(1),
+  mergeStrategy: z.enum(["merge_commit", "squash", "fast_forward"]).optional(),
+  message: z.string().max(32_768).optional(),
+});
+
+registerWriteTool(
+  "bitbucket_pr_merge",
+  {
+    mutates: "bitbucket.pr.merge",
+    recoverable: true,
+    scopeTargetOf: (p) => ({ kind: "repo", value: p.repoFull }),
+  },
+  "Merge a pull request.",
+  bitbucketPrMergeSchema,
+  async (parsed) => {
+    const { workspace, repoSlug } = splitRepoFull(parsed.repoFull);
+    const path = `/repositories/${encodeURIComponent(workspace)}/${encodeURIComponent(repoSlug)}/pullrequests/${String(parsed.pullRequestId)}/merge`;
+    const body: Record<string, unknown> = { type: "pullrequest" };
+    if (parsed.mergeStrategy !== undefined) {
+      body["merge_strategy"] = parsed.mergeStrategy;
+    }
+    if (parsed.message !== undefined) {
+      body["message"] = parsed.message;
+    }
+    const res = await bbFetch(path, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify(body),
+    });
+    return mcpJsonResultIfOk("Bitbucket", res);
+  },
+);
+
+const bitbucketRepoPagedSchema = repoFullArg.extend({
+  pagelen: z.number().int().min(1).max(100).optional(),
+  page: z.string().max(2000).optional(),
+});
+
+reg(
+  "bitbucket_pipeline_list",
+  "List Pipelines runs for a repository.",
+  bitbucketRepoPagedSchema,
+  async (parsed) => {
+    if (parsed.page?.startsWith("http")) {
+      const res = await bbFetch(parsed.page);
+      return mcpJsonResultIfOk("Bitbucket", res);
+    }
+    const { workspace, repoSlug } = splitRepoFull(parsed.repoFull);
+    const base = `/repositories/${encodeURIComponent(workspace)}/${encodeURIComponent(repoSlug)}/pipelines/`;
+    const qs = new URLSearchParams();
+    qs.set("pagelen", String(parsed.pagelen ?? 30));
+    const res = await bbFetch(`${base}?${qs.toString()}`);
+    return mcpJsonResultIfOk("Bitbucket", res);
+  },
+);
+
+const bitbucketPipelineGetSchema = repoFullArg.extend({
+  pipelineUuid: z.string().min(8).max(128),
+});
+
+reg(
+  "bitbucket_pipeline_get",
+  "Get a single pipeline run by UUID.",
+  bitbucketPipelineGetSchema,
+  async (parsed) => {
+    const { workspace, repoSlug } = splitRepoFull(parsed.repoFull);
+    const encUuid = encodeURIComponent(parsed.pipelineUuid);
+    const path = `/repositories/${encodeURIComponent(workspace)}/${encodeURIComponent(repoSlug)}/pipelines/${encUuid}`;
+    const res = await bbFetch(path);
+    return mcpJsonResultIfOk("Bitbucket", res);
+  },
+);
+
+reg(
+  "bitbucket_issue_list",
+  "List issues for a repository (issue tracker must be enabled).",
+  bitbucketRepoPagedSchema,
+  async (parsed) => {
+    if (parsed.page?.startsWith("http")) {
+      const res = await bbFetch(parsed.page);
+      return mcpJsonResultIfOk("Bitbucket", res);
+    }
+    const { workspace, repoSlug } = splitRepoFull(parsed.repoFull);
+    const base = `/repositories/${encodeURIComponent(workspace)}/${encodeURIComponent(repoSlug)}/issues`;
+    const qs = new URLSearchParams();
+    qs.set("pagelen", String(parsed.pagelen ?? 30));
+    const res = await bbFetch(`${base}?${qs.toString()}`);
+    return mcpJsonResultIfOk("Bitbucket", res);
+  },
+);
+
+const transport = new StdioServerTransport();
+await server.connect(transport);

package/connectors/bitrise/nimbus.extension.json

@@ -0,0 +1,15 @@
+{
+  "id": "com.nimbus.bitrise",
+  "displayName": "Bitrise",
+  "version": "0.1.0",
+  "description": "Bitrise REST connector (mobile CI builds + apps). Read-only; surfaces build status, workflow id, branch and commit so the local index can correlate mobile CI runs back to PRs and incidents.",
+  "author": "Nimbus",
+  "entrypoint": "dist/server.js",
+  "runtime": "bun",
+  "permissions": {
+    "network": ["api.bitrise.io"]
+  },
+  "hitlRequired": [],
+  "syncInterval": 600,
+  "minNimbusVersion": "0.2.0"
+}

package/connectors/bitrise/src/search-filter.ts

@@ -0,0 +1,11 @@
+import {
+  fieldsFromKeys,
+  makeQueryFilter,
+  type SearchMatchOptions,
+} from "../../../shared/search-filter.ts";
+
+export type BitriseSearchMatchOptions = SearchMatchOptions;
+
+export const filterBitriseBuilds = makeQueryFilter(
+  fieldsFromKeys(["branch", "commit_message", "triggered_workflow", "status_text"]),
+);

package/connectors/bitrise/src/server.ts

@@ -0,0 +1,83 @@
+import { z } from "zod";
+import { matchesResult } from "../../../shared/mcp-search-tool.ts";
+import { mcpJsonResult as jsonResult } from "../../../shared/mcp-tool-kit.ts";
+import { runReadOnlyMcpConnector } from "../../../shared/run-read-only-mcp-connector.ts";
+import { filterBitriseBuilds } from "./search-filter.ts";
+
+const BITRISE_API = "https://api.bitrise.io";
+
+function authHeader(): Record<string, string> {
+  const t = process.env["BITRISE_TOKEN"]?.trim();
+  if (t === undefined || t === "") {
+    throw new Error("BITRISE_TOKEN is not set");
+  }
+  return { Authorization: t, Accept: "application/json" };
+}
+
+async function bitriseGet(path: string): Promise<unknown> {
+  const res = await fetch(`${BITRISE_API}${path}`, { headers: authHeader() });
+  const text = await res.text();
+  if (!res.ok) {
+    throw new Error(`Bitrise ${String(res.status)}: ${text.slice(0, 400)}`);
+  }
+  return JSON.parse(text) as unknown;
+}
+
+await runReadOnlyMcpConnector("nimbus-bitrise", (reg) => {
+  reg(
+    "bitrise_list",
+    "List Bitrise resources. When `appSlug` is omitted, returns the user's accessible apps via `/v0.1/me/apps`. When `appSlug` is provided, returns the app's recent builds via `/v0.1/apps/<slug>/builds` (status filter and limit optional).",
+    z.object({
+      appSlug: z.string().min(1).optional(),
+      status: z.enum(["not-finished", "successful", "failed", "aborted"]).optional(),
+      limit: z.number().int().min(1).max(50).optional(),
+    }),
+    async (p) => {
+      if (p.appSlug === undefined) {
+        const limit = p.limit ?? 50;
+        return jsonResult(await bitriseGet(`/v0.1/me/apps?limit=${String(limit)}`));
+      }
+      const params: string[] = [];
+      params.push(`limit=${String(p.limit ?? 50)}`);
+      if (p.status !== undefined) {
+        const map = { "not-finished": 0, successful: 1, failed: 2, aborted: 3 } as const;
+        params.push(`status=${String(map[p.status])}`);
+      }
+      const qs = `?${params.join("&")}`;
+      return jsonResult(
+        await bitriseGet(`/v0.1/apps/${encodeURIComponent(p.appSlug)}/builds${qs}`),
+      );
+    },
+  );
+
+  reg(
+    "bitrise_get",
+    "Fetch a single Bitrise resource. When `buildSlug` is provided, returns the build via `/v0.1/apps/<appSlug>/builds/<buildSlug>`. When omitted, returns the app via `/v0.1/apps/<appSlug>`.",
+    z.object({
+      appSlug: z.string().min(1),
+      buildSlug: z.string().min(1).optional(),
+    }),
+    async (p) => {
+      if (p.buildSlug === undefined) {
+        return jsonResult(await bitriseGet(`/v0.1/apps/${encodeURIComponent(p.appSlug)}`));
+      }
+      const path = `/v0.1/apps/${encodeURIComponent(p.appSlug)}/builds/${encodeURIComponent(p.buildSlug)}`;
+      return jsonResult(await bitriseGet(path));
+    },
+  );
+
+  reg(
+    "bitrise_search",
+    "Substring search across a Bitrise app's recent builds. Matches the query against `branch`, `commit_message`, `triggered_workflow`, and `status_text` (case-insensitive). Returns a `{ matches: [...] }` envelope.",
+    z.object({
+      appSlug: z.string().min(1),
+      query: z.string().min(1),
+      limit: z.number().int().min(1).max(200).optional(),
+    }),
+    async (p) => {
+      const root = await bitriseGet(`/v0.1/apps/${encodeURIComponent(p.appSlug)}/builds?limit=50`);
+      const data = (root as { data?: unknown[] } | null)?.data;
+      return matchesResult(data, filterBitriseBuilds, p);
+    },
+  );
+});

package/connectors/canva/nimbus.extension.json

@@ -0,0 +1,15 @@
+{
+  "id": "com.nimbus.canva",
+  "displayName": "Canva",
+  "version": "0.1.0",
+  "description": "Canva connector (read-only). Surfaces the authenticated user's designs as canva:design items in the local index via GET /rest/v1/designs — the design title, the create timestamp, the last-modified timestamp, the edit url, the view url, and the thumbnail url. Bearer OAuth auth (Authorization: Bearer <token>; short-lived access token refreshed by the Gateway via the 3-legged OAuth authorization-code flow with PKCE; never logged); fixed SaaS host api.canva.com. The list endpoint paginates by the response continuation query param until absent; the gateway-side syncable walks a single forward pass per cycle, page-capped. Read-only — hitlRequired is intentionally empty. Sparse structured design metadata; the canonical url is the design view url.",
+  "author": "Nimbus",
+  "entrypoint": "dist/server.js",
+  "runtime": "bun",
+  "permissions": {
+    "network": ["api.canva.com"]
+  },
+  "hitlRequired": [],
+  "syncInterval": 600,
+  "minNimbusVersion": "0.2.0"
+}

package/connectors/canva/src/search-filter.ts

@@ -0,0 +1,23 @@
+import {
+  asObjectish,
+  makeQueryFilter,
+  type SearchMatchOptions,
+  stringField,
+} from "../../../shared/search-filter.ts";
+
+export type CanvaSearchMatchOptions = SearchMatchOptions;
+
+/**
+ * Canva design objects are flat — `{ id, title, urls: { edit_url, view_url },
+ * thumbnail: { url, ... }, ... }`. Designs carry no description or owner field,
+ * so match against the design title (case-insensitive substring).
+ */
+function fieldsOf(item: unknown): readonly string[] | null {
+  const row = asObjectish(item);
+  if (row === undefined) {
+    return null;
+  }
+  return [stringField(row, "title")];
+}
+
+export const filterCanvaDesigns = makeQueryFilter(fieldsOf);

package/connectors/canva/src/server.ts

@@ -0,0 +1,77 @@
+import { z } from "zod";
+import { searchToolInputSchema } from "../../../shared/mcp-search-tool.ts";
+import { mcpJsonResult as jsonResult } from "../../../shared/mcp-tool-kit.ts";
+import { runReadOnlyMcpConnector } from "../../../shared/run-read-only-mcp-connector.ts";
+import { filterCanvaDesigns } from "./search-filter.ts";
+
+const BASE = "https://api.canva.com";
+
+function apiToken(): string {
+  const t = process.env["CANVA_TOKEN"]?.trim();
+  if (t === undefined || t === "") {
+    throw new Error("CANVA_TOKEN is not set");
+  }
+  return t;
+}
+
+function authHeader(): Record<string, string> {
+  return { Authorization: `Bearer ${apiToken()}`, Accept: "application/json" };
+}
+
+async function canvaGet(path: string): Promise<unknown> {
+  const res = await fetch(`${BASE}${path}`, { headers: authHeader() });
+  const text = await res.text();
+  if (!res.ok) {
+    throw new Error(`Canva ${String(res.status)}: ${text.slice(0, 400)}`);
+  }
+  return JSON.parse(text) as unknown;
+}
+
+function designsFrom(root: unknown): unknown[] {
+  const items = (root as { items?: unknown } | null)?.items;
+  return Array.isArray(items) ? items : [];
+}
+
+await runReadOnlyMcpConnector("nimbus-canva", (reg) => {
+  reg(
+    "canva_list",
+    "List the authenticated user's Canva designs (GET /rest/v1/designs?continuation=<token>). Returns the { items: [...], continuation? } envelope — `items` holds the design objects, each shaped { id, title, created_at, updated_at, urls: { edit_url, view_url }, thumbnail: { url, width, height }, ... }; `continuation` (when present) is the opaque token for the next page.",
+    z.object({
+      continuation: z.string().optional(),
+    }),
+    async (p) => {
+      const params = new URLSearchParams();
+      if (p.continuation !== undefined && p.continuation !== "") {
+        params.set("continuation", p.continuation);
+      }
+      const qs = params.toString();
+      const query = qs === "" ? "" : `?${qs}`;
+      return jsonResult(await canvaGet(`/rest/v1/designs${query}`));
+    },
+  );
+
+  reg(
+    "canva_get",
+    "Fetch one Canva design by its id (GET /rest/v1/designs/{designId}). Returns the { design: { id, title, created_at, updated_at, urls, thumbnail, ... } } envelope. Throws when no design with that id exists.",
+    z.object({
+      id: z.string().min(1),
+    }),
+    async (p) => {
+      return jsonResult(await canvaGet(`/rest/v1/designs/${encodeURIComponent(p.id)}`));
+    },
+  );
+
+  reg(
+    "canva_search",
+    "**Substring search over the FIRST PAGE only** of the authenticated user's Canva designs. This tool fetches GET /rest/v1/designs once and matches the query locally (case-insensitive) against the design title. **Designs beyond the first page are not searchable here — query the local Nimbus index instead for full coverage.** Returns a { matches: [...] } envelope.",
+    searchToolInputSchema(100),
+    async (p) => {
+      const root = await canvaGet("/rest/v1/designs");
+      const matches = filterCanvaDesigns(designsFrom(root), {
+        query: p.query,
+        limit: p.limit,
+      });
+      return jsonResult({ matches });
+    },
+  );
+});

package/connectors/circleci/nimbus.extension.json

@@ -0,0 +1,15 @@
+{
+  "id": "com.nimbus.circleci",
+  "displayName": "CircleCI",
+  "version": "0.1.0",
+  "description": "CircleCI v2 connector (pipelines, workflows, jobs). Mutations require Gateway HITL.",
+  "author": "Nimbus",
+  "entrypoint": "dist/server.js",
+  "runtime": "bun",
+  "permissions": {
+    "network": ["circleci.com", "api.circleci.com"]
+  },
+  "hitlRequired": ["write", "delete"],
+  "syncInterval": 120,
+  "minNimbusVersion": "0.2.0"
+}

package/connectors/circleci/src/server.ts

@@ -0,0 +1,184 @@
+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 { makeRestToolRegistrar } from "../../../shared/rest-tool-kit.ts";
+
+const CCI_API = "https://circleci.com/api/v2";
+
+function projectPathSegments(projectSlug: string): string {
+  return projectSlug
+    .split("/")
+    .map((s) => s.trim())
+    .filter((s) => s.length > 0)
+    .map((s) => encodeURIComponent(s))
+    .join("/");
+}
+
+async function circleciFetch(
+  token: string,
+  path: string,
+  init?: RequestInit,
+): Promise<{ ok: boolean; status: number; json: unknown; text: string }> {
+  const url = path.startsWith("http") ? path : `${CCI_API}${path}`;
+  const res = await fetch(url, {
+    ...init,
+    headers: {
+      Accept: "application/json",
+      "Circle-Token": token,
+      ...(init?.headers as Record<string, string> | undefined),
+    },
+  });
+  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 mcp = new McpServer({ name: "nimbus-circleci", version: "0.1.0" });
+const reg = createZodToolRegistrar(createRegisterSimpleTool(mcp));
+
+/**
+ * Every MUTATING circleci 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: "circleci",
+  scopeEnv: "NIMBUS_MCP_CIRCLECI_WRITE_SCOPE",
+  scopeKinds: ["project"],
+});
+
+/** Standard CircleCI read tool: token → circleciFetch(buildPath) → mcpJsonResultIfOk("CircleCI"). */
+const registerCciTool = makeRestToolRegistrar({
+  registrar: reg,
+  tokenEnv: "CIRCLECI_API_TOKEN",
+  serviceLabel: "CircleCI",
+  fetch: circleciFetch,
+});
+
+const projectSlugSchema = z.object({
+  projectSlug: z
+    .string()
+    .min(3)
+    .describe("CircleCI project slug, e.g. gh/org/repo or bb/workspace/repo"),
+});
+
+registerCciTool(
+  "circleci_pipeline_list",
+  "List pipelines for a CircleCI project.",
+  projectSlugSchema.extend({
+    pageToken: z.string().min(1).optional(),
+  }),
+  (parsed) => {
+    const base = `/project/${projectPathSegments(parsed.projectSlug)}/pipeline`;
+    const u = new URL(`${CCI_API}${base}`);
+    if (parsed.pageToken !== undefined) {
+      u.searchParams.set("page-token", parsed.pageToken);
+    }
+    return `${u.pathname}${u.search}`;
+  },
+);
+
+registerCciTool(
+  "circleci_pipeline_get",
+  "Get a pipeline by UUID.",
+  z.object({ pipelineId: z.uuid() }),
+  (parsed) => `/pipeline/${encodeURIComponent(parsed.pipelineId)}`,
+);
+
+registerCciTool(
+  "circleci_workflow_list",
+  "List workflows for a pipeline.",
+  z.object({ pipelineId: z.uuid() }),
+  (parsed) => `/pipeline/${encodeURIComponent(parsed.pipelineId)}/workflow`,
+);
+
+registerCciTool(
+  "circleci_job_list",
+  "List jobs for a workflow.",
+  z.object({ workflowId: z.uuid() }),
+  (parsed) => `/workflow/${encodeURIComponent(parsed.workflowId)}/job`,
+);
+
+registerCciTool(
+  "circleci_job_artifacts",
+  "List artifact metadata for a job number under a project.",
+  projectSlugSchema.extend({
+    jobNumber: z.number().int().min(1),
+  }),
+  (parsed) =>
+    `/project/${projectPathSegments(parsed.projectSlug)}/job/${String(parsed.jobNumber)}/artifacts`,
+);
+
+registerWriteTool(
+  "circleci_pipeline_trigger",
+  {
+    mutates: "circleci.pipeline.trigger",
+    recoverable: true,
+    scopeTargetOf: (p) => ({ kind: "project", value: p.projectSlug }),
+  },
+  "Trigger a new pipeline on a branch (or tag).",
+  projectSlugSchema.extend({
+    branch: z.string().min(1).optional(),
+    tag: z.string().min(1).optional(),
+    parameters: z.record(z.string(), z.string()).optional(),
+  }),
+  async (parsed) => {
+    const token = requireProcessEnv("CIRCLECI_API_TOKEN");
+    const path = `/project/${projectPathSegments(parsed.projectSlug)}/pipeline`;
+    const body: Record<string, unknown> = {};
+    if (parsed.tag !== undefined && parsed.tag !== "") {
+      body["tag"] = parsed.tag;
+    } else {
+      body["branch"] = parsed.branch ?? "main";
+    }
+    if (parsed.parameters !== undefined && Object.keys(parsed.parameters).length > 0) {
+      body["parameters"] = parsed.parameters;
+    }
+    const res = await circleciFetch(token, path, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify(body),
+    });
+    if (!res.ok) {
+      throw new Error(`CircleCI trigger ${String(res.status)}: ${res.text.slice(0, 400)}`);
+    }
+    return jsonResult(res.json ?? { ok: true, raw: res.text });
+  },
+);
+
+registerWriteTool(
+  "circleci_job_cancel",
+  {
+    mutates: "circleci.job.cancel",
+    recoverable: true,
+    scopeTargetOf: (p) => ({ kind: "project", value: p.projectSlug }),
+  },
+  "Cancel a running job by project slug and job number.",
+  projectSlugSchema.extend({
+    jobNumber: z.number().int().min(1),
+  }),
+  async (parsed) => {
+    const token = requireProcessEnv("CIRCLECI_API_TOKEN");
+    const path = `/project/${projectPathSegments(parsed.projectSlug)}/job/${String(parsed.jobNumber)}/cancel`;
+    const res = await circleciFetch(token, path, { method: "POST" });
+    if (!res.ok) {
+      throw new Error(`CircleCI job cancel ${String(res.status)}: ${res.text.slice(0, 400)}`);
+    }
+    return jsonResult(res.json ?? { ok: true });
+  },
+);
+
+const transport = new StdioServerTransport();
+await mcp.connect(transport);