@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.
- 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/CHANGELOG.md
CHANGED
|
@@ -1,5 +1,105 @@
|
|
|
1
1
|
# @mastra/mcp
|
|
2
2
|
|
|
3
|
+
## 1.7.0
|
|
4
|
+
|
|
5
|
+
### Minor Changes
|
|
6
|
+
|
|
7
|
+
- Added MCP Apps support for interactive UI rendering over MCP. ([#16004](https://github.com/mastra-ai/mastra/pull/16004))
|
|
8
|
+
|
|
9
|
+
**MCPClientServerProxy** — a lightweight proxy that delegates resource and tool operations to remote MCP servers via `MCPClient`, enabling Studio to fetch app resources from any connected server.
|
|
10
|
+
|
|
11
|
+
**`toMCPServerProxies()`** — new convenience method on `MCPClient` that creates proxy objects for all configured servers, ready for Mastra-level registration.
|
|
12
|
+
|
|
13
|
+
**Automatic `serverId` stamping** — tools returned by `listTools()` now carry `_meta.ui.serverId`, allowing consumers to resolve `ui://` app resources from the correct MCP server in multi-server environments.
|
|
14
|
+
|
|
15
|
+
```ts
|
|
16
|
+
const mcp = new MCPClient({
|
|
17
|
+
servers: {
|
|
18
|
+
myApps: { url: new URL('https://my-mcp-server.example.com/mcp') },
|
|
19
|
+
},
|
|
20
|
+
});
|
|
21
|
+
|
|
22
|
+
const mastra = new Mastra({
|
|
23
|
+
agents: { myAgent },
|
|
24
|
+
mcpServers: { ...mcp.toMCPServerProxies() },
|
|
25
|
+
});
|
|
26
|
+
```
|
|
27
|
+
|
|
28
|
+
- Added MCP Apps extension support (SEP-1865). MCPServer now accepts an `appResources` config to register interactive `ui://` HTML resources. MCPClient preserves full tool `_meta` (including `ui.resourceUri`) when converting MCP tools to Mastra tools. Both advertise the `io.modelcontextprotocol/ui` extension capability. ([#16004](https://github.com/mastra-ai/mastra/pull/16004))
|
|
29
|
+
|
|
30
|
+
**Example — MCPServer with app resources:**
|
|
31
|
+
|
|
32
|
+
```typescript
|
|
33
|
+
const server = new MCPServer({
|
|
34
|
+
name: 'my-server',
|
|
35
|
+
tools: { myTool },
|
|
36
|
+
appResources: {
|
|
37
|
+
dashboard: {
|
|
38
|
+
name: 'Dashboard',
|
|
39
|
+
description: 'Interactive dashboard UI',
|
|
40
|
+
html: '<html>...</html>',
|
|
41
|
+
},
|
|
42
|
+
},
|
|
43
|
+
});
|
|
44
|
+
```
|
|
45
|
+
|
|
46
|
+
### Patch Changes
|
|
47
|
+
|
|
48
|
+
- Added Fine-Grained Authorization (FGA) enforcement to MCP tool execution. Both transport-driven calls and direct `executeTool()` calls now run the same authorization checks when a request user is present, and typed FGA permission constants are accepted in MCP server authorization config. ([#15410](https://github.com/mastra-ai/mastra/pull/15410))
|
|
49
|
+
|
|
50
|
+
- Fixed trace parenting for long-lived MCP Stream connections. ([#15716](https://github.com/mastra-ai/mastra/pull/15716))
|
|
51
|
+
|
|
52
|
+
- Updated dependencies [[`6dcd65f`](https://github.com/mastra-ai/mastra/commit/6dcd65f2a34069e6dc43ba35f1d11119b9b40bef), [`86c0298`](https://github.com/mastra-ai/mastra/commit/86c0298e647306423c842f9d5ac827bd616bd13d), [`c05c9a1`](https://github.com/mastra-ai/mastra/commit/c05c9a13230988cef6d438a62f37760f31927bc7), [`ca28c23`](https://github.com/mastra-ai/mastra/commit/ca28c232a2f18801a6cf20fe053479237b4d4fb0), [`e24aacb`](https://github.com/mastra-ai/mastra/commit/e24aacba07bd66f5d95b636dc24016fca26b52cf), [`7679a63`](https://github.com/mastra-ai/mastra/commit/7679a634eae8e8ca459fd87538fdf72b4389b07f), [`7fce309`](https://github.com/mastra-ai/mastra/commit/7fce30912b14170bfc41f0ac736cca0f39fe0cd4), [`1d64a76`](https://github.com/mastra-ai/mastra/commit/1d64a765861a0772ea187bab76e5ed37bf82d042), [`1c2dda8`](https://github.com/mastra-ai/mastra/commit/1c2dda805fbfccc0abf55d4cb20cc34402dc3f0c), [`c721164`](https://github.com/mastra-ai/mastra/commit/c7211643f7ac861f83b19a3757cc921487fc9d75), [`1b55954`](https://github.com/mastra-ai/mastra/commit/1b559541c1e08a10e49d01ffc51a634dfc37a286), [`7997c2e`](https://github.com/mastra-ai/mastra/commit/7997c2e55ddd121562a4098cd8d2b89c68433bf1), [`5adc55e`](https://github.com/mastra-ai/mastra/commit/5adc55e63407be8ee977914957d68bcc2a075ceb), [`7679a63`](https://github.com/mastra-ai/mastra/commit/7679a634eae8e8ca459fd87538fdf72b4389b07f), [`a0d9b6d`](https://github.com/mastra-ai/mastra/commit/a0d9b6d6b810aeaa9e177a0dcc99a4402e609634), [`e97ccb9`](https://github.com/mastra-ai/mastra/commit/e97ccb900f8b7a390ce82c9f8eb8d6eb2c5e3777), [`c5daf48`](https://github.com/mastra-ai/mastra/commit/c5daf48556e98c46ae06caf00f92c249912007e9), [`70017d7`](https://github.com/mastra-ai/mastra/commit/70017d72ab741b5d7040e2a15c251a317782e39e), [`cd96779`](https://github.com/mastra-ai/mastra/commit/cd9677937f113b2856dc8b9f3d4bdabcee58bb2e), [`b0c7022`](https://github.com/mastra-ai/mastra/commit/b0c70224f80dad7c0cdbfb22cbff22e0f75c064f), [`e4942bc`](https://github.com/mastra-ai/mastra/commit/e4942bc7fdc903572f7d84f26d5e15f9d39c763d)]:
|
|
53
|
+
- @mastra/core@1.32.0
|
|
54
|
+
|
|
55
|
+
## 1.7.0-alpha.2
|
|
56
|
+
|
|
57
|
+
### Minor Changes
|
|
58
|
+
|
|
59
|
+
- Added MCP Apps support for interactive UI rendering over MCP. ([#16004](https://github.com/mastra-ai/mastra/pull/16004))
|
|
60
|
+
|
|
61
|
+
**MCPClientServerProxy** — a lightweight proxy that delegates resource and tool operations to remote MCP servers via `MCPClient`, enabling Studio to fetch app resources from any connected server.
|
|
62
|
+
|
|
63
|
+
**`toMCPServerProxies()`** — new convenience method on `MCPClient` that creates proxy objects for all configured servers, ready for Mastra-level registration.
|
|
64
|
+
|
|
65
|
+
**Automatic `serverId` stamping** — tools returned by `listTools()` now carry `_meta.ui.serverId`, allowing consumers to resolve `ui://` app resources from the correct MCP server in multi-server environments.
|
|
66
|
+
|
|
67
|
+
```ts
|
|
68
|
+
const mcp = new MCPClient({
|
|
69
|
+
servers: {
|
|
70
|
+
myApps: { url: new URL('https://my-mcp-server.example.com/mcp') },
|
|
71
|
+
},
|
|
72
|
+
});
|
|
73
|
+
|
|
74
|
+
const mastra = new Mastra({
|
|
75
|
+
agents: { myAgent },
|
|
76
|
+
mcpServers: { ...mcp.toMCPServerProxies() },
|
|
77
|
+
});
|
|
78
|
+
```
|
|
79
|
+
|
|
80
|
+
- Added MCP Apps extension support (SEP-1865). MCPServer now accepts an `appResources` config to register interactive `ui://` HTML resources. MCPClient preserves full tool `_meta` (including `ui.resourceUri`) when converting MCP tools to Mastra tools. Both advertise the `io.modelcontextprotocol/ui` extension capability. ([#16004](https://github.com/mastra-ai/mastra/pull/16004))
|
|
81
|
+
|
|
82
|
+
**Example — MCPServer with app resources:**
|
|
83
|
+
|
|
84
|
+
```typescript
|
|
85
|
+
const server = new MCPServer({
|
|
86
|
+
name: 'my-server',
|
|
87
|
+
tools: { myTool },
|
|
88
|
+
appResources: {
|
|
89
|
+
dashboard: {
|
|
90
|
+
name: 'Dashboard',
|
|
91
|
+
description: 'Interactive dashboard UI',
|
|
92
|
+
html: '<html>...</html>',
|
|
93
|
+
},
|
|
94
|
+
},
|
|
95
|
+
});
|
|
96
|
+
```
|
|
97
|
+
|
|
98
|
+
### Patch Changes
|
|
99
|
+
|
|
100
|
+
- Updated dependencies [[`7679a63`](https://github.com/mastra-ai/mastra/commit/7679a634eae8e8ca459fd87538fdf72b4389b07f), [`1d64a76`](https://github.com/mastra-ai/mastra/commit/1d64a765861a0772ea187bab76e5ed37bf82d042), [`7679a63`](https://github.com/mastra-ai/mastra/commit/7679a634eae8e8ca459fd87538fdf72b4389b07f), [`a0d9b6d`](https://github.com/mastra-ai/mastra/commit/a0d9b6d6b810aeaa9e177a0dcc99a4402e609634)]:
|
|
101
|
+
- @mastra/core@1.32.0-alpha.4
|
|
102
|
+
|
|
3
103
|
## 1.6.1-alpha.1
|
|
4
104
|
|
|
5
105
|
### Patch Changes
|
package/dist/client/client.d.ts
CHANGED
|
@@ -164,5 +164,6 @@ export declare class InternalMastraMCPClient extends MastraBase {
|
|
|
164
164
|
setProgressNotificationHandler(handler: ProgressHandler): void;
|
|
165
165
|
private convertInputSchema;
|
|
166
166
|
tools(): Promise<Record<string, Tool<any, any, any, any>>>;
|
|
167
|
+
private stampServerIdInMeta;
|
|
167
168
|
}
|
|
168
169
|
//# sourceMappingURL=client.d.ts.map
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../../src/client/client.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAC1C,OAAO,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AAG/C,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,oBAAoB,CAAC;AAS/C,OAAO,KAAK,EACV,WAAW,EACX,eAAe,EACf,iBAAiB,EACjB,mBAAmB,EACnB,2BAA2B,EAE3B,kBAAkB,EACnB,MAAM,oCAAoC,CAAC;AAoB5C,OAAO,EAAE,wBAAwB,EAAE,MAAM,uBAAuB,CAAC;AACjE,OAAO,EAAE,qBAAqB,EAAE,MAAM,oBAAoB,CAAC;AAC3D,OAAO,EAAE,mBAAmB,EAAE,MAAM,kBAAkB,CAAC;AACvD,OAAO,EAAE,qBAAqB,EAAE,MAAM,oBAAoB,CAAC;AAE3D,OAAO,KAAK,EAGV,kBAAkB,EAClB,eAAe,EAEf,8BAA8B,EAC9B,IAAI,EAEL,MAAM,SAAS,CAAC;AAGjB,YAAY,EACV,YAAY,EACZ,UAAU,EACV,UAAU,EACV,kBAAkB,EAClB,eAAe,EACf,eAAe,EACf,yBAAyB,EACzB,8BAA8B,EAC9B,IAAI,EACJ,mBAAmB,EACnB,qBAAqB,EACrB,0BAA0B,GAC3B,MAAM,SAAS,CAAC;AA0GjB;;;;;;;GAOG;AACH,qBAAa,uBAAwB,SAAQ,UAAU;IACrD,IAAI,EAAE,MAAM,CAAC;IACb,OAAO,CAAC,MAAM,CAAS;IACvB,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAS;IACjC,OAAO,CAAC,UAAU,CAAC,CAAa;IAChC,OAAO,CAAC,gBAAgB,CAAC,CAAU;IACnC,OAAO,CAAC,sBAAsB,CAAC,CAAU;IACzC,OAAO,CAAC,YAAY,CAA4B;IAChD,OAAO,CAAC,SAAS,CAAC,CAAY;IAC9B,OAAO,CAAC,qBAAqB,CAAkD;IAC/E,OAAO,CAAC,mBAAmB,CAAC,CAAa;IACzC,OAAO,CAAC,cAAc,CAAC,CAAa;IACpC,OAAO,CAAC,aAAa,CAAC,CAAa;IACnC,OAAO,CAAC,MAAM,CAAS;IACvB,OAAO,CAAC,QAAQ,CAAC,mBAAmB,CAAkC;IAEtE,2EAA2E;IAC3E,SAAgB,SAAS,EAAE,qBAAqB,CAAC;IACjD,sEAAsE;IACtE,SAAgB,OAAO,EAAE,mBAAmB,CAAC;IAC7C,mEAAmE;IACnE,SAAgB,WAAW,EAAE,wBAAwB,CAAC;IACtD,6DAA6D;IAC7D,SAAgB,QAAQ,EAAE,qBAAqB,CAAC;IAEhD;;OAEG;gBACS,EACV,IAAI,EACJ,OAAiB,EACjB,MAAM,EACN,YAAiB,EACjB,OAAsC,GACvC,EAAE,8BAA8B;
|
|
1
|
+
{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../../src/client/client.ts"],"names":[],"mappings":"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"}
|
|
@@ -1,5 +1,6 @@
|
|
|
1
1
|
import type { Stream } from 'node:stream';
|
|
2
2
|
import { MastraBase } from '@mastra/core/base';
|
|
3
|
+
import type { MCPServerBase } from '@mastra/core/mcp';
|
|
3
4
|
import type { Tool } from '@mastra/core/tools';
|
|
4
5
|
import type { ElicitRequest, ElicitResult, ProgressNotification, Prompt, Resource, ResourceTemplate } from '@modelcontextprotocol/sdk/types.js';
|
|
5
6
|
import type { MastraMCPServerDefinition } from './client.js';
|
|
@@ -428,6 +429,7 @@ export declare class MCPClient extends MastraBase {
|
|
|
428
429
|
type: "resource_link";
|
|
429
430
|
description?: string | undefined;
|
|
430
431
|
mimeType?: string | undefined;
|
|
432
|
+
size?: number | undefined;
|
|
431
433
|
annotations?: {
|
|
432
434
|
audience?: ("user" | "assistant")[] | undefined;
|
|
433
435
|
priority?: number | undefined;
|
|
@@ -598,6 +600,30 @@ export declare class MCPClient extends MastraBase {
|
|
|
598
600
|
toolsets: Record<string, Record<string, Tool<any, any, any, any>>>;
|
|
599
601
|
errors: Record<string, string>;
|
|
600
602
|
}>;
|
|
603
|
+
/**
|
|
604
|
+
* Creates MCPServerBase-compatible proxy objects for each server connection
|
|
605
|
+
* in this MCPClient. The returned record can be spread directly into
|
|
606
|
+
* Mastra's `mcpServers` config so that external (non-Mastra) servers
|
|
607
|
+
* appear in Studio alongside native MCPServer instances.
|
|
608
|
+
*
|
|
609
|
+
* @returns Record mapping server names to MCPServerBase proxy instances
|
|
610
|
+
*
|
|
611
|
+
* @example
|
|
612
|
+
* ```typescript
|
|
613
|
+
* const mcp = new MCPClient({
|
|
614
|
+
* servers: {
|
|
615
|
+
* trailhead: { command: 'npx', args: ['trailhead-server'] },
|
|
616
|
+
* },
|
|
617
|
+
* });
|
|
618
|
+
*
|
|
619
|
+
* const mastra = new Mastra({
|
|
620
|
+
* mcpServers: {
|
|
621
|
+
* ...mcp.toMCPServerProxies(),
|
|
622
|
+
* },
|
|
623
|
+
* });
|
|
624
|
+
* ```
|
|
625
|
+
*/
|
|
626
|
+
toMCPServerProxies(): Record<string, MCPServerBase>;
|
|
601
627
|
/**
|
|
602
628
|
* Gets current session IDs for all connected MCP clients using Streamable HTTP transport.
|
|
603
629
|
*
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"configuration.d.ts","sourceRoot":"","sources":["../../src/client/configuration.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,aAAa,CAAC;AAC1C,OAAO,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AAE/C,OAAO,KAAK,EAAE,IAAI,EAAE,MAAM,oBAAoB,CAAC;AAE/C,OAAO,KAAK,EACV,aAAa,EACb,YAAY,EACZ,oBAAoB,EACpB,MAAM,EACN,QAAQ,EACR,gBAAgB,EACjB,MAAM,oCAAoC,CAAC;AAG5C,OAAO,KAAK,EAAE,yBAAyB,EAAE,MAAM,UAAU,CAAC;
|
|
1
|
+
{"version":3,"file":"configuration.d.ts","sourceRoot":"","sources":["../../src/client/configuration.ts"],"names":[],"mappings":"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"}
|
package/dist/client/index.d.ts
CHANGED
|
@@ -2,4 +2,5 @@ export type { LoggingLevel, LogMessage, LogHandler, MastraMCPServerDefinition, E
|
|
|
2
2
|
export * from './client.js';
|
|
3
3
|
export * from './configuration.js';
|
|
4
4
|
export * from './oauth-provider.js';
|
|
5
|
+
export { MCPClientServerProxy } from './server-proxy.js';
|
|
5
6
|
//# sourceMappingURL=index.d.ts.map
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/client/index.ts"],"names":[],"mappings":"AAAA,YAAY,EACV,YAAY,EACZ,UAAU,EACV,UAAU,EACV,yBAAyB,EACzB,kBAAkB,EAClB,eAAe,EACf,8BAA8B,EAC9B,mBAAmB,EACnB,qBAAqB,EACrB,0BAA0B,GAC3B,MAAM,SAAS,CAAC;AACjB,cAAc,UAAU,CAAC;AACzB,cAAc,iBAAiB,CAAC;AAChC,cAAc,kBAAkB,CAAC"}
|
|
1
|
+
{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/client/index.ts"],"names":[],"mappings":"AAAA,YAAY,EACV,YAAY,EACZ,UAAU,EACV,UAAU,EACV,yBAAyB,EACzB,kBAAkB,EAClB,eAAe,EACf,8BAA8B,EAC9B,mBAAmB,EACnB,qBAAqB,EACrB,0BAA0B,GAC3B,MAAM,SAAS,CAAC;AACjB,cAAc,UAAU,CAAC;AACzB,cAAc,iBAAiB,CAAC;AAChC,cAAc,kBAAkB,CAAC;AACjC,OAAO,EAAE,oBAAoB,EAAE,MAAM,gBAAgB,CAAC"}
|
|
@@ -0,0 +1,88 @@
|
|
|
1
|
+
import type { ToolsInput } from '@mastra/core/agent';
|
|
2
|
+
import { MCPServerBase } from '@mastra/core/mcp';
|
|
3
|
+
import type { MCPServerConfig, MCPServerHonoSSEOptions, MCPServerHTTPOptions, MCPServerSSEOptions, MCPToolType, ServerDetailInfo, ServerInfo } from '@mastra/core/mcp';
|
|
4
|
+
import type { InternalMastraMCPClient } from './client.js';
|
|
5
|
+
type ToolListResult = {
|
|
6
|
+
tools: Array<{
|
|
7
|
+
id?: string;
|
|
8
|
+
name: string;
|
|
9
|
+
description?: string;
|
|
10
|
+
inputSchema: any;
|
|
11
|
+
outputSchema?: any;
|
|
12
|
+
toolType?: MCPToolType;
|
|
13
|
+
_meta?: Record<string, unknown>;
|
|
14
|
+
}>;
|
|
15
|
+
};
|
|
16
|
+
/**
|
|
17
|
+
* A lightweight proxy that wraps a single MCPClient server connection as an
|
|
18
|
+
* MCPServerBase instance. This allows external (non-Mastra) MCP servers
|
|
19
|
+
* connected through MCPClient to be registered in Mastra's `mcpServers`
|
|
20
|
+
* config and appear in Studio alongside native MCPServer instances.
|
|
21
|
+
*
|
|
22
|
+
* Tool and resource operations are delegated lazily to the underlying
|
|
23
|
+
* InternalMastraMCPClient connection.
|
|
24
|
+
*/
|
|
25
|
+
export declare class MCPClientServerProxy extends MCPServerBase {
|
|
26
|
+
private clientGetter;
|
|
27
|
+
private cachedClient;
|
|
28
|
+
private _cachedToolList;
|
|
29
|
+
constructor(config: {
|
|
30
|
+
name: string;
|
|
31
|
+
version?: string;
|
|
32
|
+
id?: string;
|
|
33
|
+
description?: string;
|
|
34
|
+
}, clientGetter: () => Promise<InternalMastraMCPClient>);
|
|
35
|
+
private getClient;
|
|
36
|
+
private convertSchema;
|
|
37
|
+
private fetchToolList;
|
|
38
|
+
convertTools(_tools: ToolsInput, _agents?: MCPServerConfig['agents'], _workflows?: MCPServerConfig['workflows']): Record<string, any>;
|
|
39
|
+
/**
|
|
40
|
+
* Returns the cached tool list synchronously, or triggers an async fetch.
|
|
41
|
+
* The Studio API handlers are async and will auto-await a returned Promise.
|
|
42
|
+
*/
|
|
43
|
+
getToolListInfo(): ToolListResult | Promise<ToolListResult>;
|
|
44
|
+
getToolInfo(toolId: string): {
|
|
45
|
+
name: string;
|
|
46
|
+
description?: string;
|
|
47
|
+
inputSchema: any;
|
|
48
|
+
outputSchema?: any;
|
|
49
|
+
toolType?: MCPToolType;
|
|
50
|
+
_meta?: Record<string, unknown>;
|
|
51
|
+
} | undefined | Promise<{
|
|
52
|
+
name: string;
|
|
53
|
+
description?: string;
|
|
54
|
+
inputSchema: any;
|
|
55
|
+
outputSchema?: any;
|
|
56
|
+
toolType?: MCPToolType;
|
|
57
|
+
_meta?: Record<string, unknown>;
|
|
58
|
+
} | undefined>;
|
|
59
|
+
executeTool(toolId: string, args: any, _executionContext?: {
|
|
60
|
+
messages?: any[];
|
|
61
|
+
toolCallId?: string;
|
|
62
|
+
}): Promise<any>;
|
|
63
|
+
listResources(): Promise<{
|
|
64
|
+
resources: Array<{
|
|
65
|
+
uri: string;
|
|
66
|
+
name: string;
|
|
67
|
+
description?: string;
|
|
68
|
+
mimeType?: string;
|
|
69
|
+
_meta?: Record<string, unknown>;
|
|
70
|
+
}>;
|
|
71
|
+
}>;
|
|
72
|
+
readResource(uri: string): Promise<{
|
|
73
|
+
contents: Array<{
|
|
74
|
+
uri: string;
|
|
75
|
+
text?: string;
|
|
76
|
+
blob?: string;
|
|
77
|
+
}>;
|
|
78
|
+
}>;
|
|
79
|
+
startStdio(): Promise<void>;
|
|
80
|
+
startSSE(_options: MCPServerSSEOptions): Promise<void>;
|
|
81
|
+
startHonoSSE(_options: MCPServerHonoSSEOptions): Promise<Response | undefined>;
|
|
82
|
+
startHTTP(_options: MCPServerHTTPOptions): Promise<void>;
|
|
83
|
+
close(): Promise<void>;
|
|
84
|
+
getServerInfo(): ServerInfo;
|
|
85
|
+
getServerDetail(): ServerDetailInfo;
|
|
86
|
+
}
|
|
87
|
+
export {};
|
|
88
|
+
//# sourceMappingURL=server-proxy.d.ts.map
|
|
@@ -0,0 +1 @@
|
|
|
1
|
+
{"version":3,"file":"server-proxy.d.ts","sourceRoot":"","sources":["../../src/client/server-proxy.ts"],"names":[],"mappings":"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"}
|
package/dist/docs/SKILL.md
CHANGED
|
@@ -3,7 +3,7 @@ name: mastra-mcp
|
|
|
3
3
|
description: Documentation for @mastra/mcp. Use when working with @mastra/mcp APIs, configuration, or implementation.
|
|
4
4
|
metadata:
|
|
5
5
|
package: "@mastra/mcp"
|
|
6
|
-
version: "1.
|
|
6
|
+
version: "1.7.0"
|
|
7
7
|
---
|
|
8
8
|
|
|
9
9
|
## When to use
|
|
@@ -16,6 +16,7 @@ Read the individual reference documents for detailed explanations and code examp
|
|
|
16
16
|
|
|
17
17
|
### Docs
|
|
18
18
|
|
|
19
|
+
- [MCP Apps](references/docs-mcp-mcp-apps.md) - Serve interactive HTML UIs from MCP tools using the MCP Apps extension.
|
|
19
20
|
- [MCP overview](references/docs-mcp-overview.md) - Learn about the Model Context Protocol (MCP), how to use third-party tools via MCPClient, connect to registries, and share your own tools using MCPServer.
|
|
20
21
|
|
|
21
22
|
### Reference
|
|
@@ -0,0 +1,304 @@
|
|
|
1
|
+
# MCP Apps
|
|
2
|
+
|
|
3
|
+
The [MCP Apps extension](https://github.com/modelcontextprotocol/ext-apps) allows MCP tools to serve interactive HTML UIs via `ui://` resources. When a tool has an associated app resource, Mastra Studio renders it in a sandboxed iframe alongside the tool form or inline in agent chat.
|
|
4
|
+
|
|
5
|
+
## When to use MCP Apps
|
|
6
|
+
|
|
7
|
+
Use MCP Apps when a tool result is better presented as an interactive UI rather than plain text. For example:
|
|
8
|
+
|
|
9
|
+
- A calculator that renders input fields and buttons for computation
|
|
10
|
+
- A color picker that displays swatches and hex values
|
|
11
|
+
- A form builder that captures structured user input
|
|
12
|
+
- A data visualizer that renders charts
|
|
13
|
+
|
|
14
|
+
## Quickstart
|
|
15
|
+
|
|
16
|
+
Define app resources on your `MCPServer` by providing a `ui://` URI mapped to inline HTML or an HTML file path.
|
|
17
|
+
|
|
18
|
+
```typescript
|
|
19
|
+
import { MCPServer } from '@mastra/mcp'
|
|
20
|
+
import { createTool } from '@mastra/core/tools'
|
|
21
|
+
import { z } from 'zod'
|
|
22
|
+
|
|
23
|
+
const calculatorTool = createTool({
|
|
24
|
+
id: 'calculatorWithUI',
|
|
25
|
+
description: 'An interactive calculator',
|
|
26
|
+
inputSchema: z.object({
|
|
27
|
+
num1: z.number(),
|
|
28
|
+
num2: z.number(),
|
|
29
|
+
operation: z.enum(['add', 'subtract']),
|
|
30
|
+
}),
|
|
31
|
+
execute: async ({ num1, num2, operation }) => {
|
|
32
|
+
const result = operation === 'add' ? num1 + num2 : num1 - num2
|
|
33
|
+
return {
|
|
34
|
+
content: [{ type: 'text', text: 'An interactive calculator is displayed.' }],
|
|
35
|
+
structuredContent: { result },
|
|
36
|
+
}
|
|
37
|
+
},
|
|
38
|
+
})
|
|
39
|
+
|
|
40
|
+
const server = new MCPServer({
|
|
41
|
+
id: 'my-app-server',
|
|
42
|
+
name: 'My App Server',
|
|
43
|
+
version: '1.0.0',
|
|
44
|
+
tools: { calculatorTool },
|
|
45
|
+
appResources: {
|
|
46
|
+
'ui://calculator/main': {
|
|
47
|
+
name: 'Interactive Calculator',
|
|
48
|
+
html: `<html>
|
|
49
|
+
<body>
|
|
50
|
+
<h2>Calculator</h2>
|
|
51
|
+
<button id="btn">Compute</button>
|
|
52
|
+
<script type="module">
|
|
53
|
+
import { App } from 'https://cdn.jsdelivr.net/npm/@modelcontextprotocol/ext-apps/+esm';
|
|
54
|
+
const app = new App({ name: 'Calculator', version: '1.0.0' });
|
|
55
|
+
app.ontoolinput = (params) => {
|
|
56
|
+
console.log('Tool input:', params.arguments);
|
|
57
|
+
};
|
|
58
|
+
document.getElementById('btn').addEventListener('click', async () => {
|
|
59
|
+
const result = await app.callServerTool({
|
|
60
|
+
name: 'calculatorWithUI',
|
|
61
|
+
arguments: { num1: 10, num2: 5, operation: 'add' }
|
|
62
|
+
});
|
|
63
|
+
document.body.innerHTML += '<p>Result: ' + JSON.stringify(result) + '</p>';
|
|
64
|
+
});
|
|
65
|
+
await app.connect();
|
|
66
|
+
</script>
|
|
67
|
+
</body>
|
|
68
|
+
</html>`,
|
|
69
|
+
},
|
|
70
|
+
},
|
|
71
|
+
})
|
|
72
|
+
```
|
|
73
|
+
|
|
74
|
+
Link the tool to its app resource by adding `_meta.ui.resourceUri` to the tool definition:
|
|
75
|
+
|
|
76
|
+
```typescript
|
|
77
|
+
calculatorTool._meta = {
|
|
78
|
+
ui: { resourceUri: 'ui://calculator/main' },
|
|
79
|
+
}
|
|
80
|
+
```
|
|
81
|
+
|
|
82
|
+
> **Note:** Visit [MCPServer reference](https://mastra.ai/reference/tools/mcp-server) for the full `appResources` configuration.
|
|
83
|
+
|
|
84
|
+
## Connecting MCP Apps to agents
|
|
85
|
+
|
|
86
|
+
Agents consume tools — they do not need to know about MCP servers. Pass tools to the agent's `tools` config, and register the MCP server at the Mastra level so Studio can resolve app resources.
|
|
87
|
+
|
|
88
|
+
```typescript
|
|
89
|
+
import { Agent } from '@mastra/core/agent'
|
|
90
|
+
import { calculatorTool } from '../mcp/tools'
|
|
91
|
+
|
|
92
|
+
export const myAgent = new Agent({
|
|
93
|
+
id: 'my-agent',
|
|
94
|
+
name: 'My Agent',
|
|
95
|
+
instructions: 'You have access to interactive UI tools.',
|
|
96
|
+
model: 'openai/gpt-5-mini',
|
|
97
|
+
tools: { calculatorTool },
|
|
98
|
+
})
|
|
99
|
+
```
|
|
100
|
+
|
|
101
|
+
Register the MCP server at the Mastra level. Studio scans registered MCP servers to map tools to their app resources.
|
|
102
|
+
|
|
103
|
+
```typescript
|
|
104
|
+
import { Mastra } from '@mastra/core/mastra'
|
|
105
|
+
import { myAgent } from './agents'
|
|
106
|
+
import { myAppServer } from './mcp/server'
|
|
107
|
+
|
|
108
|
+
export const mastra = new Mastra({
|
|
109
|
+
agents: { myAgent },
|
|
110
|
+
mcpServers: { myAppServer },
|
|
111
|
+
})
|
|
112
|
+
```
|
|
113
|
+
|
|
114
|
+
For remote MCP servers, use `MCPClient.listTools()` to get tools and `toMCPServerProxies()` to register the server:
|
|
115
|
+
|
|
116
|
+
```typescript
|
|
117
|
+
import { MCPClient } from '@mastra/mcp'
|
|
118
|
+
|
|
119
|
+
const mcpClient = new MCPClient({
|
|
120
|
+
servers: {
|
|
121
|
+
remoteApp: { url: new URL('https://remote-mcp-server.example.com/mcp') },
|
|
122
|
+
},
|
|
123
|
+
})
|
|
124
|
+
|
|
125
|
+
const myAgent = new Agent({
|
|
126
|
+
id: 'my-agent',
|
|
127
|
+
name: 'My Agent',
|
|
128
|
+
model: 'openai/gpt-5-mini',
|
|
129
|
+
tools: await mcpClient.listTools(),
|
|
130
|
+
})
|
|
131
|
+
|
|
132
|
+
export const mastra = new Mastra({
|
|
133
|
+
agents: { myAgent },
|
|
134
|
+
mcpServers: { ...mcpClient.toMCPServerProxies() },
|
|
135
|
+
})
|
|
136
|
+
```
|
|
137
|
+
|
|
138
|
+
When tools come from `MCPClient.listTools()`, each tool's `_meta.ui` is automatically stamped with a `serverId` so Studio can resolve its app resources without scanning all servers.
|
|
139
|
+
|
|
140
|
+
## How MCP Apps work
|
|
141
|
+
|
|
142
|
+
MCP Apps follow a specific communication pattern between the host (Mastra Studio) and the iframe:
|
|
143
|
+
|
|
144
|
+
1. The tool executes and returns a brief summary in `content` (visible to the model) and detailed data in `structuredContent` (visible to the UI only).
|
|
145
|
+
2. The host renders the app HTML in a sandboxed iframe.
|
|
146
|
+
3. The iframe communicates with the host via a JSON-RPC postMessage protocol.
|
|
147
|
+
4. The app can call server tools using `callServerTool()` and inject messages into the chat using `sendMessage()`.
|
|
148
|
+
|
|
149
|
+
```text
|
|
150
|
+
Agent calls tool → Tool returns brief content + structuredContent
|
|
151
|
+
→ Host renders iframe with app HTML
|
|
152
|
+
→ User interacts with UI
|
|
153
|
+
→ UI calls callServerTool() for computation
|
|
154
|
+
→ UI calls sendMessage() to inject result into chat
|
|
155
|
+
```
|
|
156
|
+
|
|
157
|
+
## Tool result format
|
|
158
|
+
|
|
159
|
+
Tools with app resources should return two fields:
|
|
160
|
+
|
|
161
|
+
- `content`: A brief text summary for the model. Keep this short so the agent does not parrot the full result.
|
|
162
|
+
- `structuredContent`: The data payload that hydrates the UI. The model does not see this field.
|
|
163
|
+
|
|
164
|
+
```typescript
|
|
165
|
+
execute: async ({ num1, num2, operation }) => {
|
|
166
|
+
const result = operation === 'add' ? num1 + num2 : num1 - num2
|
|
167
|
+
return {
|
|
168
|
+
content: [{ type: 'text', text: 'An interactive calculator is displayed.' }],
|
|
169
|
+
structuredContent: { result },
|
|
170
|
+
}
|
|
171
|
+
}
|
|
172
|
+
```
|
|
173
|
+
|
|
174
|
+
## App API (guest-side)
|
|
175
|
+
|
|
176
|
+
MCP App HTML uses the standard [`App` class from `@modelcontextprotocol/ext-apps`](https://github.com/modelcontextprotocol/ext-apps) to communicate with the host. Import it via ESM CDN or bundle it.
|
|
177
|
+
|
|
178
|
+
```javascript
|
|
179
|
+
import { App } from 'https://cdn.jsdelivr.net/npm/@modelcontextprotocol/ext-apps/+esm'
|
|
180
|
+
const app = new App({ name: 'MyApp', version: '1.0.0' })
|
|
181
|
+
```
|
|
182
|
+
|
|
183
|
+
### `app.callServerTool(params)`
|
|
184
|
+
|
|
185
|
+
Calls an MCP server tool from within the iframe. This is useful for interactive computation without leaving the UI.
|
|
186
|
+
|
|
187
|
+
```javascript
|
|
188
|
+
const result = await app.callServerTool({
|
|
189
|
+
name: 'calculatorWithUI',
|
|
190
|
+
arguments: { num1: 42, num2: 8, operation: 'add' },
|
|
191
|
+
})
|
|
192
|
+
```
|
|
193
|
+
|
|
194
|
+
### `app.sendMessage(params)`
|
|
195
|
+
|
|
196
|
+
Injects a user message into the agent chat, triggering a new model turn. Use this for sharing results or requesting follow-up actions.
|
|
197
|
+
|
|
198
|
+
```javascript
|
|
199
|
+
await app.sendMessage({
|
|
200
|
+
role: 'user',
|
|
201
|
+
content: [{ type: 'text', text: 'The result of 42 + 8 is 50' }],
|
|
202
|
+
})
|
|
203
|
+
```
|
|
204
|
+
|
|
205
|
+
### `app.ontoolinput`
|
|
206
|
+
|
|
207
|
+
A callback that fires when the host delivers tool input data to the iframe, allowing pre-population of form fields. The `params.arguments` object contains the tool call arguments.
|
|
208
|
+
|
|
209
|
+
```javascript
|
|
210
|
+
app.ontoolinput = params => {
|
|
211
|
+
document.getElementById('num1').value = params.arguments.num1
|
|
212
|
+
}
|
|
213
|
+
```
|
|
214
|
+
|
|
215
|
+
> **Preventing UI flicker:** If your app has default form values, the user may briefly see them before `ontoolinput` hydrates the correct values. To prevent this, start the body hidden and reveal it after hydration:
|
|
216
|
+
>
|
|
217
|
+
> ```html
|
|
218
|
+
> <style>
|
|
219
|
+
> body {
|
|
220
|
+
> opacity: 0;
|
|
221
|
+
> transition: opacity 0.15s;
|
|
222
|
+
> }
|
|
223
|
+
> body.ready {
|
|
224
|
+
> opacity: 1;
|
|
225
|
+
> }
|
|
226
|
+
> </style>
|
|
227
|
+
> <script type="module">
|
|
228
|
+
> import { App } from 'https://cdn.jsdelivr.net/npm/@modelcontextprotocol/ext-apps/+esm'
|
|
229
|
+
> const app = new App({ name: 'MyApp', version: '1.0.0' })
|
|
230
|
+
>
|
|
231
|
+
> app.ontoolinput = params => {
|
|
232
|
+
> // Hydrate form fields from params.arguments
|
|
233
|
+
> document.body.classList.add('ready')
|
|
234
|
+
> }
|
|
235
|
+
>
|
|
236
|
+
> await app.connect()
|
|
237
|
+
> // Fallback: reveal after connection if no tool input arrives
|
|
238
|
+
> setTimeout(() => document.body.classList.add('ready'), 150)
|
|
239
|
+
> </script>
|
|
240
|
+
> ```
|
|
241
|
+
|
|
242
|
+
### `app.connect()`
|
|
243
|
+
|
|
244
|
+
Establishes the connection to the host. Call this after registering all event handlers.
|
|
245
|
+
|
|
246
|
+
```javascript
|
|
247
|
+
await app.connect()
|
|
248
|
+
```
|
|
249
|
+
|
|
250
|
+
> **Note:** See the [`App` class API reference](https://apps.extensions.modelcontextprotocol.io/api/classes/app.App.html) for the full list of methods, callbacks, and lifecycle hooks.
|
|
251
|
+
|
|
252
|
+
## Using external MCP servers with apps
|
|
253
|
+
|
|
254
|
+
External (non-Mastra) MCP servers that implement the MCP Apps extension work with Mastra via `MCPClient`. Use `listTools()` for agent tools and `toMCPServerProxies()` to register them in Studio.
|
|
255
|
+
|
|
256
|
+
```typescript
|
|
257
|
+
import { Mastra } from '@mastra/core/mastra'
|
|
258
|
+
import { MCPClient } from '@mastra/mcp'
|
|
259
|
+
import { Agent } from '@mastra/core/agent'
|
|
260
|
+
|
|
261
|
+
const mcpClient = new MCPClient({
|
|
262
|
+
servers: {
|
|
263
|
+
'external-server': {
|
|
264
|
+
command: 'node',
|
|
265
|
+
args: ['path/to/external-server.js'],
|
|
266
|
+
},
|
|
267
|
+
},
|
|
268
|
+
})
|
|
269
|
+
|
|
270
|
+
const myAgent = new Agent({
|
|
271
|
+
id: 'my-agent',
|
|
272
|
+
name: 'My Agent',
|
|
273
|
+
model: 'openai/gpt-5-mini',
|
|
274
|
+
tools: await mcpClient.listTools(),
|
|
275
|
+
})
|
|
276
|
+
|
|
277
|
+
export const mastra = new Mastra({
|
|
278
|
+
agents: { myAgent },
|
|
279
|
+
mcpServers: {
|
|
280
|
+
...mcpClient.toMCPServerProxies(),
|
|
281
|
+
},
|
|
282
|
+
})
|
|
283
|
+
```
|
|
284
|
+
|
|
285
|
+
> **Note:** Visit [MCPClient reference](https://mastra.ai/reference/tools/mcp-client) for more details on proxying external servers.
|
|
286
|
+
|
|
287
|
+
## Sandbox security
|
|
288
|
+
|
|
289
|
+
Mastra Studio uses [`@mcp-ui/client`](https://www.npmjs.com/package/@mcp-ui/client) to render MCP App iframes through a sandbox proxy. The proxy loads app HTML via `postMessage` rather than `srcDoc`, providing additional isolation.
|
|
290
|
+
|
|
291
|
+
App iframes are sandboxed with the following permissions:
|
|
292
|
+
|
|
293
|
+
- `allow-scripts`: Enables JavaScript execution
|
|
294
|
+
- `allow-forms`: Allows form submission
|
|
295
|
+
- `allow-popups`: Permits `window.open()` and link targets
|
|
296
|
+
|
|
297
|
+
The iframe does not have access to the parent page's DOM, cookies, or storage. All communication happens through the JSON-RPC postMessage protocol managed by `@mcp-ui/client`'s `AppRenderer` on the host side and `@modelcontextprotocol/ext-apps`'s `App` class on the guest side.
|
|
298
|
+
|
|
299
|
+
## Related
|
|
300
|
+
|
|
301
|
+
- [MCP overview](https://mastra.ai/docs/mcp/overview)
|
|
302
|
+
- [MCPServer reference](https://mastra.ai/reference/tools/mcp-server)
|
|
303
|
+
- [MCPClient reference](https://mastra.ai/reference/tools/mcp-client)
|
|
304
|
+
- [MCP Apps extension spec](https://github.com/modelcontextprotocol/ext-apps)
|
|
@@ -408,8 +408,15 @@ export const mcp = new MCPClient({
|
|
|
408
408
|
|
|
409
409
|
As an alternative to MCP, Ampersand's AI SDK also has an adapter for Mastra, so you can [directly import Ampersand tools](https://docs.withampersand.com/ai-sdk#use-with-mastra) for your agent to access.
|
|
410
410
|
|
|
411
|
+
## MCP Apps
|
|
412
|
+
|
|
413
|
+
MCP servers can serve interactive HTML UIs via the MCP Apps extension. Tools with associated `ui://` resources render sandboxed iframes in Studio — both on tool detail pages and inline in agent chat. The app iframe can call server tools and inject messages into the conversation.
|
|
414
|
+
|
|
415
|
+
> **Note:** Visit [MCP Apps](https://mastra.ai/docs/mcp/mcp-apps) for setup instructions and the app bridge API.
|
|
416
|
+
|
|
411
417
|
## Related
|
|
412
418
|
|
|
419
|
+
- [MCP Apps](https://mastra.ai/docs/mcp/mcp-apps)
|
|
413
420
|
- [Using Tools](https://mastra.ai/docs/agents/using-tools)
|
|
414
421
|
- [MCPClient](https://mastra.ai/reference/tools/mcp-client)
|
|
415
422
|
- [MCPServer](https://mastra.ai/reference/tools/mcp-server)
|