@cursor/july 0.1.32 → 0.1.34

package/src/internal/mcp-endpoint.ts

@@ -16,8 +16,19 @@
  *   directly (no model turn). Registered only when server tools exist.
  */
 
+import type {
+  SDKCustomToolContent,
+  SDKCustomToolResult,
+  SDKJsonValue,
+} from "@cursor/sdk";
+import { Server } from "@modelcontextprotocol/sdk/server/index.js";
 import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
 import { WebStandardStreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/webStandardStreamableHttp.js";
+import {
+  CallToolRequestSchema,
+  type CallToolResult,
+  ListToolsRequestSchema,
+} from "@modelcontextprotocol/sdk/types.js";
 import { z } from "zod";
 import type {
   AgentProject,
@@ -40,6 +51,8 @@ export const MCP_CHANNEL_ID = "mcp";
 
 /** Mount path of the MCP surface, relative to the agent base. */
 export const MCP_ENDPOINT_PATH = "/v1/mcp";
+/** Direct authored server tools used by this agent's cloud turns. */
+export const TOOL_MCP_ENDPOINT_PATH = "/v1/mcp/tools";
 
 /**
  * Bounded waits stay below the MCP client default request timeout (60s) so
@@ -147,6 +160,170 @@ export function createAgentMcpEndpoint(args: {
   };
 }
 
+export function createToolMcpEndpoint(args: {
+  engine: SessionEngine;
+  logger?: (line: string) => void;
+}): AgentMcpEndpoint {
+  const { engine, logger } = args;
+  return {
+    handle(request): Promise<Response> {
+      const url = new URL(request.url);
+      const sessionId = url.searchParams.get("agentkitSessionId");
+      // `connection=<name>` serves a host connection bridge instead of the
+      // authored server tools: same endpoint, same auth, same session
+      // binding, but tools/list and tools/call forward to `host.mcp` for
+      // that connection (see buildConnectionBridgeMcpServer).
+      const connection = url.searchParams.get("connection");
+      return handleStatelessMcpRequest({
+        request,
+        buildServer: () =>
+          connection === null
+            ? buildToolMcpServer(engine, sessionId)
+            : buildConnectionBridgeMcpServer(engine, sessionId, connection),
+        label:
+          connection === null
+            ? "tool mcp endpoint"
+            : `connection bridge mcp endpoint (${connection})`,
+        ...(logger === undefined ? {} : { logger }),
+      });
+    },
+  };
+}
+
+function buildToolMcpServer(
+  engine: SessionEngine,
+  sessionId: string | null
+): Server {
+  const server = new Server(
+    { name: `${engine.project.name}:tools`, version: "0.1.0" },
+    {
+      capabilities: { tools: {} },
+      instructions:
+        "Direct tools implemented by the AgentSDK deployment for its active cloud turn.",
+    }
+  );
+  const tools = engine.project.agent.tools.filter(
+    (tool) => tool.execution === "server"
+  );
+  server.setRequestHandler(ListToolsRequestSchema, () =>
+    Promise.resolve({
+      tools: tools.map((tool) => ({
+        name: tool.name,
+        description: tool.description,
+        inputSchema: tool.inputSchema,
+      })),
+    })
+  );
+  server.setRequestHandler(CallToolRequestSchema, async (request) => {
+    if (sessionId === null || sessionId === "") {
+      return errorResult("Missing AgentSDK session binding.");
+    }
+    const tool = tools.find(
+      (candidate) => candidate.name === request.params.name
+    );
+    if (tool === undefined) {
+      return errorResult(`Unknown server tool "${request.params.name}".`);
+    }
+    const result = await engine.callActiveServerTool(
+      sessionId,
+      tool.name,
+      request.params.arguments ?? {}
+    );
+    return sdkResultToMcpResult(result);
+  });
+  return server;
+}
+
+/**
+ * Host connection bridge: one authored MCP connection served to a cloud turn
+ * over the tool MCP endpoint. Listing and calling forward to the host-side
+ * client (`host.mcp`), where the connection's credential — account bridge
+ * secret or host OAuth token — actually lives, so nothing key-shaped ever
+ * travels in the turn's MCP config or lands on the VM.
+ *
+ * The engine gates access twice, mirroring the authored server-tool path:
+ * only bridgeable names (`isCloudBridgedConnection`) — `hostOnly`
+ * connections and unknown names stay unreachable from a VM even with a
+ * valid endpoint credential — and only while the bound session has a turn
+ * in flight (`hasActiveTurn`), so a credential that persists on a VM after
+ * its turn cannot keep calling host connectors. Listing forwards per
+ * request, so a server that adds tools mid-session (`tools/list_changed`,
+ * e.g. Datadog's skills-first mode) is picked up on the next list instead
+ * of never.
+ */
+function buildConnectionBridgeMcpServer(
+  engine: SessionEngine,
+  sessionId: string | null,
+  connectionName: string
+): Server {
+  const server = new Server(
+    {
+      name: `${engine.project.name}:bridge:${connectionName}`,
+      version: "0.1.0",
+    },
+    {
+      capabilities: { tools: {} },
+      instructions: `Tools from the "${connectionName}" MCP connection, listed and called on the serve host where its credential lives.`,
+    }
+  );
+  const rejected = (): string | undefined => {
+    if (sessionId === null || sessionId === "") {
+      return "Missing AgentSDK session binding.";
+    }
+    if (!engine.isCloudBridgedConnection(connectionName)) {
+      return `MCP connection "${connectionName}" is not bridged to cloud turns.`;
+    }
+    if (!engine.hasActiveTurn(sessionId)) {
+      return `Session ${sessionId} has no active turn for connection "${connectionName}".`;
+    }
+    return undefined;
+  };
+  server.setRequestHandler(ListToolsRequestSchema, async () => {
+    const reason = rejected();
+    if (reason !== undefined) {
+      throw new Error(reason);
+    }
+    const tools = await engine.host.mcp.listTools(connectionName);
+    return {
+      tools: tools.map((tool) => ({
+        name: tool.name,
+        ...(tool.description === undefined
+          ? {}
+          : { description: tool.description }),
+        inputSchema: tool.inputSchema ?? { type: "object" },
+      })),
+    };
+  });
+  server.setRequestHandler(CallToolRequestSchema, async (request) => {
+    const reason = rejected();
+    if (reason !== undefined) {
+      return errorResult(reason);
+    }
+    try {
+      const result = await engine.host.mcp.callTool(
+        connectionName,
+        request.params.name,
+        request.params.arguments ?? {}
+      );
+      return {
+        // The host client already speaks MCP, so the content array is valid
+        // CallToolResult content; HostMcpCallResult just types the tail of
+        // the union open-endedly.
+        content: result.content as CallToolResult["content"],
+        ...(result.isError === undefined ? {} : { isError: result.isError }),
+        ...(result.structuredContent === undefined
+          ? {}
+          : { structuredContent: result.structuredContent }),
+      };
+    } catch (error) {
+      return errorResult(
+        `MCP connection "${connectionName}" is not reachable from the serve host: ${describeError(error)}`
+      );
+    }
+  });
+  return server;
+}
+
 // ============================================================================
 // Server construction (per request; tools close over the caller principal)
 // ============================================================================
@@ -489,6 +666,72 @@ function errorResult(message: string): McpToolResult {
   };
 }
 
+function sdkResultToMcpResult(result: SDKCustomToolResult) {
+  if (isSdkToolEnvelope(result)) {
+    return {
+      content: result.content.map(toMcpContent),
+      ...(result.isError === true ? { isError: true } : {}),
+      ...(result.structuredContent === undefined
+        ? {}
+        : { structuredContent: result.structuredContent }),
+    };
+  }
+  if (typeof result === "string") {
+    return { content: [{ type: "text" as const, text: result }] };
+  }
+  return {
+    content: [{ type: "text" as const, text: JSON.stringify(result) }],
+    ...(isJsonObject(result) ? { structuredContent: result } : {}),
+  };
+}
+
+function toMcpContent(content: SDKCustomToolContent) {
+  if (content.type === "text") {
+    return content;
+  }
+  return {
+    type: "image" as const,
+    data: content.data,
+    mimeType: content.mimeType ?? "application/octet-stream",
+  };
+}
+
+function isSdkToolEnvelope(
+  result: SDKCustomToolResult
+): result is Extract<SDKCustomToolResult, { content: unknown }> {
+  return (
+    typeof result === "object" &&
+    result !== null &&
+    !Array.isArray(result) &&
+    "content" in result &&
+    Array.isArray(result.content) &&
+    result.content.every(isSdkToolContent)
+  );
+}
+
+function isSdkToolContent(value: unknown): value is SDKCustomToolContent {
+  if (typeof value !== "object" || value === null || !("type" in value)) {
+    return false;
+  }
+  if (value.type === "text") {
+    return "text" in value && typeof value.text === "string";
+  }
+  return (
+    value.type === "image" &&
+    "data" in value &&
+    typeof value.data === "string" &&
+    (!("mimeType" in value) ||
+      value.mimeType === undefined ||
+      typeof value.mimeType === "string")
+  );
+}
+
+function isJsonObject(
+  value: SDKJsonValue
+): value is Record<string, SDKJsonValue> {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+
 /** Resolve to the promise value, or undefined once `ms` elapses first. */
 function raceTimeout<T>(
   promise: Promise<T>,

package/src/internal/resolved-connections.ts

@@ -25,13 +25,24 @@ export function validateMountConnectionsConfig(args: {
   project: AgentProject;
   accountRefs?: CursorAccountConnectionRef[];
   publicUrl?: string;
+  /**
+   * True when serve has a cloud tools URL (`--cloud-tools-url`, always set on
+   * managed hosting): cloud turns then reach filtered account connections
+   * through the host connection bridge on the tool MCP endpoint, so the
+   * filter is honored host-side and no `--public-url` is needed.
+   */
+  cloudToolsBridge?: boolean;
 }): void {
   if (args.accountRefs === undefined || args.accountRefs.length === 0) {
     return;
   }
   const agent = args.project.agent;
   const cloudCapable = agent.runtime === "cloud" || agent.cloud !== undefined;
-  if (!cloudCapable || args.publicUrl !== undefined) {
+  if (
+    !cloudCapable ||
+    args.publicUrl !== undefined ||
+    args.cloudToolsBridge === true
+  ) {
     return;
   }
   const label = args.slug === "" ? args.project.name : args.slug;
@@ -59,6 +70,12 @@ export function validateMountConnectionsConfig(args: {
 export function assertCloudCanHonorAccountServersFilters(args: {
   runtime: "local" | "cloud";
   resolvedConnections: readonly EngineResolvedConnection[];
+  /**
+   * Connection names this cloud turn reaches through the host connection
+   * bridge (tool MCP endpoint). The filter is honored on the serve host
+   * there, so a missing `cloudUrl` is not a fail-open.
+   */
+  bridgedNames?: ReadonlySet<string>;
 }): void {
   if (args.runtime !== "cloud") {
     return;
@@ -66,7 +83,8 @@ export function assertCloudCanHonorAccountServersFilters(args: {
   const blocked = args.resolvedConnections.filter(
     (connection) =>
       connection.accountServersFilter !== undefined &&
-      connection.cloudUrl === undefined
+      connection.cloudUrl === undefined &&
+      args.bridgedNames?.has(connection.name) !== true
   );
   if (blocked.length === 0) {
     return;
@@ -111,6 +129,8 @@ export function resolveMountConnections(args: {
   accountBridge?: CursorAccountMcpBridge;
   publicUrl?: string;
   authToken?: string;
+  /** See {@link validateMountConnectionsConfig}. */
+  cloudToolsBridge?: boolean;
   logger: (line: string) => void;
 }): EngineResolvedConnection[] {
   const agent = args.project.agent;
@@ -128,9 +148,13 @@ export function resolveMountConnections(args: {
       .map((connection) => connection.name);
     if (hostOauthNames.length > 0) {
       args.logger(
-        `[agent-sdk] warning: agent "${label}" has host-OAuth MCP connections (${hostOauthNames.join(
-          ", "
-        )}) whose tokens live on this serve host; cloud-runtime turns omit them. Mark them \`hostOnly: true\` and call them from host tools, or drop \`oauth\` and authorize the server another way.`
+        args.cloudToolsBridge === true
+          ? `[agent-sdk] agent "${label}": host-OAuth MCP connections (${hostOauthNames.join(
+              ", "
+            )}) reach cloud turns through the host connection bridge; their tokens stay on this serve host.`
+          : `[agent-sdk] warning: agent "${label}" has host-OAuth MCP connections (${hostOauthNames.join(
+              ", "
+            )}) whose tokens live on this serve host; cloud-runtime turns omit them. Mark them \`hostOnly: true\` and call them from host tools, or drop \`oauth\` and authorize the server another way.`
       );
     }
   }
@@ -168,7 +192,9 @@ export function resolveMountConnections(args: {
     args.accountBridge.logPreflight(args.accountRefs);
     if (cloudCapable && args.publicUrl === undefined) {
       args.logger(
-        `[agent-sdk] agent "${label}": cloud-runtime turns omit the account bridge without --public-url (cloud agents fall back to the account's native connectors).`
+        args.cloudToolsBridge === true
+          ? `[agent-sdk] agent "${label}": cloud-runtime turns reach filtered account connections through the host connection bridge (unfiltered ones fall back to the account's native connectors).`
+          : `[agent-sdk] agent "${label}": cloud-runtime turns omit the account bridge without --public-url (cloud agents fall back to the account's native connectors).`
       );
     }
   }

package/src/internal/review-comments.ts

@@ -1,6 +1,7 @@
 import { spawn } from "node:child_process";
+import type { HostGitHubClient } from "../types.js";
 
-export type ReviewCommentPublisher = "local_gh";
+export type ReviewCommentPublisher = "local_gh" | "host_github";
 
 export type ReviewCommentPostResult = {
   posted: boolean;
@@ -84,6 +85,80 @@ export function createLocalGhReviewPublisher(): ReviewCommentPublisherImplementa
   };
 }
 
+/**
+ * Posts a PR review through the host GitHub client (Cursor account lease,
+ * App installation token, or PAT). Prefer this on Cursor-deployed agents —
+ * no separate GitHub write secret is required when `githubChannel({
+ * cursorAccount })` is bound.
+ */
+export function createHostGithubReviewPublisher(
+  github: HostGitHubClient
+): ReviewCommentPublisherImplementation {
+  return {
+    async postReview(args) {
+      return postReviewViaHostGithub(github, args);
+    },
+  };
+}
+
+async function postReviewViaHostGithub(
+  github: HostGitHubClient,
+  args: ReviewCommentPostArgs
+): Promise<ReviewCommentPostResult> {
+  const prepared = prepareReviewCommentsRequest(args);
+  if (prepared.kind === "skipped") {
+    return {
+      ...prepared.result,
+      publisher: "host_github",
+    };
+  }
+
+  const { request } = prepared;
+  const [owner, repo] = request.repo.split("/", 2);
+  if (owner === undefined || repo === undefined || repo === "") {
+    return skippedHost("unparseable owner/repo from PR URL");
+  }
+
+  try {
+    args.signal?.throwIfAborted();
+    const octokit = await github.getOctokit();
+    args.signal?.throwIfAborted();
+    const response = await octokit.rest.pulls.createReview({
+      owner,
+      repo,
+      pull_number: request.prNumber,
+      commit_id: request.headSha,
+      body: request.message,
+      event: "COMMENT",
+      comments: request.comments.map(toGithubPullRequestReviewComment),
+    });
+    const htmlUrl =
+      typeof response.data.html_url === "string"
+        ? response.data.html_url
+        : undefined;
+    const inlineCommentCount = request.comments.length;
+    return {
+      posted: true,
+      publisher: "host_github",
+      mode:
+        inlineCommentCount > 0
+          ? "review_with_inline_comments"
+          : "review_body_only",
+      inlineCommentCount,
+      detail: htmlUrl
+        ? `posted via host GitHub: ${htmlUrl}`
+        : `posted via host GitHub with ${inlineCommentCount} inline comment(s)`,
+    };
+  } catch (error) {
+    if (args.signal?.aborted) {
+      throw error;
+    }
+    return skippedHost(
+      `host GitHub review post failed: ${error instanceof Error ? error.message : String(error)}`
+    );
+  }
+}
+
 async function postReviewViaLocalGh(
   args: ReviewCommentPostArgs
 ): Promise<ReviewCommentPostResult> {
@@ -129,10 +204,25 @@ async function postReviewViaLocalGh(
   }
 }
 
+type GithubPullRequestReviewComment = {
+  path: string;
+  body: string;
+  line: number;
+  side: "RIGHT";
+  start_line?: number;
+  start_side?: "RIGHT";
+};
+
 function toGithubReviewComment(
   comment: ReviewInlineComment
 ): Record<string, string | number> {
-  const body: Record<string, string | number> = {
+  return toGithubPullRequestReviewComment(comment);
+}
+
+function toGithubPullRequestReviewComment(
+  comment: ReviewInlineComment
+): GithubPullRequestReviewComment {
+  const body: GithubPullRequestReviewComment = {
     path: comment.file,
     body: comment.body,
     line: comment.line,
@@ -159,6 +249,16 @@ function skipped(detail: string): ReviewCommentPostResult {
   };
 }
 
+function skippedHost(detail: string): ReviewCommentPostResult {
+  return {
+    posted: false,
+    publisher: "host_github",
+    mode: "skipped",
+    inlineCommentCount: 0,
+    detail,
+  };
+}
+
 function parseGithubPrUrl(
   prUrl: string
 ):

package/src/internal/server.ts

@@ -103,7 +103,12 @@ import {
   type LocalControlPlane,
 } from "./local-control-plane.js";
 import { createLogRing, type LogRing } from "./log-ring.js";
-import { createAgentMcpEndpoint, MCP_ENDPOINT_PATH } from "./mcp-endpoint.js";
+import {
+  createAgentMcpEndpoint,
+  createToolMcpEndpoint,
+  MCP_ENDPOINT_PATH,
+  TOOL_MCP_ENDPOINT_PATH,
+} from "./mcp-endpoint.js";
 import { isLoopbackAddress } from "./net.js";
 import { collectPeerConnections } from "./peer-connections.js";
 import {
@@ -681,6 +686,7 @@ export async function startServer(
       ...(options.publicUrl === undefined
         ? {}
         : { publicUrl: options.publicUrl }),
+      cloudToolsBridge: options.cloudToolsUrl !== undefined,
     });
   }
 
@@ -751,11 +757,55 @@ export async function startServer(
       ...(options.authToken === undefined
         ? {}
         : { authToken: options.authToken }),
+      cloudToolsBridge: options.cloudToolsUrl !== undefined,
       logger,
     });
     if (resolved.length > 0) {
       runtime.engine.setResolvedConnections(resolved);
     }
+    const hasServerTools = runtime.project.agent.tools.some(
+      (tool) => tool.execution === "server"
+    );
+    // Host-bridged connections ride the same endpoint as server tools, so
+    // the cloud tools connection is set whenever either needs it.
+    const bridgeableNames = runtime.engine.cloudBridgeableConnectionNames();
+    const cloudCapable =
+      runtime.project.agent.runtime === "cloud" ||
+      runtime.project.agent.cloud !== undefined;
+    if ((hasServerTools || bridgeableNames.length > 0) && cloudCapable) {
+      const basePath = runtime.slug === "" ? "" : `/${runtime.slug}`;
+      const publicToolsUrl =
+        options.cloudToolsUrl ??
+        (options.publicUrl === undefined
+          ? undefined
+          : `${options.publicUrl.replace(/\/$/, "")}${basePath}${TOOL_MCP_ENDPOINT_PATH}`);
+      if (publicToolsUrl === undefined) {
+        if (hasServerTools) {
+          logger(
+            `[agent-sdk] warning: agent "${runtime.project.name}" has server tools but no --public-url or --cloud-tools-url; cloud turns omit those tools.`
+          );
+        }
+      } else {
+        const headers =
+          options.cloudToolsUrl !== undefined
+            ? accountKey === undefined
+              ? undefined
+              : { authorization: `Bearer ${accountKey.apiKey}` }
+            : options.authToken === undefined
+              ? undefined
+              : { authorization: `Bearer ${options.authToken}` };
+        if (options.cloudToolsUrl !== undefined && headers === undefined) {
+          throw new Error(
+            `Agent "${runtime.project.name}" needs a Cursor API key to authenticate --cloud-tools-url. ${SIGN_IN_HINT}`
+          );
+        }
+        runtime.engine.setCloudServerToolsConnection({
+          type: "http",
+          url: publicToolsUrl,
+          ...(headers === undefined ? {} : { headers }),
+        });
+      }
+    }
   }
 
   const agents: MountedAgentInfo[] = runtimes.map(({ slug, project }) => ({
@@ -959,7 +1009,15 @@ function mountAgentRoutes(
     method: "GET",
     pattern: `${base}/v1/health`,
     auth: "none",
-    handler: () => jsonResponse({ ok: true, name: project.name }),
+    // Temporal consumes this response before promoting a newly deployed pod.
+    // Include the framework build there so deploy observability gets the
+    // version from the process that will serve turns, with no second request.
+    handler: () =>
+      jsonResponse({
+        ok: true,
+        name: project.name,
+        version: packageVersion(),
+      }),
   });
 
   // Bootstrap the SPA can't derive from its own URL (agent name, dev mode, and
@@ -1091,6 +1149,44 @@ function mountAgentRoutes(
     },
   });
 
+  // File/blob payload of one artifact (`tag({ contents })`).
+  router.add({
+    method: "GET",
+    pattern: `${base}/v1/artifacts/:id/content`,
+    auth: httpAuth,
+    handler: async (_request, ctx) => {
+      const includeAll =
+        relaxSessionReadAuth &&
+        (relaxSessionReadAuthBeyondLoopback ||
+          (typeof ctx.requestIp === "string" &&
+            isLoopbackAddress(ctx.requestIp)));
+      const found = await engine.getArtifactContent(
+        ctx.auth,
+        ctx.params.id ?? "",
+        { includeAll }
+      );
+      if (found === undefined) {
+        return errorResponse(
+          404,
+          "not_found",
+          "No such artifact, or it carries no content."
+        );
+      }
+      // A view over bytes is a valid fetch body; the DOM lib types are
+      // narrower than the runtime.
+      // contentType is author/model-controlled and the playground shares
+      // this origin: force download, never render or sniff.
+      return new Response(found.body as unknown as BodyInit, {
+        headers: {
+          "content-type":
+            found.record.content?.contentType ?? "application/octet-stream",
+          "content-disposition": "attachment",
+          "x-content-type-options": "nosniff",
+        },
+      });
+    },
+  });
+
   // The agent's MCP surface: peers and external MCP clients delegate to
   // this agent (ask / check / call_tool) over streamable HTTP. Stateless —
   // POST only; GET/DELETE get a spec-compliant 405 from the endpoint.
@@ -1104,6 +1200,16 @@ function mountAgentRoutes(
     });
   }
 
+  const toolMcpEndpoint = createToolMcpEndpoint({ engine, logger });
+  for (const method of ["POST", "GET", "DELETE"] as const) {
+    router.add({
+      method,
+      pattern: `${base}${TOOL_MCP_ENDPOINT_PATH}`,
+      auth: defaultAuth,
+      handler: (request, ctx) => toolMcpEndpoint.handle(request, ctx.auth),
+    });
+  }
+
   // Deterministic tool invocation: run an authored server tool directly,
   // without a model turn deciding to call it.
   router.add({