@mastra/mcp 1.7.1-alpha.0 → 1.8.0-alpha.1
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 +52 -0
- package/dist/client/client.d.ts.map +1 -1
- package/dist/client/index.d.ts +1 -1
- package/dist/client/index.d.ts.map +1 -1
- package/dist/client/types.d.ts +35 -1
- package/dist/client/types.d.ts.map +1 -1
- package/dist/docs/SKILL.md +1 -1
- package/dist/docs/assets/SOURCE_MAP.json +1 -1
- package/dist/docs/references/reference-tools-mcp-client.md +27 -2
- package/dist/index.cjs +11 -2
- package/dist/index.cjs.map +1 -1
- package/dist/index.js +11 -2
- package/dist/index.js.map +1 -1
- package/package.json +3 -3
package/CHANGELOG.md
CHANGED
|
@@ -1,5 +1,57 @@
|
|
|
1
1
|
# @mastra/mcp
|
|
2
2
|
|
|
3
|
+
## 1.8.0-alpha.1
|
|
4
|
+
|
|
5
|
+
### Minor Changes
|
|
6
|
+
|
|
7
|
+
- Added MCP tool annotations to the `requireToolApproval` context and exposed them on tools returned from `listTools()` / `listToolsets()`. ([#16784](https://github.com/mastra-ai/mastra/pull/16784))
|
|
8
|
+
|
|
9
|
+
The `requireToolApproval` callback now receives the server-advertised `annotations` (`title`, `readOnlyHint`, `destructiveHint`, `idempotentHint`, `openWorldHint`) alongside `toolName` and `args`. This lets you write declarative approval policies instead of hardcoding tool name lists. Annotations are also propagated onto Mastra tools as `tool.mcp.annotations` so apps can render them in UI.
|
|
10
|
+
|
|
11
|
+
**Security caveat (per the MCP spec):** annotations are _hints_, not guarantees. Clients MUST treat them as untrusted unless they come from a trusted server. Do not use annotations alone as a security boundary for servers you do not control — set `requireToolApproval: true` for those. When the server omits annotations entirely, this field is `undefined`, so policies can distinguish "no annotations" from "annotated as safe".
|
|
12
|
+
|
|
13
|
+
```ts
|
|
14
|
+
import { MCPClient } from '@mastra/mcp';
|
|
15
|
+
|
|
16
|
+
// Before — hardcoded tool name lists, server-specific
|
|
17
|
+
const mcp = new MCPClient({
|
|
18
|
+
servers: {
|
|
19
|
+
github: {
|
|
20
|
+
url: new URL('https://example.com/mcp'),
|
|
21
|
+
requireToolApproval: ({ toolName }) => toolName === 'delete_repo',
|
|
22
|
+
},
|
|
23
|
+
},
|
|
24
|
+
});
|
|
25
|
+
|
|
26
|
+
// After — annotation-driven, works across any trusted MCP server
|
|
27
|
+
const mcp = new MCPClient({
|
|
28
|
+
servers: {
|
|
29
|
+
github: {
|
|
30
|
+
url: new URL('https://example.com/mcp'),
|
|
31
|
+
requireToolApproval: ({ annotations }) => {
|
|
32
|
+
if (!annotations) return true;
|
|
33
|
+
if (annotations.readOnlyHint) return false;
|
|
34
|
+
if (annotations.destructiveHint) return true;
|
|
35
|
+
return false;
|
|
36
|
+
},
|
|
37
|
+
},
|
|
38
|
+
},
|
|
39
|
+
});
|
|
40
|
+
|
|
41
|
+
// Annotations are also visible on tools returned by listTools()
|
|
42
|
+
const tools = await mcp.listTools();
|
|
43
|
+
for (const tool of Object.values(tools)) {
|
|
44
|
+
console.log(tool.mcp?.annotations);
|
|
45
|
+
}
|
|
46
|
+
```
|
|
47
|
+
|
|
48
|
+
Closes #16766.
|
|
49
|
+
|
|
50
|
+
### Patch Changes
|
|
51
|
+
|
|
52
|
+
- Updated dependencies [[`c272d50`](https://github.com/mastra-ai/mastra/commit/c272d50610a54496b6b6d92ccd4d37b333a2613a), [`d8692af`](https://github.com/mastra-ai/mastra/commit/d8692afa253028e39cdce2aafa0ac414071a762e), [`841a222`](https://github.com/mastra-ai/mastra/commit/841a222560d8c19238f8213713f30535cdd82284)]:
|
|
53
|
+
- @mastra/core@1.36.0-alpha.4
|
|
54
|
+
|
|
3
55
|
## 1.7.1-alpha.0
|
|
4
56
|
|
|
5
57
|
### Patch Changes
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../../src/client/client.ts"],"names":[],"mappings":"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
|
|
1
|
+
{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../../src/client/client.ts"],"names":[],"mappings":"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"}
|
package/dist/client/index.d.ts
CHANGED
|
@@ -1,4 +1,4 @@
|
|
|
1
|
-
export type { LoggingLevel, LogMessage, LogHandler, MastraMCPServerDefinition, ElicitationHandler, ProgressHandler, InternalMastraMCPClientOptions, RequireToolApproval, RequireToolApprovalFn, RequireToolApprovalContext, } from './types.js';
|
|
1
|
+
export type { LoggingLevel, LogMessage, LogHandler, MastraMCPServerDefinition, ElicitationHandler, ProgressHandler, InternalMastraMCPClientOptions, RequireToolApproval, RequireToolApprovalFn, RequireToolApprovalContext, ToolAnnotations, } from './types.js';
|
|
2
2
|
export * from './client.js';
|
|
3
3
|
export * from './configuration.js';
|
|
4
4
|
export * from './oauth-provider.js';
|
|
@@ -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,
|
|
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,EAC1B,eAAe,GAChB,MAAM,SAAS,CAAC;AACjB,cAAc,UAAU,CAAC;AACzB,cAAc,iBAAiB,CAAC;AAChC,cAAc,kBAAkB,CAAC;AACjC,OAAO,EAAE,oBAAoB,EAAE,MAAM,gBAAgB,CAAC"}
|
package/dist/client/types.d.ts
CHANGED
|
@@ -3,7 +3,8 @@ import type { RequestContext } from '@mastra/core/di';
|
|
|
3
3
|
import type { SSEClientTransportOptions } from '@modelcontextprotocol/sdk/client/sse.js';
|
|
4
4
|
import type { StreamableHTTPClientTransportOptions } from '@modelcontextprotocol/sdk/client/streamableHttp.js';
|
|
5
5
|
export type { FetchLike } from '@modelcontextprotocol/sdk/shared/transport.js';
|
|
6
|
-
import type { ClientCapabilities, ElicitRequest, ElicitResult, LoggingLevel, ProgressNotification } from '@modelcontextprotocol/sdk/types.js';
|
|
6
|
+
import type { ClientCapabilities, ElicitRequest, ElicitResult, LoggingLevel, ProgressNotification, ToolAnnotations } from '@modelcontextprotocol/sdk/types.js';
|
|
7
|
+
export type { ToolAnnotations } from '@modelcontextprotocol/sdk/types.js';
|
|
7
8
|
import type { jsonSchemaValidator } from '@modelcontextprotocol/sdk/validation/types.js';
|
|
8
9
|
/**
|
|
9
10
|
* Extended fetch function type that receives the current request context as a third argument.
|
|
@@ -100,6 +101,28 @@ export interface RequireToolApprovalContext {
|
|
|
100
101
|
args: Record<string, unknown>;
|
|
101
102
|
/** Request-scoped context (e.g., user info, auth data) as a plain object */
|
|
102
103
|
requestContext?: Record<string, unknown>;
|
|
104
|
+
/**
|
|
105
|
+
* Tool annotations advertised by the MCP server in `tools/list` (title,
|
|
106
|
+
* readOnlyHint, destructiveHint, idempotentHint, openWorldHint).
|
|
107
|
+
*
|
|
108
|
+
* Use these to drive declarative, server-agnostic approval policies
|
|
109
|
+
* instead of hardcoding tool name lists.
|
|
110
|
+
*
|
|
111
|
+
* SECURITY (per MCP spec): annotations are **hints**, not guarantees.
|
|
112
|
+
* Clients MUST consider them untrusted unless they come from a trusted
|
|
113
|
+
* server. Do not use annotations alone as a security boundary — gate
|
|
114
|
+
* dangerous behaviour with `requireToolApproval: true` (or a server-name
|
|
115
|
+
* allowlist) for any server you do not control.
|
|
116
|
+
*
|
|
117
|
+
* Spec defaults when a hint is omitted: `readOnlyHint: false`,
|
|
118
|
+
* `destructiveHint: true`, `idempotentHint: false`, `openWorldHint: true`.
|
|
119
|
+
* This field is `undefined` (not auto-defaulted) when the server omits
|
|
120
|
+
* annotations entirely, so policies can distinguish "no annotations" from
|
|
121
|
+
* "annotated as safe".
|
|
122
|
+
*
|
|
123
|
+
* @see https://modelcontextprotocol.io/specification/2025-11-25/server/tools#tool-annotations
|
|
124
|
+
*/
|
|
125
|
+
annotations?: ToolAnnotations;
|
|
103
126
|
}
|
|
104
127
|
/**
|
|
105
128
|
* Function type for dynamic tool approval logic.
|
|
@@ -146,6 +169,17 @@ export type BaseServerOptions = {
|
|
|
146
169
|
* if (toolName === 'delete_repo') return true;
|
|
147
170
|
* return false;
|
|
148
171
|
* }
|
|
172
|
+
*
|
|
173
|
+
* // Declarative, server-agnostic approval driven by MCP tool annotations.
|
|
174
|
+
* // NOTE: only sound for trusted servers — annotations are hints, not
|
|
175
|
+
* // guarantees, per the MCP spec.
|
|
176
|
+
* requireToolApproval: ({ annotations }) => {
|
|
177
|
+
* // No annotations? Assume the worst (spec default: destructive).
|
|
178
|
+
* if (!annotations) return true;
|
|
179
|
+
* if (annotations.readOnlyHint) return false;
|
|
180
|
+
* if (annotations.destructiveHint) return true;
|
|
181
|
+
* return false;
|
|
182
|
+
* }
|
|
149
183
|
* ```
|
|
150
184
|
*/
|
|
151
185
|
requireToolApproval?: RequireToolApproval;
|
|
@@ -1 +1 @@
|
|
|
1
|
-
{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/client/types.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,oBAAoB,CAAC;AACjD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,iBAAiB,CAAC;AACtD,OAAO,KAAK,EAAE,yBAAyB,EAAE,MAAM,yCAAyC,CAAC;AACzF,OAAO,KAAK,EAAE,oCAAoC,EAAE,MAAM,oDAAoD,CAAC;AAE/G,YAAY,EAAE,SAAS,EAAE,MAAM,+CAA+C,CAAC;AAC/E,OAAO,KAAK,EACV,kBAAkB,EAClB,aAAa,EACb,YAAY,EACZ,YAAY,EACZ,oBAAoB,
|
|
1
|
+
{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/client/types.ts"],"names":[],"mappings":"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"}
|
package/dist/docs/SKILL.md
CHANGED
|
@@ -53,7 +53,7 @@ Each server in the `servers` map is configured using the `MastraMCPServerDefinit
|
|
|
53
53
|
|
|
54
54
|
**enableServerLogs** (`boolean`): Whether to enable logging for this server. (Default: `true`)
|
|
55
55
|
|
|
56
|
-
**requireToolApproval** (`boolean | (params: RequireToolApprovalContext) => boolean | Promise<boolean>`): Require human approval before executing tools from this server. When set to \`true\`, all tools require approval. When set to a function, the function is called with the tool name, arguments,
|
|
56
|
+
**requireToolApproval** (`boolean | (params: RequireToolApprovalContext) => boolean | Promise<boolean>`): Require human approval before executing tools from this server. When set to \`true\`, all tools require approval. When set to a function, the function is called with the tool name, arguments, request context, and any tool annotations advertised by the server to dynamically decide whether approval is needed.
|
|
57
57
|
|
|
58
58
|
## Tool approval
|
|
59
59
|
|
|
@@ -76,7 +76,7 @@ const mcp = new MCPClient({
|
|
|
76
76
|
|
|
77
77
|
### Dynamic approval with a function
|
|
78
78
|
|
|
79
|
-
Pass a function to decide per-call whether approval is needed. The function receives the tool name, the arguments the model passed,
|
|
79
|
+
Pass a function to decide per-call whether approval is needed. The function receives the tool name, the arguments the model passed, any request context from the incoming request, and the tool's MCP `annotations` (when the server advertises them):
|
|
80
80
|
|
|
81
81
|
```typescript
|
|
82
82
|
const mcp = new MCPClient({
|
|
@@ -98,6 +98,31 @@ const mcp = new MCPClient({
|
|
|
98
98
|
|
|
99
99
|
The function can also be async. It receives `requestContext` from the incoming request, which you can use for auth checks or other per-request logic.
|
|
100
100
|
|
|
101
|
+
### Use tool annotations from a trusted server
|
|
102
|
+
|
|
103
|
+
If you trust the MCP server, you can use its [tool annotations](https://modelcontextprotocol.io/specification/2025-11-25/server/tools#tool-annotations) (`readOnlyHint`, `destructiveHint`, `idempotentHint`, `openWorldHint`, `title`) to drive approval decisions:
|
|
104
|
+
|
|
105
|
+
```typescript
|
|
106
|
+
const mcp = new MCPClient({
|
|
107
|
+
servers: {
|
|
108
|
+
github: {
|
|
109
|
+
url: new URL('http://localhost:3000/mcp'),
|
|
110
|
+
requireToolApproval: ({ annotations }) => {
|
|
111
|
+
// Skip approval for tools the server has marked read-only
|
|
112
|
+
if (annotations?.readOnlyHint) return false
|
|
113
|
+
// Always require approval for destructive tools
|
|
114
|
+
if (annotations?.destructiveHint) return true
|
|
115
|
+
return true
|
|
116
|
+
},
|
|
117
|
+
},
|
|
118
|
+
},
|
|
119
|
+
})
|
|
120
|
+
```
|
|
121
|
+
|
|
122
|
+
Per the MCP specification, **clients MUST consider tool annotations to be untrusted unless they come from trusted servers**. Annotations are advisory hints, not a security boundary — a malicious or buggy server can claim a tool is read-only when it isn't. Only use annotations to relax approval requirements for servers you trust.
|
|
123
|
+
|
|
124
|
+
The same annotations are also exposed on the tools returned by `listTools()` and `listToolsets()` under `tool.mcp.annotations`, so you can inspect them when wiring tools into an agent.
|
|
125
|
+
|
|
101
126
|
## Methods
|
|
102
127
|
|
|
103
128
|
### `listTools()`
|
package/dist/index.cjs
CHANGED
|
@@ -972,18 +972,25 @@ var InternalMastraMCPClient = class extends base.MastraBase {
|
|
|
972
972
|
try {
|
|
973
973
|
let requireApproval;
|
|
974
974
|
let needsApprovalFn;
|
|
975
|
+
const annotations = tool.annotations;
|
|
975
976
|
if (typeof this.requireToolApproval === "function") {
|
|
976
977
|
const serverApprovalFn = this.requireToolApproval;
|
|
977
978
|
const toolName = tool.name;
|
|
978
979
|
requireApproval = true;
|
|
979
980
|
needsApprovalFn = (args, ctx = {}) => {
|
|
980
|
-
return serverApprovalFn({ toolName, args, ...ctx });
|
|
981
|
+
return serverApprovalFn({ toolName, args, ...ctx, annotations });
|
|
981
982
|
};
|
|
982
983
|
} else if (this.requireToolApproval === true) {
|
|
983
984
|
requireApproval = true;
|
|
984
985
|
}
|
|
985
986
|
const rawMeta = tool._meta;
|
|
986
987
|
const toolMeta = rawMeta ? this.stampServerIdInMeta(rawMeta) : void 0;
|
|
988
|
+
const mcpToolProps = toolMeta || annotations ? {
|
|
989
|
+
mcp: {
|
|
990
|
+
...toolMeta ? { _meta: toolMeta } : {},
|
|
991
|
+
...annotations ? { annotations } : {}
|
|
992
|
+
}
|
|
993
|
+
} : {};
|
|
987
994
|
const mastraTool = tools.createTool({
|
|
988
995
|
id: `${this.name}_${tool.name}`,
|
|
989
996
|
description: tool.description || "",
|
|
@@ -991,7 +998,9 @@ var InternalMastraMCPClient = class extends base.MastraBase {
|
|
|
991
998
|
strict: getMastraToolStrictMeta(toolMeta),
|
|
992
999
|
// Preserve the full _meta from the remote MCP server (including ui.resourceUri
|
|
993
1000
|
// for MCP Apps) so downstream consumers (e.g. Studio) can detect app tools.
|
|
994
|
-
|
|
1001
|
+
// Also propagate MCP tool annotations so listTools() / listToolsets() consumers
|
|
1002
|
+
// can read them via `tool.mcp.annotations`.
|
|
1003
|
+
...mcpToolProps,
|
|
995
1004
|
// Don't pass outputSchema to createTool — the MCP SDK's Client.callTool()
|
|
996
1005
|
// already validates structuredContent against the tool's outputSchema using AJV.
|
|
997
1006
|
// Passing it here causes Zod to strip unrecognized keys from the CallToolResult
|