npm - @mastra/mcp - Versions diffs - 1.6.1-alpha.1 → 1.7.0 - Mend

@mastra/mcp 1.6.1-alpha.1 → 1.7.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (24) hide show

package/CHANGELOG.md +100 -0
package/dist/client/client.d.ts +1 -0
package/dist/client/client.d.ts.map +1 -1
package/dist/client/configuration.d.ts +26 -0
package/dist/client/configuration.d.ts.map +1 -1
package/dist/client/index.d.ts +1 -0
package/dist/client/index.d.ts.map +1 -1
package/dist/client/server-proxy.d.ts +88 -0
package/dist/client/server-proxy.d.ts.map +1 -0
package/dist/docs/SKILL.md +2 -1
package/dist/docs/assets/SOURCE_MAP.json +1 -1
package/dist/docs/references/docs-mcp-mcp-apps.md +304 -0
package/dist/docs/references/docs-mcp-overview.md +7 -0
package/dist/docs/references/reference-tools-mcp-client.md +32 -0
package/dist/docs/references/reference-tools-mcp-server.md +64 -0
package/dist/index.cjs +348 -6
package/dist/index.cjs.map +1 -1
package/dist/index.js +348 -7
package/dist/index.js.map +1 -1
package/dist/server/server.d.ts +59 -1
package/dist/server/server.d.ts.map +1 -1
package/dist/server/types.d.ts +37 -0
package/dist/server/types.d.ts.map +1 -1
package/package.json +8 -7

package/dist/docs/references/reference-tools-mcp-client.md CHANGED Viewed

@@ -126,6 +126,38 @@ Disconnects from all MCP servers and cleans up resources.
 async disconnect(): Promise<void>
 ```
+### `toMCPServerProxies()`
+Returns a map of `MCPClientServerProxy` instances, one per configured server. Each proxy wraps the underlying client connection as an `MCPServerBase` instance, allowing external (non-Mastra) MCP servers to be registered in `mcpServers` and appear in Studio.
+```typescript
+async toMCPServerProxies(): Promise<Record<string, MCPClientServerProxy>>
+```
+Spread the result into the `mcpServers` config on `Mastra`:
+```typescript
+import { Mastra } from '@mastra/core/mastra'
+import { MCPClient } from '@mastra/mcp'
+const mcpClient = new MCPClient({
+  servers: {
+    'color-mixer': {
+      command: 'node',
+      args: ['path/to/color-mixer-server.js'],
+    },
+  },
+})
+export const mastra = new Mastra({
+  mcpServers: {
+    ...(await mcpClient.toMCPServerProxies()),
+  },
+})
+```
+This is useful for connecting external MCP servers that implement the MCP Apps extension or other features to Studio without wrapping them in a Mastra `MCPServer`.
 ### `resources` Property
 The `MCPClient` instance has a `resources` property that provides access to resource-related operations.

package/dist/docs/references/reference-tools-mcp-server.md CHANGED Viewed

@@ -83,6 +83,8 @@ The constructor accepts an `MCPServerConfig` object with the following propertie
 **prompts** (`MCPServerPrompts`): An object defining how the server should handle MCP prompts. See Prompt Handling section for details.
+**appResources** (`AppResources`): A map of \`ui://\` URIs to app resource configurations. Each entry defines an interactive HTML UI served via the MCP Apps extension (SEP-1865). See the MCP Apps section for details.
 ## Exposing agents as tools
 A powerful feature of `MCPServer` is its ability to automatically expose your Mastra Agents as callable tools. When you provide agents in the `agents` property of the configuration:
@@ -1263,6 +1265,68 @@ app.all('/mcp', async (req, res) => {
 app.listen(3000)
 ```
+## MCP Apps (`appResources`)
+The `appResources` option lets you serve interactive HTML UIs from your MCP server via the [MCP Apps extension](https://github.com/modelcontextprotocol/ext-apps). Each entry maps a `ui://` URI to an HTML app that renders in a sandboxed iframe in Mastra Studio.
+### `AppResources` type
+**Key (URI)** (`string`): A \`ui://\` URI that identifies the app resource (e.g., \`ui://calculator/main\`).
+Each value is an `AppResource` object:
+**name** (`string`): Display name for the UI resource.
+**description** (`string`): Optional description of the UI resource.
+**html** (`string`): Inline HTML content for the UI. Provide either \`html\` or \`htmlPath\`.
+**htmlPath** (`string`): Path to an HTML file. Resolved at server startup. Provide either \`html\` or \`htmlPath\`.
+**meta** (`McpUiResourceMeta`): UI resource metadata (CSP, permissions, rendering preferences) from the official ext-apps SDK.
+### Example
+```typescript
+import { MCPServer } from '@mastra/mcp'
+import { createTool } from '@mastra/core/tools'
+import { z } from 'zod'
+const calculatorTool = createTool({
+  id: 'calculatorWithUI',
+  description: 'An interactive calculator',
+  inputSchema: z.object({
+    num1: z.number(),
+    num2: z.number(),
+    operation: z.enum(['add', 'subtract']),
+  }),
+  execute: async ({ num1, num2, operation }) => {
+    const result = operation === 'add' ? num1 + num2 : num1 - num2
+    return {
+      content: [{ type: 'text', text: 'An interactive calculator is displayed.' }],
+      structuredContent: { result },
+    }
+  },
+})
+const server = new MCPServer({
+  id: 'app-server',
+  name: 'App Server',
+  version: '1.0.0',
+  tools: { calculatorTool },
+  appResources: {
+    'ui://calculator/main': {
+      name: 'Interactive Calculator',
+      html: '<html><body><h2>Calculator</h2>...</body></html>',
+    },
+  },
+})
+```
+Link a tool to its app resource by setting `_meta.ui.resourceUri` on the tool to the matching `ui://` URI. The server auto-normalizes this metadata when registering tools.
+> **Note:** Visit [MCP Apps](https://mastra.ai/docs/mcp/mcp-apps) for the full app bridge API and usage patterns.
 ## Related information
 - For connecting to MCP servers in Mastra, see the [MCPClient documentation](https://mastra.ai/reference/tools/mcp-client).

package/dist/index.cjs CHANGED Viewed

@@ -15,9 +15,11 @@ var crypto$1 = require('crypto');
 var error = require('@mastra/core/error');
 var equal = require('fast-deep-equal');
 var mcp = require('@mastra/core/mcp');
-var requestContext = require('@mastra/core/request-context');
 var schema = require('@mastra/core/schema');
+var fs = require('fs');
+var requestContext = require('@mastra/core/request-context');
 var utils = require('@mastra/core/utils');
+var extApps = require('@modelcontextprotocol/ext-apps');
 var index_js$1 = require('@modelcontextprotocol/sdk/server/index.js');
 var sse_js$1 = require('@modelcontextprotocol/sdk/server/sse.js');
 var stdio_js$1 = require('@modelcontextprotocol/sdk/server/stdio.js');
@@ -542,7 +544,12 @@ var InternalMastraMCPClient = class extends base.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 index_js.Client(
       {
@@ -975,11 +982,16 @@ var InternalMastraMCPClient = class extends base.MastraBase {
         } else if (this.requireToolApproval === true) {
           requireApproval = true;
         }
+        const rawMeta = tool._meta;
+        const toolMeta = rawMeta ? this.stampServerIdInMeta(rawMeta) : void 0;
         const mastraTool = tools.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
@@ -1059,7 +1071,152 @@ var InternalMastraMCPClient = class extends base.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 mcp.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$1) {
+    if (schema.isStandardSchemaWithJSON(schema$1)) {
+      return schema.standardSchemaToJSONSchema(schema$1);
+    }
+    return schema$1?.jsonSchema || schema$1;
+  }
+  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 base.MastraBase {
@@ -1827,6 +1984,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.
    *
@@ -2684,19 +2874,28 @@ var MCPServer = class extends mcp.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 index_js$1.Server(
       {
         name: this.name,
@@ -2792,6 +2991,81 @@ var MCPServer = class extends mcp.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 = fs.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: extApps.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.
@@ -2807,6 +3081,18 @@ var MCPServer = class extends mcp.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 index_js$1.Server(
       {
         name: this.name,
@@ -2844,7 +3130,15 @@ var MCPServer = class extends mcp.MCPServerBase {
           }
           const toolMeta = withMastraToolStrictMeta(tool.mcp?._meta, tool.strict);
           if (toolMeta) {
-            toolSpec._meta = toolMeta;
+            const uiMeta = toolMeta.ui;
+            const legacyUri = toolMeta[extApps.RESOURCE_URI_META_KEY];
+            if (uiMeta?.resourceUri && !legacyUri) {
+              toolSpec._meta = { ...toolMeta, [extApps.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;
         })
@@ -4337,6 +4631,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 error.MastraError({
+        id: "MCP_SERVER_RESOURCES_NOT_CONFIGURED",
+        domain: error.ErrorDomain.MCP,
+        category: error.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, '\\"');
@@ -4597,6 +4938,7 @@ Object.defineProperty(exports, "startAuthorization", {
 exports.InMemoryOAuthStorage = InMemoryOAuthStorage;
 exports.InternalMastraMCPClient = InternalMastraMCPClient;
 exports.MCPClient = MCPClient;
+exports.MCPClientServerProxy = MCPClientServerProxy;
 exports.MCPOAuthClientProvider = MCPOAuthClientProvider;
 exports.MCPServer = MCPServer;
 exports.createIntrospectionValidator = createIntrospectionValidator;