@mastra/mcp 1.6.1-alpha.1 → 1.7.0

package/dist/index.js

@@ -13,9 +13,11 @@ import { createHash, randomUUID } from 'crypto';
 import { MastraError, ErrorCategory, ErrorDomain } from '@mastra/core/error';
 import equal from 'fast-deep-equal';
 import { MCPServerBase } from '@mastra/core/mcp';
-import { RequestContext } from '@mastra/core/request-context';
 import { isStandardSchemaWithJSON, standardSchemaToJSONSchema } from '@mastra/core/schema';
+import { readFileSync } from 'fs';
+import { RequestContext } from '@mastra/core/request-context';
 import { makeCoreTool } from '@mastra/core/utils';
+import { RESOURCE_MIME_TYPE, RESOURCE_URI_META_KEY } from '@modelcontextprotocol/ext-apps';
 import { Server } from '@modelcontextprotocol/sdk/server/index.js';
 import { SSEServerTransport } from '@modelcontextprotocol/sdk/server/sse.js';
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
@@ -535,7 +537,12 @@ var InternalMastraMCPClient = class extends MastraBase {
         ...capabilities.elicitation ?? {}
       },
       // Auto-enable roots capability if roots are provided
-      ...hasRoots ? { roots: { listChanged: true, ...capabilities.roots ?? {} } } : {}
+      ...hasRoots ? { roots: { listChanged: true, ...capabilities.roots ?? {} } } : {},
+      // Advertise MCP Apps extension support so servers know we can render UI resources
+      extensions: {
+        ...capabilities.extensions ?? {},
+        "io.modelcontextprotocol/ui": {}
+      }
     };
     this.client = new Client(
       {
@@ -968,11 +975,16 @@ var InternalMastraMCPClient = class extends MastraBase {
         } else if (this.requireToolApproval === true) {
           requireApproval = true;
         }
+        const rawMeta = tool._meta;
+        const toolMeta = rawMeta ? this.stampServerIdInMeta(rawMeta) : void 0;
         const mastraTool = createTool({
           id: `${this.name}_${tool.name}`,
           description: tool.description || "",
           inputSchema: await this.convertInputSchema(tool.inputSchema),
-          strict: getMastraToolStrictMeta(tool._meta),
+          strict: getMastraToolStrictMeta(toolMeta),
+          // Preserve the full _meta from the remote MCP server (including ui.resourceUri
+          // for MCP Apps) so downstream consumers (e.g. Studio) can detect app tools.
+          ...toolMeta ? { mcp: { _meta: toolMeta } } : {},
           // Don't pass outputSchema to createTool — the MCP SDK's Client.callTool()
           // already validates structuredContent against the tool's outputSchema using AJV.
           // Passing it here causes Zod to strip unrecognized keys from the CallToolResult
@@ -1052,7 +1064,152 @@ var InternalMastraMCPClient = class extends MastraBase {
     }
     return toolsRes;
   }
+  stampServerIdInMeta(meta) {
+    const ui = meta.ui;
+    if (!ui?.resourceUri) return meta;
+    return {
+      ...meta,
+      ui: { ...ui, serverId: this.name }
+    };
+  }
+};
+var MCPClientServerProxy = class extends MCPServerBase {
+  clientGetter;
+  cachedClient = null;
+  _cachedToolList = null;
+  constructor(config, clientGetter) {
+    const serverConfig = {
+      name: config.name,
+      version: config.version ?? "1.0.0",
+      id: config.id,
+      description: config.description,
+      tools: {}
+    };
+    super(serverConfig);
+    this.clientGetter = clientGetter;
+  }
+  async getClient() {
+    if (!this.cachedClient) {
+      this.cachedClient = await this.clientGetter();
+    }
+    return this.cachedClient;
+  }
+  convertSchema(schema) {
+    if (isStandardSchemaWithJSON(schema)) {
+      return standardSchemaToJSONSchema(schema);
+    }
+    return schema?.jsonSchema || schema;
+  }
+  async fetchToolList() {
+    if (this._cachedToolList) return this._cachedToolList;
+    const client = await this.getClient();
+    const tools = await client.tools();
+    this._cachedToolList = {
+      tools: Object.entries(tools).map(([toolName, tool]) => ({
+        id: toolName,
+        name: tool.id || toolName,
+        description: tool.description,
+        inputSchema: this.convertSchema(tool.inputSchema),
+        outputSchema: this.convertSchema(tool.outputSchema),
+        toolType: tool.mcp?.toolType,
+        _meta: tool.mcp?._meta
+      }))
+    };
+    this.convertedTools = tools;
+    return this._cachedToolList;
+  }
+  // ---------- MCPServerBase abstract implementations ----------
+  convertTools(_tools, _agents, _workflows) {
+    return {};
+  }
+  /**
+   * Returns the cached tool list synchronously, or triggers an async fetch.
+   * The Studio API handlers are async and will auto-await a returned Promise.
+   */
+  getToolListInfo() {
+    if (this._cachedToolList) return this._cachedToolList;
+    return this.fetchToolList();
+  }
+  getToolInfo(toolId) {
+    if (this._cachedToolList) {
+      return this._cachedToolList.tools.find((t) => t.id === toolId || t.name === toolId);
+    }
+    return this.fetchToolList().then((list) => list.tools.find((t) => t.id === toolId || t.name === toolId));
+  }
+  async executeTool(toolId, args, _executionContext) {
+    const client = await this.getClient();
+    const tools = await client.tools();
+    const tool = tools[toolId];
+    if (!tool) {
+      throw new Error(`Tool '${toolId}' not found on remote MCP server '${this.name}'`);
+    }
+    if (!tool.execute) {
+      throw new Error(`Tool '${toolId}' on remote MCP server '${this.name}' has no execute method`);
+    }
+    return tool.execute(args, _executionContext);
+  }
+  async listResources() {
+    const client = await this.getClient();
+    const resources = await client.resources.list();
+    return {
+      resources: resources.map((r) => ({
+        uri: r.uri,
+        name: r.name ?? r.uri,
+        description: r.description,
+        mimeType: r.mimeType,
+        _meta: r._meta
+      }))
+    };
+  }
+  async readResource(uri) {
+    const client = await this.getClient();
+    const result = await client.resources.read(uri);
+    return {
+      contents: (result.contents ?? []).map((c) => ({
+        uri: c.uri ?? uri,
+        ...c.text !== void 0 ? { text: c.text } : {},
+        ...c.blob !== void 0 ? { blob: c.blob } : {}
+      }))
+    };
+  }
+  // Transport methods — not applicable for client proxies
+  async startStdio() {
+    throw new Error("MCPClientServerProxy does not support stdio transport");
+  }
+  async startSSE(_options) {
+    throw new Error("MCPClientServerProxy does not support SSE transport");
+  }
+  async startHonoSSE(_options) {
+    throw new Error("MCPClientServerProxy does not support Hono SSE transport");
+  }
+  async startHTTP(_options) {
+    throw new Error("MCPClientServerProxy does not support HTTP transport");
+  }
+  async close() {
+    this.cachedClient = null;
+  }
+  getServerInfo() {
+    return {
+      id: this.id,
+      name: this.name,
+      description: this.description,
+      version_detail: {
+        version: this.version,
+        release_date: this.releaseDate,
+        is_latest: this.isLatest
+      }
+    };
+  }
+  getServerDetail() {
+    return {
+      ...this.getServerInfo(),
+      packages: this.packages ?? [],
+      remotes: this.remotes ?? []
+    };
+  }
 };
+
+// src/client/configuration.ts
 var mcpClientInstances = /* @__PURE__ */ new Map();
 var TOOL_DISCOVERY_MAX_ATTEMPTS = 2;
 var MCPClient = class extends MastraBase {
@@ -1820,6 +1977,39 @@ To fix this you have three different options:
     }
     return { toolsets: connectedToolsets, errors };
   }
+  /**
+   * Creates MCPServerBase-compatible proxy objects for each server connection
+   * in this MCPClient.  The returned record can be spread directly into
+   * Mastra's `mcpServers` config so that external (non-Mastra) servers
+   * appear in Studio alongside native MCPServer instances.
+   *
+   * @returns Record mapping server names to MCPServerBase proxy instances
+   *
+   * @example
+   * ```typescript
+   * const mcp = new MCPClient({
+   *   servers: {
+   *     trailhead: { command: 'npx', args: ['trailhead-server'] },
+   *   },
+   * });
+   *
+   * const mastra = new Mastra({
+   *   mcpServers: {
+   *     ...mcp.toMCPServerProxies(),
+   *   },
+   * });
+   * ```
+   */
+  toMCPServerProxies() {
+    const proxies = {};
+    for (const serverName of Object.keys(this.serverConfigs)) {
+      proxies[serverName] = new MCPClientServerProxy(
+        { name: serverName, id: serverName },
+        () => this.getConnectedClientForServer(serverName)
+      );
+    }
+    return proxies;
+  }
   /**
    * Gets current session IDs for all connected MCP clients using Streamable HTTP transport.
    *
@@ -2677,19 +2867,28 @@ var MCPServer = class extends MCPServerBase {
    */
   constructor(opts) {
     super(opts);
-    this.resourceOptions = opts.resources;
+    this.resourceOptions = this.mergeAppResources(opts.resources, opts.appResources);
     this.promptOptions = opts.prompts;
     this.jsonSchemaValidator = opts.jsonSchemaValidator;
     const capabilities = {
       tools: {},
       logging: { enabled: true }
     };
-    if (opts.resources) {
+    if (this.resourceOptions) {
       capabilities.resources = { subscribe: true, listChanged: true };
     }
     if (opts.prompts) {
       capabilities.prompts = { listChanged: true };
     }
+    const hasUiTools = Object.values(this.convertedTools).some(
+      (tool) => tool.mcp?._meta?.ui?.resourceUri
+    );
+    if (hasUiTools || opts.appResources) {
+      capabilities.extensions = {
+        ...capabilities.extensions,
+        "io.modelcontextprotocol/ui": {}
+      };
+    }
     this.server = new Server(
       {
         name: this.name,
@@ -2785,6 +2984,81 @@ var MCPServer = class extends MCPServerBase {
       req.on("error", reject);
     });
   }
+  /**
+   * Merges appResources into the resource system alongside any user-provided resources.
+   *
+   * App resources are auto-registered as `ui://` resources with the MCP Apps MIME type.
+   * If the user also provides a `resources` config, the two are merged — user callbacks
+   * take precedence for overlapping URIs.
+   */
+  mergeAppResources(userResources, appResources) {
+    if (!appResources || Object.keys(appResources).length === 0) {
+      return userResources;
+    }
+    const resolvedAppResources = /* @__PURE__ */ new Map();
+    for (const [uri, appResource] of Object.entries(appResources)) {
+      let html;
+      if (appResource.html) {
+        html = appResource.html;
+      } else if (appResource.htmlPath) {
+        html = readFileSync(appResource.htmlPath, "utf-8");
+      } else {
+        this.logger.warn(`App resource '${uri}' has neither html nor htmlPath \u2014 skipping`);
+        continue;
+      }
+      const resource = {
+        uri,
+        name: appResource.name,
+        ...appResource.description ? { description: appResource.description } : {},
+        mimeType: RESOURCE_MIME_TYPE,
+        ...appResource.meta ? { _meta: { ui: appResource.meta } } : {}
+      };
+      resolvedAppResources.set(uri, { resource, html });
+    }
+    if (resolvedAppResources.size === 0) {
+      return userResources;
+    }
+    const appListResources = async () => {
+      return Array.from(resolvedAppResources.values()).map((r) => r.resource);
+    };
+    const appGetResourceContent = async ({ uri }) => {
+      const appRes = resolvedAppResources.get(uri);
+      if (appRes) {
+        return { text: appRes.html };
+      }
+      throw new Error(`App resource not found: ${uri}`);
+    };
+    if (!userResources) {
+      return {
+        listResources: appListResources,
+        getResourceContent: appGetResourceContent
+      };
+    }
+    return {
+      listResources: async ({ extra }) => {
+        const userResourceList = await userResources.listResources({ extra });
+        const appResourceList = await appListResources();
+        const userUris = new Set(userResourceList.map((r) => r.uri));
+        const nonConflicting = appResourceList.filter((r) => !userUris.has(r.uri));
+        return [...userResourceList, ...nonConflicting];
+      },
+      getResourceContent: async ({ uri, extra }) => {
+        const appRes = resolvedAppResources.get(uri);
+        if (appRes) {
+          try {
+            const userResourceList = await userResources.listResources({ extra });
+            if (userResourceList.some((r) => r.uri === uri)) {
+              return userResources.getResourceContent({ uri, extra });
+            }
+          } catch {
+          }
+          return { text: appRes.html };
+        }
+        return userResources.getResourceContent({ uri, extra });
+      },
+      ...userResources.resourceTemplates ? { resourceTemplates: userResources.resourceTemplates } : {}
+    };
+  }
   /**
    * Creates a new Server instance configured with all handlers for HTTP sessions.
    * Each HTTP client connection gets its own Server instance to avoid routing conflicts.
@@ -2800,6 +3074,18 @@ var MCPServer = class extends MCPServerBase {
     if (this.promptOptions) {
       capabilities.prompts = { listChanged: true };
     }
+    const hasUiTools = Object.values(this.convertedTools).some(
+      (tool) => tool.mcp?._meta?.ui?.resourceUri
+    );
+    if (hasUiTools || this.resourceOptions) {
+      const hasUiResources = this.definedResources?.some((r) => r.uri.startsWith("ui://"));
+      if (hasUiTools || hasUiResources) {
+        capabilities.extensions = {
+          ...capabilities.extensions,
+          "io.modelcontextprotocol/ui": {}
+        };
+      }
+    }
     const serverInstance = new Server(
       {
         name: this.name,
@@ -2837,7 +3123,15 @@ var MCPServer = class extends MCPServerBase {
           }
           const toolMeta = withMastraToolStrictMeta(tool.mcp?._meta, tool.strict);
           if (toolMeta) {
-            toolSpec._meta = toolMeta;
+            const uiMeta = toolMeta.ui;
+            const legacyUri = toolMeta[RESOURCE_URI_META_KEY];
+            if (uiMeta?.resourceUri && !legacyUri) {
+              toolSpec._meta = { ...toolMeta, [RESOURCE_URI_META_KEY]: uiMeta.resourceUri };
+            } else if (legacyUri && !uiMeta?.resourceUri) {
+              toolSpec._meta = { ...toolMeta, ui: { ...toolMeta.ui ?? {}, resourceUri: legacyUri } };
+            } else {
+              toolSpec._meta = toolMeta;
+            }
           }
           return toolSpec;
         })
@@ -4330,6 +4624,53 @@ Provided arguments: ${JSON.stringify(args, null, 2)}`,
       throw mastraError;
     }
   }
+  /**
+   * Reads the content of a resource by URI.
+   *
+   * Used by the Studio API to proxy `ui://` resource reads for MCP Apps rendering.
+   *
+   * @param uri - The resource URI to read (e.g. `ui://weather/dashboard`)
+   * @returns Promise resolving to the resource content
+   */
+  async readResource(uri) {
+    if (!this.resourceOptions?.getResourceContent) {
+      throw new MastraError({
+        id: "MCP_SERVER_RESOURCES_NOT_CONFIGURED",
+        domain: ErrorDomain.MCP,
+        category: ErrorCategory.USER,
+        details: { uri }
+      });
+    }
+    const extra = {};
+    const result = await this.resourceOptions.getResourceContent({ uri, extra });
+    const contents = Array.isArray(result) ? result : [result];
+    return {
+      contents: contents.map((c) => ({
+        uri,
+        ..."text" in c && c.text !== void 0 ? { text: c.text } : {},
+        ..."blob" in c && c.blob !== void 0 ? { blob: c.blob } : {}
+      }))
+    };
+  }
+  /**
+   * Lists all resources available on this MCP server.
+   *
+   * Used by the Studio API to discover `ui://` resources for MCP Apps.
+   *
+   * @returns Promise resolving to the list of resources
+   */
+  async listResources() {
+    if (!this.resourceOptions?.listResources) {
+      return { resources: [] };
+    }
+    const extra = {};
+    if (this.definedResources) {
+      return { resources: this.definedResources };
+    }
+    const resources = await this.resourceOptions.listResources({ extra });
+    this.definedResources = resources;
+    return { resources };
+  }
 };
 function escapeHeaderValue(value) {
   return value.replace(/\\/g, "\\\\").replace(/"/g, '\\"');
@@ -4535,6 +4876,6 @@ function createIntrospectionValidator(introspectionEndpoint, clientCredentials)
   };
 }
 
-export { InMemoryOAuthStorage, InternalMastraMCPClient, MCPClient, MCPOAuthClientProvider, MCPServer, createIntrospectionValidator, createOAuthMiddleware, createSimpleTokenProvider, createStaticTokenValidator, extractBearerToken, generateProtectedResourceMetadata, generateWWWAuthenticateHeader };
+export { InMemoryOAuthStorage, InternalMastraMCPClient, MCPClient, MCPClientServerProxy, MCPOAuthClientProvider, MCPServer, createIntrospectionValidator, createOAuthMiddleware, createSimpleTokenProvider, createStaticTokenValidator, extractBearerToken, generateProtectedResourceMetadata, generateWWWAuthenticateHeader };
 //# sourceMappingURL=index.js.map
 //# sourceMappingURL=index.js.map