@mastra/mcp 2.3.0 → 2.4.0-alpha.0

package/dist/index.js

@@ -6,13 +6,13 @@ import { createTool, isValidationError, noopObserve, validateToolOutput } from "
 import { Client, DEFAULT_REQUEST_TIMEOUT_MSEC, LOG_LEVEL_META_KEY, ProtocolErrorCode, StreamableHTTPClientTransport, UnauthorizedError, auth, buildDiscoveryUrls, discoverAuthorizationServerMetadata, discoverOAuthMetadata, discoverOAuthProtectedResourceMetadata, exchangeAuthorization, extractResourceMetadataUrl, parseErrorResponse, refreshAuthorization, selectResourceURL, startAuthorization, validateClientMetadataUrl } from "@modelcontextprotocol/client";
 import { StdioClientTransport, getDefaultEnvironment } from "@modelcontextprotocol/client/stdio";
 import { asyncExitHook, gracefulExit } from "exit-hook";
+import { EntityType, SpanType, formatTraceparent, getOrCreateSpan, parseTraceparent, resolveExportedSpanId } from "@mastra/core/observability";
 import { createHash, timingSafeEqual } from "crypto";
 import equal from "fast-deep-equal";
 import { createServer } from "http";
 import { MCPServerBase } from "@mastra/core/mcp";
 import { isStandardSchemaWithJSON, standardSchemaToJSONSchema, toStandardSchema } from "@mastra/core/schema";
 import { readFileSync } from "fs";
-import { EntityType, SpanType, getOrCreateSpan } from "@mastra/core/observability";
 import { RequestContext } from "@mastra/core/request-context";
 import { makeCoreTool } from "@mastra/core/utils";
 import { PromptSchema } from "@modelcontextprotocol/core";
@@ -22301,21 +22301,21 @@ function rewrite(schema, depth, budget, isRoot = false) {
 }
 //#endregion
 //#region src/shared/mastra-tool-meta.ts
-const MASTRA_META_KEY = "mastra";
+const MASTRA_META_KEY$1 = "mastra";
 const STRICT_META_KEY = "strict";
 function withMastraToolStrictMeta(meta, strict) {
 	if (strict == null) return meta;
-	const mastraMeta = meta?.[MASTRA_META_KEY] && typeof meta[MASTRA_META_KEY] === "object" ? meta[MASTRA_META_KEY] : void 0;
+	const mastraMeta = meta?.[MASTRA_META_KEY$1] && typeof meta[MASTRA_META_KEY$1] === "object" ? meta[MASTRA_META_KEY$1] : void 0;
 	return {
 		...meta ?? {},
-		[MASTRA_META_KEY]: {
+		[MASTRA_META_KEY$1]: {
 			...mastraMeta ?? {},
 			[STRICT_META_KEY]: strict
 		}
 	};
 }
 function getMastraToolStrictMeta(meta) {
-	const mastraMeta = meta?.[MASTRA_META_KEY];
+	const mastraMeta = meta?.[MASTRA_META_KEY$1];
 	if (!mastraMeta || typeof mastraMeta !== "object") return;
 	const strict = mastraMeta[STRICT_META_KEY];
 	return typeof strict === "boolean" ? strict : void 0;
@@ -22409,6 +22409,122 @@ function traceContextToMeta(traceContext) {
 		...traceContext.baggage !== void 0 ? { [BAGGAGE_META_KEY]: traceContext.baggage } : {}
 	};
 }
+/**
+* Request params without the W3C trace fields in `_meta`. They are removed
+* whenever present, valid or not: a valid caller span is recorded as a link,
+* and `tracestate` and `baggage` are untrusted data the span doesn't need.
+*/
+function withoutTraceContext(params) {
+	const meta = params?._meta;
+	if (!meta || typeof meta !== "object" || Array.isArray(meta) || ![
+		TRACEPARENT_META_KEY,
+		TRACESTATE_META_KEY,
+		BAGGAGE_META_KEY
+	].some((key) => key in meta)) return params;
+	const { [TRACEPARENT_META_KEY]: _traceparent, [TRACESTATE_META_KEY]: _tracestate, [BAGGAGE_META_KEY]: _baggage, ...restMeta } = meta;
+	const { _meta, ...rest } = params;
+	return Object.keys(restMeta).length > 0 ? {
+		...rest,
+		_meta: restMeta
+	} : rest;
+}
+/**
+* Reads the caller's trace context from a `traceparent` and its `tracestate`.
+* A `traceparent` that doesn't parse yields nothing, and its `tracestate` is
+* ignored with it, as the W3C spec requires.
+*/
+function callerTraceContext(traceparent, tracestate) {
+	const parts = parseTraceparent(traceparent);
+	if (!parts) return void 0;
+	const cappedTracestate = typeof tracestate === "string" ? capTracestate(tracestate) : void 0;
+	return {
+		link: {
+			traceId: parts.traceId,
+			spanId: parts.spanId
+		},
+		traceparent: traceparent.trim(),
+		...cappedTracestate ? { tracestate: cappedTracestate } : {}
+	};
+}
+const TRACESTATE_MAX_LENGTH = 512;
+const TRACESTATE_MAX_MEMBERS = 32;
+const TRACESTATE_LONG_MEMBER = 128;
+/**
+* Caps a `tracestate` at 512 characters the way the W3C spec asks: keep at most
+* 32 entries, drop entries longer than 128 characters first, then drop entries
+* from the end. Entries are never cut in the middle.
+* @see https://www.w3.org/TR/trace-context/#tracestate-limits
+*/
+function capTracestate(value) {
+	let members = value.split(",").map((member) => member.trim()).filter(Boolean).slice(0, TRACESTATE_MAX_MEMBERS);
+	const length = () => members.join(",").length;
+	if (length() > TRACESTATE_MAX_LENGTH) members = members.filter((member) => member.length <= TRACESTATE_LONG_MEMBER);
+	while (members.length > 0 && length() > TRACESTATE_MAX_LENGTH) members.pop();
+	return members.length > 0 ? members.join(",") : void 0;
+}
+/**
+* The trace context that makes `span` the parent of an outgoing request. A span
+* that is not recorded, or whose ids are not W3C-sized, propagates nothing. A
+* span hidden from exporters is replaced by its closest exported ancestor.
+*/
+function traceContextFromSpan(span) {
+	if (!span?.isValid) return void 0;
+	const traceparent = formatTraceparent(span.traceId, resolveExportedSpanId(span) ?? "", true);
+	return parseTraceparent(traceparent) ? { traceparent } : void 0;
+}
+/**
+* Reply `_meta` key under which a Mastra server returns the `traceparent` of the
+* span that served the request, so the caller can link back to it.
+*/
+const MASTRA_META_KEY = "mastra";
+const SERVER_TRACEPARENT_KEY = "traceparent";
+/**
+* Adds the `traceparent` of `span`, the span serving the request, to the reply
+* `_meta`. Only callers that sent their own trace context get it back.
+*/
+function withServerTraceContext(result, span, callerSentTrace) {
+	const traceparent = callerSentTrace ? traceContextFromSpan(span)?.traceparent : void 0;
+	if (!traceparent || !result || typeof result !== "object" || Array.isArray(result)) return result;
+	const meta = result._meta ?? {};
+	const mastraMeta = meta[MASTRA_META_KEY];
+	return {
+		...result,
+		_meta: {
+			...meta,
+			[MASTRA_META_KEY]: {
+				...mastraMeta && typeof mastraMeta === "object" ? mastraMeta : {},
+				[SERVER_TRACEPARENT_KEY]: traceparent
+			}
+		}
+	};
+}
+/**
+* Splits the server's span out of a reply: returns the span the server named in
+* its reply `_meta`, if any, and the reply without that key.
+*/
+function takeServerTraceContext(result) {
+	const meta = result?._meta;
+	const mastraMeta = meta?.[MASTRA_META_KEY];
+	if (!mastraMeta || typeof mastraMeta !== "object" || !(SERVER_TRACEPARENT_KEY in mastraMeta)) return { result };
+	const { [SERVER_TRACEPARENT_KEY]: traceparent, ...restMastra } = mastraMeta;
+	const { [MASTRA_META_KEY]: _mastra, ...restMeta } = meta;
+	const nextMeta = Object.keys(restMastra).length > 0 ? {
+		...restMeta,
+		[MASTRA_META_KEY]: restMastra
+	} : restMeta;
+	const { _meta, ...rest } = result;
+	const parts = parseTraceparent(traceparent);
+	return {
+		result: Object.keys(nextMeta).length > 0 ? {
+			...rest,
+			_meta: nextMeta
+		} : rest,
+		...parts ? { serverSpan: {
+			traceId: parts.traceId,
+			spanId: parts.spanId
+		} } : {}
+	};
+}
 //#endregion
 //#region src/client/actions/progress.ts
 /**
@@ -23316,10 +23432,11 @@ var InternalMastraMCPClient = class extends MastraBase {
 	/**
 	* Request metadata every outgoing request carries: the per-request log-level
 	* opt-in (when enabled) and the W3C trace fields resolved for this request,
-	* merged under caller-supplied keys.
+	* merged under caller-supplied keys. A configured `traceContext` provider owns
+	* the trace fields; without one they name `span`, the span making the request.
 	*/
-	requestMeta(meta) {
-		const traceContext = this.serverConfig.traceContext?.();
+	requestMeta(meta, span) {
+		const traceContext = this.serverConfig.traceContext ? this.serverConfig.traceContext() : traceContextFromSpan(span);
 		const merged = {
 			...this.serverLogLevel ? { [LOG_LEVEL_META_KEY]: this.serverLogLevel } : {},
 			...traceContext ? traceContextToMeta(traceContext) : {},
@@ -24059,15 +24176,17 @@ var InternalMastraMCPClient = class extends MastraBase {
 							const _meta = this.requestMeta({
 								...context?._meta,
 								...progressMeta
-							});
-							const res = await this.client.callTool({
+							}, context?.tracingContext?.currentSpan);
+							const { result: res, serverSpan } = takeServerTraceContext(await this.client.callTool({
 								name: tool.name,
 								arguments: input,
 								..._meta ? { _meta } : {}
 							}, {
 								timeout: this.timeout,
 								signal: context?.abortSignal
-							});
+							}));
+							const toolCallSpan = context?.tracingContext?.currentSpan;
+							if (toolCallSpan && serverSpan) toolCallSpan.links = [...toolCallSpan.links ?? [], serverSpan];
 							if (res.isError && this.onToolError === "throw") {
 								const errorText = extractToolErrorText(res.content);
 								this.log("debug", `Tool reported an error: ${tool.name}`, { error: errorText });
@@ -26141,6 +26260,16 @@ function toToolExecutionContext(ctx, loggerName) {
 	};
 }
 /**
+* The caller's trace context a request names: `traceparent` and `tracestate` in
+* `_meta`, else the HTTP headers, which is where OpenTelemetry-instrumented hosts
+* put them.
+*/
+function callerTrace(ctx) {
+	const meta = ctx.mcpReq._meta;
+	const headers = ctx.http?.req?.headers;
+	return callerTraceContext(meta?.traceparent, meta?.tracestate) ?? callerTraceContext(headers?.get("traceparent"), headers?.get("tracestate"));
+}
+/**
 * Builds the trusted application context for one request. Auth is re-derived from
 * the transport every time; nothing is carried between continuation rounds. The W3C
 * trace fields sent by the client are exposed under `traceContext` as opaque
@@ -26560,29 +26689,33 @@ var MCPServer = class extends MCPServerBase {
 	setTracedHandler(server, method, handler) {
 		server.setRequestHandler(method, async (request, ctx) => {
 			const params = request.params;
+			const caller = callerTrace(ctx);
 			let requestContext;
 			try {
 				requestContext = await toRequestContext(ctx, this.mapAuthInfoToUser);
 			} catch (error) {
 				this.startRequestSpan(method, params, {
 					server,
-					ctx
+					ctx,
+					caller
 				})?.error({ error });
 				throw error;
 			}
 			const requestSpan = this.startRequestSpan(method, params, {
 				server,
 				ctx,
+				caller,
 				requestContext
 			});
 			let reportedError;
-			return this.traceRequest(requestSpan, () => handler(request, ctx, {
+			const result = await this.traceRequest(requestSpan, () => handler(request, ctx, {
 				requestSpan,
 				requestContext,
 				reportError: (error) => {
 					reportedError = error;
 				}
 			}), () => reportedError);
+			return method === "tools/call" ? withServerTraceContext(result, requestSpan, caller !== void 0) : result;
 		});
 	}
 	/**
@@ -26595,13 +26728,14 @@ var MCPServer = class extends MCPServerBase {
 		const client = envelope?.[CLIENT_INFO_META_KEY] ?? connection?.server?.getClientVersion();
 		const target = params?.name ?? params?.uri;
 		const targetName = typeof target === "string" ? target : void 0;
+		const caller = connection?.caller;
 		return getOrCreateSpan({
 			type: SpanType.MCP_SERVER_REQUEST,
 			name: targetName ? `${method} ${targetName}` : method,
 			entityType: EntityType.MCP_SERVER,
 			entityId: this.id,
 			entityName: this.name,
-			input: params,
+			input: withoutTraceContext(params),
 			attributes: {
 				mcpMethod: method,
 				targetName,
@@ -26609,9 +26743,12 @@ var MCPServer = class extends MCPServerBase {
 				serverVersion: this.version,
 				mcpProtocolVersion: typeof protocolVersion === "string" ? protocolVersion : void 0,
 				clientName: client?.name,
-				clientVersion: client?.version
+				clientVersion: client?.version,
+				callerTraceparent: caller?.traceparent,
+				callerTracestate: caller?.tracestate
 			},
 			tracingContext: {},
+			links: caller && [caller.link],
 			requestContext: connection?.requestContext,
 			mastra: this.mastra
 		});