@cursor/july 0.1.1

package/src/internal/mcp-host.ts

@@ -0,0 +1,211 @@
+/**
+ * Host-side MCP clients for authored `agent/mcp-connections/*`.
+ *
+ * Every connection is always available in three places:
+ * - the Cursor agent, via SDK `mcpServers` (local harness or cloud)
+ * - the agent-serve host, for in-process server tools through
+ *   {@link HostMcpRegistry} on {@link ToolContext.host}.mcp
+ * - channel / webhook route handlers through
+ *   {@link HostMcpRegistry} on {@link ChannelHandlerArgs.host}.mcp
+ */
+
+import { Client } from "@modelcontextprotocol/sdk/client/index.js";
+import { SSEClientTransport } from "@modelcontextprotocol/sdk/client/sse.js";
+import { StdioClientTransport } from "@modelcontextprotocol/sdk/client/stdio.js";
+import { StreamableHTTPClientTransport } from "@modelcontextprotocol/sdk/client/streamableHttp.js";
+import type {
+  DiscoveredConnection,
+  HostMcpCallResult,
+  HostMcpRegistry,
+  HostMcpToolInfo,
+  JsonObject,
+} from "../types.js";
+
+interface OpenedConnection {
+  client: Client;
+  close: () => Promise<void>;
+}
+
+export class McpHost implements HostMcpRegistry {
+  private readonly byName = new Map<string, DiscoveredConnection>();
+  private readonly clients = new Map<string, Promise<OpenedConnection>>();
+
+  constructor(connections: DiscoveredConnection[]) {
+    for (const connection of connections) {
+      this.byName.set(connection.name, connection);
+    }
+  }
+
+  /**
+   * Register a connection after construction (serve-time resolved peers).
+   * Clients open lazily on first use, so adding before first call is safe.
+   */
+  addConnection(connection: DiscoveredConnection): void {
+    this.byName.set(connection.name, connection);
+  }
+
+  names(): string[] {
+    return [...this.byName.keys()].sort();
+  }
+
+  async listTools(connectionName: string): Promise<HostMcpToolInfo[]> {
+    const { client } = await this.getClient(connectionName);
+    const listed = await client.listTools();
+    return listed.tools.map((tool) => ({
+      name: tool.name,
+      ...(tool.description === undefined
+        ? {}
+        : { description: tool.description }),
+      ...(tool.inputSchema === undefined
+        ? {}
+        : { inputSchema: tool.inputSchema as JsonObject }),
+    }));
+  }
+
+  async callTool(
+    connectionName: string,
+    toolName: string,
+    args: Record<string, unknown> = {}
+  ): Promise<HostMcpCallResult> {
+    const { client } = await this.getClient(connectionName);
+    const result = await client.callTool({
+      name: toolName,
+      arguments: args,
+    });
+    return normalizeCallResult(result);
+  }
+
+  async close(): Promise<void> {
+    const opened = await Promise.allSettled([...this.clients.values()]);
+    this.clients.clear();
+    await Promise.allSettled(
+      opened.map(async (settled) => {
+        if (settled.status === "fulfilled") {
+          await settled.value.close();
+        }
+      })
+    );
+  }
+
+  private getClient(name: string): Promise<OpenedConnection> {
+    let pending = this.clients.get(name);
+    if (pending === undefined) {
+      pending = this.connect(name).catch((error) => {
+        this.clients.delete(name);
+        throw error;
+      });
+      this.clients.set(name, pending);
+    }
+    return pending;
+  }
+
+  private async connect(name: string): Promise<OpenedConnection> {
+    const connection = this.byName.get(name);
+    if (connection === undefined) {
+      const known = this.names().join(", ") || "(none)";
+      throw new Error(
+        `Unknown MCP connection "${name}". Authored MCP connections: ${known}.`
+      );
+    }
+    return openConnection(connection);
+  }
+}
+
+async function openConnection(
+  connection: DiscoveredConnection
+): Promise<OpenedConnection> {
+  const client = new Client({
+    name: "agent-serve",
+    version: "0.1.0",
+  });
+  const transport = createTransport(connection);
+  await client.connect(transport);
+
+  return {
+    client,
+    close: async () => {
+      try {
+        await client.close();
+      } catch {
+        // Best-effort teardown.
+      }
+      try {
+        await transport.close?.();
+      } catch {
+        // Best-effort teardown.
+      }
+    },
+  };
+}
+
+function createTransport(connection: DiscoveredConnection) {
+  const transport = connection.transport;
+  if ("agent" in transport) {
+    // Peers are resolved to concrete URLs by the serve host before any call
+    // (SessionEngine.setResolvedConnections); reaching here means the
+    // connection is being used outside a running server.
+    throw new Error(
+      `MCP connection "${connection.name}" targets peer agent "${transport.agent}" and has not been resolved; peer MCP connections are only callable on a running serve host.`
+    );
+  }
+  if ("cursorAccount" in transport) {
+    // Same contract as peers: the serve host resolves the account bridge URL
+    // before any call (SessionEngine.setResolvedConnections).
+    throw new Error(
+      `MCP connection "${connection.name}" exposes the Cursor account's connectors and has not been resolved; Cursor account MCP connections are only callable on a running serve host.`
+    );
+  }
+  if ("command" in transport) {
+    return new StdioClientTransport({
+      command: transport.command,
+      ...(transport.args === undefined ? {} : { args: transport.args }),
+      env: {
+        ...Object.fromEntries(
+          Object.entries(process.env).filter(
+            (entry): entry is [string, string] => entry[1] !== undefined
+          )
+        ),
+        ...(transport.env ?? {}),
+      },
+      ...(transport.cwd === undefined ? {} : { cwd: transport.cwd }),
+    });
+  }
+
+  const url = new URL(transport.url);
+  const requestInit =
+    transport.headers === undefined
+      ? undefined
+      : { headers: transport.headers };
+
+  if (transport.type === "sse") {
+    return new SSEClientTransport(url, {
+      ...(requestInit === undefined ? {} : { requestInit }),
+    });
+  }
+
+  return new StreamableHTTPClientTransport(url, {
+    ...(requestInit === undefined ? {} : { requestInit }),
+  });
+}
+
+function normalizeCallResult(result: unknown): HostMcpCallResult {
+  if (typeof result !== "object" || result === null) {
+    return {
+      content: [{ type: "text", text: String(result) }],
+    };
+  }
+  const record = result as {
+    content?: HostMcpCallResult["content"];
+    isError?: boolean;
+    structuredContent?: JsonObject;
+  };
+  return {
+    content: Array.isArray(record.content)
+      ? record.content
+      : [{ type: "text", text: JSON.stringify(result) }],
+    ...(record.isError === undefined ? {} : { isError: record.isError }),
+    ...(record.structuredContent === undefined
+      ? {}
+      : { structuredContent: record.structuredContent }),
+  };
+}

package/src/internal/net.ts

@@ -0,0 +1,31 @@
+/** True for IPv4/IPv6 loopback addresses (including IPv4-mapped IPv6). */
+export function isLoopbackAddress(address: string): boolean {
+  const normalized = address.startsWith("::ffff:")
+    ? address.slice("::ffff:".length)
+    : address;
+  if (normalized === "::1" || normalized === "localhost") {
+    return true;
+  }
+  return normalized.startsWith("127.");
+}
+
+/** True when a parsed URL hostname refers to loopback (localhost / 127.x / ::1). */
+export function isLoopbackHostname(hostname: string): boolean {
+  const normalized = hostname.toLowerCase();
+  if (normalized === "localhost" || normalized === "::1") {
+    return true;
+  }
+  if (normalized.startsWith("[") && normalized.endsWith("]")) {
+    const inner = normalized.slice(1, -1);
+    return inner === "::1";
+  }
+  const ipv4 = /^(\d{1,3})\.(\d{1,3})\.(\d{1,3})\.(\d{1,3})$/.exec(normalized);
+  if (ipv4 === null) {
+    return false;
+  }
+  const octets = ipv4.slice(1, 5).map((part) => Number(part));
+  if (octets.some((octet) => octet > 255)) {
+    return false;
+  }
+  return octets[0] === 127;
+}

package/src/internal/peer-connections.ts

@@ -0,0 +1,100 @@
+/**
+ * Peer MCP connections: `defineConnection({ agent: "<slug>" })` addresses
+ * another agent mounted on the same serve host. Discovery keeps the
+ * transport symbolic (the target slug); the server resolves it to that
+ * agent's MCP endpoint (`/<slug>/v1/mcp`) once mounts and the listen
+ * address are known.
+ *
+ * Local-runtime turns (and host-side `ctx.host.mcp` calls) use the loopback
+ * server URL. Cloud-runtime turns run on a VM that cannot reach loopback,
+ * so they use the serve `publicUrl` when configured — and omit the peer
+ * (with a startup warning) when it is not.
+ */
+
+import { type AgentProject, isPeerConnectionTransport } from "../types.js";
+import { MCP_ENDPOINT_PATH } from "./mcp-endpoint.js";
+import type { EngineResolvedConnection } from "./session-engine.js";
+
+/** A validated peer reference: MCP connection name → target mount slug. */
+export interface PeerConnectionRef {
+  /** Connection (MCP server) name — the filename under `agent/mcp-connections/`. */
+  name: string;
+  /** Slug of the peer agent mount this connection targets. */
+  targetSlug: string;
+}
+
+/**
+ * Validate every peer MCP connection across `mounts` and return them grouped by
+ * the referencing mount's slug. Throws on references to unknown slugs and on
+ * self-references (an agent asking itself recurses forever).
+ */
+export function collectPeerConnections(
+  mounts: Array<{ slug: string; project: AgentProject }>
+): Map<string, PeerConnectionRef[]> {
+  const knownSlugs = new Set(
+    mounts.map(({ slug }) => slug).filter((slug) => slug !== "")
+  );
+  const bySlug = new Map<string, PeerConnectionRef[]>();
+  for (const { slug, project } of mounts) {
+    const refs: PeerConnectionRef[] = [];
+    for (const connection of project.agent.connections) {
+      if (!isPeerConnectionTransport(connection.transport)) {
+        continue;
+      }
+      const targetSlug = connection.transport.agent;
+      const label = slug === "" ? project.name : slug;
+      if (targetSlug === slug) {
+        throw new Error(
+          `Agent "${label}" connection "${connection.name}" references itself (agent: "${targetSlug}"); an agent cannot be its own peer.`
+        );
+      }
+      if (!knownSlugs.has(targetSlug)) {
+        const available = [...knownSlugs].sort().join(", ") || "(none)";
+        throw new Error(
+          `Agent "${label}" connection "${connection.name}" references unknown peer agent "${targetSlug}". Mounted agents: ${available}. Peers require multi-agent serve (each agent mounted under its directory-name slug).`
+        );
+      }
+      refs.push({ name: connection.name, targetSlug });
+    }
+    if (refs.length > 0) {
+      bySlug.set(slug, refs);
+    }
+  }
+  return bySlug;
+}
+
+/**
+ * Resolve validated peer refs to concrete MCP URLs once the server is
+ * listening. `serverUrl` is the loopback base (`http://127.0.0.1:<port>`);
+ * `publicUrl` (when configured) is the externally reachable base used for
+ * cloud-runtime turns. When the host requires a bearer token, it is attached
+ * so peer calls pass the target agent's auth chain.
+ */
+export function resolvePeerConnections(args: {
+  refs: PeerConnectionRef[];
+  serverUrl: string;
+  publicUrl?: string;
+  authToken?: string;
+}): EngineResolvedConnection[] {
+  const serverBase = trimTrailingSlash(args.serverUrl);
+  const publicBase =
+    args.publicUrl === undefined
+      ? undefined
+      : trimTrailingSlash(args.publicUrl);
+  const headers =
+    args.authToken === undefined
+      ? undefined
+      : { authorization: `Bearer ${args.authToken}` };
+  return args.refs.map((ref) => ({
+    name: ref.name,
+    localUrl: `${serverBase}/${ref.targetSlug}${MCP_ENDPOINT_PATH}`,
+    ...(publicBase === undefined
+      ? {}
+      : { cloudUrl: `${publicBase}/${ref.targetSlug}${MCP_ENDPOINT_PATH}` }),
+    ...(headers === undefined ? {} : { headers }),
+  }));
+}
+
+function trimTrailingSlash(url: string): string {
+  return url.endsWith("/") ? url.slice(0, -1) : url;
+}

package/src/internal/playground/static.ts

@@ -0,0 +1,189 @@
+/**
+ * Serves the built Vite playground SPA and the multi-agent index page.
+ *
+ * The playground is a Vite + React app (see `playground/`). `serve` auto-builds
+ * `dist/playground/` when the local vite toolchain is present (see
+ * `toolchain.ts`); `pnpm run build` also emits it for publish. In `--dev`,
+ * Vite HMR is spawned separately; this module only serves the static bundle.
+ *
+ * The server mounts the SPA at `/playground` (single agent) or
+ * `/<slug>/playground` (multi), so the built `index.html` — whose asset URLs
+ * are relative — gets a `<base href>` injected to resolve them under the mount.
+ */
+
+import { existsSync, readFileSync } from "node:fs";
+import { extname, join, normalize } from "node:path";
+import { fileURLToPath } from "node:url";
+
+// src/internal/playground/static.ts -> packages/agent-serve/dist/playground/.
+// Resolves the same from compiled dist/internal/playground/static.js.
+const DIST_DIR = fileURLToPath(
+  new URL("../../../dist/playground/", import.meta.url)
+);
+const INDEX_HTML = join(DIST_DIR, "index.html");
+const ASSETS_DIR = join(DIST_DIR, "assets");
+
+/** Content types for the static bundles this server ships (playground, docs). */
+export const STATIC_CONTENT_TYPES: Record<string, string> = {
+  ".html": "text/html; charset=utf-8",
+  ".js": "text/javascript; charset=utf-8",
+  ".mjs": "text/javascript; charset=utf-8",
+  ".css": "text/css; charset=utf-8",
+  ".map": "application/json; charset=utf-8",
+  ".json": "application/json; charset=utf-8",
+  ".svg": "image/svg+xml",
+  ".png": "image/png",
+  ".jpg": "image/jpeg",
+  ".jpeg": "image/jpeg",
+  ".gif": "image/gif",
+  ".webp": "image/webp",
+  ".ico": "image/x-icon",
+  ".woff": "font/woff",
+  ".woff2": "font/woff2",
+  ".ttf": "font/ttf",
+};
+
+/** Whether `pnpm run build:playground` has produced the SPA bundle. */
+export function playgroundBundleExists(): boolean {
+  return existsSync(INDEX_HTML);
+}
+
+/**
+ * The SPA `index.html` with a `<base href>` injected so its relative asset
+ * URLs resolve under the mount point (`/playground/` or `/<slug>/playground/`).
+ * Falls back to a helpful placeholder page when the bundle is missing.
+ */
+export function renderPlaygroundIndexHtml(baseHref: string): string {
+  if (!playgroundBundleExists()) {
+    return fallbackHtml(baseHref);
+  }
+  const html = readFileSync(INDEX_HTML, "utf8");
+  const baseTag = `<base href="${escapeHtml(baseHref)}" />`;
+  if (html.includes("<head>")) {
+    return html.replace("<head>", `<head>\n    ${baseTag}`);
+  }
+  return `${baseTag}\n${html}`;
+}
+
+/** Serve one built asset from `dist/playground/assets/` by filename. */
+export function renderPlaygroundAsset(file: string): Response {
+  // The route captures a single path segment, but normalize + reject anything
+  // that escapes the assets dir defensively.
+  const safe = normalize(file).replace(/^(\.\.[/\\])+/, "");
+  if (safe.includes("/") || safe.includes("\\") || safe === "") {
+    return new Response("Not found", { status: 404 });
+  }
+  const filePath = join(ASSETS_DIR, safe);
+  if (!filePath.startsWith(ASSETS_DIR) || !existsSync(filePath)) {
+    return new Response("Not found", { status: 404 });
+  }
+  const body = readFileSync(filePath);
+  const type =
+    STATIC_CONTENT_TYPES[extname(safe).toLowerCase()] ??
+    "application/octet-stream";
+  return new Response(new Uint8Array(body), {
+    headers: {
+      "content-type": type,
+      // Vite emits content-hashed filenames, so they are safe to cache hard.
+      "cache-control": "public, max-age=31536000, immutable",
+    },
+  });
+}
+
+/** One row on the multi-agent index page. */
+export interface AgentIndexEntry {
+  slug: string;
+  name: string;
+  model: string;
+  tools: number;
+  channels: number;
+}
+
+/** Standalone index page listing every mounted agent (multi-agent serving). */
+export function renderAgentsIndexHtml(agents: AgentIndexEntry[]): string {
+  const cards = agents
+    .map((agent) => {
+      const meta = `${agent.model || "—"} · ${agent.tools} tool${
+        agent.tools === 1 ? "" : "s"
+      } · ${agent.channels} channel${agent.channels === 1 ? "" : "s"}`;
+      return `      <a class="card" href="/${escapeHtml(agent.slug)}/playground">
+        <div class="card-name">${escapeHtml(agent.name)}</div>
+        <div class="card-slug">/${escapeHtml(agent.slug)}</div>
+        <div class="card-meta">${escapeHtml(meta)}</div>
+      </a>`;
+    })
+    .join("\n");
+  return AGENTS_INDEX_TEMPLATE.replace(
+    "<!--CARDS-->",
+    cards || '      <div class="card-meta">No agents mounted.</div>'
+  ).replace("<!--COUNT-->", String(agents.length));
+}
+
+function escapeHtml(value: string): string {
+  return value
+    .replace(/&/g, "&amp;")
+    .replace(/</g, "&lt;")
+    .replace(/>/g, "&gt;")
+    .replace(/"/g, "&quot;");
+}
+
+function fallbackHtml(baseHref: string): string {
+  return `<!doctype html>
+<html lang="en">
+  <head>
+    <base href="${escapeHtml(baseHref)}" />
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <title>agent-serve playground</title>
+    <style>
+      body { margin: 0; background: #0e1116; color: #e6edf3; font: 14px/1.6 ui-sans-serif, system-ui, sans-serif; }
+      .box { max-width: 640px; margin: 64px auto; padding: 0 24px; }
+      code { background: #1b212b; padding: 2px 6px; border-radius: 6px; font-family: ui-monospace, monospace; }
+      h1 { font-size: 18px; }
+      a { color: #6cb6ff; }
+    </style>
+  </head>
+  <body>
+    <div class="box">
+      <h1>Playground bundle not built</h1>
+      <p>
+        The Vite playground has not been built yet. <code>agent-serve serve</code>
+        auto-builds it when the local vite toolchain is available; otherwise run
+        <code>pnpm run build:playground</code> from <code>packages/agent-serve</code>,
+        or <code>pnpm run dev:playground</code> for Vite HMR.
+      </p>
+    </div>
+  </body>
+</html>`;
+}
+
+const AGENTS_INDEX_TEMPLATE = `<!doctype html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1" />
+    <title>agent-serve — agents</title>
+    <style>
+      :root { color-scheme: dark; }
+      body { margin: 0; background: #0e1116; color: #e6edf3; font: 14px/1.6 ui-sans-serif, system-ui, -apple-system, sans-serif; }
+      .agents-wrap { max-width: 880px; margin: 0 auto; padding: 48px 24px; }
+      .agents-wrap h1 { font-size: 20px; font-weight: 650; margin: 0 0 2px; }
+      .agents-wrap .sub { color: #8b949e; font-size: 13px; margin-bottom: 28px; }
+      .agents-grid { display: grid; grid-template-columns: repeat(auto-fill, minmax(240px, 1fr)); gap: 14px; }
+      .card { display: block; text-decoration: none; color: inherit; background: #161b22; border: 1px solid #30363d; border-radius: 12px; padding: 16px 18px; transition: border-color 0.12s; }
+      .card:hover { border-color: #6cb6ff; }
+      .card-name { font-size: 15px; font-weight: 600; }
+      .card-slug { font-family: ui-monospace, monospace; font-size: 12px; color: #6cb6ff; margin-top: 2px; }
+      .card-meta { color: #6e7681; font-size: 12px; margin-top: 10px; }
+    </style>
+  </head>
+  <body>
+    <div class="agents-wrap">
+      <h1>agent-serve</h1>
+      <div class="sub"><!--COUNT--> agents mounted</div>
+      <div class="agents-grid">
+<!--CARDS-->
+      </div>
+    </div>
+  </body>
+</html>`;