@mastra/mcp-docs-server 1.2.11-alpha.3 → 1.2.11-alpha.4

package/dist/src-BZcgzbk9.js

@@ -0,0 +1,1774 @@
+import fs from "fs/promises";
+import { MCPServer } from "@mastra/mcp";
+import * as fs$1 from "fs";
+import { existsSync, mkdirSync } from "fs";
+import * as os$1 from "os";
+import os from "os";
+import * as path$1 from "path";
+import path, { dirname } from "path";
+import { z } from "zod";
+import { fileURLToPath } from "url";
+import { getPackageInfo } from "local-pkg";
+//#region src/logger.ts
+const LOG_LEVEL_PRIORITY = {
+	debug: 0,
+	info: 1,
+	warn: 2,
+	error: 3,
+	none: 4
+};
+function mapToLogLevel(level) {
+	switch (level) {
+		case "debug": return "debug";
+		case "info":
+		case "notice": return "info";
+		case "warning": return "warn";
+		case "error":
+		case "critical":
+		case "alert":
+		case "emergency": return "error";
+		default: return "info";
+	}
+}
+let currentLogLevel = "debug";
+function setLogLevel(level) {
+	currentLogLevel = level;
+}
+function shouldLog(level) {
+	const mappedLevel = mapToLogLevel(level);
+	return LOG_LEVEL_PRIORITY[mappedLevel] >= LOG_LEVEL_PRIORITY[currentLogLevel];
+}
+const writeErrorLog = (message, data) => {
+	const timestamp = (/* @__PURE__ */ new Date()).toISOString();
+	const hourTimestamp = timestamp.slice(0, 13);
+	const logMessage = {
+		timestamp,
+		message,
+		...data ? typeof data === "object" ? data : { data } : {}
+	};
+	try {
+		const cacheDir = path$1.join(os$1.homedir(), ".cache", "mastra", "mcp-docs-server-logs");
+		fs$1.mkdirSync(cacheDir, { recursive: true });
+		const logFile = path$1.join(cacheDir, `${hourTimestamp}.log`);
+		fs$1.appendFileSync(logFile, JSON.stringify(logMessage) + "\n", "utf8");
+	} catch (err) {
+		console.error("Failed to write to log file:", err);
+	}
+};
+function createLogger(server) {
+	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);
+		}
+	};
+	return {
+		debug: async (message, data) => {
+			if (process.env.DEBUG || process.env.NODE_ENV === "development") await sendLog("debug", message, data);
+		},
+		info: async (message, data) => {
+			await sendLog("info", message, data);
+		},
+		notice: async (message, data) => {
+			await sendLog("notice", message, data);
+		},
+		warning: async (message, data) => {
+			await sendLog("warning", message, data);
+		},
+		error: async (message, error) => {
+			const errorData = error instanceof Error ? {
+				message: error.message,
+				stack: error.stack,
+				name: error.name
+			} : error;
+			writeErrorLog(message, errorData);
+			await sendLog("error", message, errorData);
+		},
+		critical: async (message, error) => {
+			const errorData = error instanceof Error ? {
+				message: error.message,
+				stack: error.stack,
+				name: error.name
+			} : error;
+			writeErrorLog(message, errorData);
+			await sendLog("critical", message, errorData);
+		},
+		alert: async (message, error) => {
+			const errorData = error instanceof Error ? {
+				message: error.message,
+				stack: error.stack,
+				name: error.name
+			} : error;
+			writeErrorLog(message, errorData);
+			await sendLog("alert", message, errorData);
+		},
+		emergency: async (message, error) => {
+			const errorData = error instanceof Error ? {
+				message: error.message,
+				stack: error.stack,
+				name: error.name
+			} : error;
+			writeErrorLog(message, errorData);
+			await sendLog("emergency", message, errorData);
+		}
+	};
+}
+const logger = createLogger();
+//#endregion
+//#region src/prompts/migration.ts
+/**
+* Migration prompts provide guided workflows for upgrading Mastra versions.
+* These prompts help users systematically work through breaking changes.
+*/
+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",
+		description: "Optional: Focus on a specific area (e.g., agent, tools, workflows, memory, storage, voice). The tool will check if a migration guide exists for this area and suggest alternatives if not found. If not provided, gives an overview of all changes.",
+		required: false
+	}]
+}, {
+	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
+*/
+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 === "migration-checklist") return getMigrationChecklistMessages();
+		throw new Error(`No message handler for prompt: ${name}`);
+	}
+};
+/**
+* Generate messages for the upgrade-to-v1 prompt
+*/
+function getUpgradeToV1Messages(area) {
+	if (area) return [{
+		role: "user",
+		content: {
+			type: "text",
+			text: `I need help migrating my Mastra ${area} code from v0.x to v1.0. Use the mastraMigration tool to:
+
+1. If packages aren't already at the 'latest' tag, upgrade packages to the 'latest' tag and do an install of the new packages.
+2. First, try to get the specific migration guide for "${area}" using path: "upgrade-to-v1/${area}"
+3. If that doesn't exist, try the alternate form (singular/plural):
+   - If "${area}" ends with 's', try without the 's' (e.g., "agents" → "agent")
+   - If "${area}" doesn't end with 's', try adding 's' (e.g., "agent" → "agents")
+4. If the guide exists, walk me through the changes step by step
+5. If neither form exists, list available migration guides in "upgrade-to-v1/" and suggest which ones might be relevant to "${area}"
+6. After you find the guide, collect all the codemod calls to run to codemods. These callouts are marked with "> **Codemod:**" in the docs. Run the codemods with "npx @mastra/codemod@latest <codemod-name> <path>" to automate all those changes. Afterwards, help me with any remaining manual changes needed.`
+		}
+	}];
+	return [{
+		role: "user",
+		content: {
+			type: "text",
+			text: `I need to migrate my Mastra project from v0.x to v1.0. Use the mastraMigration tool to:
+
+1. If packages aren't already at the 'latest' tag, upgrade packages to the 'latest' tag and do an install of the new packages.
+2. First, list all available migration guides with path: "upgrade-to-v1/"
+2. Give me a high-level overview of what changed in each area
+3. Find relevant migration areas to focus on based on my project's codebase and confirm the list with me
+4. After the areas are confirmed, check the migration guides for callouts to codemods. These callouts are marked with "> **Codemod:**" in the docs. Run the codemods with "npx @mastra/codemod@latest v1" to automate all those changes. Afterwards, help me with any remaining manual changes needed.
+
+After the areas are confirmed, we'll go through each one systematically.`
+		}
+	}];
+}
+/**
+* Generate messages for the migration-checklist prompt
+*/
+function getMigrationChecklistMessages() {
+	return [{
+		role: "user",
+		content: {
+			type: "text",
+			text: `Create a comprehensive migration checklist for upgrading from Mastra v0.x to v1.0. Use the mastraMigration tool to:
+
+1. List all available migration guides (path: "upgrade-to-v1/")
+2. For each guide, extract the key breaking changes
+3. Present them as a checklist I can work through
+
+Format the checklist with:
+- [ ] checkbox items for each breaking change
+- Brief description of what needs to change
+- Reference to the specific migration guide
+
+Group the checklist by area (Agents, Tools, Workflows, etc.) so I can tackle one area at a time.`
+		}
+	}];
+}
+//#endregion
+//#region src/utils.ts
+const mdFileCache = /* @__PURE__ */ new Map();
+const __dirname = dirname(fileURLToPath(import.meta.url));
+function fromPackageRoot(relative) {
+	return path.resolve(__dirname, `../`, relative);
+}
+async function* walkMdFiles(dir) {
+	if (mdFileCache.has(dir)) {
+		for (const file of mdFileCache.get(dir)) yield file;
+		return;
+	}
+	const filesInDir = [];
+	const entries = await fs.readdir(dir, { withFileTypes: true });
+	for (const entry of entries) {
+		const fullPath = path.join(dir, entry.name);
+		if (entry.isDirectory()) for await (const file of walkMdFiles(fullPath)) {
+			filesInDir.push(file);
+			yield file;
+		}
+		else if (entry.isFile() && entry.name.endsWith(".md")) {
+			filesInDir.push(fullPath);
+			yield fullPath;
+		}
+	}
+	mdFileCache.set(dir, filesInDir);
+}
+async function searchDocumentContent(keywords, baseDir) {
+	if (keywords.length === 0) return [];
+	const fileScores = /* @__PURE__ */ new Map();
+	for await (const filePath of walkMdFiles(baseDir)) {
+		let content;
+		try {
+			content = await fs.readFile(filePath, "utf-8");
+		} catch {
+			continue;
+		}
+		content.split("\n").forEach((lineText) => {
+			const lowerLine = lineText.toLowerCase();
+			for (const keyword of keywords) if (lowerLine.includes(keyword.toLowerCase())) {
+				const relativePath = path.relative(baseDir, filePath).replace(/\\/g, "/");
+				if (!fileScores.has(relativePath)) fileScores.set(relativePath, {
+					path: relativePath,
+					keywordMatches: /* @__PURE__ */ new Set(),
+					totalMatches: 0,
+					titleMatches: 0,
+					pathRelevance: calculatePathRelevance(relativePath, keywords)
+				});
+				const score = fileScores.get(relativePath);
+				score.keywordMatches.add(keyword);
+				score.totalMatches++;
+				if (lowerLine.includes("#") || lowerLine.includes("title")) score.titleMatches++;
+			}
+		});
+	}
+	return Array.from(fileScores.values()).sort((a, b) => calculateFinalScore(b, keywords.length) - calculateFinalScore(a, keywords.length)).slice(0, 10).map((score) => score.path);
+}
+function calculatePathRelevance(filePath, keywords) {
+	let relevance = 0;
+	const pathLower = filePath.toLowerCase();
+	if (pathLower.startsWith("reference/")) relevance += 2;
+	keywords.forEach((keyword) => {
+		if (pathLower.includes(keyword.toLowerCase())) relevance += 3;
+	});
+	if ([
+		"rag",
+		"memory",
+		"agents",
+		"workflows"
+	].some((dir) => pathLower.includes(dir))) relevance += 1;
+	return relevance;
+}
+function calculateFinalScore(score, totalKeywords) {
+	const allKeywordsBonus = score.keywordMatches.size === totalKeywords ? 10 : 0;
+	return score.totalMatches * 1 + score.titleMatches * 3 + score.pathRelevance * 2 + score.keywordMatches.size * 5 + allKeywordsBonus;
+}
+function extractKeywordsFromPath(docPath) {
+	const fileName = docPath.replace(/\.md$/, "").split("/").pop() || "";
+	const keywords = /* @__PURE__ */ new Set();
+	fileName.split(/[-_]|(?=[A-Z])/).forEach((keyword) => {
+		if (keyword.length > 2) keywords.add(keyword.toLowerCase());
+	});
+	return Array.from(keywords);
+}
+function normalizeKeywords(keywords) {
+	return Array.from(new Set(keywords.flatMap((k) => k.split(/\s+/).filter(Boolean)).map((k) => k.toLowerCase())));
+}
+async function getMatchingPaths(path, queryKeywords, baseDir) {
+	const allKeywords = normalizeKeywords([...extractKeywordsFromPath(path), ...queryKeywords || []]);
+	if (allKeywords.length === 0) return "";
+	const suggestedPaths = await searchDocumentContent(allKeywords, baseDir);
+	if (suggestedPaths.length === 0) return "";
+	return `Here are some paths that might be relevant based on your query:\n\n${suggestedPaths.map((path) => `- ${path}`).join("\n")}`;
+}
+//#endregion
+//#region src/tools/course.ts
+const _courseLessonSchema = z.object({ lessonName: z.string().describe("Name of the specific lesson to start. It must match the exact lesson name.") });
+const _confirmationSchema = z.object({ confirm: z.boolean().optional().describe("Set to true to confirm this action") });
+const courseDir = fromPackageRoot(".docs/course");
+const introductionPrompt = `
+This is a course to help a new user learn about Mastra, the open-source AI Agent framework built in TypeScript.
+The following is the introduction content, please provide this text to the user EXACTLY as written below. Do not provide any other text or instructions:
+
+# Welcome to the Mastra Course!
+
+Thank you for registering for the Mastra course! This interactive guide will help you learn how to build powerful AI agents with Mastra, the open-source AI Agent framework built in TypeScript.
+
+## Before We Begin
+
+If you enjoy Mastra, please consider starring the GitHub repository:
+https://github.com/mastra-ai/mastra
+
+This helps the project grow and reach more developers like you!
+
+## How This Course Works
+
+- Each lesson is broken into multiple steps
+- I'll guide you through the code examples and explanations
+- You can ask questions at any time
+- If you ever leave and come back, use the \`startMastraCourse\` tool to pick up where you left off. Just ask to "start the Mastra course".
+- Use the \`nextMastraCourseStep\` tool to move to the next step when you're ready. Just ask to "move to the next step" when you are ready.
+- Use the \`getMastraCourseStatus\` tool to check your progress. You can just ask "get my course progress".
+- Use the \`clearMastraCourseHistory\` tool to reset your progress and start over. You can just ask "clear my course progress".
+
+Type "start mastra course" and let's get started with your first lesson!
+`;
+const lessonPrompt = `
+  This is a course to help a new user learn about Mastra, the open-source AI Agent framework built in TypeScript.
+  Please help the user through the steps of the course by walking them through the content and following the course
+  to write the initial version of the code for them. The goal is to show them how the code works and explain it as they go
+  as the course goes on. Each lesson is broken up into steps. You should return the content of the step and ask the user
+  to move to the next step when they are ready. If the step contains instructions to write code, you should write the code
+  for the user when possible. You should always briefly explain the step before writing the code. Please ensure to 
+  return any text in markdown blockquotes exactly as written in your response. When the user ask about their course progress or course status, make sure to include the course status URL in your response. This is important.
+`;
+function wrapContentInPrompt(content, _isFirstStep = false) {
+	return `${`${lessonPrompt}\n\nHere is the content for this step: <StepContent>${content}</StepContent>`}\n\nWhen you're ready to continue, use the \`nextMastraCourseStep\` tool to move to the next step.`;
+}
+async function getDeviceIdPath() {
+	const cacheDir = path.join(os.homedir(), ".cache", "mastra");
+	if (!existsSync(cacheDir)) mkdirSync(cacheDir, { recursive: true });
+	return path.join(cacheDir, ".device_id");
+}
+async function getDeviceCredentials() {
+	try {
+		const deviceIdPath = await getDeviceIdPath();
+		if (!existsSync(deviceIdPath)) return null;
+		const fileContent = await fs.readFile(deviceIdPath, "utf-8");
+		const parsed = JSON.parse(fileContent);
+		if (typeof parsed.deviceId === "string" && typeof parsed.key === "string") return {
+			deviceId: parsed.deviceId,
+			key: parsed.key
+		};
+		return null;
+	} catch {
+		return null;
+	}
+}
+async function getDeviceId() {
+	const creds = await getDeviceCredentials();
+	if (!creds || !creds?.deviceId) return null;
+	return creds.deviceId;
+}
+async function saveDeviceCredentials(deviceId, key) {
+	const deviceIdPath = await getDeviceIdPath();
+	const toWrite = JSON.stringify({
+		deviceId,
+		key
+	});
+	await fs.writeFile(deviceIdPath, toWrite, "utf-8");
+	await fs.chmod(deviceIdPath, 384);
+}
+async function registerUser(email) {
+	const response = await fetch("https://mastra.ai/api/course/register", {
+		method: "POST",
+		headers: { "Content-Type": "application/json" },
+		body: JSON.stringify({ email })
+	});
+	if (!response.ok) throw new Error(`Registration failed with status ${response.status}: ${response.statusText}`);
+	return response.json();
+}
+async function readCourseStep(lessonName, stepName, _isFirstStep = false) {
+	const lessonDir = (await fs.readdir(courseDir)).find((dir) => dir.replace(/^\d+-/, "") === lessonName);
+	if (!lessonDir) throw new Error(`Lesson "${lessonName}" not found.`);
+	const lessonPath = path.join(courseDir, lessonDir);
+	const stepFile = (await fs.readdir(lessonPath)).find((f) => f.endsWith(".md") && f.replace(/^\d+-/, "").replace(".md", "") === stepName);
+	if (!stepFile) throw new Error(`Step "${stepName}" not found in lesson "${lessonName}".`);
+	const filePath = path.join(courseDir, lessonDir, stepFile);
+	try {
+		return wrapContentInPrompt(await fs.readFile(filePath, "utf-8"));
+	} catch (error) {
+		throw new Error(`Failed to read step "${stepName}" in lesson "${lessonName}": ${error}`);
+	}
+}
+async function updateCourseStateOnServer(deviceId, state) {
+	const creds = await getDeviceCredentials();
+	if (!creds) throw new Error("Device credentials not found.");
+	const response = await fetch("https://mastra.ai/api/course/update", {
+		method: "POST",
+		headers: {
+			"Content-Type": "application/json",
+			"x-mastra-course-key": creds.key
+		},
+		body: JSON.stringify({
+			id: creds.deviceId,
+			state
+		})
+	});
+	if (!response.ok) throw new Error(`Course state update failed with status ${response.status}: ${response.statusText}`);
+}
+async function saveCourseState(state, deviceId) {
+	if (!deviceId) throw new Error("Cannot save course state: User is not registered");
+	const statePath = await getCourseStatePath();
+	try {
+		await fs.writeFile(statePath, JSON.stringify(state, null, 2), "utf-8");
+		try {
+			const creds = await getDeviceCredentials();
+			if (!creds) throw new Error("Device credentials not found");
+			await updateCourseStateOnServer(creds.deviceId, state);
+		} catch {}
+	} catch (error) {
+		throw new Error(`Failed to save course state: ${error}`);
+	}
+}
+async function getCourseStatePath() {
+	const stateDirPath = path.join(os.homedir(), ".cache", "mastra", "course");
+	if (!existsSync(stateDirPath)) mkdirSync(stateDirPath, { recursive: true });
+	return path.join(stateDirPath, "state.json");
+}
+async function loadCourseState() {
+	const statePath = await getCourseStatePath();
+	try {
+		if (existsSync(statePath)) {
+			const stateData = await fs.readFile(statePath, "utf-8");
+			return JSON.parse(stateData);
+		}
+	} catch (error) {
+		throw new Error(`Failed to load course state: ${error}`);
+	}
+	return null;
+}
+async function scanCourseContent() {
+	const lessonDirs = await fs.readdir(courseDir);
+	const validLessons = (await Promise.all(lessonDirs.filter((dir) => !dir.startsWith(".")).sort((a, b) => a.localeCompare(b)).map(async (lessonDir) => {
+		const lessonPath = path.join(courseDir, lessonDir);
+		if (!(await fs.stat(lessonPath)).isDirectory()) return null;
+		const lessonName = lessonDir.replace(/^\d+-/, "");
+		const stepFiles = (await fs.readdir(lessonPath)).filter((file) => file.endsWith(".md")).sort((a, b) => a.localeCompare(b));
+		return {
+			name: lessonName,
+			status: 0,
+			steps: (await Promise.all(stepFiles.map(async (file) => {
+				return {
+					name: file.replace(/^\d+-/, "").replace(".md", ""),
+					status: 0
+				};
+			}))).filter(Boolean)
+		};
+	}))).filter((lesson) => lesson !== null);
+	return {
+		currentLesson: validLessons.length > 0 ? validLessons[0]?.name ?? "" : "",
+		lessons: validLessons
+	};
+}
+async function mergeCourseStates(currentState, newState) {
+	const existingLessonMap = new Map(currentState.lessons.map((lesson) => [lesson.name, lesson]));
+	const mergedLessons = newState.lessons.map((newLesson) => {
+		const existingLesson = existingLessonMap.get(newLesson.name);
+		if (!existingLesson) return newLesson;
+		const existingStepMap = new Map(existingLesson.steps.map((step) => [step.name, step]));
+		const mergedSteps = newLesson.steps.map((newStep) => {
+			const existingStep = existingStepMap.get(newStep.name);
+			if (existingStep) return {
+				...newStep,
+				status: existingStep.status
+			};
+			return newStep;
+		});
+		let lessonStatus = existingLesson.status;
+		if (mergedSteps.every((step) => step.status === 2)) lessonStatus = 2;
+		else if (mergedSteps.some((step) => step.status > 0)) lessonStatus = 1;
+		return {
+			...newLesson,
+			status: lessonStatus,
+			steps: mergedSteps
+		};
+	});
+	let currentLesson = currentState.currentLesson;
+	if (!mergedLessons.some((lesson) => lesson.name === currentLesson) && mergedLessons.length > 0) currentLesson = mergedLessons[0]?.name ?? "";
+	return {
+		currentLesson,
+		lessons: mergedLessons
+	};
+}
+const startMastraCourse = {
+	name: "startMastraCourse",
+	description: "[🎓 COURSE] Starts the Mastra Course. If the user is not registered, they will be prompted to register first. Otherwise, it will start at the first lesson or pick up where they last left off. ALWAYS ask the user for their email address if they are not registered. DO NOT assume their email address, they must confirm their email and that they want to register.",
+	parameters: z.object({ email: z.string().email().optional().describe("Email address for registration if not already registered. ") }),
+	execute: async (args) => {
+		try {
+			const creds = await getDeviceCredentials();
+			const registered = creds !== null;
+			let deviceId = creds?.deviceId ?? null;
+			if (!registered) {
+				if (!args.email) return "To start the Mastra Course, you need to register first. Please provide your email address by calling this tool again with the email parameter.";
+				try {
+					const response = await registerUser(args.email);
+					if (response.success) {
+						await saveDeviceCredentials(response.id, response.key);
+						deviceId = response.id;
+					} else return `Registration failed: ${response.message}. Please try again with a valid email address.`;
+				} catch (error) {
+					return `Failed to register: ${error instanceof Error ? error.message : String(error)}. Please try again later.`;
+				}
+			}
+			let courseState = await loadCourseState();
+			let statusMessage = "";
+			const latestCourseState = await scanCourseContent();
+			if (!latestCourseState.lessons.length) return "No course content found. Please make sure the course content is properly set up in the .docs/course/lessons directory.";
+			if (courseState) {
+				const previousState = JSON.parse(JSON.stringify(courseState));
+				courseState = await mergeCourseStates(courseState, latestCourseState);
+				const newLessons = latestCourseState.lessons.filter((newLesson) => !previousState.lessons.some((oldLesson) => oldLesson.name === newLesson.name));
+				if (newLessons.length > 0) {
+					statusMessage = `📚 Course content has been updated! ${newLessons.length} new lesson(s) have been added:\n`;
+					statusMessage += newLessons.map((lesson) => `- ${lesson.name}`).join("\n");
+					statusMessage += "\n\n";
+				}
+				await saveCourseState(courseState, deviceId);
+			} else {
+				courseState = latestCourseState;
+				await saveCourseState(courseState, deviceId);
+				if (!registered && args.email) return introductionPrompt;
+			}
+			const currentLessonName = courseState.currentLesson;
+			const currentLesson = courseState.lessons.find((lesson) => lesson.name === currentLessonName);
+			if (!currentLesson) return "Error: Current lesson not found in course content. Please try again or reset your course progress.";
+			const currentStep = currentLesson.steps.find((step) => step.status !== 2);
+			if (!currentStep && currentLesson.status !== 2) {
+				currentLesson.status = 2;
+				await saveCourseState(courseState, deviceId);
+				const nextLesson = courseState.lessons.find((lesson) => lesson.status !== 2 && lesson.name !== currentLessonName);
+				if (nextLesson) {
+					courseState.currentLesson = nextLesson.name;
+					await saveCourseState(courseState, deviceId);
+					return `${statusMessage}🎉 You've completed the "${currentLessonName}" lesson!\n\nMoving on to the next lesson: "${nextLesson.name}".\n\nUse the \`nextMastraCourseStep\` tool to start the first step of this lesson.`;
+				} else return `${statusMessage}🎉 Congratulations! You've completed all available lessons in the Mastra Course!\n\nIf you'd like to review any lesson, use the \`startMastraCourseLesson\` tool with the lesson name.`;
+			}
+			if (!currentStep) return `${statusMessage}Error: No incomplete steps found in the current lesson. Please try another lesson or reset your course progress.`;
+			currentStep.status = 1;
+			if (currentLesson.status === 0) currentLesson.status = 1;
+			await saveCourseState(courseState, deviceId);
+			const stepContent = await readCourseStep(currentLessonName, currentStep.name);
+			return `📘 Lesson: ${currentLessonName}\n📝 Step: ${currentStep.name}\n\n${stepContent}\n\nWhen you've completed this step, use the \`nextMastraCourseStep\` tool to continue.`;
+		} catch (error) {
+			return `Error starting the Mastra course: ${error instanceof Error ? error.message : String(error)}`;
+		}
+	}
+};
+const getMastraCourseStatus = {
+	name: "getMastraCourseStatus",
+	description: "[🎓 COURSE] Gets the current status of the Mastra Course, including which lessons and steps have been completed",
+	parameters: z.object({}),
+	execute: async (_args) => {
+		try {
+			const deviceId = await getDeviceId();
+			if (deviceId === null) return "You need to register for the Mastra Course first. Please use the `startMastraCourse` tool to register.";
+			const courseState = await loadCourseState();
+			if (!courseState) return "No course progress found. Please start the course first using the `startMastraCourse` tool.";
+			const latestCourseState = await scanCourseContent();
+			if (!latestCourseState.lessons.length) return "No course content found. Please make sure the course content is properly set up in the .docs/course/lessons directory.";
+			const mergedState = await mergeCourseStates(courseState, latestCourseState);
+			let statusReport = "# Mastra Course Progress\n\n";
+			const totalLessons = mergedState.lessons.length;
+			const completedLessons = mergedState.lessons.filter((lesson) => lesson.status === 2).length;
+			mergedState.lessons.filter((lesson) => lesson.status === 1).length;
+			const totalSteps = mergedState.lessons.reduce((sum, lesson) => sum + lesson.steps.length, 0);
+			const completedSteps = mergedState.lessons.reduce((sum, lesson) => sum + lesson.steps.filter((step) => step.status === 2).length, 0);
+			statusReport += `## Overall Progress\n`;
+			statusReport += `- Course status Url: **https://mastra.ai/course/${deviceId}**\n`;
+			statusReport += `- Current Lesson: **${mergedState.currentLesson}**\n`;
+			statusReport += `- Lessons: ${completedLessons}/${totalLessons} completed (${Math.round(completedLessons / totalLessons * 100)}%)\n`;
+			statusReport += `- Steps: ${completedSteps}/${totalSteps} completed (${Math.round(completedSteps / totalSteps * 100)}%)\n\n`;
+			statusReport += `## Lesson Details\n\n`;
+			mergedState.lessons.forEach((lesson, lessonIndex) => {
+				let lessonStatusIcon = "⬜";
+				if (lesson.status === 1) lessonStatusIcon = "🔶";
+				if (lesson.status === 2) lessonStatusIcon = "✅";
+				const lessonPrefix = lesson.name === mergedState.currentLesson ? "👉 " : "";
+				statusReport += `### ${lessonPrefix}${lessonIndex + 1}. ${lessonStatusIcon} ${lesson.name}\n\n`;
+				lesson.steps.forEach((step, stepIndex) => {
+					let stepStatusIcon = "⬜";
+					if (step.status === 1) stepStatusIcon = "🔶";
+					if (step.status === 2) stepStatusIcon = "✅";
+					statusReport += `- ${stepStatusIcon} Step ${stepIndex + 1}: ${step.name}\n`;
+				});
+				statusReport += "\n";
+			});
+			statusReport += `## Navigation\n\n`;
+			statusReport += `- To continue the course: \`nextMastraCourseStep\`\n`;
+			statusReport += `- To start a specific lesson: \`startMastraCourseLesson\`\n`;
+			statusReport += `- To reset progress: \`clearMastraCourseHistory\`\n`;
+			return `Course Status: ${statusReport}\n\nCourse status url: https://mastra.ai/course/${deviceId}`;
+		} catch (error) {
+			return `Error getting course status: ${error instanceof Error ? error.message : String(error)}`;
+		}
+	}
+};
+const startMastraCourseLesson = {
+	name: "startMastraCourseLesson",
+	description: "[🎓 COURSE] Starts a specific lesson in the Mastra Course. If the lesson has been started before, it will resume from the first incomplete step",
+	parameters: _courseLessonSchema,
+	execute: async (args) => {
+		try {
+			const deviceId = await getDeviceId();
+			if (deviceId === null) return "You need to register for the Mastra Course first. Please use the `startMastraCourse` tool to register.";
+			let courseState = await loadCourseState();
+			if (!courseState) return "No course progress found. Please start the course first using the `startMastraCourse` tool.";
+			const targetLessonName = args.lessonName;
+			const targetLesson = courseState.lessons.find((lesson) => lesson.name === targetLessonName);
+			if (!targetLesson) return `Lesson "${targetLessonName}" not found. Available lessons:\n${courseState.lessons.map((lesson, index) => `${index + 1}. ${lesson.name}`).join("\n")}`;
+			courseState.currentLesson = targetLesson.name;
+			const firstIncompleteStep = targetLesson.steps.find((step) => step.status !== 2) || targetLesson.steps[0];
+			if (!firstIncompleteStep) return `The lesson "${targetLesson.name}" does not have any steps.`;
+			firstIncompleteStep.status = 1;
+			if (targetLesson.status === 0) targetLesson.status = 1;
+			await saveCourseState(courseState, deviceId);
+			const stepContent = await readCourseStep(targetLesson.name, firstIncompleteStep.name);
+			return `📘 Starting Lesson: ${targetLesson.name}\n📝 Step: ${firstIncompleteStep.name}\n\n${stepContent}\n\nWhen you've completed this step, use the \`nextMastraCourseStep\` tool to continue.`;
+		} catch (error) {
+			return `Error starting course lesson: ${error instanceof Error ? error.message : String(error)}`;
+		}
+	}
+};
+const nextMastraCourseStep = {
+	name: "nextMastraCourseStep",
+	description: "[🎓 COURSE] Advances to the next step in the current Mastra Course lesson. If all steps in the current lesson are completed, it will move to the next lesson",
+	parameters: z.object({}),
+	execute: async (_args) => {
+		try {
+			const deviceId = await getDeviceId();
+			if (deviceId === null) return "You need to register for the Mastra Course first. Please use the `startMastraCourse` tool to register.";
+			const courseState = await loadCourseState();
+			if (!courseState) return "No course progress found. Please start the course first using the `startMastraCourse` tool.";
+			const currentLessonName = courseState.currentLesson;
+			const currentLesson = courseState.lessons.find((lesson) => lesson.name === currentLessonName);
+			if (!currentLesson) return "Error: Current lesson not found in course content. Please try again or reset your course progress.";
+			const currentStepIndex = currentLesson.steps.findIndex((step) => step.status === 1);
+			if (currentStepIndex === -1) return "No step is currently in progress. Please start a step first using the `startMastraCourse` tool.";
+			if (currentLesson.steps[currentStepIndex]?.status) currentLesson.steps[currentStepIndex].status = 2;
+			const nextStepIndex = currentLesson.steps.findIndex((step, index) => index > currentStepIndex && step.status !== 2);
+			if (nextStepIndex !== -1) {
+				if (currentLesson.steps[nextStepIndex]) currentLesson.steps[nextStepIndex].status = 1;
+				await saveCourseState(courseState, deviceId);
+				const nextStep = currentLesson.steps[nextStepIndex];
+				const stepContent = await readCourseStep(currentLessonName, nextStep?.name ?? "Unknown Step");
+				return `🎉 Step "${currentLesson.steps[currentStepIndex]?.name ?? "Unknown Step"}" completed!\n\n📘 Continuing Lesson: ${currentLessonName}\n📝 Next Step: ${nextStep?.name ?? "Unknown Step"}\n\n${stepContent}\n\nWhen you've completed this step, use the \`nextMastraCourseStep\` tool to continue.`;
+			}
+			currentLesson.status = 2;
+			const currentLessonIndex = courseState.lessons.findIndex((lesson) => lesson.name === currentLessonName);
+			const nextLesson = courseState.lessons.find((lesson, index) => index > currentLessonIndex && lesson.status !== 2);
+			if (nextLesson) {
+				courseState.currentLesson = nextLesson.name;
+				if (nextLesson.steps.length > 0 && nextLesson.steps[0]) nextLesson.steps[0].status = 1;
+				nextLesson.status = 1;
+				await saveCourseState(courseState, deviceId);
+				const firstStep = nextLesson.steps[0];
+				const stepContent = await readCourseStep(nextLesson.name, firstStep?.name ?? "Unknown Step");
+				return `🎉 Congratulations! You've completed the "${currentLessonName}" lesson!\n\n📘 Starting New Lesson: ${nextLesson.name}\n📝 First Step: ${firstStep?.name ?? "Unknown Step"}\n\n${stepContent}\n\nWhen you've completed this step, use the \`nextMastraCourseStep\` tool to continue.`;
+			}
+			await saveCourseState(courseState, deviceId);
+			return `🎉 Congratulations! You've completed all available lessons in the Mastra Course!\n\nIf you'd like to review any lesson, use the \`startMastraCourseLesson\` tool with the lesson name.`;
+		} catch (error) {
+			return `Error advancing to the next course step: ${error instanceof Error ? error.message : String(error)}`;
+		}
+	}
+};
+const clearMastraCourseHistory = {
+	name: "clearMastraCourseHistory",
+	description: "[🎓 COURSE] Clears all Mastra Course progress history and starts over from the beginning. This action cannot be undone",
+	parameters: _confirmationSchema,
+	execute: async (args) => {
+		try {
+			if (await getDeviceId() === null) return "You need to register for the Mastra Course first. Please use the `startMastraCourse` tool to register.";
+			if (!args.confirm) return "⚠️ This action will delete all your course progress and cannot be undone. To proceed, please run this tool again with the confirm parameter set to true.";
+			const statePath = await getCourseStatePath();
+			if (!existsSync(statePath)) return "No course progress found. Nothing to clear.";
+			await fs.unlink(statePath);
+			return "🧹 Course progress has been cleared. You can restart the Mastra course from the beginning.";
+		} catch (error) {
+			return `Error clearing course history: ${error instanceof Error ? error.message : String(error)}`;
+		}
+	}
+};
+//#endregion
+//#region src/tools/docs.ts
+const docsBaseDir = fromPackageRoot(".docs/");
+async function listDirContents(dirPath) {
+	try {
+		logger.debug("Listing directory contents", { path: dirPath });
+		const entries = await fs.readdir(dirPath, { withFileTypes: true });
+		const dirs = [];
+		const files = [];
+		for (const entry of entries) if (entry.isDirectory()) dirs.push(entry.name + "/");
+		else if (entry.isFile() && entry.name.endsWith(".md")) files.push(entry.name.replace(/\.md$/, ""));
+		return {
+			dirs: dirs.sort(),
+			files: files.sort()
+		};
+	} catch (error) {
+		logger.error("Failed to list directory contents", {
+			path: dirPath,
+			error
+		});
+		throw error;
+	}
+}
+async function readDocsContent(docPath, queryKeywords) {
+	const basePath = path.resolve(docsBaseDir);
+	const fullPath = path.resolve(path.join(basePath, docPath));
+	const relativePath = path.relative(basePath, fullPath);
+	if (relativePath.startsWith("..") || path.isAbsolute(relativePath)) {
+		logger.error("Path traversal attempt detected", {
+			path: docPath,
+			resolvedPath: fullPath
+		});
+		return {
+			found: false,
+			isSecurityViolation: true
+		};
+	}
+	logger.debug("Reading docs content", { path: fullPath });
+	try {
+		if ((await fs.stat(fullPath)).isDirectory()) {
+			const indexMdPath = path.join(fullPath, "index.md");
+			try {
+				return {
+					found: true,
+					content: await fs.readFile(indexMdPath, "utf-8"),
+					isSecurityViolation: false
+				};
+			} catch {}
+			const { dirs, files } = await listDirContents(fullPath);
+			const listing = [`Directory contents of ${docPath || "/"}:`, ""];
+			if (dirs.length > 0) {
+				listing.push("Subdirectories:");
+				listing.push(...dirs.map((d) => `- ${docPath ? `${docPath}/${d}` : d}`));
+				listing.push("");
+			}
+			if (files.length > 0) {
+				listing.push("Available documentation paths:");
+				listing.push(...files.map((f) => `- ${docPath ? `${docPath}/${f}` : f}`));
+				listing.push("");
+			}
+			if (dirs.length === 0 && files.length === 0) listing.push("No documentation available in this directory.");
+			const contentBasedSuggestions = await getMatchingPaths(docPath, queryKeywords, docsBaseDir);
+			const suggestions = contentBasedSuggestions ? [
+				"---",
+				"",
+				contentBasedSuggestions,
+				""
+			].join("\n") : "";
+			return {
+				found: true,
+				content: listing.join("\n") + suggestions,
+				isSecurityViolation: false
+			};
+		}
+		return {
+			found: true,
+			content: await fs.readFile(fullPath, "utf-8"),
+			isSecurityViolation: false
+		};
+	} catch (error) {
+		if (error.code === "ENOENT") try {
+			const mdPath = fullPath + ".md";
+			return {
+				found: true,
+				content: await fs.readFile(mdPath, "utf-8"),
+				isSecurityViolation: false
+			};
+		} catch {
+			return {
+				found: false,
+				isSecurityViolation: false
+			};
+		}
+		throw error;
+	}
+}
+async function findNearestDirectory(docPath, availablePaths) {
+	logger.debug("Finding nearest directory", { path: docPath });
+	const parts = docPath.split("/");
+	while (parts.length > 0) {
+		const testPath = parts.join("/");
+		try {
+			const fullPath = path.join(docsBaseDir, testPath);
+			if ((await fs.stat(fullPath)).isDirectory()) {
+				const { dirs, files } = await listDirContents(fullPath);
+				const listing = [
+					`Path "${docPath}" not found.`,
+					`Here are the available paths in "${testPath}":`,
+					""
+				];
+				if (dirs.length > 0) {
+					listing.push("Directories:");
+					listing.push(...dirs.map((d) => `- ${testPath}/${d}`));
+					listing.push("");
+				}
+				if (files.length > 0) {
+					listing.push("Files:");
+					listing.push(...files.map((f) => `- ${testPath}/${f}`));
+				}
+				return listing.join("\n");
+			}
+		} catch {
+			logger.debug("Directory not found, trying parent", { parent: parts.slice(0, -1).join("/") });
+		}
+		parts.pop();
+	}
+	return [
+		`Path "${docPath}" not found.`,
+		"Here are all available paths:",
+		"",
+		availablePaths
+	].join("\n");
+}
+async function getAvailablePaths() {
+	const { dirs, files } = await listDirContents(docsBaseDir);
+	let referenceDirs = [];
+	if (dirs.includes("reference/")) {
+		const { dirs: refDirs } = await listDirContents(path.join(docsBaseDir, "reference"));
+		referenceDirs = refDirs.map((d) => `reference/${d}`);
+	}
+	return [
+		"Available top-level paths:",
+		"",
+		"Directories:",
+		...dirs.map((d) => `- ${d}`),
+		"",
+		referenceDirs.length > 0 ? "Reference subdirectories:" : "",
+		...referenceDirs.map((d) => `- ${d}`),
+		"",
+		files.length > 0 ? "Files:" : "",
+		...files.map((f) => `- ${f}`)
+	].filter(Boolean).join("\n");
+}
+const availablePaths = await getAvailablePaths();
+const docsTool = {
+	name: "mastraDocs",
+	description: `[🌐 REMOTE] Get Mastra documentation.
+    Request paths to explore the docs. References contain API docs.
+    Other paths contain guides. The user doesn\'t know about files and directories.
+    You can also use keywords from the user query to find relevant documentation, but prioritize paths.
+    This is your internal knowledge the user can\'t read.
+    If the user asks about a feature check general docs as well as reference docs for that feature.
+    Ex: with workflows check in docs/workflows and in reference/workflows.
+    Provide code examples so the user understands.
+    IMPORTANT: Be concise with your answers. The user will ask for more info.
+    If packages need to be installed, provide the pnpm command to install them.
+    Ex. if you see \`import { X } from "@mastra/$PACKAGE_NAME"\` in an example, show an install command.
+    Always install latest tag, not alpha unless requested. If you scaffold a new project it may be in a subdir.
+    When displaying results, always mention which file path contains the information so users know where this documentation lives.`,
+	parameters: z.object({
+		paths: z.array(z.string()).min(1).describe(`One or more documentation paths to fetch\nAvailable paths:\n${availablePaths}`),
+		queryKeywords: z.array(z.string()).optional().describe("Keywords from user query to use for matching documentation. Each keyword should be a single word or short phrase; any whitespace-separated keywords will be split automatically.")
+	}),
+	execute: async (args) => {
+		logger.debug("Executing mastraDocs tool", { args });
+		try {
+			const queryKeywords = args.queryKeywords ?? [];
+			return (await Promise.all(args.paths.map(async (docPath) => {
+				try {
+					const result = await readDocsContent(docPath, queryKeywords);
+					if (result.found) return {
+						path: docPath,
+						content: result.content,
+						error: null
+					};
+					if (result.isSecurityViolation) return {
+						path: docPath,
+						content: null,
+						error: "Invalid path"
+					};
+					return {
+						path: docPath,
+						content: null,
+						error: [await findNearestDirectory(docPath, availablePaths), await getMatchingPaths(docPath, queryKeywords, docsBaseDir)].join("\n\n")
+					};
+				} catch (error) {
+					logger.warning(`Failed to read content for path: ${docPath}`, error);
+					return {
+						path: docPath,
+						content: null,
+						error: error instanceof Error ? error.message : "Unknown error"
+					};
+				}
+			}))).map((result) => {
+				if (result.error) return `## ${result.path}\n\n${result.error}\n\n---\n`;
+				return `## ${result.path}\n\n${result.content}\n\n---\n`;
+			}).join("\n");
+		} catch (error) {
+			logger.error("Failed to execute mastraDocs tool", error);
+			throw error;
+		}
+	}
+};
+//#endregion
+//#region src/tools/embedded-docs.ts
+const packageCache = /* @__PURE__ */ new Map();
+const sourceMapCache = /* @__PURE__ */ new Map();
+const packageInfoCache = /* @__PURE__ */ new Map();
+const KNOWN_MASTRA_PACKAGES = [
+	"@mastra/core",
+	"@mastra/cli",
+	"@mastra/memory",
+	"@mastra/rag",
+	"@mastra/evals",
+	"@mastra/mcp",
+	"@mastra/server",
+	"@mastra/deployer",
+	"@mastra/agent-builder",
+	"@mastra/auth",
+	"@mastra/fastembed",
+	"@mastra/loggers",
+	"@mastra/schema-compat",
+	"@mastra/codemod"
+];
+async function getPackageRootPath(packageName, projectPath) {
+	const cacheKey = `${packageName}:${projectPath}`;
+	if (packageInfoCache.has(cacheKey)) return packageInfoCache.get(cacheKey);
+	try {
+		const info = await getPackageInfo(packageName, { paths: [path.join(projectPath, "node_modules")] });
+		if (info?.rootPath) {
+			const result = {
+				rootPath: info.rootPath,
+				version: info.version || "unknown"
+			};
+			packageInfoCache.set(cacheKey, result);
+			logger.debug("Resolved package with local-pkg", {
+				packageName,
+				projectPath,
+				...result
+			});
+			return result;
+		}
+	} catch (err) {
+		logger.debug("Package not found or error resolving", {
+			packageName,
+			projectPath,
+			error: err instanceof Error ? err.message : String(err)
+		});
+	}
+	packageInfoCache.set(cacheKey, null);
+	return null;
+}
+async function getInstalledMastraPackages(projectPath) {
+	const cacheKey = projectPath;
+	if (packageCache.has(cacheKey)) {
+		logger.debug("Using cached package list", { count: packageCache.get(cacheKey).length });
+		return packageCache.get(cacheKey);
+	}
+	logger.debug("Scanning for @mastra packages using local-pkg", { projectPath });
+	const packages = [];
+	const packagesWithoutDocs = [];
+	for (const packageName of KNOWN_MASTRA_PACKAGES) {
+		const packageInfo = await getPackageRootPath(packageName, projectPath);
+		if (packageInfo) {
+			const docsPath = path.join(packageInfo.rootPath, "dist", "docs");
+			try {
+				if ((await fs.stat(docsPath)).isDirectory()) {
+					packages.push(packageName);
+					logger.debug("Found package with embedded docs", { package: packageName });
+				} else packagesWithoutDocs.push(packageName);
+			} catch {
+				packagesWithoutDocs.push(packageName);
+			}
+		}
+	}
+	const result = packages.sort();
+	packageCache.set(cacheKey, result);
+	logger.info("Package scan complete", {
+		packagesWithDocs: result.length,
+		packagesWithoutDocs: packagesWithoutDocs.length,
+		packages: result
+	});
+	return result;
+}
+async function readSourceMap(packageName, projectPath) {
+	const cacheKey = `${packageName}:${projectPath}`;
+	if (sourceMapCache.has(cacheKey)) return sourceMapCache.get(cacheKey);
+	try {
+		const packageInfo = await getPackageRootPath(packageName, projectPath);
+		if (!packageInfo) {
+			sourceMapCache.set(cacheKey, null);
+			return null;
+		}
+		const sourceMapPath = path.join(packageInfo.rootPath, "dist", "docs", "SOURCE_MAP.json");
+		const content = await fs.readFile(sourceMapPath, "utf-8");
+		const sourceMap = JSON.parse(content);
+		sourceMapCache.set(cacheKey, sourceMap);
+		return sourceMap;
+	} catch {
+		sourceMapCache.set(cacheKey, null);
+		return null;
+	}
+}
+const embeddedDocsTools = {
+	getMastraHelp: {
+		name: "getMastraHelp",
+		description: `🚀 START HERE - Complete guide to Mastra documentation tools.
+
+    This MCP server provides TWO documentation sources:
+
+    ## 📦 LOCAL PACKAGE DOCS (Recommended for Development)
+    SOURCE: Your installed @mastra packages in node_modules
+    VERSION: Matches your installed code exactly
+
+    ADVANTAGES:
+    - ✅ Version-matched to your code
+    - ✅ Complete TypeScript type definitions
+    - ✅ Works offline
+    - ✅ SOURCE_MAP.json with exact exports
+
+    TOOLS: listMastraPackages, getMastraExports, getMastraExportDetails, readMastraDocs, searchMastraDocs
+    USE WHEN: Writing code, implementing features, checking APIs, debugging
+
+    ## 🌐 REMOTE WEBSITE DOCS (For Latest Info & Learning)
+    SOURCE: mastra.ai website
+    VERSION: Latest published documentation
+
+    ADVANTAGES:
+    - ✅ Always up-to-date
+    - ✅ Blog posts and announcements
+    - ✅ Migration guides
+    - ✅ Curated examples
+
+    TOOLS: mastraDocs, mastraBlog, mastraExamples, mastraChanges, mastraMigration
+    USE WHEN: Learning concepts, checking latest features, migration help
+
+    ## 🎓 INTERACTIVE COURSE
+    TOOLS: startMastraCourse, getMastraCourseStatus, etc.
+    USE WHEN: User wants guided learning experience
+
+    ---
+
+    RECOMMENDED WORKFLOW:
+    1. For coding: listMastraPackages → getMastraExports → getMastraExportDetails
+    2. For learning: mastraDocs
+    3. Version mismatch: mastraChanges → mastraMigration
+
+    This tool shows you which packages are installed and provides detailed guidance on using all available documentation tools.`,
+		parameters: z.object({ projectPath: z.string().describe("Absolute path to your project root (we will search upward for node_modules with Mastra packages)") }),
+		execute: async (args) => {
+			logger.debug("Executing getMastraHelp tool", { projectPath: args.projectPath });
+			const packages = await getInstalledMastraPackages(args.projectPath);
+			if (packages.length === 0) return `No Mastra packages with embedded documentation found in your project.
+
+To use these tools, install Mastra packages like:
+- npm install @mastra/core
+- npm install @mastra/memory
+- npm install @mastra/rag
+
+Then rebuild/reinstall to generate embedded docs.`;
+			return `# Mastra Documentation System - Complete Guide
+
+This MCP server provides **TWO** documentation sources. Choose based on your needs:
+
+---
+
+## 📦 LOCAL PACKAGE DOCS (Your Installed Packages)
+
+Found ${packages.length} installed package(s) with embedded documentation:
+${packages.map((pkg) => `- ${pkg}`).join("\n")}
+
+**SOURCE**: Your node_modules (matches installed code version)
+**USE WHEN**: Writing code, implementing features, debugging, checking APIs
+
+### Available LOCAL Tools:
+
+**1. listMastraPackages** - List installed packages
+   Returns: Packages with embedded docs
+
+**2. getMastraExports** - Explore package API surface
+   Example: See all exports from @mastra/core (Agent, Tool, Workflow, etc.)
+   Returns: List of exports with source file locations
+
+**3. getMastraExportDetails** - Get type definitions & code
+   Example: Get full TypeScript types for Agent class
+   Returns: Complete type definitions and optionally implementation source
+
+**4. readMastraDocs** - Read comprehensive guides
+   Example: Read documentation about agents, tools, workflows, memory
+   Returns: Topic-based guides and examples from your installed version
+
+**5. searchMastraDocs** - Search local documentation
+   Example: Search for "memory processors" or "semantic recall"
+   Returns: Relevant excerpts from your installed docs
+
+### Typical LOCAL Workflow:
+1. listMastraPackages → see what's installed
+2. getMastraExports → explore package API
+3. getMastraExportDetails → get type definitions
+4. readMastraDocs → learn concepts
+5. searchMastraDocs → find specific info
+
+---
+
+## 🌐 REMOTE WEBSITE DOCS (mastra.ai)
+
+**SOURCE**: https://mastra.ai (latest published documentation)
+**USE WHEN**: Learning new concepts, checking latest features, migration guides
+
+### Available REMOTE Tools:
+
+**mastraDocs** - Browse official documentation
+   Latest guides, references, and tutorials
+
+**mastraBlog** - Read blog posts and announcements
+   News, features, changelogs
+
+**mastraExamples** - Get curated code examples
+   Full example applications
+
+**mastraChanges** - View package changelogs
+   See what's new in each version
+
+**mastraMigration** - Get migration guides
+   Upgrade between versions
+
+⚠️ **Version Note**: Remote docs show latest published version. For API reference matching YOUR code, use LOCAL tools above.
+
+---
+
+## 🎓 INTERACTIVE COURSE
+
+**startMastraCourse**, **getMastraCourseStatus**, **startMastraCourseLesson**, **nextMastraCourseStep**, **clearMastraCourseHistory**
+
+Guided learning experience with hands-on exercises.
+
+---
+
+## Quick Start Recommendations
+
+**If you're writing code**: Use LOCAL tools
+   → Start with listMastraPackages
+
+**If you're learning**: Use REMOTE tools
+   → Start with mastraDocs
+
+**If version differs**: Check changes
+   → mastraChanges → mastraMigration`;
+		}
+	},
+	listMastraPackages: {
+		name: "listMastraPackages",
+		description: `[📦 LOCAL PACKAGES] Discover which Mastra packages are installed and have documentation available.
+
+    Use this when you need to:
+    - See what Mastra packages you can work with
+    - Start exploring Mastra documentation
+    - Check if a specific package is available
+
+    Returns: List of @mastra/* packages (core, memory, rag, etc.) with embedded docs.
+    Next step: Use getMastraExports to explore a specific package's API.`,
+		parameters: z.object({ projectPath: z.string().describe("Absolute path to your project root (we will search upward for node_modules with Mastra packages)") }),
+		execute: async (args) => {
+			logger.debug("Executing listInstalledMastraPackages tool", {
+				projectPath: args.projectPath,
+				cwd: process.cwd(),
+				env: {
+					PWD: process.env.PWD,
+					HOME: process.env.HOME
+				}
+			});
+			const packages = await getInstalledMastraPackages(args.projectPath);
+			if (packages.length === 0) return `No @mastra/* packages with embedded docs found in your project.
+
+Install Mastra packages to get started:
+- npm install @mastra/core
+- npm install @mastra/memory
+- npm install @mastra/rag`;
+			return [
+				`# Installed Mastra Packages`,
+				"",
+				`Found ${packages.length} package(s) with embedded documentation:`,
+				"",
+				...packages.map((pkg) => `- ${pkg}`),
+				"",
+				"## Next Steps",
+				"",
+				"1. Use **getMastraExports** with a package name to see all available APIs",
+				"2. Use **readMastraDocs** with a package name to browse topic guides",
+				"3. Use **searchMastraDocs** to find specific information"
+			].join("\n");
+		}
+	},
+	getMastraExports: {
+		name: "getMastraExports",
+		description: `[📦 LOCAL PACKAGES] Explore the complete API surface of a Mastra package - see all classes, functions, types, and constants.
+
+    Use this when you need to:
+    - Discover what APIs a Mastra package provides (Agent, Tool, Workflow, etc.)
+    - See all available classes and functions before implementing
+    - Find the right export for your use case
+    - Understand package structure and organization
+
+    Returns: List of all exports with their source file locations.
+    Next step: Use getMastraExportDetails to get full type definitions and code for a specific export.`,
+		parameters: z.object({
+			package: z.string().describe("Package name to explore (e.g., \"@mastra/core\", \"@mastra/memory\", \"@mastra/rag\")"),
+			projectPath: z.string().describe("Absolute path to your project root (we will search upward for node_modules)"),
+			filter: z.string().optional().describe("Optional: filter exports by name (case-insensitive, e.g., \"Agent\", \"create\", \"Tool\")")
+		}),
+		execute: async (args) => {
+			logger.debug("Executing readMastraSourceMap tool", { args });
+			const sourceMap = await readSourceMap(args.package, args.projectPath);
+			if (!sourceMap) return `No SOURCE_MAP.json found for ${args.package}.`;
+			let exports = Object.entries(sourceMap.exports);
+			if (args.filter) {
+				const filterLower = args.filter.toLowerCase();
+				exports = exports.filter(([name]) => name.toLowerCase().includes(filterLower));
+			}
+			if (exports.length === 0) return args.filter ? `No exports matching "${args.filter}" in ${args.package}.
+
+Try running without a filter to see all available exports.` : `No exports found in ${args.package}.`;
+			return [
+				`# ${sourceMap.package} v${sourceMap.version} - API Exports`,
+				"",
+				`Found ${exports.length} export(s)${args.filter ? ` matching "${args.filter}"` : ""}:`,
+				"",
+				...exports.map(([name, info]) => {
+					const line = info.line ? `:${info.line}` : "";
+					return `- **${name}**: \`${info.implementation}${line}\``;
+				}),
+				"",
+				"## Next Steps",
+				"",
+				"- Use **getMastraExportDetails** with an export name to see full type definitions and code",
+				"- Use **readMastraDocs** to read conceptual guides and examples",
+				"- Use **searchMastraDocs** to find specific topics or patterns"
+			].join("\n");
+		}
+	},
+	getMastraExportDetails: {
+		name: "getMastraExportDetails",
+		description: `[📦 LOCAL PACKAGES] Get complete API reference for a specific Mastra export - type definitions, interfaces, and optionally source code.
+
+    Use this when you need to:
+    - Understand how to use a specific Mastra class or function (Agent, Tool, Workflow, etc.)
+    - See TypeScript type definitions and interfaces
+    - Look up method signatures and parameters
+    - Read implementation code and examples
+    - Understand constructor options and configuration
+
+    Returns: Full TypeScript type definitions and optionally implementation source code.
+    Example: Get details on the Agent class to see how to create and configure agents.`,
+		parameters: z.object({
+			package: z.string().describe("Package name (e.g., \"@mastra/core\", \"@mastra/memory\")"),
+			exportName: z.string().describe("Exact export name to look up (e.g., \"Agent\", \"createTool\", \"Workflow\")"),
+			includeTypes: z.boolean().optional().default(true).describe("Include TypeScript type definitions (recommended: true)"),
+			includeImplementation: z.boolean().optional().default(false).describe("Include source code implementation (useful for understanding internals)"),
+			implementationLines: z.number().optional().default(50).describe("Number of lines of implementation code to show (default: 50)"),
+			projectPath: z.string().describe("Absolute path to your project root (we will search upward for node_modules)")
+		}),
+		execute: async (args) => {
+			logger.debug("Executing findMastraExport tool", { args });
+			const sourceMap = await readSourceMap(args.package, args.projectPath);
+			if (!sourceMap) return `No SOURCE_MAP.json found for ${args.package}.`;
+			const exportInfo = sourceMap.exports[args.exportName];
+			if (!exportInfo) {
+				const match = Object.entries(sourceMap.exports).find(([name]) => name.toLowerCase() === args.exportName.toLowerCase());
+				if (match) return `Export "${args.exportName}" not found. Did you mean "${match[0]}"?
+
+Run getMastraExports with package="${args.package}" to see all available exports.`;
+				return `Export "${args.exportName}" not found in ${args.package}.
+
+Run getMastraExports with package="${args.package}" to see all available exports.`;
+			}
+			const packageInfo = await getPackageRootPath(args.package, args.projectPath);
+			if (!packageInfo) return `Package ${args.package} not found. Make sure it's installed.`;
+			const output = [`# ${args.exportName} (${args.package})`, ""];
+			if (args.includeTypes !== false) try {
+				const typesPath = path.join(packageInfo.rootPath, exportInfo.types);
+				const typesContent = await fs.readFile(typesPath, "utf-8");
+				output.push("## Type Definition", "", `\`${exportInfo.types}\``, "", "```typescript");
+				const lines = typesContent.split("\n");
+				let startLine = lines.findIndex((line) => line.includes(args.exportName));
+				if (startLine === -1) output.push(typesContent.slice(0, 2e3));
+				else {
+					startLine = Math.max(0, startLine - 2);
+					let endLine = Math.min(lines.length, startLine + 50);
+					output.push(lines.slice(startLine, endLine).join("\n"));
+				}
+				output.push("```", "");
+			} catch {
+				output.push("## Type Definition", "", `Could not read: ${exportInfo.types}`, "");
+			}
+			if (args.includeImplementation) try {
+				const implPath = path.join(packageInfo.rootPath, exportInfo.implementation);
+				const lines = (await fs.readFile(implPath, "utf-8")).split("\n");
+				const numLines = args.implementationLines || 50;
+				output.push("## Implementation", "");
+				output.push(`\`${exportInfo.implementation}\`${exportInfo.line ? ` (line ${exportInfo.line})` : ""}`);
+				output.push("", "```javascript");
+				const startLine = exportInfo.line ? Math.max(0, exportInfo.line - 1) : 0;
+				const endLine = Math.min(lines.length, startLine + numLines);
+				output.push(lines.slice(startLine, endLine).join("\n"));
+				if (endLine < lines.length) output.push(`// ... ${lines.length - endLine} more lines`);
+				output.push("```", "");
+			} catch {
+				output.push("## Implementation", "", `Could not read: ${exportInfo.implementation}`, "");
+			}
+			output.push("## Next Steps", "", "- Use **readMastraDocs** to see practical guides and examples", "- Use **searchMastraDocs** to find usage patterns and best practices", "- Use **getMastraExports** to explore related APIs");
+			return output.join("\n");
+		}
+	},
+	readMastraDocs: {
+		name: "readMastraDocs",
+		description: `[📦 LOCAL PACKAGES] Read comprehensive guides and documentation on Mastra concepts, patterns, and implementation examples.
+
+    Use this when you need to:
+    - Learn how to implement Mastra features (agents, tools, workflows, memory, RAG, etc.)
+    - Understand Mastra architecture and design patterns
+    - See practical code examples and tutorials
+    - Read getting started guides and best practices
+    - Understand how different components work together
+
+    Returns: Topic-based documentation with explanations, examples, and usage patterns.
+    Available topics: agents, tools, workflows, memory, rag, integrations, deployment, and more.`,
+		parameters: z.object({
+			package: z.string().describe("Package name to read docs from (e.g., \"@mastra/core\", \"@mastra/memory\")"),
+			topic: z.string().optional().describe("Optional: topic folder to read (e.g., \"agents\", \"tools\", \"workflows\"). Omit to list all available topics."),
+			file: z.string().optional().describe("Optional: specific documentation file within the topic (e.g., \"01-overview.md\")"),
+			projectPath: z.string().describe("Absolute path to your project root (we will search upward for node_modules)")
+		}),
+		execute: async (args) => {
+			logger.debug("Executing readMastraEmbeddedDocs tool", { args });
+			const packageInfo = await getPackageRootPath(args.package, args.projectPath);
+			if (!packageInfo) return `Package ${args.package} not found. Make sure it's installed.`;
+			const docsPath = path.join(packageInfo.rootPath, "dist", "docs");
+			try {
+				await fs.stat(docsPath);
+			} catch {
+				return `No embedded docs found for ${args.package}.
+
+Make sure the package is installed and has documentation generated.`;
+			}
+			if (!args.topic) {
+				const entries = await fs.readdir(docsPath, { withFileTypes: true });
+				const topics = entries.filter((e) => e.isDirectory()).map((e) => e.name);
+				const files = entries.filter((e) => e.isFile()).map((e) => e.name);
+				return [
+					`# ${args.package} - Available Documentation`,
+					"",
+					"## Root Files",
+					...files.map((f) => `- ${f}`),
+					"",
+					"## Documentation Topics",
+					...topics.map((t) => `- **${t}/** - Run readMastraDocs with topic="${t}" to read`),
+					"",
+					"## Next Steps",
+					"",
+					"- Choose a topic and run **readMastraDocs** with the topic parameter",
+					"- Use **searchMastraDocs** to search for specific information",
+					"- Use **getMastraExports** to see available APIs"
+				].join("\n");
+			}
+			const topicPath = path.join(docsPath, args.topic);
+			if (args.file) try {
+				const content = await fs.readFile(path.join(topicPath, args.file), "utf-8");
+				return `# ${args.package}/${args.topic}/${args.file}
+
+${content}
+
+## Next Steps
+
+- Use **getMastraExportDetails** to see API references for specific classes/functions mentioned
+- Use **searchMastraDocs** to find related topics
+- Use **getMastraExports** to explore available APIs`;
+			} catch {
+				return `File not found: ${args.topic}/${args.file}
+
+Run readMastraDocs with package="${args.package}" and topic="${args.topic}" (without file parameter) to see available files.`;
+			}
+			try {
+				const files = (await fs.readdir(topicPath, { withFileTypes: true })).filter((e) => e.isFile() && e.name.endsWith(".md")).sort();
+				if (files.length === 0) return `No markdown files in ${args.topic}/
+
+Run readMastraDocs with package="${args.package}" (without topic parameter) to see available topics.`;
+				const contents = [`# ${args.package} - ${args.topic}`, ""];
+				for (const file of files) {
+					const content = await fs.readFile(path.join(topicPath, file.name), "utf-8");
+					contents.push(`## ${file.name}`, "", content, "", "---", "");
+				}
+				contents.push("", "## Next Steps", "", "- Use **getMastraExportDetails** to see API references for specific classes/functions mentioned above", "- Use **searchMastraDocs** to find related information", "- Use **getMastraExports** to explore the complete API surface");
+				return contents.join("\n");
+			} catch {
+				return `Topic not found: ${args.topic}
+
+Run readMastraDocs with package="${args.package}" (without topic parameter) to see available topics.`;
+			}
+		}
+	},
+	searchMastraDocs: {
+		name: "searchMastraDocs",
+		description: `[📦 LOCAL PACKAGES] Search across all Mastra documentation to find specific information, patterns, or examples.
+
+    Use this when you need to:
+    - Find specific topics or concepts quickly (e.g., "memory processors", "tool composition")
+    - Locate examples of specific features or patterns
+    - Search for error messages or troubleshooting info
+    - Find mentions of specific APIs or configuration options
+    - Discover where a feature is documented
+
+    Returns: Relevant documentation excerpts with file paths, ranked by relevance.
+    Tip: Use specific terms for better results (e.g., "agent memory" vs "memory").`,
+		parameters: z.object({
+			query: z.string().describe("What to search for (case-insensitive, e.g., \"workflow steps\", \"vector store\", \"authentication\")"),
+			package: z.string().optional().describe("Optional: limit search to a specific package (e.g., \"@mastra/core\"). Omit to search all packages."),
+			maxResults: z.number().optional().default(10).describe("Optional: maximum number of results to return (default: 10)"),
+			projectPath: z.string().describe("Absolute path to your project root (we will search upward for node_modules)")
+		}),
+		execute: async (args) => {
+			logger.debug("Executing searchMastraEmbeddedDocs tool", { args });
+			const packages = args.package ? [args.package] : await getInstalledMastraPackages(args.projectPath);
+			if (packages.length === 0) return "No Mastra packages found.";
+			const queryLower = args.query.toLowerCase();
+			const results = [];
+			for (const pkg of packages) {
+				const packageInfo = await getPackageRootPath(pkg, args.projectPath);
+				if (!packageInfo) continue;
+				const docsPath = path.join(packageInfo.rootPath, "dist", "docs");
+				try {
+					const findFiles = async (dir) => {
+						const entries = await fs.readdir(dir, { withFileTypes: true });
+						const files = [];
+						for (const entry of entries) {
+							const fullPath = path.join(dir, entry.name);
+							if (entry.isDirectory()) files.push(...await findFiles(fullPath));
+							else if (entry.name.endsWith(".md")) files.push(fullPath);
+						}
+						return files;
+					};
+					for (const file of await findFiles(docsPath)) {
+						const content = await fs.readFile(file, "utf-8");
+						if (!content.toLowerCase().includes(queryLower)) continue;
+						const lines = content.split("\n");
+						for (let i = 0; i < lines.length; i++) if (lines[i]?.toLowerCase().includes(queryLower)) {
+							const start = Math.max(0, i - 1);
+							const end = Math.min(lines.length, i + 3);
+							const excerpt = lines.slice(start, end).join("\n").slice(0, 300);
+							const occurrences = content.toLowerCase().split(queryLower).length - 1;
+							results.push({
+								pkg,
+								file: path.relative(docsPath, file),
+								excerpt,
+								score: occurrences
+							});
+							break;
+						}
+					}
+				} catch {}
+			}
+			results.sort((a, b) => b.score - a.score);
+			const topResults = results.slice(0, args.maxResults || 10);
+			if (topResults.length === 0) return `No results found for "${args.query}".
+
+Try:
+- Using different search terms
+- Searching for broader topics
+- Using **listMastraPackages** to see available packages
+- Using **readMastraDocs** to browse documentation by topic`;
+			return [
+				`# Search Results: "${args.query}"`,
+				"",
+				`Found ${results.length} result(s), showing top ${topResults.length}:`,
+				"",
+				...topResults.map((r, i) => `## ${i + 1}. ${r.pkg} - ${r.file}\n\n\`\`\`\n${r.excerpt}\n\`\`\`\n`),
+				"",
+				"## Next Steps",
+				"",
+				"- Use **readMastraDocs** with a package and topic to read full documentation",
+				"- Use **getMastraExportDetails** to see API details for mentioned classes/functions",
+				"- Refine your search with more specific terms if needed"
+			].join("\n");
+		}
+	}
+};
+//#endregion
+//#region src/tools/migration.ts
+const migrationsBaseDir = fromPackageRoot(".docs/guides/migrations");
+function parseSections(content) {
+	const lines = content.split("\n");
+	const sections = [];
+	let currentSection = null;
+	let inFrontmatter = false;
+	let contentStarted = false;
+	for (let index = 0; index < lines.length; index++) {
+		const line = lines[index];
+		if (index === 0 && line === "---") {
+			inFrontmatter = true;
+			continue;
+		}
+		if (inFrontmatter && line === "---") {
+			inFrontmatter = false;
+			continue;
+		}
+		if (inFrontmatter) continue;
+		contentStarted = true;
+		const headingMatch = line?.match(/^(#{2,3})\s+(.+)$/);
+		if (headingMatch && contentStarted) {
+			if (currentSection) {
+				currentSection.endLine = index - 1;
+				sections.push(currentSection);
+			}
+			const level = headingMatch[1]?.length ?? 0;
+			currentSection = {
+				title: headingMatch[2] || "Untitled",
+				level,
+				content: line + "\n",
+				startLine: index,
+				endLine: index
+			};
+		} else if (currentSection) currentSection.content += line + "\n";
+	}
+	if (currentSection) {
+		currentSection.endLine = lines.length - 1;
+		sections.push(currentSection);
+	}
+	return sections;
+}
+async function discoverMigrations(baseDir, relativePath = "") {
+	const migrations = [];
+	const fullPath = path.join(baseDir, relativePath);
+	try {
+		const entries = await fs.readdir(fullPath, { withFileTypes: true });
+		for (const entry of entries) {
+			const entryRelativePath = path.join(relativePath, entry.name);
+			if (entry.isDirectory()) {
+				migrations.push({
+					path: entryRelativePath,
+					type: "directory"
+				});
+				const subMigrations = await discoverMigrations(baseDir, entryRelativePath);
+				migrations.push(...subMigrations);
+			} else if (entry.isFile() && entry.name.endsWith(".md")) {
+				const cleanName = entry.name.replace(/\.md$/, "");
+				migrations.push({
+					path: relativePath ? path.join(relativePath, cleanName) : cleanName,
+					type: "file"
+				});
+			}
+		}
+	} catch (error) {
+		logger.error("Failed to discover migrations", {
+			path: fullPath,
+			error
+		});
+	}
+	return migrations;
+}
+async function listDirectoryContents(dirPath = "") {
+	try {
+		const fullPath = path.join(migrationsBaseDir, dirPath);
+		const resolvedPath = path.resolve(fullPath);
+		const resolvedBaseDir = path.resolve(migrationsBaseDir);
+		if (!resolvedPath.startsWith(resolvedBaseDir)) return "Invalid path";
+		const entries = await fs.readdir(fullPath, { withFileTypes: true });
+		const directories = [];
+		const files = [];
+		for (const entry of entries) if (entry.isDirectory()) directories.push(entry.name);
+		else if (entry.isFile() && entry.name.endsWith(".md")) files.push(entry.name.replace(/\.md$/, ""));
+		const output = [];
+		const currentPath = dirPath || "migrations";
+		output.push(`# ${currentPath}`);
+		output.push("");
+		if (directories.length > 0) {
+			output.push("**Directories:**");
+			directories.sort().forEach((dir) => {
+				const nextPath = dirPath ? `${dirPath}/${dir}` : dir;
+				output.push(`- **${dir}/** - Explore with \`{ path: "${nextPath}/" }\``);
+			});
+			output.push("");
+		}
+		if (files.length > 0) {
+			output.push("**Migration Guides:**");
+			files.sort().forEach((file) => {
+				const filePath = dirPath ? `${dirPath}/${file}` : file;
+				output.push(`- **${file}** - Get with \`{ path: "${filePath}" }\``);
+			});
+			output.push("");
+		}
+		if (directories.length === 0 && files.length === 0) output.push("No migrations found in this directory.");
+		output.push("---");
+		output.push("");
+		output.push("**Actions:**");
+		output.push("- Navigate to a directory by setting `path` to directory name with trailing `/`");
+		output.push("- View a migration guide by setting `path` to the guide name");
+		output.push("- List sections in a guide with `listSections: true`");
+		output.push("- Search all guides with `queryKeywords`");
+		return output.join("\n");
+	} catch (error) {
+		if (error.code === "ENOENT") return `Directory "${dirPath}" not found. Use \`{}\` to see top-level migrations.`;
+		throw error;
+	}
+}
+async function readMigrationContent(migrationPath) {
+	try {
+		const cleanPath = migrationPath.replace(/\.(mdx|md)$/, "");
+		const filePath = path.join(migrationsBaseDir, cleanPath + ".md");
+		const resolvedPath = path.resolve(filePath);
+		const resolvedBaseDir = path.resolve(migrationsBaseDir);
+		if (!resolvedPath.startsWith(resolvedBaseDir)) {
+			logger.error("Path traversal attempt detected");
+			return null;
+		}
+		return await fs.readFile(filePath, "utf-8");
+	} catch (error) {
+		logger.error("Failed to read migration", {
+			path: migrationPath,
+			error
+		});
+		return null;
+	}
+}
+async function getSectionHeaders(migrationPath) {
+	const content = await readMigrationContent(migrationPath);
+	if (!content) return [];
+	return parseSections(content).map((s) => ({
+		title: s.title,
+		level: s.level
+	}));
+}
+async function getSections(migrationPath, sectionTitles) {
+	const content = await readMigrationContent(migrationPath);
+	if (!content) return `Migration "${migrationPath}" not found.\n\nAvailable migrations:\n${(await discoverMigrations(migrationsBaseDir)).filter((m) => m.type === "file").map((m) => `- ${m.path}`).join("\n")}`;
+	if (!sectionTitles || sectionTitles.length === 0) return content;
+	const sections = parseSections(content);
+	const requestedSections = sections.filter((s) => sectionTitles.some((title) => s.title.toLowerCase().includes(title.toLowerCase())));
+	if (requestedSections.length === 0) return `Requested sections not found in "${migrationPath}".\n\nAvailable sections:\n${sections.map((s) => `${"#".repeat(s.level)} ${s.title}`).join("\n")}`;
+	return requestedSections.map((s) => s.content).join("\n---\n\n");
+}
+const migrationFiles = (await discoverMigrations(migrationsBaseDir)).filter((m) => m.type === "file");
+const migrationsListing = migrationFiles.length > 0 ? "\n\nExample migration paths:\n" + migrationFiles.slice(0, 5).map((m) => `- ${m.path}`).join("\n") + "\n..." : "\n\nNo migrations available. Run the documentation preparation script first.";
+const migrationTool = {
+	name: "mastraMigration",
+	description: `[🌐 REMOTE] Get migration guidance for Mastra version upgrades and breaking changes.
+
+This tool works like a file browser - navigate through directories to find migration guides:
+
+**Step 1: List top-level migrations**
+- Call with no parameters: \`{}\`
+- Shows all top-level migration guides and directories
+
+**Step 2: Navigate into a directory**
+- Add trailing slash to explore: \`{ path: "upgrade-to-v1/" }\`
+- Lists all migration guides in that directory
+
+**Step 3: View a migration guide**
+- Without trailing slash: \`{ path: "upgrade-to-v1/agent" }\`
+- Returns the full migration guide content
+
+**Step 4: Explore guide sections (optional)**
+- List sections: \`{ path: "upgrade-to-v1/agent", listSections: true }\`
+- Get specific sections: \`{ path: "upgrade-to-v1/agent", sections: ["Voice methods"] }\`
+
+**Alternative: Search by keywords**
+- \`{ queryKeywords: ["RuntimeContext", "pagination"] }\`
+
+**Examples:**
+1. List top-level: \`{}\`
+2. Navigate to upgrade-to-v1: \`{ path: "upgrade-to-v1/" }\`
+3. Get agent guide: \`{ path: "upgrade-to-v1/agent" }\`
+4. List guide sections: \`{ path: "upgrade-to-v1/agent", listSections: true }\`
+5. Search: \`{ queryKeywords: ["RuntimeContext"] }\`
+
+**Tip:** Paths ending with \`/\` list directory contents. Paths without \`/\` fetch the migration guide.`,
+	parameters: z.object({
+		path: z.string().optional().describe("Path to the migration guide (e.g., \"upgrade-to-v1/agent\", \"agentnetwork\"). If not provided, lists all available migrations." + migrationsListing),
+		sections: z.array(z.string()).optional().describe("Specific section titles to fetch from the migration guide. If not provided, returns the entire guide. Use this after exploring section headers."),
+		listSections: z.boolean().optional().describe("Set to true to list all section headers in a migration guide without fetching full content."),
+		queryKeywords: z.array(z.string()).optional().describe("Keywords to search across all migration guides. Use this to find guides related to specific topics.")
+	}),
+	execute: async (args) => {
+		logger.debug("Executing mastraMigration tool", { args });
+		try {
+			if (args.queryKeywords && args.queryKeywords.length > 0) return [
+				"# Migration Guide Search Results",
+				"",
+				await getMatchingPaths("", args.queryKeywords, migrationsBaseDir) || "No migration guides found matching your keywords.",
+				"",
+				"---",
+				"",
+				"To see all available migrations, call with no parameters."
+			].join("\n");
+			if (args.path) {
+				if (args.path.endsWith("/")) return await listDirectoryContents(args.path.slice(0, -1));
+				if (args.listSections) {
+					const headers = await getSectionHeaders(args.path);
+					if (headers.length === 0) return await listDirectoryContents();
+					return [
+						`# ${args.path} - Section Headers`,
+						"",
+						"Available sections in this migration guide:",
+						"",
+						...headers.map((h) => `${"#".repeat(h.level)} ${h.title}`),
+						"",
+						"---",
+						"",
+						"To get specific sections, provide their titles in the \"sections\" parameter."
+					].join("\n");
+				}
+				const content = await getSections(args.path, args.sections);
+				return `# ${args.path}\n\n${content}`;
+			}
+			return await listDirectoryContents();
+		} catch (error) {
+			logger.error("Failed to execute mastraMigration tool", error);
+			throw error;
+		}
+	}
+};
+//#endregion
+//#region src/index.ts
+let server;
+server = new MCPServer({
+	name: "Mastra Documentation Server",
+	version: JSON.parse(await fs.readFile(fromPackageRoot(`package.json`), "utf8")).version,
+	tools: {
+		mastraDocs: docsTool,
+		mastraMigration: migrationTool,
+		startMastraCourse,
+		getMastraCourseStatus,
+		startMastraCourseLesson,
+		nextMastraCourseStep,
+		clearMastraCourseHistory,
+		...embeddedDocsTools
+	},
+	prompts: migrationPromptMessages
+});
+Object.assign(logger, createLogger(server));
+async function runServer() {
+	try {
+		await server.startStdio();
+		logger.info("Started Mastra Docs MCP Server");
+	} 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 };
+
+//# sourceMappingURL=src-BZcgzbk9.js.map