@nimbus-dev/connectors 0.2.0 → 0.2.2

package/connectors/circleci/src/server.ts

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

package/connectors/circleci/src/tools.ts

@@ -0,0 +1,193 @@
+import { z } from "zod";
+import type { ConsentServer } from "../../../shared/consent-kit.ts";
+import { createWriteToolRegistrar } from "../../../shared/consent-kit.ts";
+import {
+  createRegisterSimpleTool,
+  createZodToolRegistrar,
+  mcpJsonResult as jsonResult,
+  requireProcessEnv,
+} from "../../../shared/mcp-tool-kit.ts";
+import {
+  makeRestToolRegistrar,
+  type RestFetchResult,
+  toRestFetchResult,
+} 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<RestFetchResult> {
+  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),
+    },
+  });
+  return toRestFetchResult(res);
+}
+
+/** Tool names exposed by this connector — for contract/introspection tests. */
+export const CIRCLECI_TOOL_NAMES = [
+  "circleci_pipeline_list",
+  "circleci_pipeline_get",
+  "circleci_workflow_list",
+  "circleci_job_list",
+  "circleci_job_artifacts",
+  "circleci_pipeline_trigger",
+  "circleci_job_cancel",
+] as const;
+
+export function registerCircleciTools(
+  server: ConsentServer & { tool: (...args: never) => unknown },
+): void {
+  const reg = createZodToolRegistrar(createRegisterSimpleTool(server));
+
+  /**
+   * 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(server, {
+    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);
+      }
+      // Relative to CCI_API, like every other tool here: the fetcher prefixes the base, which
+      // already ends in /api/v2, so returning `u.pathname` requested /api/v2/api/v2/….
+      return `${base}${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 });
+    },
+  );
+}

package/connectors/cloud-logging/src/tools.ts

@@ -1,4 +1,10 @@
 import { z } from "zod";
+import {
+  createCliJsonRunner,
+  gcloudProjectArgs,
+  isRecord,
+  strField,
+} from "../../../shared/cli-json-kit.ts";
 import { mcpJsonResult as jsonResult } from "../../../shared/mcp-tool-kit.ts";
 import { nimbusSpawn } from "../../../shared/nimbus-spawn.ts";
 import type { ZodToolRegistrar } from "../../../shared/run-read-only-mcp-connector.ts";
@@ -20,42 +26,23 @@ export const CLOUD_LOGGING_TOOL_NAMES = [
   "cloud_logging_search",
 ] as const;
 
-function isRecord(v: unknown): v is Record<string, unknown> {
-  return v !== null && typeof v === "object" && !Array.isArray(v);
-}
-
-function strField(r: Record<string, unknown>, key: string): string {
-  const v = r[key];
-  return typeof v === "string" ? v : "";
-}
-
 function asArray(parsed: unknown): unknown[] {
   return Array.isArray(parsed) ? parsed : [];
 }
 
-/** The configured GCP project id, if `GOOGLE_CLOUD_PROJECT` is set at spawn. */
-function projectArgs(): string[] {
-  const project = process.env["GOOGLE_CLOUD_PROJECT"]?.trim();
-  return project !== undefined && project !== "" ? ["--project", project] : [];
-}
-
 /**
  * Run `gcloud logging <args> --format json` and parse stdout. gcloud reads
  * Application Default Credentials from `GOOGLE_APPLICATION_CREDENTIALS`
  * natively from the process env injected at spawn time. Throws on non-zero exit.
  */
-async function gcloudLogging(args: string[]): Promise<unknown> {
-  const { code, stdout, stderr } = await nimbusSpawn(
-    ["gcloud", "logging", ...args, ...projectArgs(), "--format", "json"],
-    {},
-  );
-  const out = stdout.trim();
-  const err = stderr.trim();
-  if (code !== 0) {
-    throw new Error(`gcloud logging ${args[0] ?? ""} failed: ${err.slice(0, 400)}`);
-  }
-  return out === "" ? [] : (JSON.parse(out) as unknown);
-}
+const gcloudLogging = createCliJsonRunner(
+  {
+    argv: (args) => ["gcloud", "logging", ...args, ...gcloudProjectArgs(), "--format", "json"],
+    label: "gcloud logging",
+    emptyResult: [],
+  },
+  nimbusSpawn,
+);
 
 function sinkMatches(entry: unknown, q: string): boolean {
   if (!isRecord(entry)) {

package/connectors/cloudwatch/src/tools.ts

@@ -1,18 +1,20 @@
 import { z } from "zod";
+import {
+  asArray,
+  cliArg,
+  createCliJsonRunner,
+  isRecord,
+  strField,
+} from "../../../shared/cli-json-kit.ts";
 import { mcpJsonResult as jsonResult } from "../../../shared/mcp-tool-kit.ts";
 import { nimbusSpawn } from "../../../shared/nimbus-spawn.ts";
 import type { ZodToolRegistrar } from "../../../shared/run-read-only-mcp-connector.ts";
-import { isSafeCliArg } from "../../../shared/safe-cli-arg.ts";
 
 /**
  * A log-group name / prefix passed as a value to the `aws logs` CLI. Rejected at
  * the schema boundary if it begins with `-` (argv flag smuggling) or contains
  * control characters.
  */
-const cliArg = z
-  .string()
-  .min(1)
-  .refine(isSafeCliArg, { message: 'must not start with "-" or contain control characters' });
 
 /**
  * Amazon CloudWatch Logs (Tier-3, no-row-data) MCP tool surface. ALL tools
@@ -32,40 +34,19 @@ export const CLOUDWATCH_TOOL_NAMES = [
 
 const LIMIT = "50";
 
-function isRecord(v: unknown): v is Record<string, unknown> {
-  return v !== null && typeof v === "object" && !Array.isArray(v);
-}
-
-function strField(r: Record<string, unknown>, key: string): string {
-  const v = r[key];
-  return typeof v === "string" ? v : "";
-}
-
-function asArray(parsed: unknown, key: string): unknown[] {
-  if (!isRecord(parsed)) {
-    return [];
-  }
-  const arr = parsed[key];
-  return Array.isArray(arr) ? arr : [];
-}
-
 /**
  * Run `aws logs <args> --output json` and parse stdout. The AWS CLI reads
  * AWS_ACCESS_KEY_ID / AWS_SECRET_ACCESS_KEY / AWS_DEFAULT_REGION / AWS_PROFILE
  * natively from the process env injected at spawn time. Throws on non-zero exit.
  */
-async function logsCli(args: string[]): Promise<unknown> {
-  const { code, stdout, stderr } = await nimbusSpawn(
-    ["aws", "logs", ...args, "--output", "json"],
-    {},
-  );
-  const out = stdout.trim();
-  const err = stderr.trim();
-  if (code !== 0) {
-    throw new Error(`aws logs ${args[0] ?? ""} failed: ${err.slice(0, 400)}`);
-  }
-  return out === "" ? {} : (JSON.parse(out) as unknown);
-}
+const logsCli = createCliJsonRunner(
+  {
+    argv: (args) => ["aws", "logs", ...args, "--output", "json"],
+    label: "aws logs",
+    emptyResult: {},
+  },
+  nimbusSpawn,
+);
 
 function groupMatches(entry: unknown, q: string): boolean {
   if (!isRecord(entry)) {

package/connectors/codemagic/src/server.ts

@@ -1,74 +1,6 @@
-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 { filterCodemagicBuilds } from "./search-filter.ts";
-
-const CODEMAGIC_API = "https://api.codemagic.io";
-
-function authHeader(): Record<string, string> {
-  const t = process.env["CODEMAGIC_TOKEN"]?.trim();
-  if (t === undefined || t === "") {
-    throw new Error("CODEMAGIC_TOKEN is not set");
-  }
-  return { "x-auth-token": t, Accept: "application/json" };
-}
-
-async function codemagicGet(path: string): Promise<unknown> {
-  const res = await fetch(`${CODEMAGIC_API}${path}`, { headers: authHeader() });
-  const text = await res.text();
-  if (!res.ok) {
-    throw new Error(`Codemagic ${String(res.status)}: ${text.slice(0, 400)}`);
-  }
-  return JSON.parse(text) as unknown;
-}
+import { registerCodemagicTools } from "./tools.ts";
 
 await runReadOnlyMcpConnector("nimbus-codemagic", (reg) => {
-  reg(
-    "codemagic_list",
-    "List Codemagic resources. When `appId` is omitted, returns the user's accessible apps via `/apps`. When `appId` is provided, returns the app's recent builds via `/builds?appId=<id>` (limit optional).",
-    z.object({
-      appId: z.string().min(1).optional(),
-      limit: z.number().int().min(1).max(50).optional(),
-    }),
-    async (p) => {
-      if (p.appId === undefined) {
-        return jsonResult(await codemagicGet("/apps"));
-      }
-      const limit = p.limit ?? 50;
-      return jsonResult(
-        await codemagicGet(`/builds?appId=${encodeURIComponent(p.appId)}&limit=${String(limit)}`),
-      );
-    },
-  );
-
-  reg(
-    "codemagic_get",
-    "Fetch a single Codemagic resource. When `buildId` is provided, returns the build via `/builds/<buildId>`. When omitted, returns the app via `/apps` filtered to `appId`.",
-    z.object({
-      appId: z.string().min(1),
-      buildId: z.string().min(1).optional(),
-    }),
-    async (p) => {
-      if (p.buildId === undefined) {
-        return jsonResult(await codemagicGet("/apps"));
-      }
-      return jsonResult(await codemagicGet(`/builds/${encodeURIComponent(p.buildId)}`));
-    },
-  );
-
-  reg(
-    "codemagic_search",
-    "Substring search across a Codemagic app's recent builds. Matches the query against `branch`, `message`, `workflowId`, and `status` (case-insensitive). Returns a `{ matches: [...] }` envelope.",
-    z.object({
-      appId: z.string().min(1),
-      query: z.string().min(1),
-      limit: z.number().int().min(1).max(200).optional(),
-    }),
-    async (p) => {
-      const root = await codemagicGet(`/builds?appId=${encodeURIComponent(p.appId)}&limit=50`);
-      const builds = (root as { builds?: unknown[] } | null)?.builds;
-      return matchesResult(builds, filterCodemagicBuilds, p);
-    },
-  );
+  registerCodemagicTools(reg);
 });

package/connectors/codemagic/src/tools.ts

@@ -0,0 +1,71 @@
+import { z } from "zod";
+import { createJsonGetter, envAuthHeaders } from "../../../shared/env-json-api.ts";
+import { matchesResult } from "../../../shared/mcp-search-tool.ts";
+import { mcpJsonResult as jsonResult } from "../../../shared/mcp-tool-kit.ts";
+import type { ZodToolRegistrar } from "../../../shared/run-read-only-mcp-connector.ts";
+import { filterCodemagicBuilds } from "./search-filter.ts";
+
+const CODEMAGIC_API = "https://api.codemagic.io";
+
+const codemagicGet = createJsonGetter({
+  base: CODEMAGIC_API,
+  label: "Codemagic",
+  headers: envAuthHeaders({ env: "CODEMAGIC_TOKEN", scheme: "", header: "x-auth-token" }),
+});
+
+/** Tool names exposed by this connector — for contract/introspection tests. */
+export const CODEMAGIC_TOOL_NAMES = [
+  "codemagic_list",
+  "codemagic_get",
+  "codemagic_search",
+] as const;
+
+export function registerCodemagicTools(reg: ZodToolRegistrar): void {
+  reg(
+    "codemagic_list",
+    "List Codemagic resources. When `appId` is omitted, returns the user's accessible apps via `/apps`. When `appId` is provided, returns the app's recent builds via `/builds?appId=<id>` (limit optional).",
+    z.object({
+      appId: z.string().min(1).optional(),
+      limit: z.number().int().min(1).max(50).optional(),
+    }),
+    async (p) => {
+      if (p.appId === undefined) {
+        return jsonResult(await codemagicGet("/apps"));
+      }
+      const limit = p.limit ?? 50;
+      return jsonResult(
+        await codemagicGet(`/builds?appId=${encodeURIComponent(p.appId)}&limit=${String(limit)}`),
+      );
+    },
+  );
+
+  reg(
+    "codemagic_get",
+    "Fetch a single Codemagic resource. When `buildId` is provided, returns the build via `/builds/<buildId>`. When omitted, returns the app via `/apps` filtered to `appId`.",
+    z.object({
+      appId: z.string().min(1),
+      buildId: z.string().min(1).optional(),
+    }),
+    async (p) => {
+      if (p.buildId === undefined) {
+        return jsonResult(await codemagicGet("/apps"));
+      }
+      return jsonResult(await codemagicGet(`/builds/${encodeURIComponent(p.buildId)}`));
+    },
+  );
+
+  reg(
+    "codemagic_search",
+    "Substring search across a Codemagic app's recent builds. Matches the query against `branch`, `message`, `workflowId`, and `status` (case-insensitive). Returns a `{ matches: [...] }` envelope.",
+    z.object({
+      appId: z.string().min(1),
+      query: z.string().min(1),
+      limit: z.number().int().min(1).max(200).optional(),
+    }),
+    async (p) => {
+      const root = await codemagicGet(`/builds?appId=${encodeURIComponent(p.appId)}&limit=50`);
+      const builds = (root as { builds?: unknown[] } | null)?.builds;
+      return matchesResult(builds, filterCodemagicBuilds, p);
+    },
+  );
+}