@cursor/july 0.1.1

package/src/internal/mcp-endpoint.ts

@@ -0,0 +1,518 @@
+/**
+ * Per-agent MCP surface: every mounted agent is also a Model Context
+ * Protocol server over streamable HTTP at `<base>/v1/mcp`, so other agents
+ * (peer MCP connections) and ordinary MCP clients can delegate work to it.
+ *
+ * The endpoint is stateless (a fresh `McpServer` + transport per POST, JSON
+ * response mode): session identity travels in tool arguments, not in MCP
+ * transport session headers, so any number of hosts can sit in front of it.
+ *
+ * Tools:
+ * - `ask` — start (or continue, via `sessionId`) a conversation with this
+ *   agent; runs a model turn in the agent's own context and returns the
+ *   reply. Bounded wait: long turns return `status: "running"`.
+ * - `check` — wait for / poll a running session started by `ask`.
+ * - `call_tool` — call one of the agent's deterministic server tools
+ *   directly (no model turn). Registered only when server tools exist.
+ */
+
+import { McpServer } from "@modelcontextprotocol/sdk/server/mcp.js";
+import { WebStandardStreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/webStandardStreamableHttp.js";
+import { z } from "zod";
+import type {
+  AgentProject,
+  AuthContext,
+  SessionRecord,
+  TurnOutcome,
+} from "../types.js";
+import { samePrincipal } from "./auth.js";
+import {
+  SessionBusyError,
+  type SessionEngine,
+  ToolInputError,
+  ToolNotDirectlyCallableError,
+  UnknownSessionError,
+  UnknownToolError,
+} from "./session-engine.js";
+
+/** Channel id recorded on sessions created through the MCP surface. */
+export const MCP_CHANNEL_ID = "mcp";
+
+/** Mount path of the MCP surface, relative to the agent base. */
+export const MCP_ENDPOINT_PATH = "/v1/mcp";
+
+/**
+ * Bounded waits stay below the MCP client default request timeout (60s) so
+ * a long model turn degrades to `status: "running"` instead of a client
+ * timeout that loses the session id.
+ */
+const MAX_WAIT_SECONDS = 55;
+const DEFAULT_WAIT_SECONDS = 50;
+
+export interface AgentMcpEndpoint {
+  /**
+   * Handle one HTTP request to the MCP mount. `auth` is the principal
+   * resolved by the route auth chain; sessions created through `ask` bind
+   * to it, and follow-ups enforce the same principal.
+   */
+  handle(request: Request, auth: AuthContext | null): Promise<Response>;
+}
+
+/** Minimal shape both `McpServer` and the low-level `Server` satisfy. */
+interface ConnectableMcpServer {
+  connect(transport: WebStandardStreamableHTTPServerTransport): Promise<void>;
+  close(): Promise<void>;
+}
+
+/**
+ * Serve one stateless streamable-HTTP MCP request: a fresh server +
+ * transport per POST, JSON response mode, spec-compliant 405 on other
+ * methods. Shared by the per-agent MCP endpoint and the Cursor account
+ * bridge so the subtle transport/error plumbing exists once.
+ */
+export async function handleStatelessMcpRequest(args: {
+  request: Request;
+  /** Builds the per-request MCP server (tools close over request state). */
+  buildServer: () => ConnectableMcpServer;
+  /** Label used in the failure log line, e.g. `"mcp endpoint"`. */
+  label: string;
+  logger?: (line: string) => void;
+}): Promise<Response> {
+  const logger = args.logger ?? (() => {});
+  if (args.request.method !== "POST") {
+    // Stateless server: no server-initiated SSE stream (GET) and no
+    // transport sessions to delete (DELETE). 405 per the MCP spec;
+    // clients treat it as "streaming unsupported" and carry on.
+    return new Response(
+      JSON.stringify({
+        jsonrpc: "2.0",
+        error: { code: -32000, message: "Method not allowed." },
+        id: null,
+      }),
+      {
+        status: 405,
+        headers: { "content-type": "application/json", allow: "POST" },
+      }
+    );
+  }
+  const server = args.buildServer();
+  const transport = new WebStandardStreamableHTTPServerTransport({
+    sessionIdGenerator: undefined,
+    enableJsonResponse: true,
+  });
+  try {
+    await server.connect(transport);
+    // JSON-response mode materializes the full body before resolving,
+    // so closing in `finally` never truncates a streamed response.
+    return await transport.handleRequest(args.request);
+  } catch (error) {
+    logger(
+      `[agent-serve] ${args.label} request failed: ${describeError(error)}`
+    );
+    return new Response(
+      JSON.stringify({
+        jsonrpc: "2.0",
+        error: { code: -32603, message: "Internal server error." },
+        id: null,
+      }),
+      { status: 500, headers: { "content-type": "application/json" } }
+    );
+  } finally {
+    void server.close().catch(() => {});
+  }
+}
+
+/** Tool names the MCP surface exposes for `project` (info projection). */
+export function mcpEndpointToolNames(project: AgentProject): string[] {
+  const names = ["ask", "check"];
+  if (project.agent.tools.some((tool) => tool.execution === "server")) {
+    names.push("call_tool");
+  }
+  return names;
+}
+
+export function createAgentMcpEndpoint(args: {
+  engine: SessionEngine;
+  logger?: (line: string) => void;
+}): AgentMcpEndpoint {
+  const { engine, logger } = args;
+
+  return {
+    handle(request, auth): Promise<Response> {
+      return handleStatelessMcpRequest({
+        request,
+        buildServer: () => buildAgentMcpServer(engine, auth),
+        label: "mcp endpoint",
+        ...(logger === undefined ? {} : { logger }),
+      });
+    },
+  };
+}
+
+// ============================================================================
+// Server construction (per request; tools close over the caller principal)
+// ============================================================================
+
+function buildAgentMcpServer(
+  engine: SessionEngine,
+  auth: AuthContext | null
+): McpServer {
+  const project = engine.project;
+  const agent = project.agent;
+  const server = new McpServer(
+    { name: project.name, version: "0.1.0" },
+    { instructions: buildInstructions(project) }
+  );
+
+  server.registerTool(
+    "ask",
+    {
+      description: buildAskDescription(project),
+      inputSchema: {
+        message: z.string().describe("The message or task for this agent."),
+        sessionId: z
+          .string()
+          .optional()
+          .describe(
+            "Existing session to follow up on (from a previous ask). Omit to start a fresh session with fresh context."
+          ),
+        waitSeconds: z
+          .number()
+          .min(0)
+          .max(MAX_WAIT_SECONDS)
+          .optional()
+          .describe(
+            `How long to wait for the turn to finish before returning status "running" (default ${DEFAULT_WAIT_SECONDS}).`
+          ),
+      },
+    },
+    async ({ message, sessionId, waitSeconds }) => {
+      try {
+        const targetSessionId = await (sessionId === undefined
+          ? startSession(engine, auth, message)
+          : followUpSession(engine, auth, sessionId, message));
+        const payload = await waitForReply(
+          engine,
+          targetSessionId,
+          waitSeconds ?? DEFAULT_WAIT_SECONDS
+        );
+        return toToolResult(payload);
+      } catch (error) {
+        return errorResult(describeError(error));
+      }
+    }
+  );
+
+  server.registerTool(
+    "check",
+    {
+      description:
+        'Wait for (or poll) a session started with ask. Returns the final reply once the turn completes, or status "running" to keep waiting. Use waitSeconds: 0 for a non-blocking poll.',
+      inputSchema: {
+        sessionId: z.string().describe("Session id returned by ask."),
+        waitSeconds: z
+          .number()
+          .min(0)
+          .max(MAX_WAIT_SECONDS)
+          .optional()
+          .describe(
+            `How long to wait for the running turn before returning status "running" (default ${DEFAULT_WAIT_SECONDS}).`
+          ),
+      },
+    },
+    async ({ sessionId, waitSeconds }) => {
+      try {
+        await requireOwnedSession(engine, auth, sessionId);
+        const payload = await waitForReply(
+          engine,
+          sessionId,
+          waitSeconds ?? DEFAULT_WAIT_SECONDS
+        );
+        return toToolResult(payload);
+      } catch (error) {
+        return errorResult(describeError(error));
+      }
+    }
+  );
+
+  const serverTools = agent.tools.filter((tool) => tool.execution === "server");
+  if (serverTools.length > 0) {
+    server.registerTool(
+      "call_tool",
+      {
+        description: `Call one of this agent's deterministic server tools directly (no model turn decides anything). Available tools: ${serverTools
+          .map((tool) => tool.name)
+          .join(", ")}.`,
+        inputSchema: {
+          toolName: z.string().describe("Name of the server tool to call."),
+          input: z
+            .record(z.unknown())
+            .optional()
+            .describe("Tool input, validated against the tool's schema."),
+          sessionId: z
+            .string()
+            .optional()
+            .describe(
+              "Run the tool inside an existing session (recorded on its event stream). Omit for an ephemeral scratch workspace."
+            ),
+        },
+      },
+      async ({ toolName, input, sessionId }) => {
+        try {
+          if (sessionId !== undefined) {
+            await requireOwnedSession(engine, auth, sessionId);
+          }
+          const outcome = await engine.callTool(toolName, input ?? {}, {
+            auth,
+            ...(sessionId === undefined ? {} : { sessionId }),
+          });
+          return {
+            content: [
+              {
+                type: "text" as const,
+                text: JSON.stringify({
+                  toolName: outcome.toolName,
+                  isError: outcome.isError,
+                  result: outcome.result,
+                  durationMs: outcome.durationMs,
+                  ...(outcome.errorMessage === undefined
+                    ? {}
+                    : { errorMessage: outcome.errorMessage }),
+                }),
+              },
+            ],
+            ...(outcome.isError ? { isError: true as const } : {}),
+          };
+        } catch (error) {
+          if (error instanceof UnknownToolError) {
+            return errorResult(
+              `${error.message}. Available tools: ${error.availableToolNames.join(", ") || "(none)"}.`
+            );
+          }
+          if (
+            error instanceof ToolNotDirectlyCallableError ||
+            error instanceof ToolInputError ||
+            error instanceof SessionBusyError ||
+            error instanceof UnknownSessionError
+          ) {
+            return errorResult(error.message);
+          }
+          return errorResult(describeError(error));
+        }
+      }
+    );
+  }
+
+  return server;
+}
+
+function buildInstructions(project: AgentProject): string {
+  const agent = project.agent;
+  const parts = [
+    `This MCP server fronts the Cursor agent "${project.name}".`,
+    ...(agent.description === undefined ? [] : [agent.description]),
+    'Delegate a task with the ask tool: each call without a sessionId starts a fresh session (fresh context); pass the returned sessionId to continue the same conversation. When ask returns status "running", call check with that sessionId to keep waiting for the reply.',
+  ];
+  return parts.join(" ");
+}
+
+function buildAskDescription(project: AgentProject): string {
+  const description = project.agent.description;
+  const purpose =
+    description === undefined || description.trim() === ""
+      ? `the "${project.name}" agent`
+      : `the "${project.name}" agent — ${description.trim()}`;
+  return `Send a message to ${purpose}. Runs a full model turn in that agent's own context and returns its reply. Omit sessionId to start a fresh session; pass it to follow up. Long turns return status "running" — call check with the sessionId to keep waiting.`;
+}
+
+// ============================================================================
+// Session helpers
+// ============================================================================
+
+async function startSession(
+  engine: SessionEngine,
+  auth: AuthContext | null,
+  message: string
+): Promise<string> {
+  const session = await engine.send(MCP_CHANNEL_ID, message, { auth });
+  return session.id;
+}
+
+async function followUpSession(
+  engine: SessionEngine,
+  auth: AuthContext | null,
+  sessionId: string,
+  message: string
+): Promise<string> {
+  const record = await requireOwnedSession(engine, auth, sessionId);
+  if (record.mode === "task") {
+    throw new Error(
+      `Session ${sessionId} is a fire-and-forget task session; it does not accept follow-ups.`
+    );
+  }
+  if (record.continuationKey === null) {
+    throw new Error(
+      `Session ${sessionId} is not addressable for follow-ups (no active continuation).`
+    );
+  }
+  // Send as the session owner after the ownership gate above, mirroring the
+  // HTTP follow-up route (machine callers address sessions by id; the HTTP
+  // continuation token is not rotated).
+  await engine.send(record.channelId, message, {
+    auth: record.auth,
+    continuationToken: record.continuationKey,
+  });
+  return sessionId;
+}
+
+async function requireOwnedSession(
+  engine: SessionEngine,
+  auth: AuthContext | null,
+  sessionId: string
+): Promise<SessionRecord> {
+  const record = await engine.sessions.get(sessionId);
+  if (record === undefined) {
+    throw new UnknownSessionError(sessionId);
+  }
+  if (!samePrincipal(record.auth, auth)) {
+    throw new Error(
+      `Session ${sessionId} belongs to a different principal; use the credentials that created it.`
+    );
+  }
+  return record;
+}
+
+interface ReplyPayload {
+  status: "completed" | "running" | "error" | "cancelled";
+  sessionId: string;
+  reply?: string;
+  errorMessage?: string;
+  note?: string;
+}
+
+async function waitForReply(
+  engine: SessionEngine,
+  sessionId: string,
+  waitSeconds: number
+): Promise<ReplyPayload> {
+  const waitMs = Math.max(0, Math.min(waitSeconds, MAX_WAIT_SECONDS)) * 1000;
+  const outcome = await raceTimeout(
+    engine.waitForCompletion(sessionId),
+    waitMs
+  );
+  if (outcome === undefined) {
+    return {
+      status: "running",
+      sessionId,
+      note: `The turn is still running. Call check with { "sessionId": "${sessionId}" } to keep waiting.`,
+    };
+  }
+  return toReplyPayload(engine, sessionId, outcome);
+}
+
+async function toReplyPayload(
+  engine: SessionEngine,
+  sessionId: string,
+  outcome: TurnOutcome
+): Promise<ReplyPayload> {
+  if (outcome.status === "finished") {
+    let reply = outcome.result;
+    if (reply === undefined || reply === "") {
+      // The engine's in-memory outcome is gone after a host restart; fall
+      // back to the durable event log for the last completed turn.
+      reply = await latestReplyFromEvents(engine, sessionId);
+    }
+    return {
+      status: "completed",
+      sessionId,
+      ...(reply === undefined ? {} : { reply }),
+    };
+  }
+  if (outcome.status === "cancelled") {
+    return {
+      status: "cancelled",
+      sessionId,
+      errorMessage: outcome.errorMessage ?? "The turn was cancelled.",
+    };
+  }
+  return {
+    status: "error",
+    sessionId,
+    errorMessage: outcome.errorMessage ?? "The turn failed.",
+  };
+}
+
+async function latestReplyFromEvents(
+  engine: SessionEngine,
+  sessionId: string
+): Promise<string | undefined> {
+  let events: Awaited<ReturnType<SessionEngine["listEvents"]>>;
+  try {
+    events = await engine.listEvents(sessionId);
+  } catch {
+    return undefined;
+  }
+  for (let i = events.length - 1; i >= 0; i--) {
+    const event = events[i];
+    if (event === undefined) {
+      continue;
+    }
+    if (event.type === "turn.completed" && event.data.result !== undefined) {
+      return event.data.result;
+    }
+    if (event.type === "message.completed" && event.data.text !== "") {
+      return event.data.text;
+    }
+  }
+  return undefined;
+}
+
+// ============================================================================
+// Result shaping
+// ============================================================================
+
+interface McpToolResult {
+  content: Array<{ type: "text"; text: string }>;
+  isError?: true;
+  [key: string]: unknown;
+}
+
+function toToolResult(payload: ReplyPayload): McpToolResult {
+  return {
+    content: [{ type: "text", text: JSON.stringify(payload) }],
+    ...(payload.status === "error" ? { isError: true as const } : {}),
+  };
+}
+
+function errorResult(message: string): McpToolResult {
+  return {
+    content: [{ type: "text", text: message }],
+    isError: true,
+  };
+}
+
+/** Resolve to the promise value, or undefined once `ms` elapses first. */
+function raceTimeout<T>(
+  promise: Promise<T>,
+  ms: number
+): Promise<T | undefined> {
+  return new Promise<T | undefined>((resolve, reject) => {
+    const timer = setTimeout(() => {
+      resolve(undefined);
+    }, ms);
+    promise.then(
+      (value) => {
+        clearTimeout(timer);
+        resolve(value);
+      },
+      (error: unknown) => {
+        clearTimeout(timer);
+        reject(error instanceof Error ? error : new Error(String(error)));
+      }
+    );
+  });
+}
+
+function describeError(error: unknown): string {
+  return error instanceof Error ? error.message : String(error);
+}