@nimbus-dev/connectors 0.1.0

package/connectors/outlook/nimbus.extension.json

@@ -0,0 +1,15 @@
+{
+  "id": "com.nimbus.outlook",
+  "displayName": "Outlook",
+  "version": "0.1.0",
+  "description": "Microsoft Graph Outlook connector (mail, calendar). Mutations require Gateway HITL.",
+  "author": "Nimbus",
+  "entrypoint": "dist/server.js",
+  "runtime": "bun",
+  "permissions": {
+    "network": ["graph.microsoft.com", "login.microsoftonline.com"]
+  },
+  "hitlRequired": ["write", "delete"],
+  "syncInterval": 120,
+  "minNimbusVersion": "0.2.0"
+}

package/connectors/outlook/src/server.ts

@@ -0,0 +1,358 @@
+/**
+ * nimbus-connector outlook — Microsoft Graph mail, calendar, contacts (read + guarded writes).
+ * Access token is injected as MICROSOFT_OAUTH_ACCESS_TOKEN (never logged).
+ * Optional `MICROSOFT_OAUTH_SCOPES` (space-separated) gates which tools register; the Gateway
+ * audit-ignore-next-line D11-vault-key (JSDoc reference, not vault-key construction)
+ * sets it from `microsoft.oauth` JSON when `scopes` is present.
+ * Send / calendar mutations require Gateway HITL (email.send, calendar.event.create | delete).
+ */
+
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { z } from "zod";
+import { headerLine } from "../../../shared/header-safe.ts";
+import {
+  createRegisterSimpleTool,
+  createZodToolRegistrar,
+  mcpJsonResult,
+  mcpJsonResultIfOk,
+  requireProcessEnv,
+  type ZodObjectSchema,
+} from "../../../shared/mcp-tool-kit.ts";
+import { makeRestFetcher, makeRestToolRegistrar } from "../../../shared/rest-tool-kit.ts";
+import {
+  outlookToolShouldRegister,
+  parseMicrosoftOAuthScopesFromEnv,
+} from "./tool-scope-policy.ts";
+
+const GRAPH = "https://graph.microsoft.com/v1.0";
+
+function graphRequest(
+  token: string,
+  pathOrUrl: string,
+  init?: RequestInit,
+): Promise<{ ok: boolean; status: number; json: unknown; text: string }> {
+  return makeRestFetcher({ apiBase: GRAPH, token })(pathOrUrl, init);
+}
+
+const server = new McpServer({ name: "nimbus-outlook", version: "0.1.0" });
+
+const reg = createZodToolRegistrar(createRegisterSimpleTool(server));
+const grantedOutlookScopes = parseMicrosoftOAuthScopesFromEnv();
+
+/** Standard Graph read tool: token → graphRequest(buildPath[, buildInit]) → mcpJsonResultIfOk("Graph", …, 200). */
+import { createWriteToolRegistrar, type WriteToolConfig } from "../../../shared/consent-kit.ts";
+
+/**
+ * Every MUTATING outlook 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: "outlook",
+  scopeEnv: "NIMBUS_MCP_OUTLOOK_WRITE_SCOPE",
+  scopeKinds: ["recipient", "calendar"],
+});
+
+/**
+ * The write-tool equivalent of `registerOutlookTool`: identical fetch and result handling, routed
+ * through the write registrar.
+ */
+function registerOutlookWriteTool<T>(
+  name: string,
+  cfg: WriteToolConfig<T>,
+  description: string,
+  schema: ZodObjectSchema<T>,
+  buildPath: (p: T) => string,
+  buildInit?: (p: T) => RequestInit,
+): void {
+  registerWriteTool(name, cfg, description, schema, async (parsed) => {
+    const token = requireProcessEnv("MICROSOFT_OAUTH_ACCESS_TOKEN");
+    const res = await graphRequest(token, buildPath(parsed), buildInit?.(parsed));
+    return mcpJsonResultIfOk("Graph", res, 200);
+  });
+}
+
+const registerOutlookTool = makeRestToolRegistrar({
+  registrar: reg,
+  tokenEnv: "MICROSOFT_OAUTH_ACCESS_TOKEN",
+  serviceLabel: "Graph",
+  fetch: graphRequest,
+  snippetMax: 200,
+});
+
+const outlookMailFoldersArgs = z.object({
+  top: z.number().int().min(1).max(200).optional(),
+  nextLink: z.url().optional(),
+});
+
+if (outlookToolShouldRegister("outlook_mail_folders", grantedOutlookScopes)) {
+  registerOutlookTool(
+    "outlook_mail_folders",
+    "List mail folders (pagination via nextLink).",
+    outlookMailFoldersArgs,
+    (data) => {
+      if (data.nextLink !== undefined && data.nextLink !== "") {
+        return data.nextLink;
+      }
+      const top = data.top ?? 50;
+      return `/me/mailFolders?$top=${String(top)}`;
+    },
+  );
+}
+
+const outlookMailListArgs = z.object({
+  folderId: z.string().min(1).optional(),
+  top: z.number().int().min(1).max(100).optional(),
+  skip: z.number().int().min(0).optional(),
+  nextLink: z.url().optional(),
+  filter: z.string().max(500).optional(),
+});
+
+if (outlookToolShouldRegister("outlook_mail_list", grantedOutlookScopes)) {
+  registerOutlookTool(
+    "outlook_mail_list",
+    "List mail messages (default folder inbox if folderId omitted). Pagination via nextLink.",
+    outlookMailListArgs,
+    (data) => {
+      if (data.nextLink !== undefined && data.nextLink !== "") {
+        return data.nextLink;
+      }
+      const top = data.top ?? 25;
+      const fid = data.folderId !== undefined && data.folderId !== "" ? data.folderId : "inbox";
+      const skip = data.skip ?? 0;
+      const u = new URL(`${GRAPH}/me/mailFolders/${encodeURIComponent(fid)}/messages`);
+      u.searchParams.set("$top", String(top));
+      u.searchParams.set("$skip", String(skip));
+      u.searchParams.set(
+        "$select",
+        "id,subject,bodyPreview,receivedDateTime,lastModifiedDateTime,hasAttachments,webLink",
+      );
+      if (data.filter !== undefined && data.filter !== "") {
+        u.searchParams.set("$filter", data.filter);
+      }
+      return `${u.pathname}${u.search}`;
+    },
+  );
+}
+
+const outlookMailReadArgs = z.object({
+  messageId: z.string().min(1),
+});
+
+if (outlookToolShouldRegister("outlook_mail_read", grantedOutlookScopes)) {
+  registerOutlookTool(
+    "outlook_mail_read",
+    "Read a single message (body, headers, attachments metadata).",
+    outlookMailReadArgs,
+    (data) => `/me/messages/${encodeURIComponent(data.messageId)}?$expand=attachments`,
+  );
+}
+
+const outlookMailSendArgs = z.object({
+  to: headerLine({ min: 1, max: 2000 }),
+  subject: headerLine({ min: 1, max: 500 }),
+  body: z.string().min(1).max(1_000_000),
+  contentType: z.enum(["text", "html"]).optional(),
+  cc: headerLine({ max: 2000 }).optional(),
+});
+
+if (outlookToolShouldRegister("outlook_mail_send", grantedOutlookScopes)) {
+  registerWriteTool(
+    "outlook_mail_send",
+    {
+      mutates: "outlook.mail.send",
+      recoverable: false,
+      capturePreState: (p) => Promise.resolve({ to: p.to, subject: p.subject }),
+      scopeTargetOf: (p) => ({ kind: "recipient", value: p.to }),
+    },
+    "Send an email via Microsoft Graph. Requires Gateway HITL email.send.",
+    outlookMailSendArgs,
+    async (data) => {
+      const token = requireProcessEnv("MICROSOFT_OAUTH_ACCESS_TOKEN");
+      const toList = data.to
+        .split(",")
+        .map((s) => s.trim())
+        .filter((s) => s.length > 0);
+      const message: Record<string, unknown> = {
+        subject: data.subject,
+        body: {
+          contentType: (data.contentType ?? "text") === "html" ? "HTML" : "Text",
+          content: data.body,
+        },
+        toRecipients: toList.map((addr) => ({
+          emailAddress: { address: addr },
+        })),
+      };
+      if (data.cc !== undefined && data.cc !== "") {
+        const ccList = data.cc
+          .split(",")
+          .map((s) => s.trim())
+          .filter((s) => s.length > 0);
+        message["ccRecipients"] = ccList.map((addr) => ({
+          emailAddress: { address: addr },
+        }));
+      }
+      const r = await graphRequest(token, "/me/sendMail", {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify({ message, saveToSentItems: true }),
+      });
+      if (!r.ok) {
+        throw new Error(`Graph ${String(r.status)}: ${r.text.slice(0, 200)}`);
+      }
+      return mcpJsonResult({ ok: true });
+    },
+  );
+}
+
+const outlookCalendarListArgs = z.object({
+  startDateTime: z.string().min(1),
+  endDateTime: z.string().min(1),
+  top: z.number().int().min(1).max(200).optional(),
+  nextLink: z.url().optional(),
+});
+
+if (outlookToolShouldRegister("outlook_calendar_list", grantedOutlookScopes)) {
+  registerOutlookTool(
+    "outlook_calendar_list",
+    "List calendar events in a time window (ISO 8601 startDateTime / endDateTime).",
+    outlookCalendarListArgs,
+    (data) => {
+      if (data.nextLink !== undefined && data.nextLink !== "") {
+        return data.nextLink;
+      }
+      const top = data.top ?? 50;
+      const s = encodeURIComponent(data.startDateTime);
+      const e = encodeURIComponent(data.endDateTime);
+      return `/me/calendarView?startDateTime=${s}&endDateTime=${e}&$top=${String(top)}`;
+    },
+  );
+}
+
+const outlookCalendarGetArgs = z.object({
+  eventId: z.string().min(1),
+});
+
+if (outlookToolShouldRegister("outlook_calendar_get", grantedOutlookScopes)) {
+  registerOutlookTool(
+    "outlook_calendar_get",
+    "Get a single calendar event by id.",
+    outlookCalendarGetArgs,
+    (data) => `/me/events/${encodeURIComponent(data.eventId)}`,
+  );
+}
+
+const outlookCalendarCreateArgs = z.object({
+  subject: headerLine({ min: 1, max: 500 }),
+  startDateTime: z.string().min(1),
+  endDateTime: z.string().min(1),
+  timeZone: z.string().min(1).max(100).optional(),
+  body: z.string().max(50_000).optional(),
+  attendees: headerLine({ max: 4000 }).optional(),
+});
+
+if (outlookToolShouldRegister("outlook_calendar_create", grantedOutlookScopes)) {
+  registerOutlookWriteTool(
+    "outlook_calendar_create",
+    {
+      mutates: "outlook.calendar.create",
+      recoverable: true,
+      scopeTargetOf: (p) => ({ kind: "calendar", value: p.subject }),
+    },
+    "Create a calendar event. Requires Gateway HITL calendar.event.create.",
+    outlookCalendarCreateArgs,
+    () => "/me/events",
+    (data) => {
+      const tz = data.timeZone ?? "UTC";
+      const body: Record<string, unknown> = {
+        subject: data.subject,
+        start: { dateTime: data.startDateTime, timeZone: tz },
+        end: { dateTime: data.endDateTime, timeZone: tz },
+      };
+      if (data.body !== undefined && data.body !== "") {
+        body["body"] = { contentType: "Text", content: data.body };
+      }
+      if (data.attendees !== undefined && data.attendees !== "") {
+        const addrs = data.attendees
+          .split(",")
+          .map((s) => s.trim())
+          .filter((s) => s.length > 0);
+        body["attendees"] = addrs.map((a) => ({
+          emailAddress: { address: a },
+          type: "required",
+        }));
+      }
+      return {
+        method: "POST",
+        headers: { "Content-Type": "application/json" },
+        body: JSON.stringify(body),
+      };
+    },
+  );
+}
+
+const outlookCalendarDeleteArgs = z.object({
+  eventId: z.string().min(1),
+});
+
+if (outlookToolShouldRegister("outlook_calendar_delete", grantedOutlookScopes)) {
+  registerWriteTool(
+    "outlook_calendar_delete",
+    {
+      mutates: "outlook.calendar.delete",
+      recoverable: false,
+      capturePreState: (p) => Promise.resolve({ eventId: p.eventId }),
+      scopeTargetOf: (p) => ({ kind: "calendar", value: p.eventId }),
+    },
+    "Delete a calendar event. Requires Gateway HITL calendar.event.delete.",
+    outlookCalendarDeleteArgs,
+    async (data) => {
+      const token = requireProcessEnv("MICROSOFT_OAUTH_ACCESS_TOKEN");
+      const r = await graphRequest(token, `/me/events/${encodeURIComponent(data.eventId)}`, {
+        method: "DELETE",
+      });
+      if (!r.ok && r.status !== 204) {
+        throw new Error(`Graph ${String(r.status)}: ${r.text.slice(0, 200)}`);
+      }
+      return mcpJsonResult({ ok: true });
+    },
+  );
+}
+
+const outlookContactListArgs = z.object({
+  top: z.number().int().min(1).max(200).optional(),
+  skip: z.number().int().min(0).optional(),
+  nextLink: z.url().optional(),
+});
+
+if (outlookToolShouldRegister("outlook_contact_list", grantedOutlookScopes)) {
+  registerOutlookTool(
+    "outlook_contact_list",
+    "List contacts from the default folder.",
+    outlookContactListArgs,
+    (data) => {
+      if (data.nextLink !== undefined && data.nextLink !== "") {
+        return data.nextLink;
+      }
+      const top = data.top ?? 50;
+      const skip = data.skip ?? 0;
+      return `/me/contacts?$top=${String(top)}&$skip=${String(skip)}`;
+    },
+  );
+}
+
+const outlookContactGetArgs = z.object({
+  contactId: z.string().min(1),
+});
+
+if (outlookToolShouldRegister("outlook_contact_get", grantedOutlookScopes)) {
+  registerOutlookTool(
+    "outlook_contact_get",
+    "Get a single contact by id.",
+    outlookContactGetArgs,
+    (data) => `/me/contacts/${encodeURIComponent(data.contactId)}`,
+  );
+}
+
+await server.connect(new StdioServerTransport());

package/connectors/outlook/src/tool-scope-policy.ts

@@ -0,0 +1,53 @@
+const OUTLOOK_TOOL_MIN_SCOPES: Readonly<Record<string, readonly string[]>> = {
+  outlook_mail_folders: ["Mail.Read"],
+  outlook_mail_list: ["Mail.Read"],
+  outlook_mail_read: ["Mail.Read"],
+  outlook_mail_send: ["Mail.Send"],
+  outlook_calendar_list: ["Calendars.Read"],
+  outlook_calendar_get: ["Calendars.Read"],
+  outlook_calendar_create: ["Calendars.ReadWrite"],
+  outlook_calendar_delete: ["Calendars.ReadWrite"],
+  outlook_contact_list: ["Contacts.Read"],
+  outlook_contact_get: ["Contacts.Read"],
+};
+
+function scopeSatisfied(granted: ReadonlySet<string>, required: string): boolean {
+  if (granted.has(required)) {
+    return true;
+  }
+  if (required === "Calendars.Read" && granted.has("Calendars.ReadWrite")) {
+    return true;
+  }
+  if (required === "Mail.Read" && granted.has("Mail.ReadWrite")) {
+    return true;
+  }
+  return false;
+}
+
+export function outlookToolAllowed(toolId: string, grantedScopes: readonly string[]): boolean {
+  const reqs = OUTLOOK_TOOL_MIN_SCOPES[toolId];
+  if (reqs === undefined) {
+    return true;
+  }
+  const g = new Set(grantedScopes);
+  return reqs.every((r) => scopeSatisfied(g, r));
+}
+
+export function parseMicrosoftOAuthScopesFromEnv(): string[] | undefined {
+  const raw = process.env["MICROSOFT_OAUTH_SCOPES"];
+  if (raw === undefined) {
+    return undefined;
+  }
+  const parts = raw.split(/\s+/).filter((s) => s.length > 0);
+  return parts.length === 0 ? undefined : parts;
+}
+
+export function outlookToolShouldRegister(
+  toolId: string,
+  grantedFromEnv: string[] | undefined,
+): boolean {
+  if (grantedFromEnv === undefined) {
+    return true;
+  }
+  return outlookToolAllowed(toolId, grantedFromEnv);
+}

package/connectors/pagerduty/nimbus.extension.json

@@ -0,0 +1,15 @@
+{
+  "id": "com.nimbus.pagerduty",
+  "displayName": "PagerDuty",
+  "version": "0.1.0",
+  "description": "PagerDuty REST + Events API connector (incidents, services, schedules). Mutations require Gateway HITL.",
+  "author": "Nimbus",
+  "entrypoint": "dist/server.js",
+  "runtime": "bun",
+  "permissions": {
+    "network": ["api.pagerduty.com", "events.pagerduty.com"]
+  },
+  "hitlRequired": ["write", "delete"],
+  "syncInterval": 60,
+  "minNimbusVersion": "0.2.0"
+}

package/connectors/pagerduty/src/server.ts

@@ -0,0 +1,140 @@
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { z } from "zod";
+
+import {
+  createRegisterSimpleTool,
+  createZodToolRegistrar,
+  mcpJsonResult as jsonResult,
+  requireProcessEnv,
+} from "../../../shared/mcp-tool-kit.ts";
+import { makeRestToolRegistrar } from "../../../shared/rest-tool-kit.ts";
+
+const API = "https://api.pagerduty.com";
+
+async function pdFetch(
+  token: string,
+  path: string,
+  init?: RequestInit,
+): Promise<{ ok: boolean; status: number; json: unknown; text: string }> {
+  const rel = path.startsWith("/") ? path : `/${path}`;
+  const url = path.startsWith("http") ? path : `${API}${rel}`;
+  const res = await fetch(url, {
+    ...init,
+    headers: {
+      Accept: "application/vnd.pagerduty+json;version=2",
+      Authorization: `Token token=${token}`,
+      "Content-Type": "application/json",
+      ...(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 };
+}
+
+async function pdIncidentPutMutation(actionLabel: string, pathSuffix: string, incidentId: string) {
+  const token = requireProcessEnv("PAGERDUTY_API_TOKEN");
+  const res = await pdFetch(token, `/incidents/${encodeURIComponent(incidentId)}/${pathSuffix}`, {
+    method: "PUT",
+    body: JSON.stringify({ incident: { type: "incident_reference", id: incidentId } }),
+  });
+  if (!res.ok) {
+    throw new Error(`PagerDuty ${actionLabel} ${String(res.status)}: ${res.text.slice(0, 400)}`);
+  }
+  return jsonResult(res.json ?? { ok: true });
+}
+
+const mcp = new McpServer({ name: "nimbus-pagerduty", version: "0.1.0" });
+
+import { createWriteToolRegistrar } from "../../../shared/consent-kit.ts";
+
+const reg = createZodToolRegistrar(createRegisterSimpleTool(mcp));
+
+/**
+ * Every MUTATING pagerduty 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: "pagerduty",
+  scopeEnv: "NIMBUS_MCP_PAGERDUTY_WRITE_SCOPE",
+  scopeKinds: ["incident"],
+});
+
+/** Standard PagerDuty read tool: token → pdFetch(buildPath) → mcpJsonResultIfOk("PagerDuty"). */
+const registerPdTool = makeRestToolRegistrar({
+  registrar: reg,
+  tokenEnv: "PAGERDUTY_API_TOKEN",
+  serviceLabel: "PagerDuty",
+  fetch: pdFetch,
+});
+
+registerPdTool(
+  "pd_incident_list",
+  "List PagerDuty incidents (open and recently resolved).",
+  z.object({
+    statuses: z.array(z.enum(["triggered", "acknowledged", "resolved"])).optional(),
+    limit: z.number().int().min(1).max(100).optional(),
+  }),
+  (parsed) => {
+    const u = new URL(`${API}/incidents`);
+    u.searchParams.set("limit", String(parsed.limit ?? 25));
+    const st = parsed.statuses ?? ["triggered", "acknowledged"];
+    for (const s of st) {
+      u.searchParams.append("statuses[]", s);
+    }
+    return `${u.pathname}${u.search}`;
+  },
+);
+
+registerPdTool(
+  "pd_incident_get",
+  "Get a single incident by id.",
+  z.object({ incidentId: z.string().min(1) }),
+  (parsed) => `/incidents/${encodeURIComponent(parsed.incidentId)}`,
+);
+
+registerWriteTool(
+  "pd_incident_acknowledge",
+  {
+    mutates: "pagerduty.incident.acknowledge",
+    recoverable: true,
+    scopeTargetOf: (p) => ({ kind: "incident", value: p.incidentId }),
+  },
+  "Acknowledge an incident.",
+  z.object({ incidentId: z.string().min(1) }),
+  async (parsed) => pdIncidentPutMutation("acknowledge", "acknowledge", parsed.incidentId),
+);
+
+registerWriteTool(
+  "pd_incident_resolve",
+  {
+    mutates: "pagerduty.incident.resolve",
+    recoverable: true,
+    scopeTargetOf: (p) => ({ kind: "incident", value: p.incidentId }),
+  },
+  "Resolve an incident.",
+  z.object({ incidentId: z.string().min(1) }),
+  async (parsed) => pdIncidentPutMutation("resolve", "resolve", parsed.incidentId),
+);
+
+registerWriteTool(
+  "pd_incident_escalate",
+  {
+    mutates: "pagerduty.incident.escalate",
+    recoverable: true,
+    scopeTargetOf: (p) => ({ kind: "incident", value: p.incidentId }),
+  },
+  "Escalate an incident.",
+  z.object({ incidentId: z.string().min(1) }),
+  async (parsed) => pdIncidentPutMutation("escalate", "escalate", parsed.incidentId),
+);
+
+const transport = new StdioServerTransport();
+await mcp.connect(transport);

package/connectors/pipedrive/nimbus.extension.json

@@ -0,0 +1,15 @@
+{
+  "id": "com.nimbus.pipedrive",
+  "displayName": "Pipedrive",
+  "version": "0.1.0",
+  "description": "Pipedrive connector (read-only). Surfaces the user's Pipedrive CRM deals as `pipedrive:deal` items in the local index — the deal title, value + currency, status (open/won/lost), stage and pipeline ids, the linked person/organization names, the owner, probability, label, expected close date, and won/close times. Useful for answering sales questions (\"what deals are closing this month?\", \"find the Acme renewal deal\") without leaving Nimbus. Auth is via the API token IN THE QUERY STRING (`?api_token=<token>`) — there is NO Authorization header, so the request URL itself carries the secret and is never logged or surfaced in errors. The SaaS host (api.pipedrive.com) is fixed. Pipedrive paginates `/v1/deals` by `start`/`next_start` offsets (page_size=100), returning the `{ success, data, additional_data: { pagination: { more_items_in_collection, next_start } } }` envelope; `data` may be null. Pipedrive's `add_time` / `update_time` are non-ISO `\"YYYY-MM-DD HH:MM:SS\"` UTC strings (converted to epoch-ms on index). Persons / organizations / activities / notes are deferred follow-ups; v1 indexes deals only.",
+  "author": "Nimbus",
+  "entrypoint": "dist/server.js",
+  "runtime": "bun",
+  "permissions": {
+    "network": ["api.pipedrive.com"]
+  },
+  "hitlRequired": [],
+  "syncInterval": 600,
+  "minNimbusVersion": "0.2.0"
+}

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

@@ -0,0 +1,11 @@
+import {
+  fieldsFromKeys,
+  makeQueryFilter,
+  type SearchMatchOptions,
+} from "../../../shared/search-filter.ts";
+
+export type PipedriveSearchMatchOptions = SearchMatchOptions;
+
+export const filterPipedriveDeals = makeQueryFilter(
+  fieldsFromKeys(["title", "status", "org_name", "person_name", "owner_name", "label"]),
+);

package/connectors/pipedrive/src/server.ts

@@ -0,0 +1,62 @@
+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 { filterPipedriveDeals } from "./search-filter.ts";
+
+const BASE = "https://api.pipedrive.com";
+
+function apiToken(): string {
+  const t = process.env["PIPEDRIVE_TOKEN"]?.trim();
+  if (t === undefined || t === "") {
+    throw new Error("PIPEDRIVE_TOKEN is not set");
+  }
+  return t;
+}
+
+function withToken(path: string): string {
+  const sep = path.includes("?") ? "&" : "?";
+  return `${BASE}${path}${sep}api_token=${encodeURIComponent(apiToken())}`;
+}
+
+async function pipedriveGet(path: string, resourceLabel: string): Promise<unknown> {
+  const res = await fetch(withToken(path), { headers: { Accept: "application/json" } });
+  const text = await res.text();
+  if (!res.ok) {
+    throw new Error(`Pipedrive ${resourceLabel} ${String(res.status)}: ${text.slice(0, 400)}`);
+  }
+  return JSON.parse(text) as unknown;
+}
+
+await runReadOnlyMcpConnector("nimbus-pipedrive", (reg) => {
+  reg(
+    "pipedrive_list",
+    "List the user's Pipedrive deals (`GET /v1/deals?limit=100`). Returns the `{ success, data: [...], additional_data: { pagination } }` envelope — `data` holds the deal objects (and may be null when there are no deals).",
+    z.object({}),
+    async () => {
+      return jsonResult(await pipedriveGet(`/v1/deals?limit=100`, "deals"));
+    },
+  );
+
+  reg(
+    "pipedrive_get",
+    "Fetch one Pipedrive deal by its id (`GET /v1/deals/{id}`). Returns the `{ success, data: {...} }` envelope. Throws when no match is found.",
+    z.object({
+      id: z.string().min(1),
+    }),
+    async (p) => {
+      return jsonResult(await pipedriveGet(`/v1/deals/${encodeURIComponent(p.id)}`, "deal"));
+    },
+  );
+
+  reg(
+    "pipedrive_search",
+    "Substring search across the user's Pipedrive deals (first page only). Matches the query against the deal title, status, organization name, person name, owner name, and label (case-insensitive). Returns a `{ matches: [...] }` envelope.",
+    searchToolInputSchema(100),
+    async (p) => {
+      const root = await pipedriveGet(`/v1/deals?limit=100`, "deals");
+      const data = (root as { data?: unknown } | null)?.data;
+      return matchesResult(data, filterPipedriveDeals, p);
+    },
+  );
+});