@letta-ai/letta-agent-sdk 0.5.6 → 0.5.7

package/src/mcp.ts

@@ -1,8 +1,9 @@
-import { Client } from "@modelcontextprotocol/sdk/client/index.js";
 import {
-  getDefaultEnvironment,
-  StdioClientTransport,
-} from "@modelcontextprotocol/sdk/client/stdio.js";
+  type ConnectedMcpServer,
+  connectMcpServer,
+  type McpServerConfig as LettaMcpServerConfig,
+  type McpToolDefinition,
+} from "@letta-ai/letta-code/mcp-client";
 import type {
   ConnectMcpServersOptions,
   McpToolBridge,
@@ -11,6 +12,7 @@ import type {
   AgentToolResultContent,
   AnyAgentTool,
   McpServerConfig,
+  McpServers,
 } from "./types.js";
 
 const EMPTY_BRIDGE: McpToolBridge = {
@@ -23,98 +25,119 @@ const CLIENT_INFO = {
   version: "1",
 };
 
+type NamedMcpServer = {
+  name: string;
+  config: McpServerConfig;
+};
+
+type ConnectionResult =
+  | {
+      server: NamedMcpServer;
+      connection: ConnectedMcpServer;
+    }
+  | {
+      server: NamedMcpServer;
+      error: unknown;
+    };
+
 /**
- * Connect stdio MCP servers and expose their tools through Letta Code's
- * external-tool protocol. A broken server is skipped so it cannot prevent the
- * rest of a session from starting.
+ * Connect session-scoped MCP servers through Letta Code's transport-neutral
+ * client and expose their tools through the external-tool protocol. A broken
+ * server is reported but cannot prevent healthy servers from loading.
  */
 export async function connectMcpServers(
-  servers: readonly McpServerConfig[] | undefined,
+  servers: McpServers | undefined,
   options: ConnectMcpServersOptions = {},
 ): Promise<McpToolBridge> {
-  if (!servers || servers.length === 0) return EMPTY_BRIDGE;
+  const namedServers = Object.entries(servers ?? {}).map(([name, config]) => ({
+    name,
+    config,
+  }));
+  if (namedServers.length === 0) return EMPTY_BRIDGE;
 
   const log = options.log ?? ((message: string) => console.error(message));
-  const clients: Client[] = [];
+  const results = await Promise.all(
+    namedServers.map(async (server): Promise<ConnectionResult> => {
+      try {
+        const connection = await connectMcpServer(
+          toLettaMcpServerConfig(server, options.cwd),
+          {
+            clientInfo: CLIENT_INFO,
+            stderr: "inherit",
+          },
+        );
+        return { server, connection };
+      } catch (error) {
+        return { server, error };
+      }
+    }),
+  );
+
+  const connections: ConnectedMcpServer[] = [];
   const tools: AnyAgentTool[] = [];
   const taken = new Set(options.reservedToolNames ?? []);
 
-  for (const server of servers) {
-    let client: Client | null = null;
-    try {
-      client = new Client(CLIENT_INFO);
-      await client.connect(
-        new StdioClientTransport({
-          command: server.command,
-          args: server.args ?? [],
-          env: {
-            ...getDefaultEnvironment(),
-            ...normalizeEnvironment(server.env),
-          },
-          cwd: server.cwd ?? options.cwd,
-          stderr: "inherit",
-        }),
+  for (const result of results) {
+    if ("error" in result) {
+      log(
+        `MCP server "${result.server.name}" unavailable: ${errorMessage(result.error)}`,
       );
+      continue;
+    }
 
-      const listed = await client.listTools();
-      clients.push(client);
-      for (const tool of listed.tools) {
-        const name = uniqueName(
-          `mcp__${sanitize(server.name)}__${sanitize(tool.name)}`,
-          taken,
-        );
-        tools.push(
-          bridgeTool(client, server.name, tool, name),
-        );
-      }
-      log(
-        `MCP server "${server.name}" connected (${listed.tools.length} tool${listed.tools.length === 1 ? "" : "s"})`,
+    connections.push(result.connection);
+    for (const tool of result.connection.tools) {
+      const name = uniqueName(
+        `mcp__${sanitize(result.server.name)}__${sanitize(tool.name)}`,
+        taken,
       );
-    } catch (error) {
-      if (client && !clients.includes(client)) {
-        await client.close().catch(() => undefined);
-      }
-      log(`MCP server "${server.name}" unavailable: ${String(error)}`);
+      tools.push(bridgeTool(result.connection, result.server.name, tool, name));
     }
+    log(
+      `MCP server "${result.server.name}" connected (${result.connection.tools.length} tool${result.connection.tools.length === 1 ? "" : "s"})`,
+    );
   }
 
-  if (clients.length === 0) return EMPTY_BRIDGE;
-
   let closed = false;
   return {
     tools,
     close: async () => {
       if (closed) return;
       closed = true;
-      await Promise.all(
-        clients.map((client) => client.close().catch(() => undefined)),
+      await Promise.allSettled(
+        connections.map((connection) => connection.close()),
       );
     },
   };
 }
 
-function normalizeEnvironment(
-  env: McpServerConfig["env"],
-): Record<string, string> {
-  if (!env) return {};
-  if (!Array.isArray(env)) return env;
-
-  const result: Record<string, string> = {};
-  for (const entry of env) {
-    result[entry.name] = entry.value;
+function toLettaMcpServerConfig(
+  server: NamedMcpServer,
+  sessionCwd: string | undefined,
+): LettaMcpServerConfig {
+  const config = server.config;
+  if (config.type === "http" || config.type === "sse") {
+    return {
+      name: server.name,
+      transport: config.type,
+      url: config.url,
+      ...(config.headers ? { headers: config.headers } : {}),
+    };
   }
-  return result;
-}
-
-interface McpToolDefinition {
-  name: string;
-  title?: string;
-  description?: string;
-  inputSchema?: unknown;
+  return {
+    name: server.name,
+    transport: "stdio",
+    command: config.command,
+    args: config.args ?? [],
+    ...(config.env ? { env: config.env } : {}),
+    ...(config.cwd ?? sessionCwd
+      ? { cwd: config.cwd ?? sessionCwd }
+      : {}),
+  };
 }
 
 function bridgeTool(
-  client: Client,
+  connection: ConnectedMcpServer,
   serverName: string,
   tool: McpToolDefinition,
   name: string,
@@ -126,39 +149,22 @@ function bridgeTool(
       tool.description && tool.description.trim().length > 0
         ? tool.description
         : `The ${tool.name} tool from the ${serverName} MCP server.`,
-    parameters: toolParameters(tool.inputSchema),
+    parameters: tool.inputSchema,
     execute: async (_toolCallId, args, signal) => {
-      const result = await client.callTool(
-        {
-          name: tool.name,
-          arguments: isRecord(args) ? args : {},
-        },
-        undefined,
+      const result = await connection.callTool(
+        tool.name,
+        isRecord(args) ? args : {},
         signal ? { signal } : undefined,
       );
-      const content = toToolResultContent(result.content);
-      if (result.isError) {
-        throw new Error(
-          content
-            .map((item) => item.text ?? "")
-            .filter(Boolean)
-            .join("\n") || `${tool.name} failed`,
-        );
-      }
-      return { content };
+      return {
+        content: toToolResultContent(result.content),
+        ...(result.isError === true ? { isError: true } : {}),
+      };
     },
   };
 }
 
-function toolParameters(inputSchema: unknown): Record<string, unknown> {
-  if (isRecord(inputSchema) && inputSchema.type === "object") {
-    return inputSchema;
-  }
-  return { type: "object", properties: {} };
-}
-
-function toToolResultContent(content: unknown): AgentToolResultContent[] {
-  if (!Array.isArray(content)) return [];
+function toToolResultContent(content: unknown[]): AgentToolResultContent[] {
   const mapped: AgentToolResultContent[] = [];
   for (const block of content) {
     if (!isRecord(block)) continue;
@@ -184,7 +190,7 @@ function toToolResultContent(content: unknown): AgentToolResultContent[] {
 }
 
 function sanitize(name: string): string {
-  return name.replace(/[^a-zA-Z0-9_-]/g, "_");
+  return name.replace(/[^a-zA-Z0-9_-]/g, "_") || "tool";
 }
 
 function uniqueName(name: string, taken: Set<string>): string {
@@ -198,6 +204,10 @@ function uniqueName(name: string, taken: Set<string>): string {
   return candidate;
 }
 
+function errorMessage(error: unknown): string {
+  return error instanceof Error ? error.message : String(error);
+}
+
 function isRecord(value: unknown): value is Record<string, unknown> {
   return typeof value === "object" && value !== null && !Array.isArray(value);
 }

package/src/remote-client-session-core.ts

@@ -572,6 +572,7 @@ export abstract class RemoteClientSessionCore implements LettaCodeSession {
 
   async [Symbol.asyncDispose](): Promise<void> {
     this.close();
+    await this.onCoreDisposed();
   }
 
   async changeDeviceState(
@@ -634,6 +635,10 @@ export abstract class RemoteClientSessionCore implements LettaCodeSession {
     // Optional hook for subclass-owned resources outside the controller.
   }
 
+  protected async onCoreDisposed(): Promise<void> {
+    // Optional hook for awaiting asynchronous cleanup started by onCoreClose().
+  }
+
   protected currentOptions(): LettaCodeClientSessionOptions | CreateAgentOptions {
     return this.mode.options;
   }

package/src/types.ts

@@ -227,6 +227,8 @@ export interface AgentToolResultContent {
  */
 export interface AgentToolResult<T> {
   content: AgentToolResultContent[];
+  /** Whether the tool completed with a model-visible error result. */
+  isError?: boolean;
   details?: T;
 }
 
@@ -266,27 +268,39 @@ export interface AgentTool<TParams, TResult> {
 // eslint-disable-next-line @typescript-eslint/no-explicit-any
 export type AnyAgentTool = AgentTool<any, unknown>;
 
-/** Environment variable passed to a stdio MCP server. */
-export interface McpServerEnvironmentVariable {
-  name: string;
-  value: string;
-}
-
-/**
- * A stdio MCP server whose tools should be exposed to a Letta Code session.
- *
- * The environment accepts either the object form commonly used by MCP clients
- * or the name/value array used by ACP clients such as Zed.
- */
-export interface McpServerConfig {
-  name: string;
+/** A local MCP process connected over stdin/stdout. */
+export interface McpStdioServerConfig {
+  type?: "stdio";
   command: string;
   args?: string[];
-  env?: Record<string, string> | McpServerEnvironmentVariable[];
+  env?: Record<string, string>;
   /** Override the session cwd for this server process. */
   cwd?: string;
 }
 
+/** A remote MCP server using Streamable HTTP. */
+export interface McpHttpServerConfig {
+  type: "http";
+  url: string;
+  headers?: Record<string, string>;
+}
+
+/** A remote MCP server using the legacy SSE transport. */
+export interface McpSseServerConfig {
+  type: "sse";
+  url: string;
+  headers?: Record<string, string>;
+}
+
+/** One MCP server definition. The key in {@link McpServers} supplies its name. */
+export type McpServerConfig =
+  | McpStdioServerConfig
+  | McpHttpServerConfig
+  | McpSseServerConfig;
+
+/** MCP servers keyed by the name used in `mcp__<server>__<tool>`. */
+export type McpServers = Record<string, McpServerConfig>;
+
 // ═══════════════════════════════════════════════════════════════
 // TOP-LEVEL CLIENT TYPES
 // ═══════════════════════════════════════════════════════════════
@@ -668,10 +682,11 @@ export interface CreateSessionOptions {
   tools?: AnyAgentTool[];
 
   /**
-   * Stdio MCP servers whose tools execute in the SDK process and are exposed
-   * through Letta Code's external-tool protocol for this session.
+   * Session-scoped MCP servers keyed by server name. Stdio processes and
+   * remote HTTP/SSE connections run in the Node SDK process and are exposed
+   * through Letta Code's external-tool protocol.
    */
-  mcpServers?: McpServerConfig[];
+  mcpServers?: McpServers;
 
   /**
    * Max automatic approval-conflict recovery attempts per runTurn() call.

package/src/validation.ts

@@ -8,6 +8,7 @@ import type {
   CreateSessionOptions,
   CreateAgentOptions,
   MemoryItem, 
+  McpServers,
   CreateBlock,
   SystemPromptPreset,
   SkillSource,
@@ -173,11 +174,41 @@ function validateReasoningEffort(value: unknown): void {
   }
 }
 
+function validateMcpServers(servers: McpServers | undefined): void {
+  if (servers === undefined) return;
+  if (!servers || typeof servers !== "object" || Array.isArray(servers)) {
+    throw new Error("Invalid mcpServers. Expected an object keyed by server name.");
+  }
+  for (const [name, config] of Object.entries(servers)) {
+    if (name.length === 0) {
+      throw new Error("Invalid mcpServers. Server names must be non-empty.");
+    }
+    if (!config || typeof config !== "object" || Array.isArray(config)) {
+      throw new Error(`Invalid MCP server '${name}'. Expected a configuration object.`);
+    }
+    if (config.type === "http" || config.type === "sse") {
+      if (typeof config.url !== "string" || config.url.length === 0) {
+        throw new Error(`Invalid MCP server '${name}'. Expected a non-empty url.`);
+      }
+      continue;
+    }
+    if (config.type !== undefined && config.type !== "stdio") {
+      throw new Error(
+        `Invalid MCP server '${name}' type '${String(config.type)}'. Valid values: stdio, http, sse.`,
+      );
+    }
+    if (typeof config.command !== "string" || config.command.length === 0) {
+      throw new Error(`Invalid MCP server '${name}'. Expected a non-empty command.`);
+    }
+  }
+}
+
 /**
  * Validate CreateSessionOptions (used by createSession and resumeSession).
  */
 export function validateCreateSessionOptions(options: CreateSessionOptions): void {
   validateSkillSources(options.skillSources);
+  validateMcpServers(options.mcpServers);
   validateReasoningEffort(options.reasoningEffort);
   validateDreamingOptions(options.dreaming);
   validateApprovalRecoveryOptions(options);