@nimbus-dev/connectors 0.2.3 → 0.3.0

package/connectors/readwise/src/tools.ts

@@ -6,15 +6,15 @@ import {
 } from "../../../shared/collection-tool-kit.ts";
 import { createJsonGetter, envAuthHeaders } from "../../../shared/env-json-api.ts";
 import type { ZodToolRegistrar } from "../../../shared/run-read-only-mcp-connector.ts";
+import { READWISE_BASE } from "./readwise-base.ts";
 import { filterReadwiseBooks, filterReadwiseHighlights } from "./search-filter.ts";
 
-const BASE = "https://readwise.io";
 const HIGHLIGHTS = "/api/v2/highlights/?page_size=1000";
 const BOOKS = "/api/v2/books/?page_size=1000";
 
 /** Readwise authenticates with `Authorization: Token <key>`, not Bearer. */
 const readwiseGet = createJsonGetter({
-  base: BASE,
+  base: READWISE_BASE,
   label: "Readwise",
   headers: envAuthHeaders({ env: "READWISE_TOKEN", scheme: "Token" }),
 });

package/connectors/slack/src/server.ts

@@ -1,8 +1,12 @@
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { CONSENT_SERVER_CAPABILITIES } from "../../../shared/consent-kit.ts";
 import { registerSlackTools } from "./tools.ts";
 
-const server = new McpServer({ name: "nimbus-slack", version: "0.1.0" });
+const server = new McpServer(
+  { name: "nimbus-slack", version: "0.1.0" },
+  { capabilities: CONSENT_SERVER_CAPABILITIES },
+);
 
 registerSlackTools(server);
 

package/connectors/teams/src/server.ts

@@ -1,8 +1,12 @@
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { CONSENT_SERVER_CAPABILITIES } from "../../../shared/consent-kit.ts";
 import { registerTeamsTools } from "./tools.ts";
 
-const server = new McpServer({ name: "nimbus-teams", version: "0.1.0" });
+const server = new McpServer(
+  { name: "nimbus-teams", version: "0.1.0" },
+  { capabilities: CONSENT_SERVER_CAPABILITIES },
+);
 
 registerTeamsTools(server);
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nimbus-dev/connectors",
-  "version": "0.2.3",
+  "version": "0.3.0",
   "publishConfig": {
     "access": "public"
   },
@@ -26,7 +26,7 @@
   ],
   "dependencies": {
     "@modelcontextprotocol/sdk": "1.32.0",
-    "@nimbus-dev/sdk": "^2.0.0",
+    "@nimbus-dev/sdk": "^2.1.0",
     "@types/nodemailer": "^8.0.2",
     "zod": "^4.6.5"
   },

package/shared/cli-json-kit.ts

@@ -29,12 +29,7 @@
 
 import { z } from "zod";
 import { optionalEnv } from "./env-json-api.ts";
-import {
-  awsCliArgProblem,
-  awsCliDocumentProblem,
-  azCliArgProblem,
-  cliArgProblem,
-} from "./safe-cli-arg.ts";
+import { awsCliArgProblem, azCliArgProblem, cliArgProblem } from "./safe-cli-arg.ts";
 
 /** Body-snippet length in the thrown error. The value every connector used. */
 export const DEFAULT_STDERR_SNIPPET = 400;
@@ -68,13 +63,6 @@ export const cliArg = cliArgSchema(cliArgProblem);
  */
 export const awsCliArg = cliArgSchema(awsCliArgProblem);
 
-/**
- * A DOCUMENT passed to the `aws` CLI as one argument — a CloudFormation template body. Unlike
- * {@link awsCliArg} it may span lines and run past 1024 characters; it still may not start with `-`
- * or with a prefix that makes the CLI read it from somewhere else.
- */
-export const awsCliDocument = cliArgSchema(awsCliDocumentProblem);
-
 /**
  * A value passed to the `az` CLI as an argument: {@link cliArg}, and not one `az` would replace by
  * a file's contents — a leading `@`, or `=@` anywhere.

package/shared/consent-kit.ts

@@ -59,6 +59,19 @@ export type ConsentServer = {
   sendLoggingMessage(params: { level: "info" | "warning"; data: unknown }): Promise<void>;
 };
 
+/**
+ * What a connector with write tools constructs its `McpServer` with:
+ * `new McpServer(info, { capabilities: CONSENT_SERVER_CAPABILITIES })`.
+ *
+ * The kit tells the client about every gated outcome with `notifications/message`, and the SDK
+ * sends that only for a server that declared the MCP `logging` capability. No connector did, so
+ * each notification was dropped without a word. It must be declared at construction: that is the
+ * only moment the SDK installs its `logging/setLevel` handler, and a server that declared the
+ * capability later would refuse a client setting the level. `scripts/connector-boot.test.ts`
+ * fails a connector whose manifest declares a write and whose booted server does not declare it.
+ */
+export const CONSENT_SERVER_CAPABILITIES = { logging: {} };
+
 export type WriteToolConfig<T> = {
   /** Action type this tool performs, e.g. "repo.branch.delete". Machine-readable, not prose. */
   readonly mutates: string;
@@ -185,23 +198,32 @@ export function createWriteToolRegistrar(
     outcome: AuditOutcome,
     detail: Record<string, unknown>,
   ): Promise<void> {
-    // Meant as a client-visible channel, but it reaches no client today: the SDK sends
-    // `notifications/message` only for a server that declared the MCP `logging` capability, and
-    // no connector declares it. The durable log below is the only record.
-    await server.sendLoggingMessage({
-      level: outcome === "executed" ? "info" : "warning",
-      data: { connector: cfg.connector, tool, outcome },
-    });
-    // Durable channel: only when the operator configured a path. An append that fails rejects, and
-    // every record before the mutation is awaited, so a write whose entry did not land never runs.
-    if (auditLog !== undefined && auditLog !== "") {
-      await appendAuditEntry(auditLog, {
-        ts: new Date().toISOString(),
-        connector: cfg.connector,
-        tool,
-        outcome,
-        detail,
-      });
+    try {
+      // Durable channel first: only when the operator configured a path. An append that fails
+      // rejects, and every record before the mutation is awaited, so a write whose entry did not
+      // land never runs.
+      if (auditLog !== undefined && auditLog !== "") {
+        await appendAuditEntry(auditLog, {
+          ts: new Date().toISOString(),
+          connector: cfg.connector,
+          tool,
+          outcome,
+          detail,
+        });
+      }
+    } finally {
+      // Then the client-visible channel, told of every record attempted, one whose append failed
+      // included. It reaches the client because the connector declared the MCP `logging`
+      // capability (CONSENT_SERVER_CAPABILITIES), and a client may filter it by level. Best
+      // effort, and after the durable log: a client that has gone away mid-write must not keep the
+      // `executed` or `failed` record of a write that ran out of the log, and since the capability
+      // made this channel live, a dead pipe is where a send now fails.
+      await server
+        .sendLoggingMessage({
+          level: outcome === "executed" ? "info" : "warning",
+          data: { connector: cfg.connector, tool, outcome },
+        })
+        .catch(() => undefined);
     }
   }
 

package/shared/nimbus-spawn.ts

@@ -16,6 +16,36 @@ import { batchArgumentRefusal } from "./windows-batch-args.ts";
 
 export type SpawnResult = { code: number; stdout: string; stderr: string };
 
+/**
+ * The child's environment: `base` with `overrides` laid over it.
+ *
+ * On Windows a variable's name is case-insensitive, so an override replaces the base's variable
+ * whatever its spelling, instead of sitting beside it as a second one that the child may or may
+ * not see in its place. And the search path is spelled `PATH`, the only spelling Bun resolves a
+ * bare command through. A process started from PowerShell, cmd or Explorer has `Path`, and with it
+ * a bare `az` or `gcloud`, which are the batch files `az.cmd` and `gcloud.cmd` there, did not start
+ * at all: Bun 1.3.14 answered ENOENT, while an `.exe` such as `aws.exe` still started.
+ *
+ * Elsewhere names are case-sensitive, and the two are merged as written.
+ */
+export function childEnvironment(
+  base: Record<string, string | undefined>,
+  overrides: Record<string, string | undefined>,
+  platform: NodeJS.Platform = process.platform,
+): Record<string, string | undefined> {
+  if (platform !== "win32") {
+    return { ...base, ...overrides };
+  }
+  const byName = new Map<string, readonly [string, string | undefined]>();
+  for (const source of [base, overrides]) {
+    for (const [key, value] of Object.entries(source)) {
+      const name = key.toUpperCase();
+      byName.set(name, [name === "PATH" ? "PATH" : key, value]);
+    }
+  }
+  return Object.fromEntries(byName.values());
+}
+
 /**
  * The child's environment for `env`, and why `command` must not be spawned with it, if it must
  * not. Nothing is spawned for a refused command: it resolves as a failure whose stderr says so.
@@ -24,7 +54,7 @@ function prepareSpawn(
   command: readonly string[],
   env: Record<string, string | undefined>,
 ): { childEnv: Record<string, string | undefined>; refusal: SpawnResult | undefined } {
-  const childEnv = { ...process.env, ...env };
+  const childEnv = childEnvironment(process.env, env);
   const refusal = batchArgumentRefusal(command, childEnv);
   return {
     childEnv,

package/shared/run-read-only-mcp-connector.ts

@@ -1,5 +1,6 @@
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+import { CONSENT_SERVER_CAPABILITIES } from "./consent-kit.ts";
 import {
   createRegisterSimpleTool,
   createZodToolRegistrar,
@@ -41,7 +42,12 @@ export function buildReadOnlyMcpConnector(
   register: (reg: ZodToolRegistrar, server: unknown) => void,
   options?: BuildReadOnlyMcpConnectorOptions,
 ): unknown {
-  const make = options?.createServer ?? ((info) => new McpServer(info));
+  // Every server built here declares the MCP `logging` capability, since the consent kit's
+  // notifications reach a client only through it. A truly read-only connector sends no log
+  // message, so declaring it costs that connector nothing.
+  const make =
+    options?.createServer ??
+    ((info) => new McpServer(info, { capabilities: CONSENT_SERVER_CAPABILITIES }));
   const mcp = make({ name: serverName, version: "0.1.0" });
   const reg = createZodToolRegistrar(createRegisterSimpleTool(mcp));
   register(reg, mcp);

package/shared/safe-cli-arg.ts

@@ -124,26 +124,6 @@ export function awsCliArgProblem(value: unknown): string | undefined {
   return cliArgProblem(value) ?? awsPrefixProblem(value) ?? awsShorthandProblem(value);
 }
 
-/**
- * Why `value` must not be passed to the AWS CLI as a DOCUMENT — a CloudFormation template body —
- * or `undefined` when it may.
- *
- * A document legitimately spans lines and runs past the 1024 characters an argument is held to,
- * so of the argument rules only the two about where the CLI looks remain: a leading `-`, which the
- * CLI would parse as an option, and a loading prefix, which would make it read the "document" from
- * a file. `@=` is not among them: shorthand syntax applies to structure parameters, and a template
- * body is a string.
- */
-export function awsCliDocumentProblem(value: unknown): string | undefined {
-  if (typeof value !== "string" || value.length === 0) {
-    return "must be a non-empty string";
-  }
-  if (value.startsWith("-")) {
-    return 'must not start with "-" (argv flag smuggling is not allowed)';
-  }
-  return awsPrefixProblem(value);
-}
-
 // ---------------------------------------------------------------------------
 // az
 // ---------------------------------------------------------------------------

package/shared/windows-batch-args.ts

@@ -28,9 +28,9 @@
  * AWS resource name, an Azure app, cluster or node pool name, or a subscription id. An Azure
  * resource group may hold `(` and `)`, but never a space, so the runtime never quotes it and
  * `az.cmd` already failed on it as above. What did work and is now refused: an Azure subscription
- * passed by a display name holding one of these characters and a space — its id still works — and
- * a CloudFormation template body, whenever the `aws` that runs is a batch file: a pip-installed v1
- * found on `PATH` before any `aws.exe`.
+ * passed by a display name holding one of these characters and a space — its id still works. A
+ * CloudFormation template, full of quotes, was refused too whenever the `aws` that runs is a batch
+ * file, until it began to reach `aws` as a file instead of an argument.
  *
  * Which file runs is decided the way the runtime decides it — see {@link mayRunAsBatchFile} — so
  * an `aws.exe` found first is never refused, whatever batch file of that name comes later.
@@ -77,12 +77,25 @@ export function cmdMetacharacterIn(value: string): string | undefined {
   return undefined;
 }
 
+/**
+ * `name` without the dots and spaces at its end. A loop rather than `/[. ]+$/`, whose engine
+ * retries the run from every start position and so takes quadratic time on a long run of dots
+ * and spaces that something else follows.
+ */
+function withoutTrailingDotsAndSpaces(name: string): string {
+  let end = name.length;
+  while (end > 0 && (name[end - 1] === "." || name[end - 1] === " ")) {
+    end -= 1;
+  }
+  return name.slice(0, end);
+}
+
 /**
  * Whether Windows runs a file of this name through cmd.exe: a `.cmd` or a `.bat`, in any case,
  * after the trailing dots and spaces Windows drops from a file name — `az.cmd.` opens `az.cmd`.
  */
 export function isBatchFileName(name: string): boolean {
-  const trimmed = name.replace(/[. ]+$/, "").toLowerCase();
+  const trimmed = withoutTrailingDotsAndSpaces(name).toLowerCase();
   return BATCH_EXTENSIONS.some((ext) => trimmed.endsWith(ext));
 }
 
@@ -183,11 +196,12 @@ function firstHolderIsBatch(bases: readonly string[], exists: (path: string) =>
  *    and libuv starts only a `.com` or an `.exe`: never a batch file.
  *
  * It says yes where Bun could change without notice, and nowhere else: a PATH variable counts in
- * any spelling, not only `PATH` — today Bun reads no other, and a bare `az` with only `Path` set
- * does not start at all — and each is searched both as written and with whitespace and quotes
- * stripped from its entries; a name written with a `/` is looked up in its directory as one with
- * a `\` is; and the first place holding the name answers yes if it holds a `.cmd` or `.bat` by
- * that name, even beside an `.exe` Bun would try first.
+ * any spelling, not only `PATH` — Bun reads no other, though `nimbus-spawn.ts` respells the
+ * variable `PATH` before every spawn, so a bare `az` under `Path` starts too — and each is searched
+ * both as written and with whitespace and quotes stripped from its entries; a name written with a
+ * `/` is looked up in its directory as one with a `\` is; and the first place holding the name
+ * answers yes if it holds a `.cmd` or `.bat` by that name, even beside an `.exe` Bun would try
+ * first.
  */
 export function mayRunAsBatchFile(
   bin: string,