@cursor/july 0.1.68 → 0.1.74

package/src/internal/cursor/account-mcp.ts

@@ -23,9 +23,22 @@ import {
 import { bearerAuth } from "../../channels.js";
 import type { AgentProject, AuthPolicy } from "../../types.js";
 import { isCursorAccountTransport } from "../../types.js";
+import { probeConnectorAuthUrls } from "../cursor-account-mcp-auth.js";
+import { LOG_PREFIX } from "../distribution.js";
 import { handleStatelessMcpRequest } from "../mcp-endpoint.js";
 import { isLoopbackAddress } from "../net.js";
+import {
+  sanitizeMcpToolName,
+  suffixMcpToolName,
+} from "../sanitize-mcp-tool-name.js";
 import type { EngineResolvedConnection } from "../session-engine.js";
+import {
+  colorEnabledFor,
+  formatTerminalBox,
+  stdoutPalette,
+  type TerminalPalette,
+  terminalHyperlink,
+} from "../terminal-style.js";
 import type {
   AccountMcpServer,
   CursorBackendClient,
@@ -38,8 +51,13 @@ const CATALOG_TTL_MS = 60_000;
  * a model hallucinating tool names cannot turn into a backend hot loop.
  */
 const FORCE_REFRESH_MIN_INTERVAL_MS = 5_000;
-/** MCP clients commonly enforce `^[a-zA-Z0-9_-]{1,128}$` for tool names. */
-const MAX_TOOL_NAME_LENGTH = 128;
+
+/** Dashboard Integrations & MCP — reconnect team / account connectors. */
+export const CURSOR_ACCOUNT_MCP_DASHBOARD_URL =
+  "https://cursor.com/dashboard/integrations";
+/** Cursor app Settings → MCP (Connect / Authenticate on the named row). */
+export const CURSOR_ACCOUNT_MCP_SETTINGS_DEEPLINK =
+  "cursor://anysphere.cursor-deeplink/customize?tab=mcp";
 
 // ============================================================================
 // Authored account MCP connections (validated refs, mirroring peer MCP connections)
@@ -131,6 +149,8 @@ interface CatalogTool {
   serverIdentifier: string;
   description: string;
   inputSchema: Record<string, unknown>;
+  /** Present only when the connector's server declares one. */
+  outputSchema?: Record<string, unknown>;
 }
 
 interface Catalog {
@@ -155,6 +175,7 @@ export class CursorAccountMcpBridge {
   readonly secret: string = randomBytes(32).toString("hex");
   private readonly client: CursorBackendClient;
   private readonly logger: (line: string) => void;
+  private readonly palette: TerminalPalette;
   private readonly secretPolicy: AuthPolicy;
   private readonly allowRemoteCallers: boolean;
   private readonly catalogs = new Map<string, CatalogEntry>();
@@ -162,6 +183,8 @@ export class CursorAccountMcpBridge {
   constructor(args: {
     client: CursorBackendClient;
     logger?: (line: string) => void;
+    /** Defaults to stdout; tests pass `makePalette(false)` for a plain box. */
+    palette?: TerminalPalette;
     /**
      * Admit non-loopback callers presenting the secret. Only set when the
      * serve host configured a `publicUrl` (cloud turns reach the bridge
@@ -171,6 +194,7 @@ export class CursorAccountMcpBridge {
   }) {
     this.client = args.client;
     this.logger = args.logger ?? (() => {});
+    this.palette = args.palette ?? stdoutPalette();
     this.secretPolicy = bearerAuth(this.secret);
     this.allowRemoteCallers = args.allowRemoteCallers === true;
   }
@@ -213,9 +237,9 @@ export class CursorAccountMcpBridge {
 
   /**
    * Startup DX: log the account's connector statuses for `refs` without
-   * blocking serve startup. Surfaces "needsAuth" / "error" connectors with
-   * remediation hints (and a backend probe detail for `error`), and filters
-   * that matched nothing (typo'd connector names).
+   * blocking serve startup. Healthy catalogs stay a one-line summary;
+   * `needsAuth` / `error` / empty catalogs render a yellow warning box with
+   * reconnect URLs.
    *
    * Returns a promise that settles when every ref's log lines are written —
    * callers may ignore it; tests can await it.
@@ -229,28 +253,50 @@ export class CursorAccountMcpBridge {
   private async runPreflight(ref: CursorAccountConnectionRef): Promise<void> {
     try {
       const catalog = await this.getCatalog(ref);
-      if (catalog.servers.length === 0) {
+      const errorDetails = new Map<string, string>();
+      const needsAuthNames = catalog.servers
+        .filter((server) => server.status === "needsAuth")
+        .map((server) => server.serverIdentifier);
+      const [authUrls] = await Promise.all([
+        probeConnectorAuthUrls({
+          client: this.client,
+          identifiers: needsAuthNames,
+        }),
+        Promise.all(
+          catalog.servers
+            .filter((server) => server.status === "error")
+            .map(async (server) => {
+              const detail = await diagnoseConnectorError(
+                this.client,
+                server.serverIdentifier
+              );
+              if (detail !== undefined) {
+                errorDetails.set(server.serverIdentifier, detail);
+              }
+            })
+        ),
+      ]);
+
+      const unhealthy = catalog.servers.some(
+        (server) => server.status === "needsAuth" || server.status === "error"
+      );
+      if (catalog.servers.length === 0 || unhealthy) {
         this.logger(
-          `[agent-sdk] Cursor account MCP connection "${ref.name}": no matching connectors on this account — connect servers in Cursor (dashboard → MCP) or fix the \`servers\` filter`
+          formatCursorAccountMcpWarningBox({
+            connectionName: ref.name,
+            servers: catalog.servers.map((server) => ({
+              serverIdentifier: server.serverIdentifier,
+              status: server.status,
+              toolCount: server.tools.length,
+              errorDetail: errorDetails.get(server.serverIdentifier),
+              authUrl: authUrls.get(server.serverIdentifier),
+            })),
+            palette: this.palette,
+          })
         );
         return;
       }
 
-      const errorDetails = new Map<string, string>();
-      await Promise.all(
-        catalog.servers
-          .filter((server) => server.status === "error")
-          .map(async (server) => {
-            const detail = await diagnoseConnectorError(
-              this.client,
-              server.serverIdentifier
-            );
-            if (detail !== undefined) {
-              errorDetails.set(server.serverIdentifier, detail);
-            }
-          })
-      );
-
       const summary = catalog.servers
         .map((server) =>
           formatServerStatusSummary(
@@ -260,41 +306,11 @@ export class CursorAccountMcpBridge {
         )
         .join(", ");
       this.logger(
-        `[agent-sdk] Cursor account MCP connection "${ref.name}": ${summary}`
-      );
-
-      const needsAuth = catalog.servers.filter(
-        (server) => server.status === "needsAuth"
+        `${LOG_PREFIX} Cursor account MCP connection "${ref.name}": ${summary}`
       );
-      if (needsAuth.length > 0) {
-        this.logger(
-          `[agent-sdk] Cursor account MCP connection "${ref.name}": ${needsAuth
-            .map((server) => server.serverIdentifier)
-            .join(
-              ", "
-            )} need re-authorization in Cursor (dashboard → MCP / Settings → MCP) before their tools appear`
-        );
-      }
-
-      const errored = catalog.servers.filter(
-        (server) => server.status === "error"
-      );
-      if (errored.length > 0) {
-        const details = errored
-          .map((server) => {
-            const detail = errorDetails.get(server.serverIdentifier);
-            return detail === undefined
-              ? server.serverIdentifier
-              : `${server.serverIdentifier} (${detail})`;
-          })
-          .join("; ");
-        this.logger(
-          `[agent-sdk] Cursor account MCP connection "${ref.name}": ${details} — Cursor backend could not use this connector (not a missing agent-sdk login). Re-check the server in Cursor dashboard → MCP, confirm the URL is healthy, and retry after the backend can reach it`
-        );
-      }
     } catch (error: unknown) {
       this.logger(
-        `[agent-sdk] Cursor account MCP connection "${ref.name}" preflight failed: ${describeError(error)}`
+        `${LOG_PREFIX} Cursor account MCP connection "${ref.name}" preflight failed: ${describeError(error)}`
       );
     }
   }
@@ -316,6 +332,9 @@ export class CursorAccountMcpBridge {
           name: tool.exposedName,
           description: tool.description,
           inputSchema: tool.inputSchema,
+          ...(tool.outputSchema === undefined
+            ? {}
+            : { outputSchema: tool.outputSchema }),
         })),
       };
     });
@@ -448,7 +467,7 @@ function buildCatalog(servers: AccountMcpServer[]): Catalog {
   >();
   for (const server of servers) {
     for (const tool of server.tools) {
-      const base = sanitizeToolName(tool.name);
+      const base = sanitizeMcpToolName(tool.name);
       const group = byBase.get(base);
       const item = { serverIdentifier: server.serverIdentifier, tool };
       if (group === undefined) {
@@ -477,10 +496,10 @@ function buildCatalog(servers: AccountMcpServer[]): Catalog {
     });
     group.forEach(({ serverIdentifier, tool }, index) => {
       let suffixIndex = index;
-      let exposedName = suffixToolName(base, suffixIndex);
+      let exposedName = suffixMcpToolName(base, suffixIndex);
       while (byExposedName.has(exposedName)) {
         suffixIndex++;
-        exposedName = suffixToolName(base, suffixIndex);
+        exposedName = suffixMcpToolName(base, suffixIndex);
       }
       const entry: CatalogTool = {
         exposedName,
@@ -488,6 +507,9 @@ function buildCatalog(servers: AccountMcpServer[]): Catalog {
         serverIdentifier,
         description: tool.description,
         inputSchema: tool.inputSchema,
+        ...(tool.outputSchema === undefined
+          ? {}
+          : { outputSchema: tool.outputSchema }),
       };
       tools.push(entry);
       byExposedName.set(entry.exposedName, entry);
@@ -496,29 +518,142 @@ function buildCatalog(servers: AccountMcpServer[]): Catalog {
   return { servers, tools, byExposedName };
 }
 
-/** Connector display names can contain anything (spaces, dots, emoji). */
-function sanitizeToolName(name: string): string {
-  const cleaned = name
-    .replace(/[^a-zA-Z0-9_-]/g, "_")
-    .slice(0, MAX_TOOL_NAME_LENGTH);
-  return cleaned === "" ? "tool" : cleaned;
+function trimTrailingSlash(url: string): string {
+  return url.endsWith("/") ? url.slice(0, -1) : url;
+}
+
+function describeError(error: unknown): string {
+  return error instanceof Error ? error.message : String(error);
+}
+
+export interface CursorAccountMcpWarningServer {
+  serverIdentifier: string;
+  status: string;
+  toolCount: number;
+  errorDetail?: string;
+  /** Minted OAuth URL for a `needsAuth` connector, when the probe succeeded. */
+  authUrl?: string;
 }
 
-/** `base` for the first claimant, `base_2` / `base_3` … for colliders. */
-function suffixToolName(base: string, index: number): string {
-  if (index === 0) {
-    return base;
+const MAX_ERROR_DETAIL_CHARS = 72;
+
+function truncateDetail(detail: string): string {
+  const trimmed = detail.trim();
+  if (trimmed.length <= MAX_ERROR_DETAIL_CHARS) {
+    return trimmed;
   }
-  const suffix = `_${index + 1}`;
-  return `${base.slice(0, MAX_TOOL_NAME_LENGTH - suffix.length)}${suffix}`;
+  return `${trimmed.slice(0, MAX_ERROR_DETAIL_CHARS - 1)}…`;
 }
 
-function trimTrailingSlash(url: string): string {
-  return url.endsWith("/") ? url.slice(0, -1) : url;
+function formatWarningStatusRow(
+  server: CursorAccountMcpWarningServer,
+  nameWidth: number,
+  hyperlinks: boolean
+): string {
+  const name = server.serverIdentifier.padEnd(nameWidth);
+  switch (server.status) {
+    case "needsAuth":
+      return `${name}  ${terminalHyperlink(connectUrl(server.authUrl), "Connect", hyperlinks)}`;
+    case "connected":
+      return `${name}  ${server.toolCount} tools`;
+    case "error": {
+      const detail =
+        server.errorDetail === undefined || server.errorDetail.trim() === ""
+          ? "backend could not reach connector"
+          : truncateDetail(server.errorDetail);
+      return `${name}  error: ${detail}`;
+    }
+    default:
+      return `${name}  ${server.status}`;
+  }
 }
 
-function describeError(error: unknown): string {
-  return error instanceof Error ? error.message : String(error);
+function connectUrl(authUrl: string | undefined): string {
+  const minted = authUrl?.trim() ?? "";
+  if (
+    minted.startsWith("https://") &&
+    !minted.includes("\u001b") &&
+    !minted.includes("\u0007")
+  ) {
+    return minted;
+  }
+  return CURSOR_ACCOUNT_MCP_DASHBOARD_URL;
+}
+
+/**
+ * Yellow warning panel for unhealthy / missing Cursor-account connectors.
+ * One box replaces the old stacked `[agent-sdk]` log lines.
+ */
+export function formatCursorAccountMcpWarningBox(args: {
+  connectionName: string;
+  servers: readonly CursorAccountMcpWarningServer[];
+  palette?: TerminalPalette;
+  hyperlinks?: boolean;
+}): string {
+  const palette = args.palette ?? stdoutPalette();
+  const hyperlinks = args.hyperlinks ?? colorEnabledFor();
+  const copy = warningCopy({ ...args, hyperlinks });
+  return `\n${formatTerminalBox(
+    [copy.title, "", ...copy.intro, ...copy.actions],
+    {
+      color: palette.yellow,
+      padding: 2,
+    }
+  )}`;
+}
+
+function warningCopy(args: {
+  connectionName: string;
+  servers: readonly CursorAccountMcpWarningServer[];
+  hyperlinks: boolean;
+}): { title: string; intro: string[]; actions: string[] } {
+  const empty = args.servers.length === 0;
+  const hasAuth = args.servers.some((server) => server.status === "needsAuth");
+  const hasError = args.servers.some((server) => server.status === "error");
+  const nameWidth = Math.max(
+    0,
+    ...args.servers.map((server) => server.serverIdentifier.length)
+  );
+  const statusRows = args.servers.map((server) =>
+    formatWarningStatusRow(server, nameWidth, args.hyperlinks)
+  );
+  const links = [
+    `  ${CURSOR_ACCOUNT_MCP_SETTINGS_DEEPLINK}`,
+    `  ${CURSOR_ACCOUNT_MCP_DASHBOARD_URL}`,
+  ];
+  const restart = "Then press Enter to restart this serve.";
+
+  if (empty) {
+    return {
+      title: "No matching MCP connectors",
+      intro: [
+        `No matching connectors on this account ("${args.connectionName}").`,
+      ],
+      actions: [
+        "",
+        "Connect servers in Cursor, or fix the `servers` filter.",
+        ...links,
+      ],
+    };
+  }
+  if (hasAuth && !hasError) {
+    return {
+      title: "MCP authorization needed",
+      intro: statusRows,
+      actions: ["", restart, "", "Or reconnect at:", ...links],
+    };
+  }
+  return {
+    title: hasAuth ? "MCP authorization needed" : "MCP connector error",
+    intro: statusRows,
+    actions: [
+      "",
+      "Re-check the server URL is healthy, then reconnect at:",
+      ...links,
+      "",
+      restart,
+    ],
+  };
 }
 
 /** One-line status for the preflight summary (`name (12 tools)` / `name (error: …)`). */

package/src/internal/cursor/backend-client.ts

@@ -83,6 +83,8 @@ const mcpToolSchema = z.object({
   description: z.string().optional(),
   /** `google.protobuf.Value` — an arbitrary JSON Schema object. */
   inputSchema: z.unknown().optional(),
+  /** Flat JSON-string output schema (`output_schema_json` on the proto). */
+  outputSchemaJson: z.string().optional(),
 });
 
 const getAvailableMcpServersResponseSchema = z.object({
@@ -146,6 +148,12 @@ export interface AccountMcpTool {
   description: string;
   /** JSON Schema for the tool input (defaulted when the server omits it). */
   inputSchema: Record<string, unknown>;
+  /**
+   * JSON Schema for the tool's structured output. Present only when the
+   * connector's server declares one — absent stays absent (never defaulted),
+   * matching the optional MCP `Tool.outputSchema` field.
+   */
+  outputSchema?: Record<string, unknown>;
 }
 
 export interface AccountMcpServer {
@@ -321,11 +329,15 @@ export class CursorBackendClient {
     return (parsed.servers ?? []).map((server) => ({
       serverIdentifier: server.serverIdentifier,
       status: server.status,
-      tools: (server.tools ?? []).map((tool) => ({
-        name: tool.name,
-        description: tool.description ?? "",
-        inputSchema: normalizeInputSchema(tool.inputSchema),
-      })),
+      tools: (server.tools ?? []).map((tool) => {
+        const outputSchema = parseOutputSchemaJson(tool.outputSchemaJson);
+        return {
+          name: tool.name,
+          description: tool.description ?? "",
+          inputSchema: normalizeInputSchema(tool.inputSchema),
+          ...(outputSchema === undefined ? {} : { outputSchema }),
+        };
+      }),
     }));
   }
 
@@ -376,16 +388,15 @@ export class CursorBackendClient {
   }
 
   /**
-   * Probe connectors for a service account and mint OAuth `authUrl`s where
-   * authorization is needed. This is the dashboard's Authenticate flow: the
-   * caller (a team member) opens the returned URL, the cursor.com callback
-   * stores the token backend-side against the service account, and repeat
-   * probes flip `requiresAuth` off.
+   * Probe connectors and mint OAuth `authUrl`s where authorization is
+   * needed. With `serviceAccountId`, this is the dashboard Authenticate
+   * flow for a hosted deployment's service account. Omit it to probe the
+   * signed-in user (local `serve` preflight).
    */
   async checkHttpMcpStatus(args: {
     serverIds: number[];
     oauthRedirectUri: string;
-    serviceAccountId: string;
+    serviceAccountId?: string;
   }): Promise<McpConnectorStatus[]> {
     const raw = await this.rpc(
       "CheckHttpMcpStatus",
@@ -669,6 +680,29 @@ function normalizeInputSchema(schema: unknown): Record<string, unknown> {
   return { type: "object", properties: {} };
 }
 
+/**
+ * Parse the proto's flat-JSON-string output schema. Unlike
+ * {@link normalizeInputSchema} there is no fallback: outputSchema is optional
+ * on the MCP wire, so absence (or malformed JSON crossing the backend
+ * boundary) means omitted.
+ */
+function parseOutputSchemaJson(
+  outputSchemaJson: string | undefined
+): Record<string, unknown> | undefined {
+  if (outputSchemaJson === undefined) {
+    return undefined;
+  }
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(outputSchemaJson);
+  } catch {
+    return undefined;
+  }
+  return typeof parsed === "object" && parsed !== null && !Array.isArray(parsed)
+    ? (parsed as Record<string, unknown>)
+    : undefined;
+}
+
 type McpResultJson = z.infer<typeof mcpResultSchema>;
 
 function toCallResult(result: McpResultJson): AccountMcpCallResult {

package/src/internal/cursor-account-mcp-auth.ts

@@ -204,6 +204,89 @@ function selectConnectors(
   return { servers, unmatched };
 }
 
+function uniqueConnectorMatch(
+  available: AvailableMcpServer[],
+  identifier: string
+): AvailableMcpServer | undefined {
+  const wanted = identifier.trim().toLowerCase();
+  if (wanted === "") {
+    return undefined;
+  }
+  const byIdentifier = available.filter(
+    (server) => server.serverIdentifier?.toLowerCase() === wanted
+  );
+  if (byIdentifier.length === 1) {
+    return byIdentifier[0];
+  }
+  if (byIdentifier.length > 1) {
+    return undefined;
+  }
+  const byName = available.filter(
+    (server) => server.name.toLowerCase() === wanted
+  );
+  if (byName.length === 1) {
+    return byName[0];
+  }
+  return undefined;
+}
+
+/**
+ * Mint OAuth `authUrl`s for connectors matching `identifiers` (name or
+ * `serverIdentifier`). Omit `serviceAccountId` to probe the signed-in user
+ * (local `serve` preflight). Failures return an empty map so the caller
+ * can fall back to the dashboard URL.
+ */
+export async function probeConnectorAuthUrls(args: {
+  client: Pick<
+    CursorBackendClient,
+    "getAvailableMcpServers" | "checkHttpMcpStatus"
+  >;
+  identifiers: readonly string[];
+  serviceAccountId?: string;
+}): Promise<Map<string, string>> {
+  const urls = new Map<string, string>();
+  if (args.identifiers.length === 0) {
+    return urls;
+  }
+  try {
+    const available = await args.client.getAvailableMcpServers();
+    const matched: AvailableMcpServer[] = [];
+    const seen = new Set<number>();
+    for (const identifier of args.identifiers) {
+      const match = uniqueConnectorMatch(available, identifier);
+      if (match === undefined || seen.has(match.id)) {
+        continue;
+      }
+      seen.add(match.id);
+      matched.push(match);
+    }
+    if (matched.length === 0) {
+      return urls;
+    }
+    const statuses = await args.client.checkHttpMcpStatus({
+      serverIds: matched.map((server) => server.id),
+      oauthRedirectUri: mcpOauthRedirectUri(),
+      serviceAccountId: args.serviceAccountId,
+    });
+    const statusById = new Map(
+      statuses.map((status) => [status.id, status] as const)
+    );
+    for (const identifier of args.identifiers) {
+      const match = uniqueConnectorMatch(available, identifier);
+      if (match === undefined) {
+        continue;
+      }
+      const authUrl = statusById.get(match.id)?.authUrl?.trim();
+      if (authUrl !== undefined && authUrl !== "") {
+        urls.set(identifier, authUrl);
+      }
+    }
+    return urls;
+  } catch {
+    return urls;
+  }
+}
+
 async function pollUntilAuthorized(args: {
   backendClient: Pick<CursorBackendClient, "checkHttpMcpStatus">;
   serverId: number;

package/src/internal/deploy-client.ts

@@ -11,7 +11,6 @@
  */
 
 import { z } from "zod";
-import type { AgentDeployManifestV1 } from "./deploy-manifest.js";
 import {
   MAX_SECRET_VALUE_BYTES,
   MAX_SECRETS,
@@ -75,12 +74,6 @@ export type DeploySource = {
    * `X-Agent-Alias-Token` (channels authored with `publicEndpoint()`).
    */
   publicRoutePaths?: string[];
-  /**
-   * Offline deploy manifest (Wd): derived declarations + `/v1/info`
-   * payload, extracted at deploy time with no VM. Optional — servers that
-   * predate manifest storage strip unknown fields.
-   */
-  manifest?: AgentDeployManifestV1;
 };
 
 const SLUG_PATTERN = /^[a-z0-9_-]{1,64}$/;
@@ -461,9 +454,6 @@ export class AgentServeDeployClient {
         : { egressAllowedDomains: args.source.egressAllowedDomains }),
       // JSON.stringify drops undefined keys.
       publicRoutePaths: args.source.publicRoutePaths,
-      ...(args.source.manifest === undefined
-        ? {}
-        : { manifest: args.source.manifest }),
       template: args.template,
     };
     const send = (): Promise<unknown> =>