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

package/src/mcp.ts

@@ -0,0 +1,213 @@
+import {
+  type ConnectedMcpServer,
+  connectMcpServer,
+  type McpServerConfig as LettaMcpServerConfig,
+  type McpToolDefinition,
+} from "@letta-ai/letta-code/mcp-client";
+import type {
+  ConnectMcpServersOptions,
+  McpToolBridge,
+} from "./mcp-runtime.js";
+import type {
+  AgentToolResultContent,
+  AnyAgentTool,
+  McpServerConfig,
+  McpServers,
+} from "./types.js";
+
+const EMPTY_BRIDGE: McpToolBridge = {
+  tools: [],
+  close: async () => undefined,
+};
+
+const CLIENT_INFO = {
+  name: "@letta-ai/letta-agent-sdk",
+  version: "1",
+};
+
+type NamedMcpServer = {
+  name: string;
+  config: McpServerConfig;
+};
+
+type ConnectionResult =
+  | {
+      server: NamedMcpServer;
+      connection: ConnectedMcpServer;
+    }
+  | {
+      server: NamedMcpServer;
+      error: unknown;
+    };
+
+/**
+ * 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: McpServers | undefined,
+  options: ConnectMcpServersOptions = {},
+): Promise<McpToolBridge> {
+  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 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 result of results) {
+    if ("error" in result) {
+      log(
+        `MCP server "${result.server.name}" unavailable: ${errorMessage(result.error)}`,
+      );
+      continue;
+    }
+
+    connections.push(result.connection);
+    for (const tool of result.connection.tools) {
+      const name = uniqueName(
+        `mcp__${sanitize(result.server.name)}__${sanitize(tool.name)}`,
+        taken,
+      );
+      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"})`,
+    );
+  }
+
+  let closed = false;
+  return {
+    tools,
+    close: async () => {
+      if (closed) return;
+      closed = true;
+      await Promise.allSettled(
+        connections.map((connection) => connection.close()),
+      );
+    },
+  };
+}
+
+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 {
+    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(
+  connection: ConnectedMcpServer,
+  serverName: string,
+  tool: McpToolDefinition,
+  name: string,
+): AnyAgentTool {
+  return {
+    name,
+    label: tool.title ?? tool.name,
+    description:
+      tool.description && tool.description.trim().length > 0
+        ? tool.description
+        : `The ${tool.name} tool from the ${serverName} MCP server.`,
+    parameters: tool.inputSchema,
+    execute: async (_toolCallId, args, signal) => {
+      const result = await connection.callTool(
+        tool.name,
+        isRecord(args) ? args : {},
+        signal ? { signal } : undefined,
+      );
+      return {
+        content: toToolResultContent(result.content),
+        ...(result.isError === true ? { isError: true } : {}),
+      };
+    },
+  };
+}
+
+function toToolResultContent(content: unknown[]): AgentToolResultContent[] {
+  const mapped: AgentToolResultContent[] = [];
+  for (const block of content) {
+    if (!isRecord(block)) continue;
+    if (block.type === "text" && typeof block.text === "string") {
+      mapped.push({ type: "text", text: block.text });
+      continue;
+    }
+    if (
+      block.type === "image" &&
+      typeof block.data === "string" &&
+      typeof block.mimeType === "string"
+    ) {
+      mapped.push({
+        type: "image",
+        data: block.data,
+        mimeType: block.mimeType,
+      });
+      continue;
+    }
+    mapped.push({ type: "text", text: JSON.stringify(block) });
+  }
+  return mapped;
+}
+
+function sanitize(name: string): string {
+  return name.replace(/[^a-zA-Z0-9_-]/g, "_") || "tool";
+}
+
+function uniqueName(name: string, taken: Set<string>): string {
+  let candidate = name;
+  let suffix = 2;
+  while (taken.has(candidate)) {
+    candidate = `${name}_${suffix}`;
+    suffix += 1;
+  }
+  taken.add(candidate);
+  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,6 +268,39 @@ export interface AgentTool<TParams, TResult> {
 // eslint-disable-next-line @typescript-eslint/no-explicit-any
 export type AnyAgentTool = AgentTool<any, unknown>;
 
+/** A local MCP process connected over stdin/stdout. */
+export interface McpStdioServerConfig {
+  type?: "stdio";
+  command: string;
+  args?: string[];
+  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
 // ═══════════════════════════════════════════════════════════════
@@ -646,6 +681,13 @@ export interface CreateSessionOptions {
    */
   tools?: AnyAgentTool[];
 
+  /**
+   * 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?: McpServers;
+
   /**
    * Max automatic approval-conflict recovery attempts per runTurn() call.
    * Set to 0 to disable automatic recovery.

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);