@mastra/mcp-docs-server 1.2.28 → 1.3.0-alpha.2

package/.docs/reference/streaming/ChunkType.md

@@ -136,6 +136,8 @@ A tool is being called.
 
 **payload.toolName** (`string`): Name of the tool being called
 
+**payload.title** (`string`): Human-readable display name for the tool, when the tool defines one
+
 **payload.args** (`Record<string, any>`): Arguments passed to the tool
 
 **payload.providerExecuted** (`boolean`): Whether the provider executed the tool
@@ -178,6 +180,8 @@ Signals the start of streaming tool call arguments.
 
 **payload.toolName** (`string`): Name of the tool being called
 
+**payload.title** (`string`): Human-readable display name for the tool, when the tool defines one
+
 **payload.providerExecuted** (`boolean`): Whether the provider executed the tool
 
 **payload.dynamic** (`boolean`): Whether the tool call is dynamic

package/.docs/reference/tools/create-tool.md

@@ -39,6 +39,8 @@ The first `execute` parameter is the validated value from `inputSchema`. Destruc
 
 **id** (`string`): A unique identifier for the tool.
 
+**title** (`string`): A human-readable display name for the tool. It is not sent to the model. It travels on the tool-call and tool-call-input-streaming-start stream chunks and on the stored tool-invocation part, so chat UIs can read it to label the call. MCP clients receive it as the tool title.
+
 **description** (`string`): A description of what the tool does. This is used by the agent to decide when to use the tool.
 
 **inputSchema** (`StandardJSONSchemaV1`): A Standard JSON Schema defining the expected input parameters for the tool's execute function.

package/.docs/reference/tools/mcp-client.md

@@ -151,6 +151,8 @@ Per the MCP specification: **clients MUST consider tool annotations to be untrus
 
 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.
 
+Each tool also carries `tool.title`, set from the server's tool `title` and falling back to `annotations.title`. When the server provides neither, `tool.title` is `undefined` and the tool name is the display fallback, matching the MCP display-name precedence.
+
 ## Server instructions
 
 When an MCP server advertises instructions during initialization, `MCPClient` stores them for that server. Forwarding those instructions into an agent's system prompt is **opt-in**: set `forwardInstructions: true` on a server to have agents that use its tools (via `listTools()` or `listToolsets()`) receive its instructions automatically.
@@ -289,7 +291,7 @@ When called without options, the method omits only `durations`; `toolsets`, `err
 
 Returns every server's tools as plain, serializable definitions, grouped by server name and keyed by the server's own tool name (without the `serverName_toolName` namespacing that `listTools()` applies).
 
-Unlike `listTools()`, the result contains no functions or references to a live client, so it can be passed through `JSON.stringify` and cached in Redis or a database, as well as a build artifact. Each definition holds the data from the MCP `tools/list` response (name, description, input schema, output schema, annotations, and `_meta`), plus the server name, version, and instructions captured at discovery time.
+Unlike `listTools()`, the result contains no functions or references to a live client, so it can be passed through `JSON.stringify` and cached in Redis or a database, as well as a build artifact. Each definition holds the data from the MCP `tools/list` response (name, title, description, input schema, output schema, annotations, and `_meta`), plus the server name, version, and instructions captured at discovery time.
 
 ```typescript
 const definitions = await mcp.listToolDefinitions()

package/dist/index.d.ts

@@ -1,5 +1,16 @@
 import { MCPServer } from '@mastra/mcp';
-declare let server: MCPServer;
+import { MCPServer as LegacyMCPServer } from '@mastra/mcp-legacy';
+import type { ProtocolEra } from './protocol-era.js';
+/**
+ * Build the docs server for a protocol era. The same tools and prompts are
+ * registered either way; only the protocol implementation differs.
+ *
+ * `@mastra/mcp` 2.x serves the 2026-07-28 revision. Hosts that still open with
+ * a legacy `initialize` handshake get the published `@mastra/mcp` 1.x server
+ * (installed under the `@mastra/mcp-legacy` alias) so `npx @mastra/mcp-docs-server`
+ * keeps working while editors adopt the new revision.
+ */
+declare function createDocsServer(era: ProtocolEra): MCPServer | LegacyMCPServer;
 declare function runServer(): Promise<void>;
-export { runServer, server };
+export { runServer, createDocsServer };
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAexC,QAAA,IAAI,MAAM,EAAE,SAAS,CAAC;AAsBtB,iBAAe,SAAS,kBAQvB;AAED,OAAO,EAAE,SAAS,EAAE,MAAM,EAAE,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AACxC,OAAO,EAAE,SAAS,IAAI,eAAe,EAAE,MAAM,oBAAoB,CAAC;AAIlE,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,gBAAgB,CAAC;AA8BlD;;;;;;;;GAQG;AACH,iBAAS,gBAAgB,CAAC,GAAG,EAAE,WAAW,+BAEzC;AAED,iBAAe,SAAS,kBAYvB;AAED,OAAO,EAAE,SAAS,EAAE,gBAAgB,EAAE,CAAC"}

package/dist/index.js

@@ -1,2 +1,2 @@
-import { n as server, t as runServer } from "./src-D-W-bx5t.js";
-export { runServer, server };
+import { n as runServer, t as createDocsServer } from "./src-CGZ6-uLS.js";
+export { createDocsServer, runServer };

package/dist/logger.d.ts

@@ -1,4 +1,3 @@
-import type { MCPServer } from '@mastra/mcp';
 export type LogLevel = 'debug' | 'info' | 'warn' | 'error' | 'none';
 export declare function setLogLevel(level: LogLevel): void;
 export declare function getLogLevel(): LogLevel;
@@ -13,6 +12,6 @@ export interface Logger {
     emergency: (message: string, error?: any) => Promise<void>;
 }
 export declare const writeErrorLog: (message: string, data?: any) => void;
-export declare function createLogger(server?: MCPServer): Logger;
+export declare function createLogger(): Logger;
 export declare const logger: Logger;
 //# sourceMappingURL=logger.d.ts.map

package/dist/logger.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"logger.d.ts","sourceRoot":"","sources":["../src/logger.ts"],"names":[],"mappings":"AAGA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAI7C,MAAM,MAAM,QAAQ,GAAG,OAAO,GAAG,MAAM,GAAG,MAAM,GAAG,OAAO,GAAG,MAAM,CAAC;AAkCpE,wBAAgB,WAAW,CAAC,KAAK,EAAE,QAAQ,GAAG,IAAI,CAEjD;AAED,wBAAgB,WAAW,IAAI,QAAQ,CAEtC;AASD,MAAM,WAAW,MAAM;IACrB,KAAK,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,GAAG,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IACtD,IAAI,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,GAAG,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IACrD,MAAM,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,GAAG,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IACvD,OAAO,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,GAAG,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IACxD,KAAK,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,GAAG,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IACvD,QAAQ,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,GAAG,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IAC1D,KAAK,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,GAAG,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IACvD,SAAS,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,GAAG,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;CAC5D;AAED,eAAO,MAAM,aAAa,YAAa,MAAM,SAAS,GAAG,SA2BxD,CAAC;AAGF,wBAAgB,YAAY,CAAC,MAAM,CAAC,EAAE,SAAS,GAAG,MAAM,CA4FvD;AAGD,eAAO,MAAM,MAAM,QAAiB,CAAC"}
+{"version":3,"file":"logger.d.ts","sourceRoot":"","sources":["../src/logger.ts"],"names":[],"mappings":"AAOA,MAAM,MAAM,QAAQ,GAAG,OAAO,GAAG,MAAM,GAAG,MAAM,GAAG,OAAO,GAAG,MAAM,CAAC;AAkCpE,wBAAgB,WAAW,CAAC,KAAK,EAAE,QAAQ,GAAG,IAAI,CAEjD;AAED,wBAAgB,WAAW,IAAI,QAAQ,CAEtC;AASD,MAAM,WAAW,MAAM;IACrB,KAAK,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,GAAG,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IACtD,IAAI,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,GAAG,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IACrD,MAAM,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,GAAG,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IACvD,OAAO,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,GAAG,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IACxD,KAAK,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,GAAG,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IACvD,QAAQ,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,GAAG,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IAC1D,KAAK,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,GAAG,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IACvD,SAAS,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,GAAG,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;CAC5D;AAED,eAAO,MAAM,aAAa,YAAa,MAAM,SAAS,GAAG,SA2BxD,CAAC;AAIF,wBAAgB,YAAY,IAAI,MAAM,CAuErC;AAGD,eAAO,MAAM,MAAM,QAAiB,CAAC"}

package/dist/prompts/migration.d.ts

@@ -1,6 +1,16 @@
-import type { MCPServerPrompts } from '@mastra/mcp';
+import type { Prompt, PromptMessage } from '@mastra/mcp';
 /**
- * Prompt messages callback that generates contextual migration guidance
+ * Prompt callbacks that generate contextual migration guidance.
+ *
+ * Typed by what the callbacks read rather than by one package's
+ * `MCPServerPrompts`, so the same object registers on both the 2026-07-28
+ * server and the legacy 1.x server.
  */
-export declare const migrationPromptMessages: MCPServerPrompts;
+export declare const migrationPromptMessages: {
+    listPrompts: () => Promise<Prompt[]>;
+    getPromptMessages: ({ name, args, }: {
+        name: string;
+        args?: Record<string, unknown>;
+    }) => Promise<PromptMessage[]>;
+};
 //# sourceMappingURL=migration.d.ts.map

package/dist/prompts/migration.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"migration.d.ts","sourceRoot":"","sources":["../../src/prompts/migration.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,gBAAgB,EAAgB,MAAM,aAAa,CAAC;AA8BlE;;GAEG;AACH,eAAO,MAAM,uBAAuB,EAAE,gBAmBrC,CAAC"}
+{"version":3,"file":"migration.d.ts","sourceRoot":"","sources":["../../src/prompts/migration.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,MAAM,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AA2BzD;;;;;;GAMG;AACH,eAAO,MAAM,uBAAuB;IAClC,WAAW,QAAY,OAAO,CAAC,MAAM,EAAE,CAAC;IAExC,iBAAiB,oBAGd;QACD,IAAI,EAAE,MAAM,CAAC;QACb,IAAI,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;KAChC,KAAG,OAAO,CAAC,aAAa,EAAE,CAAC;CAiB7B,CAAC"}

package/dist/protocol-era.d.ts

@@ -0,0 +1,29 @@
+import type { Readable } from 'node:stream';
+/**
+ * Which MCP protocol family the connecting host speaks.
+ *
+ * - `legacy`: pre-2026 hosts. They open the connection with an `initialize`
+ *   request (protocol revisions `2024-11-05` through `2025-11-25`).
+ * - `2026-07-28`: hosts on the current revision. They never send `initialize`;
+ *   their first message is `server/discover` or an envelope-bearing request.
+ */
+export type ProtocolEra = 'legacy' | '2026-07-28';
+/**
+ * Decide the protocol era from the first JSON-RPC line a host writes to stdin.
+ *
+ * Anything that is not a legacy `initialize` request is handed to the
+ * 2026-07-28 server, which produces the spec-defined error for malformed or
+ * unsupported requests. Only a well-formed legacy handshake selects the 1.x
+ * server.
+ */
+export declare function detectProtocolEra(firstLine: string | undefined): ProtocolEra;
+/**
+ * Read up to and including the first newline from `stream`, then push every
+ * byte back so the MCP transport that starts afterwards sees the untouched
+ * message stream.
+ *
+ * Resolves with `undefined` if the stream ends before a newline arrives; the
+ * partial bytes are dropped because no transport can act on a closed stdin.
+ */
+export declare function peekFirstLine(stream: Readable): Promise<string | undefined>;
+//# sourceMappingURL=protocol-era.d.ts.map

package/dist/protocol-era.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"protocol-era.d.ts","sourceRoot":"","sources":["../src/protocol-era.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,aAAa,CAAC;AAE5C;;;;;;;GAOG;AACH,MAAM,MAAM,WAAW,GAAG,QAAQ,GAAG,YAAY,CAAC;AAElD;;;;;;;GAOG;AACH,wBAAgB,iBAAiB,CAAC,SAAS,EAAE,MAAM,GAAG,SAAS,GAAG,WAAW,CAa5E;AAED;;;;;;;GAOG;AACH,wBAAgB,aAAa,CAAC,MAAM,EAAE,QAAQ,GAAG,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CA8C3E"}

package/dist/{src-D-W-bx5t.js → src-CGZ6-uLS.js}

@@ -1,5 +1,6 @@
 import fs from "fs/promises";
 import { MCPServer } from "@mastra/mcp";
+import { MCPServer as MCPServer$1 } from "@mastra/mcp-legacy";
 import * as fs$1 from "fs";
 import { existsSync, mkdirSync } from "fs";
 import * as os$1 from "os";
@@ -55,24 +56,17 @@ const writeErrorLog = (message, data) => {
 		console.error("Failed to write to log file:", err);
 	}
 };
-function createLogger(server) {
+function createLogger() {
 	const sendLog = async (level, message, data) => {
-		if (!server) return;
 		if (!shouldLog(level)) return;
-		try {
-			const sdkServer = server.getServer();
-			if (!sdkServer) return;
-			await sdkServer.sendLoggingMessage({
-				level,
-				data: {
-					message,
-					...data ? typeof data === "object" ? data : { data } : {}
-				}
-			});
-		} catch (error) {
-			if (error instanceof Error && (error.message === "Not connected" || error.message.includes("does not support logging") || error.message.includes("Connection closed"))) return;
-			console.error(`Failed to send ${level} log:`, error instanceof Error ? error.message : error);
-		}
+		console.error(JSON.stringify(data === void 0 ? {
+			level,
+			message
+		} : {
+			level,
+			message,
+			data
+		}));
 	};
 	return {
 		debug: async (message, data) => {
@@ -134,7 +128,6 @@ const logger = createLogger();
 */
 const migrationPrompts = [{
 	name: "upgrade-to-v1",
-	version: "v1",
 	description: "Get a guided migration plan for upgrading from Mastra v0.x to v1.0. Provides step-by-step instructions for handling all breaking changes.",
 	arguments: [{
 		name: "area",
@@ -143,17 +136,23 @@ const migrationPrompts = [{
 	}]
 }, {
 	name: "migration-checklist",
-	version: "v1",
 	description: "Get a comprehensive checklist for migrating to Mastra v1.0. Lists all breaking changes that need to be addressed."
 }];
 /**
-* Prompt messages callback that generates contextual migration guidance
+* Prompt callbacks that generate contextual migration guidance.
+*
+* Typed by what the callbacks read rather than by one package's
+* `MCPServerPrompts`, so the same object registers on both the 2026-07-28
+* server and the legacy 1.x server.
 */
 const migrationPromptMessages = {
 	listPrompts: async () => migrationPrompts,
 	getPromptMessages: async ({ name, args }) => {
 		if (!migrationPrompts.find((p) => p.name === name)) throw new Error(`Prompt not found: ${name}`);
-		if (name === "upgrade-to-v1") return getUpgradeToV1Messages(args?.area);
+		if (name === "upgrade-to-v1") {
+			const area = args?.area;
+			return getUpgradeToV1Messages(typeof area === "string" ? area : void 0);
+		}
 		if (name === "migration-checklist") return getMigrationChecklistMessages();
 		throw new Error(`No message handler for prompt: ${name}`);
 	}
@@ -218,6 +217,70 @@ Group the checklist by area (Agents, Tools, Workflows, etc.) so I can tackle one
 	}];
 }
 //#endregion
+//#region src/protocol-era.ts
+/**
+* Decide the protocol era from the first JSON-RPC line a host writes to stdin.
+*
+* Anything that is not a legacy `initialize` request is handed to the
+* 2026-07-28 server, which produces the spec-defined error for malformed or
+* unsupported requests. Only a well-formed legacy handshake selects the 1.x
+* server.
+*/
+function detectProtocolEra(firstLine) {
+	if (!firstLine) return "2026-07-28";
+	try {
+		const message = JSON.parse(firstLine);
+		if (message && typeof message === "object" && message.method === "initialize") return "legacy";
+	} catch {}
+	return "2026-07-28";
+}
+/**
+* Read up to and including the first newline from `stream`, then push every
+* byte back so the MCP transport that starts afterwards sees the untouched
+* message stream.
+*
+* Resolves with `undefined` if the stream ends before a newline arrives; the
+* partial bytes are dropped because no transport can act on a closed stdin.
+*/
+function peekFirstLine(stream) {
+	return new Promise((resolve, reject) => {
+		const chunks = [];
+		const detach = () => {
+			stream.off("readable", onReadable);
+			stream.off("end", onEnd);
+			stream.off("error", onError);
+		};
+		const finish = (line) => {
+			detach();
+			for (let i = chunks.length - 1; i >= 0; i--) stream.unshift(chunks[i]);
+			resolve(line);
+		};
+		const onReadable = () => {
+			let chunk;
+			while ((chunk = stream.read()) !== null) {
+				const buffer = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);
+				chunks.push(buffer);
+				if (buffer.indexOf(10) !== -1) {
+					const head = Buffer.concat(chunks);
+					finish(head.subarray(0, head.indexOf(10)).toString("utf8"));
+					return;
+				}
+			}
+		};
+		const onEnd = () => {
+			detach();
+			resolve(void 0);
+		};
+		const onError = (error) => {
+			detach();
+			reject(error);
+		};
+		stream.on("readable", onReadable);
+		stream.on("end", onEnd);
+		stream.on("error", onError);
+	});
+}
+//#endregion
 //#region src/utils.ts
 const mdFileCache = /* @__PURE__ */ new Map();
 const __dirname = dirname(fileURLToPath(import.meta.url));
@@ -1742,8 +1805,7 @@ This tool works like a file browser - navigate through directories to find migra
 };
 //#endregion
 //#region src/index.ts
-let server;
-server = new MCPServer({
+const serverConfig = {
 	name: "Mastra Documentation Server",
 	version: JSON.parse(await fs.readFile(fromPackageRoot(`package.json`), "utf8")).version,
 	tools: {
@@ -1757,18 +1819,31 @@ server = new MCPServer({
 		...embeddedDocsTools
 	},
 	prompts: migrationPromptMessages
-});
-Object.assign(logger, createLogger(server));
+};
+/**
+* Build the docs server for a protocol era. The same tools and prompts are
+* registered either way; only the protocol implementation differs.
+*
+* `@mastra/mcp` 2.x serves the 2026-07-28 revision. Hosts that still open with
+* a legacy `initialize` handshake get the published `@mastra/mcp` 1.x server
+* (installed under the `@mastra/mcp-legacy` alias) so `npx @mastra/mcp-docs-server`
+* keeps working while editors adopt the new revision.
+*/
+function createDocsServer(era) {
+	return era === "legacy" ? new MCPServer$1(serverConfig) : new MCPServer(serverConfig);
+}
 async function runServer() {
 	try {
-		await server.startStdio();
-		logger.info("Started Mastra Docs MCP Server");
+		const era = detectProtocolEra(await peekFirstLine(process.stdin));
+		await createDocsServer(era).startStdio();
+		process.stdin.resume();
+		logger.info("Started Mastra Docs MCP Server", { protocol: era });
 	} catch (error) {
 		logger.error("Failed to start server", error);
 		process.exit(1);
 	}
 }
 //#endregion
-export { writeErrorLog as i, server as n, setLogLevel as r, runServer as t };
+export { writeErrorLog as i, runServer as n, setLogLevel as r, createDocsServer as t };
 
-//# sourceMappingURL=src-D-W-bx5t.js.map
+//# sourceMappingURL=src-CGZ6-uLS.js.map