@pipeshub-ai/mcp 2.3.0 → 2.3.2

package/src/cli/init-qm.ts

@@ -89,10 +89,147 @@ RUN npm install -g "@pipeshub-ai/mcp@${version}" \\
 # ----------------------------------------------------------------------------
 `;
 
+/**
+ * Strip JSONC comments without mangling `//` inside string values.
+ *
+ * The naive version eats the second slash of `"https://example.com"` and turns
+ * a valid config into a parse error, which is a maddening failure to debug in
+ * a file the operator did not know we read.
+ */
+export function stripJsonComments(src: string): string {
+  let out = "";
+  let inString = false;
+  let inLine = false;
+  let inBlock = false;
+  for (let i = 0; i < src.length; i++) {
+    const c = src[i];
+    const next = src[i + 1];
+    if (inLine) {
+      if (c === "\n") { inLine = false; out += c; }
+      continue;
+    }
+    if (inBlock) {
+      if (c === "*" && next === "/") { inBlock = false; i++; }
+      continue;
+    }
+    if (inString) {
+      out += c;
+      if (c === "\\") { out += next ?? ""; i++; continue; }
+      if (c === '"') inString = false;
+      continue;
+    }
+    if (c === '"') { inString = true; out += c; continue; }
+    if (c === "/" && next === "/") { inLine = true; i++; continue; }
+    if (c === "/" && next === "*") { inBlock = true; i++; continue; }
+    out += c;
+  }
+  return out;
+}
+
+/**
+ * Drop trailing commas before `}` or `]`. JSONC allows them and hand-edited
+ * configs collect them; `JSON.parse` does not. Without this a stray comma makes
+ * the config unreadable, which fails open and writes the Dockerfile we were
+ * trying not to write.
+ */
+export function dropTrailingCommas(src: string): string {
+  let out = "";
+  let inString = false;
+  for (let i = 0; i < src.length; i++) {
+    const c = src[i];
+    if (inString) {
+      out += c;
+      if (c === "\\") { out += src[i + 1] ?? ""; i++; continue; }
+      if (c === '"') inString = false;
+      continue;
+    }
+    if (c === '"') { inString = true; out += c; continue; }
+    if (c === ",") {
+      let j = i + 1;
+      while (j < src.length && /\s/.test(src[j] as string)) j++;
+      if (src[j] === "}" || src[j] === "]") continue; // drop it
+    }
+    out += c;
+  }
+  return out;
+}
+
+export interface DeploymentShape {
+  target?: string | undefined;
+  backend?: string | undefined;
+}
+
+/**
+ * Read `target` and `sandbox.backend` from the operator's existing
+ * qm.config.jsonc. Returns null when there is no readable config — a fresh
+ * directory, or a file we cannot parse. Never throws: this only decides how
+ * much to scaffold, and a config we cannot read must not stop the scaffold.
+ */
+export async function readDeploymentShape(
+  dest: string,
+): Promise<DeploymentShape | null> {
+  try {
+    const raw = await readFile(join(dest, "qm.config.jsonc"), "utf8");
+    const cfg = JSON.parse(dropTrailingCommas(stripJsonComments(raw))) as {
+      target?: unknown;
+      sandbox?: { backend?: unknown };
+    };
+    const target = typeof cfg.target === "string" ? cfg.target : undefined;
+    const backend = typeof cfg.sandbox?.backend === "string"
+      ? cfg.sandbox.backend
+      : undefined;
+    if (!target && !backend) return null;
+    return { target, backend };
+  } catch {
+    return null;
+  }
+}
+
+/**
+ * Why a custom sandbox image cannot boot for this deployment, or null when it
+ * can. A reason rather than a boolean so the report can never describe a
+ * deployment as something it is not.
+ *
+ * `backend` is what decides where sandboxes run, not `target`: the CLI requires
+ * `"backend": "aws"` to have `target: "aws"` but not the reverse, so an AWS
+ * control plane running Sprites sandboxes is a supported and different thing
+ * from Lambda MicroVMs (`config.js:1106-1112`).
+ *
+ * This describes QM as it behaves today. If yc-software/qm#272 is fixed so
+ * Sprites boot a published image, the Sprites case here stops being true.
+ */
+export type ImageSkipReason = "sprites-ignores-image" | "aws-microvm" | null;
+
+export function imageSkipReason(shape: DeploymentShape | null): ImageSkipReason {
+  if (!shape) return null;
+  // Lambda MicroVMs have no install mechanism at all (qm#350).
+  if (shape.backend === "aws") return "aws-microvm";
+  // Sprites boot the stock base and ignore a published image (qm#272).
+  if (shape.backend === "sprites" || shape.target === "fly") {
+    return "sprites-ignores-image";
+  }
+  // An AWS target with no backend declared cannot run agents yet; skip rather
+  // than write a file whose fate depends on a choice not made.
+  if (shape.target === "aws") return "sprites-ignores-image";
+  return null;
+}
+
+/**
+ * Whether to scaffold a Dockerfile. Unknown shapes scaffold as before:
+ * guessing wrong in that direction removes a file someone needs.
+ */
+export function customImageBoots(shape: DeploymentShape | null): boolean {
+  return imageSkipReason(shape) === null;
+}
+
 export interface InitResult {
   written: string[];
   skipped: string[];
-  dockerfileAction: "created" | "appended" | "manual";
+  dockerfileAction: "created" | "appended" | "manual" | "skipped-unusable";
+  shape: DeploymentShape | null;
+  skipReason: ImageSkipReason;
+  /** A Dockerfile an earlier version already wrote, on a deploy that cannot use it. */
+  staleDockerfile: boolean;
   version: string;
   configFragment: string;
 }
@@ -112,6 +249,7 @@ export async function initQm(
 
   const version = await packageVersion(root);
   const dest = resolve(targetDir);
+  const shape = await readDeploymentShape(dest);
   const written: string[] = [];
   const skipped: string[] = [];
 
@@ -133,7 +271,17 @@ export async function initQm(
   // has no PipesHub block yet, and otherwise leave it entirely alone.
   const dockerfile = join(dest, "sandbox", "Dockerfile");
   let dockerfileAction: InitResult["dockerfileAction"];
-  if (!await exists(dockerfile)) {
+  const skipReason = imageSkipReason(shape);
+  // An earlier version wrote this unconditionally. Leaving it is not neutral:
+  // upcoming QM validation rejects it outright, so the operator needs telling.
+  // Not deleted here — it is their file and may carry their own build steps.
+  let staleDockerfile = false;
+  if (skipReason !== null) {
+    // Deliberately not written. The skill installs the CLI on first use, which
+    // is the path that actually runs on these deployments.
+    staleDockerfile = await exists(dockerfile);
+    dockerfileAction = "skipped-unusable";
+  } else if (!await exists(dockerfile)) {
     await copyFile(join(bundle, "sandbox", "Dockerfile"), dockerfile);
     // Restamp the pin so it matches the version actually installed.
     const body = await readFile(dockerfile, "utf8");
@@ -157,9 +305,8 @@ export async function initQm(
     }
   }
 
-  // Do not swallow this. The fragment carries the `sandbox.env` block the
-  // operator must merge in, so reporting a successful init without it leaves
-  // them with a scaffold that cannot reach PipesHub and no sign of why.
+  // Do not swallow this. The fragment is part of the bundle contract; a
+  // successful init that cannot read it means the package was assembled wrong.
   const fragmentPath = join(bundle, "qm.config.fragment.jsonc");
   let configFragment: string;
   try {
@@ -171,7 +318,16 @@ export async function initQm(
     );
   }
 
-  return { written, skipped, dockerfileAction, version, configFragment };
+  return {
+    written,
+    skipped,
+    dockerfileAction,
+    version,
+    configFragment,
+    shape,
+    skipReason,
+    staleDockerfile,
+  };
 }
 
 export function renderInitReport(dest: string, r: InitResult): string {
@@ -183,6 +339,37 @@ export function renderInitReport(dest: string, r: InitResult): string {
   for (const f of r.skipped) lines.push(`  kept    ${f}  (already existed — use --force to replace)`);
   lines.push("");
 
+  if (r.dockerfileAction === "skipped-unusable") {
+    if (r.skipReason === "aws-microvm") {
+      lines.push("No sandbox/Dockerfile was written: AWS Lambda MicroVM sandboxes");
+      lines.push("have no way to install a binary, so the file could never run.");
+    } else {
+      lines.push("No sandbox/Dockerfile was written: Fly Sprites boot the stock");
+      lines.push("image and ignore a published one, so the file would look like the");
+      lines.push("install path while never running.");
+    }
+    lines.push("The skill installs the CLI on first use instead — that is the line");
+    lines.push("that actually executes, and it needs nothing from you.");
+    lines.push("");
+  }
+
+  if (r.staleDockerfile) {
+    lines.push("ACTION NEEDED: sandbox/Dockerfile already exists here, written by an");
+    lines.push("earlier version. This deployment cannot use it, and upcoming QM");
+    lines.push("validation rejects it rather than ignoring it — `qm check` will fail");
+    lines.push("with an error naming that file. Delete it, or remove the PipesHub");
+    lines.push("install block if the rest of it is yours.");
+    lines.push("");
+  }
+
+  if (r.skipReason === "aws-microvm") {
+    lines.push("Heads up on AWS: with Lambda MicroVM sandboxes the CLI cannot be");
+    lines.push("installed at all (yc-software/qm#350). The tool's guidance, network");
+    lines.push("allowlist, and approval rules still apply, but the binary will be");
+    lines.push("missing. The sprites backend is what this bundle is tested against.");
+    lines.push("");
+  }
+
   if (r.dockerfileAction === "appended") {
     lines.push("Appended the install block to your existing sandbox/Dockerfile.");
   } else if (r.dockerfileAction === "manual") {
@@ -195,20 +382,22 @@ export function renderInitReport(dest: string, r: InitResult): string {
   lines.push("");
   lines.push("Two things left to do:");
   lines.push("");
-  lines.push("1. Set your PipesHub origin in qm.config.jsonc. It must be a PUBLIC");
-  lines.push("   HTTPS address — QM sandboxes do not run on your machine, so");
-  lines.push("   localhost and LAN addresses are unreachable from them:");
+  lines.push("1. Set `egress` in sandbox/tools/pipeshub/tool.json to your PipesHub");
+  lines.push("   hostname (no scheme, no path). It must be reachable over public HTTPS");
+  lines.push("   — QM sandboxes do not run on your machine, so localhost is unreachable.");
   lines.push("");
-  lines.push('     "sandbox": {');
-  lines.push('       "env": { "PIPESHUB_BASE_URL": "https://pipeshub.your-company.com" }');
-  lines.push("     }");
+  lines.push("2. Each person adds two personal keychain entries (service: pipeshub):");
+  lines.push("     PIPESHUB_TOKEN     → their PAT (never paste it into chat)");
+  lines.push("     PIPESHUB_BASE_URL  → public HTTPS origin, no /mcp path");
+  lines.push("   Do NOT put a token in sandbox.secretEnv (org-wide). Do NOT rely on");
+  lines.push("   sandbox.env for the URL — it does not reach the sandbox.");
   lines.push("");
-  lines.push("   Do NOT put anyone's token in sandbox.secretEnv — that is org-wide and");
-  lines.push("   would hand one person's credential to everybody. Each person adds");
-  lines.push("   their own to their own keychain (service: pipeshub, kind: env).");
+  lines.push("Then:  qm check && qm up");
   lines.push("");
-  lines.push("2. Set `egress` in sandbox/tools/pipeshub/tool.json to your hostname,");
-  lines.push("   then run:  qm check && qm sandbox publish && qm up");
+  if (r.dockerfileAction !== "skipped-unusable") {
+    lines.push("On Sprites, `qm sandbox publish` does not put pipeshub on PATH.");
+    lines.push("The skill installs the CLI on first use.");
+  }
   return lines.join("\n");
 }
 

package/src/cli/pipeshub.ts

@@ -244,13 +244,14 @@ async function run(argv: string[]): Promise<number> {
 
   if (origin === null) {
     // Report the missing credential too when both are absent. Otherwise a
-    // person whose actual problem is "I never added my token" is told about an
-    // admin-level setting, and goes looking in the wrong place.
+    // person whose actual problem is "I never added my token" is told about a
+    // missing URL, and goes looking in the wrong place.
     const alsoNoToken = token === null
       ? " Your PipesHub credential is also missing ($PIPESHUB_TOKEN is unset)."
       : "";
     throw new CliError(
-      "PIPESHUB_BASE_URL is not set — an admin sets it once for the deployment."
+      "PIPESHUB_BASE_URL is not set — it must reach the sandbox as an env var "
+        + "(keychain or org service credential, not sandbox.env)."
         + alsoNoToken
         + " Run 'pipeshub auth connect-help' for the steps.",
       EXIT.USAGE,

package/src/mcp-server/tools/_helpers.ts

@@ -15,11 +15,23 @@ import {
 
 /**
  * Parse a fetch Response as JSON, returning a CallToolResult error when the
- * body is missing / malformed.
+ * status is not ok, or the body is missing / malformed.
+ *
+ * The status check has to happen here rather than in each caller. The SDK funcs
+ * are generated with `errorCodes: []`, so `result.ok` reports transport
+ * failures only and a 401 arrives looking exactly like a success. Parsing that
+ * body yields an envelope with no results in it, which every caller then
+ * reports as an empty corpus — a failed credential becomes "no documents
+ * found". Guarding at the single point where a body is turned into a value
+ * closes that for every present and future caller.
  */
 export async function readJson<T = unknown>(
   response: Response,
+  context = "PipesHub request",
 ): Promise<{ ok: true; value: T } | { ok: false; result: CallToolResult }> {
+  const httpErr = await httpErrorResult(response, context);
+  if (httpErr) return { ok: false, result: httpErr };
+
   const text = await response.text();
   if (!text) {
     return {
@@ -48,6 +60,24 @@ export async function readJson<T = unknown>(
   }
 }
 
+/**
+ * Reject an access token whose own expiry has already passed.
+ *
+ * Expiry is the one part of a credential's validity that can be established
+ * without asking the server, so it is worth checking before spending a
+ * round-trip — and it still answers when the server is unreachable. Returns
+ * `null` when the token is unexpired or carries no usable `exp`.
+ */
+export function expiredTokenError(exp: unknown): CallToolResult | null {
+  if (typeof exp !== "number" || !Number.isFinite(exp)) return null;
+  if (exp * 1000 > Date.now()) return null;
+  return errorResult(
+    `The access token expired on ${new Date(exp * 1000).toISOString()}. `
+      + "Mint a new personal access token in PipesHub under "
+      + "Developer Settings → Personal Access Tokens.",
+  );
+}
+
 /** Return a CallToolResult holding a single JSON-stringified text block. */
 export function jsonResult(value: unknown): CallToolResult {
   return {
@@ -105,7 +135,12 @@ export async function httpErrorResult(
     }
   }
 
-  const detail = message ? ` ${message.slice(0, 400)}` : "";
+  // The server's reason rarely ends in punctuation, which runs it straight
+  // into the hint below ("Invalid token Check that ...").
+  const reason = message.slice(0, 400).trim();
+  const detail = reason
+    ? ` ${/[.!?]$/.test(reason) ? reason : `${reason}.`}`
+    : "";
   const auth = (response.status === 401 || response.status === 403)
     ? " Check that the bearer token / credentials are valid and not expired."
     : "";
@@ -122,7 +157,12 @@ export async function httpErrorResult(
 export async function readValidated<T>(
   response: Response,
   schema: z.ZodType<T>,
+  context = "PipesHub request",
 ): Promise<{ ok: true; value: T } | { ok: false; result: CallToolResult }> {
+  // Same reasoning as readJson: never let a non-2xx body reach the parser.
+  const httpErr = await httpErrorResult(response, context);
+  if (httpErr) return { ok: false, result: httpErr };
+
   const text = await response.text();
   if (!text) {
     return { ok: false, result: errorResult("Empty response from server") };

package/src/mcp-server/tools/pipeshubDirectory.ts

@@ -12,6 +12,7 @@ import {
   decodeBearer,
   errorResult,
   jsonResult,
+  expiredTokenError,
   readJson,
 } from "./_helpers.js";
 
@@ -24,8 +25,8 @@ const args = {
     "list_my_teams",
   ]).describe(
     "What to do:\n"
-      + "- `whoami` — return the authenticated user's identity (decoded from "
-      + "the bearer JWT). No other args needed.\n"
+      + "- `whoami` — return the authenticated user's identity, confirmed "
+      + "against the server. No other args needed.\n"
       + "- `list_users` — paginated list of org users. Optional `page`, "
       + "`limit`, `search` (substring match against name or email).\n"
       + "- `get_user` — full profile for one user. Required `userId`. "
@@ -56,7 +57,8 @@ actions — pick the right \`action\`:
 
 - \`whoami\` — who is the caller?  Use this whenever you need the
   authenticated user's own id, email, or full name (e.g. before
-  \`get_user\` on themselves).
+  \`get_user\` on themselves). Errors if the credential is expired
+  or revoked.
 - \`list_users\` — search / page through org users.
 - \`get_user\` — full \`User\` document for one user (requires \`userId\`).
 - \`list_groups\` — list user groups with \`userCount\`.
@@ -86,6 +88,56 @@ Output shape varies by action; see each action's docs above.`,
               + "their email and use `list_users` with `search`.",
           );
         }
+        // The claims come out of the local token, which proves nothing about
+        // whether the server still accepts it — a revoked token carries a
+        // perfectly good name and org. Since whoami is the command people run
+        // to check "is my login working?", answering from the token alone
+        // gives a confident yes in exactly the case that matters.
+        //
+        // Expiry is checkable offline, so check it first: it is the common
+        // case and costs no round-trip.
+        const exp = claims["exp"];
+        const expired = expiredTokenError(exp);
+        if (expired) return expired;
+        const tokenExpiresAt = typeof exp === "number"
+          ? new Date(exp * 1000).toISOString()
+          : undefined;
+
+        // Revocation can only be established by asking the server. get_user on
+        // the caller's own id needs `user:read`, which whoami's callers already
+        // hold, and returns 401 for a rejected credential.
+        const userId = claims["userId"];
+        let verified: true | "unchecked" = "unchecked";
+        let unverifiedReason: string | undefined =
+          "No userId claim in the token, so the identity could not be "
+          + "confirmed with the server.";
+
+        if (typeof userId === "string" && userId) {
+          const [probe] = await usersGetUserById(client, { id: userId }, {
+            fetchOptions,
+          }).$inspect();
+
+          if (!probe.ok) {
+            unverifiedReason = `Could not reach PipesHub to confirm the `
+              + `identity (${probe.error.message}). The details below come `
+              + `from the token itself.`;
+          } else if (probe.value.status === 401) {
+            return errorResult(
+              "PipesHub rejected this access token (HTTP 401 Unauthorized), "
+                + "so the identity in it is no longer valid — it has most "
+                + "likely been revoked. Mint a new personal access token "
+                + "under Developer Settings → Personal Access Tokens.",
+            );
+          } else if (probe.value.ok) {
+            verified = true;
+            unverifiedReason = undefined;
+          } else {
+            unverifiedReason = `PipesHub returned HTTP ${probe.value.status} `
+              + `when confirming the identity, so it could not be checked. `
+              + `The details below come from the token itself.`;
+          }
+        }
+
         return jsonResult({
           userId: claims["userId"],
           orgId: claims["orgId"],
@@ -93,6 +145,12 @@ Output shape varies by action; see each action's docs above.`,
           fullName: claims["fullName"],
           mobile: claims["mobile"],
           userSlug: claims["userSlug"],
+          tokenExpiresAt,
+          // Never `false`: that reads as "the server rejected this identity",
+          // which is a different and much more alarming claim than "this was
+          // not checked". A rejection returns an error above instead.
+          identityVerified: verified,
+          note: unverifiedReason,
         });
       }
 
@@ -103,7 +161,7 @@ Output shape varies by action; see each action's docs above.`,
           search: args.search,
         }, { fetchOptions }).$inspect();
         if (!result.ok) return errorResult(result.error.message);
-        const parsed = await readJson(result.value);
+        const parsed = await readJson(result.value, "User listing");
         if (!parsed.ok) return parsed.result;
         return jsonResult(parsed.value);
       }
@@ -120,7 +178,7 @@ Output shape varies by action; see each action's docs above.`,
           id: args.userId,
         }, { fetchOptions }).$inspect();
         if (!result.ok) return errorResult(result.error.message);
-        const parsed = await readJson(result.value);
+        const parsed = await readJson(result.value, "User lookup");
         if (!parsed.ok) return parsed.result;
         return jsonResult(parsed.value);
       }
@@ -132,7 +190,7 @@ Output shape varies by action; see each action's docs above.`,
           search: args.search,
         }, { fetchOptions }).$inspect();
         if (!result.ok) return errorResult(result.error.message);
-        const parsed = await readJson(result.value);
+        const parsed = await readJson(result.value, "Group listing");
         if (!parsed.ok) return parsed.result;
         return jsonResult(parsed.value);
       }
@@ -144,7 +202,7 @@ Output shape varies by action; see each action's docs above.`,
           search: args.search,
         }, { fetchOptions }).$inspect();
         if (!result.ok) return errorResult(result.error.message);
-        const parsed = await readJson(result.value);
+        const parsed = await readJson(result.value, "Team listing");
         if (!parsed.ok) return parsed.result;
         return jsonResult(parsed.value);
       }

package/src/mcp-server/tools/pipeshubSearch.ts

@@ -80,7 +80,7 @@ When presenting results to the user, link each record using its
         status?: string;
         message?: string;
       };
-    }>(result.value);
+    }>(result.value, "PipesHub search");
     if (!parsed.ok) return parsed.result;
 
     const sr = parsed.value.searchResponse ?? {};

package/src/mcp-server/tools/pipeshubSources.ts

@@ -57,7 +57,7 @@ are returned by default; pass \`include\` to override.`,
         limit: 200,
       }, { fetchOptions }).$inspect();
       if (!r.ok) return errorResult(`sources: ${r.error.message}`);
-      const parsed = await readJson<{ items?: any[] }>(r.value);
+      const parsed = await readJson<{ items?: any[] }>(r.value, "Knowledge base listing");
       if (!parsed.ok) return parsed.result;
       result["sources"] = (parsed.value.items ?? []).map((n: any) => ({
         id: n.id,
@@ -79,7 +79,7 @@ are returned by default; pass \`include\` to override.`,
         modelType,
       }, { fetchOptions }).$inspect();
       if (!r.ok) return errorResult(`${key}: ${r.error.message}`);
-      const parsed = await readJson<{ models?: any[] }>(r.value);
+      const parsed = await readJson<{ models?: any[] }>(r.value, "Model listing");
       if (!parsed.ok) return parsed.result;
       result[key] = (parsed.value.models ?? []).map((m: any) => ({
         modelKey: m.modelKey,

package/src/tool-names.ts

@@ -22,7 +22,7 @@ export const toolNames: Array<{ name: string; description: string }>= [
   },
   {
     "name": "pipeshub_directory",
-    "description": "Look up people, groups, and teams in PipesHub. One tool with five\nactions — pick the right `action`:\n\n- `whoami` — who is the caller?  Use this whenever you need the\n  authenticated user's own id, email, or full name (e.g. before\n  `get_user` on themselves).\n- `list_users` — search / page through org users.\n- `get_user` — full `User` document for one user (requires `userId`).\n- `list_groups` — list user groups with `userCount`.\n- `list_my_teams` — teams the caller belongs to, with capability flags\n  (`canEdit` / `canDelete` / `canManageMembers`).\n\nOutput shape varies by action; see each action's docs above."
+    "description": "Look up people, groups, and teams in PipesHub. One tool with five\nactions — pick the right `action`:\n\n- `whoami` — who is the caller?  Use this whenever you need the\n  authenticated user's own id, email, or full name (e.g. before\n  `get_user` on themselves). Errors if the credential is expired\n  or revoked.\n- `list_users` — search / page through org users.\n- `get_user` — full `User` document for one user (requires `userId`).\n- `list_groups` — list user groups with `userCount`.\n- `list_my_teams` — teams the caller belongs to, with capability flags\n  (`canEdit` / `canDelete` / `canManageMembers`).\n\nOutput shape varies by action; see each action's docs above."
   },
   {
     "name": "pipeshub_agents",