@nimbus-dev/connectors 0.2.1 → 0.2.2

package/connectors/snyk/src/tools.ts

@@ -0,0 +1,136 @@
+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 { filterSnykAggregatedIssues } from "./search-filter.ts";
+
+const SNYK_API = "https://api.snyk.io";
+
+/** Snyk wants the lowercase `token` scheme. Shared with `snykPost` below. */
+const authHeader = envAuthHeaders({ env: "SNYK_TOKEN", scheme: "token" });
+
+const snykGet = createJsonGetter({
+  base: SNYK_API,
+  label: "Snyk",
+  headers: authHeader,
+});
+
+async function snykPost(path: string, body: unknown): Promise<unknown> {
+  const res = await fetch(`${SNYK_API}${path}`, {
+    method: "POST",
+    headers: { ...authHeader(), "Content-Type": "application/json" },
+    body: JSON.stringify(body),
+  });
+  const text = await res.text();
+  if (!res.ok) {
+    throw new Error(`Snyk ${String(res.status)}: ${text.slice(0, 400)}`);
+  }
+  if (text.trim() === "") {
+    return {};
+  }
+  return JSON.parse(text) as unknown;
+}
+
+/** Every severity Snyk reports: `snyk_list`'s default filter, and the one get/search always use. */
+const ALL_SEVERITIES: readonly string[] = ["critical", "high", "medium", "low"];
+
+/**
+ * One project's aggregated issues (`POST …/aggregated-issues`): vulnerability and licence issues
+ * of the given severities that are neither ignored nor patched.
+ */
+async function aggregatedIssues(
+  orgId: string,
+  projectId: string,
+  severities: readonly string[] = ALL_SEVERITIES,
+): Promise<unknown> {
+  const body = {
+    filters: {
+      severities,
+      types: ["vuln", "license"],
+      ignored: false,
+      patched: false,
+    },
+  };
+  const path = `/v1/org/${encodeURIComponent(orgId)}/project/${encodeURIComponent(projectId)}/aggregated-issues`;
+  return snykPost(path, body);
+}
+
+/** Tool names exposed by this connector — for contract/introspection tests. */
+export const SNYK_TOOL_NAMES = ["snyk_get", "snyk_list", "snyk_search"] as const;
+
+export function registerSnykTools(reg: ZodToolRegistrar): void {
+  reg(
+    "snyk_list",
+    "List Snyk projects for an org, or aggregated issues for a project. When projectId is omitted, returns the org's project list. Severities default to all four (critical/high/medium/low).",
+    z.object({
+      orgId: z.string().min(1),
+      projectId: z.string().min(1).optional(),
+      severities: z
+        .array(z.enum(["critical", "high", "medium", "low"]))
+        .min(1)
+        .optional(),
+      limit: z.number().int().min(1).max(1000).optional(),
+    }),
+    async (p) => {
+      if (p.projectId === undefined) {
+        return jsonResult(await snykGet(`/v1/org/${encodeURIComponent(p.orgId)}/projects`));
+      }
+      const data = await aggregatedIssues(p.orgId, p.projectId, p.severities);
+      if (p.limit !== undefined && data !== null && typeof data === "object") {
+        const issues = (data as { issues?: unknown[] }).issues;
+        if (Array.isArray(issues) && issues.length > p.limit) {
+          return jsonResult({
+            ...(data as Record<string, unknown>),
+            issues: issues.slice(0, p.limit),
+          });
+        }
+      }
+      return jsonResult(data);
+    },
+  );
+
+  reg(
+    "snyk_get",
+    "Fetch one Snyk issue by id from an org + project. Returns the aggregated-issue envelope for the matching `issue.id`; throws when no match is found.",
+    z.object({
+      orgId: z.string().min(1),
+      projectId: z.string().min(1),
+      issueId: z.string().min(1),
+    }),
+    async (p) => {
+      const root = await aggregatedIssues(p.orgId, p.projectId);
+      const issues = (root as { issues?: unknown[] } | null)?.issues;
+      if (!Array.isArray(issues)) {
+        throw new TypeError(`Snyk: project ${p.projectId} returned no issues envelope`);
+      }
+      const match = issues.find((it) => {
+        if (it === null || typeof it !== "object") {
+          return false;
+        }
+        const id = (it as { id?: unknown }).id;
+        return typeof id === "string" && id === p.issueId;
+      });
+      if (match === undefined) {
+        throw new Error(`Snyk: issue ${p.issueId} not found in project ${p.projectId}`);
+      }
+      return jsonResult(match);
+    },
+  );
+
+  reg(
+    "snyk_search",
+    "Substring search across a project's aggregated issues. Matches the query against `issueData.title`, `issueData.cve`, and `pkgName` (case-insensitive). Returns a `{ matches: [...] }` envelope.",
+    z.object({
+      orgId: z.string().min(1),
+      projectId: z.string().min(1),
+      query: z.string().min(1),
+      limit: z.number().int().min(1).max(200).optional(),
+    }),
+    async (p) => {
+      const root = await aggregatedIssues(p.orgId, p.projectId);
+      const issues = (root as { issues?: unknown[] } | null)?.issues;
+      return matchesResult(issues, filterSnykAggregatedIssues, p);
+    },
+  );
+}

package/connectors/sonarqube/src/server.ts

@@ -1,115 +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 { filterSonarIssues } from "./search-filter.ts";
-
-const DEFAULT_API = "https://sonarcloud.io";
-const ISSUE_TYPES = ["BUG", "VULNERABILITY", "CODE_SMELL"] as const;
-const OPEN_STATUSES = ["OPEN", "CONFIRMED", "REOPENED"] as const;
-
-function stripTrailingSlashes(s: string): string {
-  let end = s.length;
-  while (end > 0 && s.codePointAt(end - 1) === 47) end -= 1;
-  return s.slice(0, end);
-}
-
-function apiBase(): string {
-  const raw = process.env["SONARQUBE_URL"]?.trim();
-  if (raw === undefined || raw === "") {
-    return DEFAULT_API;
-  }
-  return stripTrailingSlashes(raw);
-}
-
-function authHeader(): Record<string, string> {
-  const t = process.env["SONARQUBE_TOKEN"]?.trim();
-  if (t === undefined || t === "") {
-    throw new Error("SONARQUBE_TOKEN is not set");
-  }
-  return { Authorization: `Bearer ${t}`, Accept: "application/json" };
-}
-
-async function sonarGet(path: string): Promise<unknown> {
-  const res = await fetch(`${apiBase()}${path}`, { headers: authHeader() });
-  const text = await res.text();
-  if (!res.ok) {
-    throw new Error(`SonarQube ${String(res.status)}: ${text.slice(0, 400)}`);
-  }
-  return JSON.parse(text) as unknown;
-}
+import { registerSonarqubeTools } from "./tools.ts";
 
 await runReadOnlyMcpConnector("nimbus-sonarqube", (reg) => {
-  reg(
-    "sonarqube_list",
-    "List SonarQube projects, or issues for a project. When projectKey is omitted, returns the project list (SonarCloud requires `SONARQUBE_ORGANIZATION` env; self-hosted ignores it). When projectKey is provided, returns open issues (status OPEN/CONFIRMED/REOPENED) for that project.",
-    z.object({
-      projectKey: z.string().min(1).optional(),
-      types: z.array(z.enum(ISSUE_TYPES)).min(1).optional(),
-      severities: z
-        .array(z.enum(["BLOCKER", "CRITICAL", "MAJOR", "MINOR", "INFO"]))
-        .min(1)
-        .optional(),
-      limit: z.number().int().min(1).max(500).optional(),
-    }),
-    async (p) => {
-      if (p.projectKey === undefined) {
-        const org = process.env["SONARQUBE_ORGANIZATION"]?.trim();
-        const search = new URLSearchParams({ qualifiers: "TRK", ps: "100" });
-        if (org !== undefined && org !== "") {
-          search.set("organization", org);
-        }
-        return jsonResult(await sonarGet(`/api/components/search?${search.toString()}`));
-      }
-      const types = p.types ?? ISSUE_TYPES;
-      const search = new URLSearchParams({
-        componentKeys: p.projectKey,
-        types: types.join(","),
-        statuses: OPEN_STATUSES.join(","),
-        ps: String(p.limit ?? 100),
-      });
-      if (p.severities !== undefined && p.severities.length > 0) {
-        search.set("severities", p.severities.join(","));
-      }
-      return jsonResult(await sonarGet(`/api/issues/search?${search.toString()}`));
-    },
-  );
-
-  reg(
-    "sonarqube_get",
-    "Fetch one SonarQube issue by key. Returns the matching issue envelope from `/api/issues/search?issues=<key>`; throws when no match is found.",
-    z.object({
-      issueKey: z.string().min(1),
-    }),
-    async (p) => {
-      const search = new URLSearchParams({ issues: p.issueKey, ps: "1" });
-      const root = await sonarGet(`/api/issues/search?${search.toString()}`);
-      const issues = (root as { issues?: unknown[] } | null)?.issues;
-      if (!Array.isArray(issues) || issues.length === 0) {
-        throw new Error(`SonarQube: issue ${p.issueKey} not found`);
-      }
-      return jsonResult(issues[0]);
-    },
-  );
-
-  reg(
-    "sonarqube_search",
-    "Substring search across a project's open issues. Matches the query against `message`, `rule`, `component`, and `tags` (case-insensitive). Returns a `{ matches: [...] }` envelope.",
-    z.object({
-      projectKey: z.string().min(1),
-      query: z.string().min(1),
-      limit: z.number().int().min(1).max(200).optional(),
-    }),
-    async (p) => {
-      const search = new URLSearchParams({
-        componentKeys: p.projectKey,
-        types: ISSUE_TYPES.join(","),
-        statuses: OPEN_STATUSES.join(","),
-        ps: "500",
-      });
-      const root = await sonarGet(`/api/issues/search?${search.toString()}`);
-      const issues = (root as { issues?: unknown[] } | null)?.issues;
-      return matchesResult(issues, filterSonarIssues, p);
-    },
-  );
+  registerSonarqubeTools(reg);
 });

package/connectors/sonarqube/src/tools.ts

@@ -0,0 +1,98 @@
+import { z } from "zod";
+import { createJsonGetter, envAuthHeaders, optionalBaseUrl } 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 { filterSonarIssues } from "./search-filter.ts";
+
+const DEFAULT_API = "https://sonarcloud.io";
+const ISSUE_TYPES = ["BUG", "VULNERABILITY", "CODE_SMELL"] as const;
+const OPEN_STATUSES = ["OPEN", "CONFIRMED", "REOPENED"] as const;
+
+const sonarGet = createJsonGetter({
+  base: () => optionalBaseUrl("SONARQUBE_URL", DEFAULT_API),
+  label: "SonarQube",
+  headers: envAuthHeaders({ env: "SONARQUBE_TOKEN" }),
+});
+
+/** Tool names exposed by this connector — for contract/introspection tests. */
+export const SONARQUBE_TOOL_NAMES = [
+  "sonarqube_list",
+  "sonarqube_get",
+  "sonarqube_search",
+] as const;
+
+export function registerSonarqubeTools(reg: ZodToolRegistrar): void {
+  reg(
+    "sonarqube_list",
+    "List SonarQube projects, or issues for a project. When projectKey is omitted, returns the project list (SonarCloud requires `SONARQUBE_ORGANIZATION` env; self-hosted ignores it). When projectKey is provided, returns open issues (status OPEN/CONFIRMED/REOPENED) for that project.",
+    z.object({
+      projectKey: z.string().min(1).optional(),
+      types: z.array(z.enum(ISSUE_TYPES)).min(1).optional(),
+      severities: z
+        .array(z.enum(["BLOCKER", "CRITICAL", "MAJOR", "MINOR", "INFO"]))
+        .min(1)
+        .optional(),
+      limit: z.number().int().min(1).max(500).optional(),
+    }),
+    async (p) => {
+      if (p.projectKey === undefined) {
+        const org = process.env["SONARQUBE_ORGANIZATION"]?.trim();
+        const search = new URLSearchParams({ qualifiers: "TRK", ps: "100" });
+        if (org !== undefined && org !== "") {
+          search.set("organization", org);
+        }
+        return jsonResult(await sonarGet(`/api/components/search?${search.toString()}`));
+      }
+      const types = p.types ?? ISSUE_TYPES;
+      const search = new URLSearchParams({
+        componentKeys: p.projectKey,
+        types: types.join(","),
+        statuses: OPEN_STATUSES.join(","),
+        ps: String(p.limit ?? 100),
+      });
+      if (p.severities !== undefined && p.severities.length > 0) {
+        search.set("severities", p.severities.join(","));
+      }
+      return jsonResult(await sonarGet(`/api/issues/search?${search.toString()}`));
+    },
+  );
+
+  reg(
+    "sonarqube_get",
+    "Fetch one SonarQube issue by key. Returns the matching issue envelope from `/api/issues/search?issues=<key>`; throws when no match is found.",
+    z.object({
+      issueKey: z.string().min(1),
+    }),
+    async (p) => {
+      const search = new URLSearchParams({ issues: p.issueKey, ps: "1" });
+      const root = await sonarGet(`/api/issues/search?${search.toString()}`);
+      const issues = (root as { issues?: unknown[] } | null)?.issues;
+      if (!Array.isArray(issues) || issues.length === 0) {
+        throw new Error(`SonarQube: issue ${p.issueKey} not found`);
+      }
+      return jsonResult(issues[0]);
+    },
+  );
+
+  reg(
+    "sonarqube_search",
+    "Substring search across a project's open issues. Matches the query against `message`, `rule`, `component`, and `tags` (case-insensitive). Returns a `{ matches: [...] }` envelope.",
+    z.object({
+      projectKey: z.string().min(1),
+      query: z.string().min(1),
+      limit: z.number().int().min(1).max(200).optional(),
+    }),
+    async (p) => {
+      const search = new URLSearchParams({
+        componentKeys: p.projectKey,
+        types: ISSUE_TYPES.join(","),
+        statuses: OPEN_STATUSES.join(","),
+        ps: "500",
+      });
+      const root = await sonarGet(`/api/issues/search?${search.toString()}`);
+      const issues = (root as { issues?: unknown[] } | null)?.issues;
+      return matchesResult(issues, filterSonarIssues, p);
+    },
+  );
+}

package/connectors/stackoverflow/src/server.ts

@@ -1,81 +1,6 @@
-import { z } from "zod";
-import { matchesResult, 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 { filterStackOverflowQuestions } from "./search-filter.ts";
-
-const BASE = "https://api.stackoverflowteams.com";
-
-function apiToken(): string {
-  const t = process.env["STACKOVERFLOW_TOKEN"]?.trim();
-  if (t === undefined || t === "") {
-    throw new Error("STACKOVERFLOW_TOKEN is not set");
-  }
-  return t;
-}
-
-function teamSlug(): string {
-  const t = process.env["STACKOVERFLOW_TEAM"]?.trim();
-  if (t === undefined || t === "") {
-    throw new Error("STACKOVERFLOW_TEAM is not set");
-  }
-  return t;
-}
-
-function authHeader(): Record<string, string> {
-  return { Authorization: `Bearer ${apiToken()}`, Accept: "application/json" };
-}
-
-async function stackOverflowGet(path: string): Promise<unknown> {
-  const res = await fetch(`${BASE}${path}`, { headers: authHeader() });
-  const text = await res.text();
-  if (!res.ok) {
-    throw new Error(`Stack Overflow ${String(res.status)}: ${text.slice(0, 400)}`);
-  }
-  return JSON.parse(text) as unknown;
-}
-
-function questionsBasePath(): string {
-  return `/v3/teams/${encodeURIComponent(teamSlug())}/questions`;
-}
+import { registerStackoverflowTools } from "./tools.ts";
 
 await runReadOnlyMcpConnector("nimbus-stackoverflow", (reg) => {
-  reg(
-    "stackoverflow_list",
-    "List the team's Stack Overflow for Teams questions (`GET /v3/teams/<team>/questions?page=1&pagesize=100&sort=creation&order=desc`). Returns the `{ items: [...], totalCount, pageSize, page, totalPages, sort, order }` envelope — `items` holds the question objects.",
-    z.object({}),
-    async () => {
-      return jsonResult(
-        await stackOverflowGet(
-          `${questionsBasePath()}?page=1&pagesize=100&sort=creation&order=desc`,
-        ),
-      );
-    },
-  );
-
-  reg(
-    "stackoverflow_get",
-    "Fetch one Stack Overflow for Teams question by its id (`GET /v3/teams/<team>/questions/{id}`). Returns the question object directly (NOT wrapped in an `{ items }` envelope). Throws when no match is found.",
-    z.object({
-      id: z.string().min(1),
-    }),
-    async (p) => {
-      return jsonResult(
-        await stackOverflowGet(`${questionsBasePath()}/${encodeURIComponent(p.id)}`),
-      );
-    },
-  );
-
-  reg(
-    "stackoverflow_search",
-    "Substring search across the team's Stack Overflow for Teams questions (first page only). Matches the query against the question title, body, tags, and the asking user's name (case-insensitive). Returns a `{ matches: [...] }` envelope.",
-    searchToolInputSchema(100),
-    async (p) => {
-      const root = await stackOverflowGet(
-        `${questionsBasePath()}?page=1&pagesize=100&sort=creation&order=desc`,
-      );
-      const items = (root as { items?: unknown[] } | null)?.items;
-      return matchesResult(items, filterStackOverflowQuestions, p);
-    },
-  );
+  registerStackoverflowTools(reg);
 });

package/connectors/stackoverflow/src/tools.ts

@@ -0,0 +1,66 @@
+import { z } from "zod";
+import { createJsonGetter, envAuthHeaders, requiredEnv } from "../../../shared/env-json-api.ts";
+import { matchesResult, searchToolInputSchema } 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 { filterStackOverflowQuestions } from "./search-filter.ts";
+
+const BASE = "https://api.stackoverflowteams.com";
+
+const stackOverflowGet = createJsonGetter({
+  base: BASE,
+  label: "Stack Overflow",
+  headers: envAuthHeaders({ env: "STACKOVERFLOW_TOKEN" }),
+});
+
+function questionsBasePath(): string {
+  return `/v3/teams/${encodeURIComponent(requiredEnv("STACKOVERFLOW_TEAM"))}/questions`;
+}
+
+/** Tool names exposed by this connector — for contract/introspection tests. */
+export const STACKOVERFLOW_TOOL_NAMES = [
+  "stackoverflow_list",
+  "stackoverflow_get",
+  "stackoverflow_search",
+] as const;
+
+export function registerStackoverflowTools(reg: ZodToolRegistrar): void {
+  reg(
+    "stackoverflow_list",
+    "List the team's Stack Overflow for Teams questions (`GET /v3/teams/<team>/questions?page=1&pagesize=100&sort=creation&order=desc`). Returns the `{ items: [...], totalCount, pageSize, page, totalPages, sort, order }` envelope — `items` holds the question objects.",
+    z.object({}),
+    async () => {
+      return jsonResult(
+        await stackOverflowGet(
+          `${questionsBasePath()}?page=1&pagesize=100&sort=creation&order=desc`,
+        ),
+      );
+    },
+  );
+
+  reg(
+    "stackoverflow_get",
+    "Fetch one Stack Overflow for Teams question by its id (`GET /v3/teams/<team>/questions/{id}`). Returns the question object directly (NOT wrapped in an `{ items }` envelope). Throws when no match is found.",
+    z.object({
+      id: z.string().min(1),
+    }),
+    async (p) => {
+      return jsonResult(
+        await stackOverflowGet(`${questionsBasePath()}/${encodeURIComponent(p.id)}`),
+      );
+    },
+  );
+
+  reg(
+    "stackoverflow_search",
+    "Substring search across the team's Stack Overflow for Teams questions (first page only). Matches the query against the question title, body, tags, and the asking user's name (case-insensitive). Returns a `{ matches: [...] }` envelope.",
+    searchToolInputSchema(100),
+    async (p) => {
+      const root = await stackOverflowGet(
+        `${questionsBasePath()}?page=1&pagesize=100&sort=creation&order=desc`,
+      );
+      const items = (root as { items?: unknown[] } | null)?.items;
+      return matchesResult(items, filterStackOverflowQuestions, p);
+    },
+  );
+}

package/connectors/storybook/src/storybook-parse.ts

@@ -1,6 +1,7 @@
 import { readFile } from "node:fs/promises";
 import { join, resolve } from "node:path";
 import { parseStorybookIndex, type StorybookStory } from "@nimbus-dev/sdk";
+import { requiredEnv } from "../../../shared/env-json-api.ts";
 
 export type { StorybookStory };
 export { parseStorybookIndex };
@@ -23,17 +24,13 @@ const MANIFEST_NAMES = ["index.json", "stories.json"] as const;
  * the MCP tools surface a clear error rather than reading an empty path.
  */
 export function storybookDir(): string {
-  const dir = process.env["STORYBOOK_DIR"]?.trim();
-  if (dir === undefined || dir === "") {
-    throw new Error("STORYBOOK_DIR is not set");
-  }
-  return resolve(dir);
+  return resolve(requiredEnv("STORYBOOK_DIR"));
 }
 
 async function readManifest(root: string): Promise<unknown> {
   for (const name of MANIFEST_NAMES) {
     try {
-      const buf = await readFile(join(root, name));
+      const buf = await readFile(join(root, name)); // NOSONAR S9382: a fallback chain, not independent reads — stories.json is read only when index.json cannot be read or parsed, and index.json must win when both exist.
       if (buf.byteLength > MAX_FILE_BYTES) {
         return null;
       }

package/connectors/stripe/src/server.ts

@@ -1,65 +1,6 @@
-import { z } from "zod";
-import { matchesResult, 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 { filterStripeInvoices } from "./search-filter.ts";
-
-const BASE = "https://api.stripe.com";
-
-function apiKey(): string {
-  const t = process.env["STRIPE_API_KEY"]?.trim();
-  if (t === undefined || t === "") {
-    throw new Error("STRIPE_API_KEY is not set");
-  }
-  return t;
-}
-
-function authHeader(): Record<string, string> {
-  return { Authorization: `Bearer ${apiKey()}`, Accept: "application/json" };
-}
-
-async function stripeGet(path: string): Promise<unknown> {
-  const res = await fetch(`${BASE}${path}`, { headers: authHeader() });
-  const text = await res.text();
-  if (!res.ok) {
-    throw new Error(`Stripe ${String(res.status)}: ${text.slice(0, 400)}`);
-  }
-  return JSON.parse(text) as unknown;
-}
+import { registerStripeTools } from "./tools.ts";
 
 await runReadOnlyMcpConnector("nimbus-stripe", (reg) => {
-  reg(
-    "stripe_list",
-    "List recent Stripe invoices (`GET /v1/invoices`), most-recent-first, capped at `limit` (default 100). Returns the `{ object: 'list', data, has_more }` envelope.",
-    z.object({
-      limit: z.number().int().min(1).max(100).optional(),
-    }),
-    async (p) => {
-      const search = new URLSearchParams({ limit: String(p.limit ?? 100) });
-      return jsonResult(await stripeGet(`/v1/invoices?${search.toString()}`));
-    },
-  );
-
-  reg(
-    "stripe_get",
-    "Fetch one Stripe invoice by its id (`GET /v1/invoices/{id}`, e.g. `in_1A2b...`). Returns the invoice object directly. Throws when no match is found.",
-    z.object({
-      id: z.string().min(1),
-    }),
-    async (p) => {
-      return jsonResult(await stripeGet(`/v1/invoices/${encodeURIComponent(p.id)}`));
-    },
-  );
-
-  reg(
-    "stripe_search",
-    "Substring search across recent Stripe invoices. Matches the query against id, number, status, customer id, customer name, customer email, and the description (case-insensitive). Returns a `{ matches: [...] }` envelope.",
-    searchToolInputSchema(100),
-    async (p) => {
-      const search = new URLSearchParams({ limit: "100" });
-      const root = await stripeGet(`/v1/invoices?${search.toString()}`);
-      const data = (root as { data?: unknown[] } | null)?.data;
-      return matchesResult(data, filterStripeInvoices, p);
-    },
-  );
+  registerStripeTools(reg);
 });

package/connectors/stripe/src/tools.ts

@@ -0,0 +1,54 @@
+import { z } from "zod";
+import { createJsonGetter, envAuthHeaders } from "../../../shared/env-json-api.ts";
+import { matchesResult, searchToolInputSchema } 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 { filterStripeInvoices } from "./search-filter.ts";
+
+const BASE = "https://api.stripe.com";
+
+const stripeGet = createJsonGetter({
+  base: BASE,
+  label: "Stripe",
+  headers: envAuthHeaders({ env: "STRIPE_API_KEY" }),
+});
+
+/** Tool names exposed by this connector — for contract/introspection tests. */
+export const STRIPE_TOOL_NAMES = ["stripe_get", "stripe_list", "stripe_search"] as const;
+
+export function registerStripeTools(reg: ZodToolRegistrar): void {
+  reg(
+    "stripe_list",
+    "List recent Stripe invoices (`GET /v1/invoices`), most-recent-first, capped at `limit` (default 100). Returns the `{ object: 'list', data, has_more }` envelope.",
+    z.object({
+      limit: z.number().int().min(1).max(100).optional(),
+    }),
+    async (p) => {
+      const search = new URLSearchParams({ limit: String(p.limit ?? 100) });
+      return jsonResult(await stripeGet(`/v1/invoices?${search.toString()}`));
+    },
+  );
+
+  reg(
+    "stripe_get",
+    "Fetch one Stripe invoice by its id (`GET /v1/invoices/{id}`, e.g. `in_1A2b...`). Returns the invoice object directly. Throws when no match is found.",
+    z.object({
+      id: z.string().min(1),
+    }),
+    async (p) => {
+      return jsonResult(await stripeGet(`/v1/invoices/${encodeURIComponent(p.id)}`));
+    },
+  );
+
+  reg(
+    "stripe_search",
+    "Substring search across recent Stripe invoices. Matches the query against id, number, status, customer id, customer name, customer email, and the description (case-insensitive). Returns a `{ matches: [...] }` envelope.",
+    searchToolInputSchema(100),
+    async (p) => {
+      const search = new URLSearchParams({ limit: "100" });
+      const root = await stripeGet(`/v1/invoices?${search.toString()}`);
+      const data = (root as { data?: unknown[] } | null)?.data;
+      return matchesResult(data, filterStripeInvoices, p);
+    },
+  );
+}

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

@@ -1,22 +1,11 @@
 import {
-  asRecord,
   makeQueryFilter,
+  recordFieldsFromKeys,
   type SearchMatchOptions,
 } from "../../../shared/search-filter.ts";
 
 export type SupersetSearchMatchOptions = SearchMatchOptions;
 
-function stringAt(row: Record<string, unknown>, key: string): string {
-  const v = row[key];
-  return typeof v === "string" ? v : "";
-}
-
-function fieldsOf(item: unknown): readonly string[] | null {
-  const row = asRecord(item);
-  if (row === undefined) {
-    return null;
-  }
-  return [stringAt(row, "dashboard_title"), stringAt(row, "slug")];
-}
-
-export const filterSupersetDashboards = makeQueryFilter(fieldsOf);
+export const filterSupersetDashboards = makeQueryFilter(
+  recordFieldsFromKeys(["dashboard_title", "slug"]),
+);