@nimbus-dev/connectors 0.1.0

package/connectors/teams/src/server.ts

@@ -0,0 +1,257 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { z } from "zod";
+
+import {
+  fetchBearerAuthorizedJson,
+  resolveUrlWithBase,
+} from "../../../shared/fetch-bearer-json.ts";
+import {
+  createRegisterSimpleTool,
+  createZodToolRegistrar,
+  type McpListResult,
+  mcpJsonResultIfOk,
+  requireProcessEnv,
+} from "../../../shared/mcp-tool-kit.ts";
+import { teamsBotSendActivity } from "./bot-send.ts";
+
+const GRAPH = "https://graph.microsoft.com/v1.0";
+
+async function graphRequest(
+  token: string,
+  pathOrUrl: string,
+  init?: RequestInit,
+): Promise<{ ok: boolean; status: number; json: unknown; text: string }> {
+  const url = resolveUrlWithBase(GRAPH, pathOrUrl);
+  return fetchBearerAuthorizedJson(url, token, init);
+}
+
+async function teamsPagedGraph(
+  token: string,
+  nextLink: string | undefined,
+  initialPath: string,
+): Promise<{ ok: boolean; status: number; json: unknown; text: string }> {
+  const path = nextLink !== undefined && nextLink !== "" ? nextLink : initialPath;
+  return graphRequest(token, path);
+}
+
+function graphListResult(r: {
+  ok: boolean;
+  status: number;
+  json: unknown;
+  text: string;
+}): McpListResult {
+  return mcpJsonResultIfOk("Graph", r, 200);
+}
+
+const server = new McpServer({ name: "nimbus-teams", version: "0.1.0" });
+
+const registerSimpleTool = createRegisterSimpleTool(server);
+
+import { createWriteToolRegistrar } from "../../../shared/consent-kit.ts";
+
+const reg = createZodToolRegistrar(registerSimpleTool);
+
+/**
+ * Every MUTATING teams 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: "teams",
+  scopeEnv: "NIMBUS_MCP_TEAMS_WRITE_SCOPE",
+  scopeKinds: ["channel", "chat"],
+});
+
+const teamsTeamListSchema = z.object({
+  top: z.number().int().min(1).max(100).optional(),
+  nextLink: z.url().optional(),
+});
+
+reg(
+  "teams_team_list",
+  "List Microsoft Teams the signed-in user has joined (pagination via nextLink).",
+  teamsTeamListSchema,
+  async (parsed) => {
+    const token = requireProcessEnv("MICROSOFT_OAUTH_ACCESS_TOKEN");
+    const initial = `/me/joinedTeams?$top=${String(parsed.top ?? 50)}`;
+    const r = await teamsPagedGraph(token, parsed.nextLink, initial);
+    return graphListResult(r);
+  },
+);
+
+const teamsChannelListSchema = z.object({
+  teamId: z.string().min(1),
+  top: z.number().int().min(1).max(100).optional(),
+  nextLink: z.url().optional(),
+});
+
+reg(
+  "teams_channel_list",
+  "List channels in a team (standard + private the app can read).",
+  teamsChannelListSchema,
+  async (parsed) => {
+    const token = requireProcessEnv("MICROSOFT_OAUTH_ACCESS_TOKEN");
+    const tid = encodeURIComponent(parsed.teamId);
+    const initial = `/teams/${tid}/channels?$top=${String(parsed.top ?? 50)}`;
+    const r = await teamsPagedGraph(token, parsed.nextLink, initial);
+    return graphListResult(r);
+  },
+);
+
+const teamsChannelMessagesSchema = z.object({
+  teamId: z.string().min(1),
+  channelId: z.string().min(1),
+  top: z.number().int().min(1).max(50).optional(),
+  nextLink: z.url().optional(),
+});
+
+reg(
+  "teams_channel_messages",
+  "List recent messages in a team channel (not delta; for interactive reads).",
+  teamsChannelMessagesSchema,
+  async (parsed) => {
+    const token = requireProcessEnv("MICROSOFT_OAUTH_ACCESS_TOKEN");
+    const tid = encodeURIComponent(parsed.teamId);
+    const cid = encodeURIComponent(parsed.channelId);
+    const initial = `/teams/${tid}/channels/${cid}/messages?$top=${String(parsed.top ?? 25)}`;
+    const r = await teamsPagedGraph(token, parsed.nextLink, initial);
+    return graphListResult(r);
+  },
+);
+
+const teamsChatListSchema = z.object({
+  top: z.number().int().min(1).max(50).optional(),
+  nextLink: z.url().optional(),
+});
+
+reg(
+  "teams_chat_list",
+  "List 1:1 and group chats for the signed-in user.",
+  teamsChatListSchema,
+  async (parsed) => {
+    const token = requireProcessEnv("MICROSOFT_OAUTH_ACCESS_TOKEN");
+    const initial = `/me/chats?$top=${String(parsed.top ?? 25)}`;
+    const r = await teamsPagedGraph(token, parsed.nextLink, initial);
+    return graphListResult(r);
+  },
+);
+
+const teamsChatMessagesSchema = z.object({
+  chatId: z.string().min(1),
+  top: z.number().int().min(1).max(50).optional(),
+  nextLink: z.url().optional(),
+});
+
+reg("teams_chat_messages", "List messages in a chat.", teamsChatMessagesSchema, async (parsed) => {
+  const token = requireProcessEnv("MICROSOFT_OAUTH_ACCESS_TOKEN");
+  const id = encodeURIComponent(parsed.chatId);
+  const initial = `/chats/${id}/messages?$top=${String(parsed.top ?? 25)}`;
+  const r = await teamsPagedGraph(token, parsed.nextLink, initial);
+  return graphListResult(r);
+});
+
+const teamsMessagePostSchema = z.object({
+  teamId: z.string().min(1),
+  channelId: z.string().min(1),
+  body: z.string().min(1),
+  contentType: z.enum(["text", "html"]).optional(),
+});
+
+registerWriteTool(
+  "teams_message_post",
+  {
+    mutates: "teams.message.post",
+    recoverable: true,
+    scopeTargetOf: (p) => ({ kind: "channel", value: `${p.teamId}/${p.channelId}` }),
+  },
+  "Post a message to a team channel.",
+  teamsMessagePostSchema,
+  async (parsed) => {
+    const token = requireProcessEnv("MICROSOFT_OAUTH_ACCESS_TOKEN");
+    const tid = encodeURIComponent(parsed.teamId);
+    const cid = encodeURIComponent(parsed.channelId);
+    const ct = parsed.contentType ?? "text";
+    const r = await graphRequest(token, `/teams/${tid}/channels/${cid}/messages`, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({
+        body: {
+          contentType: ct === "html" ? "html" : "text",
+          content: parsed.body,
+        },
+      }),
+    });
+    return graphListResult(r);
+  },
+);
+
+const teamsMessagePostChatSchema = z.object({
+  chatId: z.string().min(1),
+  body: z.string().min(1),
+  contentType: z.enum(["text", "html"]).optional(),
+});
+
+reg(
+  "teams_message_post_chat",
+  "Post a message to a chat (requires HITL teams.message.postChat).",
+  teamsMessagePostChatSchema,
+  async (parsed) => {
+    const token = requireProcessEnv("MICROSOFT_OAUTH_ACCESS_TOKEN");
+    const id = encodeURIComponent(parsed.chatId);
+    const ct = parsed.contentType ?? "text";
+    const r = await graphRequest(token, `/chats/${id}/messages`, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({
+        body: {
+          contentType: ct === "html" ? "html" : "text",
+          content: parsed.body,
+        },
+      }),
+    });
+    return graphListResult(r);
+  },
+);
+
+// --- ChatOps operational tools (Slice 5) -------------------------------------------------------
+// `teams_chat_post` uses bot app credentials (Bot Framework), distinct from the user Graph token.
+// Only `chatops/reply-dispatcher.ts` + `chatops/transport/` reference `teams_chat_post` (static D17).
+
+const teamsUserInfoSchema = z.object({ userId: z.string().min(1) });
+reg(
+  "teams_user_info",
+  "Fetch a Teams/AAD user (incl. mail/userPrincipalName) by id (ChatOps identity mapping).",
+  teamsUserInfoSchema,
+  async (parsed) => {
+    const token = requireProcessEnv("MICROSOFT_OAUTH_ACCESS_TOKEN");
+    const r = await teamsPagedGraph(
+      token,
+      undefined,
+      `/users/${encodeURIComponent(parsed.userId)}`,
+    );
+    return graphListResult(r);
+  },
+);
+
+const teamsChatPostSchema = z.object({
+  conversationId: z.string().min(1),
+  text: z.string().min(1),
+});
+registerWriteTool(
+  "teams_chat_post",
+  {
+    mutates: "teams.chat.post",
+    recoverable: true,
+    scopeTargetOf: (p) => ({ kind: "chat", value: p.conversationId }),
+  },
+  "Post an operational bot message to a Teams conversation (ChatOps reply surface; bot app creds).",
+  teamsChatPostSchema,
+  async (parsed) => {
+    const r = await teamsBotSendActivity(parsed.conversationId, parsed.text);
+    return graphListResult(r);
+  },
+);
+
+const transport = new StdioServerTransport();
+await server.connect(transport);

package/connectors/testflight/nimbus.extension.json

@@ -0,0 +1,15 @@
+{
+  "id": "com.nimbus.testflight",
+  "displayName": "TestFlight",
+  "version": "0.1.0",
+  "description": "TestFlight connector via Apple's App Store Connect API (read-only). Surfaces apps and recent builds (version, processing state, uploaded date, min OS, encryption flag) so the local index can correlate iOS/macOS beta builds back to releases and incidents.",
+  "author": "Nimbus",
+  "entrypoint": "dist/server.js",
+  "runtime": "bun",
+  "permissions": {
+    "network": ["api.appstoreconnect.apple.com"]
+  },
+  "hitlRequired": [],
+  "syncInterval": 600,
+  "minNimbusVersion": "0.2.0"
+}

package/connectors/testflight/src/jwt.ts

@@ -0,0 +1,27 @@
+import type { AppStoreConnectJwtParams } from "@nimbus-dev/sdk";
+
+/**
+ * App Store Connect credential plumbing.
+ *
+ * The ES256 JWT signer lives in `@nimbus-dev/sdk` (`signAppStoreConnectJwt`) so
+ * the gateway sync and this MCP server share one signer across the package
+ * boundary. This module holds only the connector's env glue: reading the
+ * spawn-injected `TESTFLIGHT_*` credentials.
+ */
+
+/** Read the three `TESTFLIGHT_*` env vars; throws if any is unset. */
+export function jwtParamsFromEnv(): AppStoreConnectJwtParams {
+  const issuerId = process.env["TESTFLIGHT_ISSUER_ID"]?.trim();
+  const keyId = process.env["TESTFLIGHT_KEY_ID"]?.trim();
+  const privateKeyPem = process.env["TESTFLIGHT_PRIVATE_KEY"];
+  if (issuerId === undefined || issuerId === "") {
+    throw new Error("TESTFLIGHT_ISSUER_ID is not set");
+  }
+  if (keyId === undefined || keyId === "") {
+    throw new Error("TESTFLIGHT_KEY_ID is not set");
+  }
+  if (privateKeyPem === undefined || privateKeyPem.trim() === "") {
+    throw new Error("TESTFLIGHT_PRIVATE_KEY is not set");
+  }
+  return { issuerId, keyId, privateKeyPem };
+}

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

@@ -0,0 +1,30 @@
+import {
+  asObjectish,
+  type FieldExtractor,
+  makeQueryFilter,
+  type SearchMatchOptions,
+  stringField,
+} from "../../../shared/search-filter.ts";
+
+export type TestflightSearchMatchOptions = SearchMatchOptions;
+
+/**
+ * App Store Connect builds are JSON:API resources — the searchable fields live
+ * under `attributes`, not at the top level. Project the version + processing
+ * state up so the shared substring filter can match them.
+ */
+const buildFields: FieldExtractor = (item: unknown) => {
+  const row = asObjectish(item);
+  if (row === undefined) {
+    return null;
+  }
+  const attributes = asObjectish(row["attributes"]) ?? {};
+  return [
+    stringField(attributes, "version"),
+    stringField(attributes, "processingState"),
+    stringField(attributes, "minOsVersion"),
+    stringField(row, "id"),
+  ];
+};
+
+export const filterTestflightBuilds = makeQueryFilter(buildFields);

package/connectors/testflight/src/server.ts

@@ -0,0 +1,74 @@
+import { signAppStoreConnectJwt } from "@nimbus-dev/sdk";
+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 { jwtParamsFromEnv } from "./jwt.ts";
+import { filterTestflightBuilds } from "./search-filter.ts";
+
+const APPSTORECONNECT_API = "https://api.appstoreconnect.apple.com";
+
+function authHeader(): Record<string, string> {
+  const token = signAppStoreConnectJwt(jwtParamsFromEnv());
+  return { Authorization: `Bearer ${token}`, Accept: "application/json" };
+}
+
+async function appstoreGet(path: string): Promise<unknown> {
+  const res = await fetch(`${APPSTORECONNECT_API}${path}`, { headers: authHeader() });
+  const text = await res.text();
+  if (!res.ok) {
+    throw new Error(`App Store Connect ${String(res.status)}: ${text.slice(0, 400)}`);
+  }
+  return JSON.parse(text) as unknown;
+}
+
+function buildsPath(appId: string, limit: number): string {
+  return `/v1/builds?filter[app]=${encodeURIComponent(appId)}&sort=-uploadedDate&limit=${String(limit)}`;
+}
+
+await runReadOnlyMcpConnector("nimbus-testflight", (reg) => {
+  reg(
+    "testflight_list",
+    "List TestFlight resources via the App Store Connect API. When `appId` is omitted, returns the user's accessible apps via `GET /v1/apps`. When `appId` is provided, returns that app's most-recent builds via `GET /v1/builds?filter[app]=<id>&sort=-uploadedDate` (limit optional).",
+    z.object({
+      appId: z.string().min(1).optional(),
+      limit: z.number().int().min(1).max(200).optional(),
+    }),
+    async (p) => {
+      if (p.appId === undefined) {
+        return jsonResult(await appstoreGet("/v1/apps"));
+      }
+      return jsonResult(await appstoreGet(buildsPath(p.appId, p.limit ?? 50)));
+    },
+  );
+
+  reg(
+    "testflight_get",
+    "Fetch a single TestFlight resource. When `buildId` is provided, returns the build via `GET /v1/builds/<buildId>`. When omitted, returns the app via `GET /v1/apps/<appId>`.",
+    z.object({
+      appId: z.string().min(1),
+      buildId: z.string().min(1).optional(),
+    }),
+    async (p) => {
+      if (p.buildId === undefined) {
+        return jsonResult(await appstoreGet(`/v1/apps/${encodeURIComponent(p.appId)}`));
+      }
+      return jsonResult(await appstoreGet(`/v1/builds/${encodeURIComponent(p.buildId)}`));
+    },
+  );
+
+  reg(
+    "testflight_search",
+    "Substring search across a TestFlight app's recent builds. Matches the query against each build's `version`, `processingState`, `minOsVersion`, and `id` (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 appstoreGet(buildsPath(p.appId, 200));
+      const data = (root as { data?: unknown[] } | null)?.data;
+      return matchesResult(data, filterTestflightBuilds, p);
+    },
+  );
+});

package/connectors/vercel/nimbus.extension.json

@@ -0,0 +1,15 @@
+{
+  "id": "com.nimbus.vercel",
+  "displayName": "Vercel",
+  "version": "0.1.0",
+  "description": "Vercel deployment connector (read-only). Surfaces deployment uid, project name, state, target (production/staging), the *.vercel.app host, inspector URL, git commit metadata (sha/message/ref/PR id), and creator into the local index as `vercel:deployment` items — useful for correlating deploys with PR / Slack history (\"which deploy shipped this commit?\"). Bearer-token auth. Optional `vercel.team_id` scopes requests to a team. The SaaS host (api.vercel.com) is fixed. Projects / domains / env vars / aliases / logs are deferred follow-ups.",
+  "author": "Nimbus",
+  "entrypoint": "dist/server.js",
+  "runtime": "bun",
+  "permissions": {
+    "network": ["api.vercel.com"]
+  },
+  "hitlRequired": [],
+  "syncInterval": 600,
+  "minNimbusVersion": "0.2.0"
+}

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

@@ -0,0 +1,34 @@
+import {
+  asObjectish,
+  makeQueryFilter,
+  type SearchMatchOptions,
+  stringField,
+} from "../../../shared/search-filter.ts";
+
+export type VercelSearchMatchOptions = SearchMatchOptions;
+
+function commitMessage(row: Record<string, unknown>): string {
+  const meta = row["meta"];
+  if (meta === null || typeof meta !== "object" || Array.isArray(meta)) {
+    return "";
+  }
+  const v = (meta as Record<string, unknown>)["githubCommitMessage"];
+  return typeof v === "string" ? v : "";
+}
+
+function fieldsOf(item: unknown): readonly string[] | null {
+  const row = asObjectish(item);
+  if (row === undefined) {
+    return null;
+  }
+  return [
+    stringField(row, "uid"),
+    stringField(row, "name"),
+    stringField(row, "state"),
+    stringField(row, "target"),
+    stringField(row, "url"),
+    commitMessage(row),
+  ];
+}
+
+export const filterVercelDeployments = makeQueryFilter(fieldsOf);

package/connectors/vercel/src/server.ts

@@ -0,0 +1,79 @@
+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 { filterVercelDeployments } from "./search-filter.ts";
+
+const BASE = "https://api.vercel.com";
+
+function token(): string {
+  const t = process.env["VERCEL_TOKEN"]?.trim();
+  if (t === undefined || t === "") {
+    throw new Error("VERCEL_TOKEN is not set");
+  }
+  return t;
+}
+
+function teamId(): string | undefined {
+  const v = process.env["VERCEL_TEAM_ID"]?.trim();
+  return v === undefined || v === "" ? undefined : v;
+}
+
+function authHeader(): Record<string, string> {
+  return { Authorization: `Bearer ${token()}`, Accept: "application/json" };
+}
+
+function withTeam(path: string): string {
+  const team = teamId();
+  if (team === undefined) {
+    return path;
+  }
+  const sep = path.includes("?") ? "&" : "?";
+  return `${path}${sep}teamId=${encodeURIComponent(team)}`;
+}
+
+async function vercelGet(path: string): Promise<unknown> {
+  const res = await fetch(`${BASE}${withTeam(path)}`, { headers: authHeader() });
+  const text = await res.text();
+  if (!res.ok) {
+    throw new Error(`Vercel ${String(res.status)}: ${text.slice(0, 400)}`);
+  }
+  return JSON.parse(text) as unknown;
+}
+
+await runReadOnlyMcpConnector("nimbus-vercel", (reg) => {
+  reg(
+    "vercel_list",
+    "List recent Vercel deployments (`GET /v6/deployments`), most-recent-first, capped at `limit` (default 100). Returns the `{ deployments, pagination }` 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 vercelGet(`/v6/deployments?${search.toString()}`));
+    },
+  );
+
+  reg(
+    "vercel_get",
+    "Fetch one Vercel deployment by its id or *.vercel.app URL (`GET /v13/deployments/{idOrUrl}`). Returns the deployment object directly. Throws when no match is found.",
+    z.object({
+      idOrUrl: z.string().min(1),
+    }),
+    async (p) => {
+      return jsonResult(await vercelGet(`/v13/deployments/${encodeURIComponent(p.idOrUrl)}`));
+    },
+  );
+
+  reg(
+    "vercel_search",
+    "Substring search across recent Vercel deployments. Matches the query against uid, project name, state, target, the *.vercel.app host, and the git commit message (case-insensitive). Returns a `{ matches: [...] }` envelope.",
+    searchToolInputSchema(100),
+    async (p) => {
+      const search = new URLSearchParams({ limit: "100" });
+      const root = await vercelGet(`/v6/deployments?${search.toString()}`);
+      const deployments = (root as { deployments?: unknown[] } | null)?.deployments;
+      return matchesResult(deployments, filterVercelDeployments, p);
+    },
+  );
+});

package/connectors/vertex-ai/nimbus.extension.json

@@ -0,0 +1,15 @@
+{
+  "id": "com.nimbus.vertex-ai",
+  "displayName": "Vertex AI",
+  "version": "0.1.0",
+  "description": "GCP Vertex AI metadata connector (Tier-3, no-row-data). Indexes Vertex AI model REGISTRY metadata only — model resource name, display name, version id, region, and create/update timestamps — via the gcloud CLI's `gcloud ai models list/describe` commands. Never calls inference / prediction: there is no `gcloud ai endpoints predict`, no `explain`, no `raw-predict`, and no batch-prediction output read. Reuses the existing GCP service-account credentials via the gcloud CLI; region defaults to us-central1 (optional `gcp.region`). Read-only; no write tools.",
+  "author": "Nimbus",
+  "entrypoint": "dist/server.js",
+  "runtime": "bun",
+  "permissions": {
+    "network": ["aiplatform.googleapis.com", "oauth2.googleapis.com", "www.googleapis.com"]
+  },
+  "hitlRequired": [],
+  "syncInterval": 600,
+  "minNimbusVersion": "0.2.0"
+}

package/connectors/vertex-ai/src/server.ts

@@ -0,0 +1,6 @@
+import { runReadOnlyMcpConnector } from "../../../shared/run-read-only-mcp-connector.ts";
+import { registerVertexAiTools } from "./tools.ts";
+
+await runReadOnlyMcpConnector("nimbus-vertex-ai", (reg) => {
+  registerVertexAiTools(reg);
+});