@mastra/mcp-docs-server 1.0.0-beta.9 → 1.0.1

package/dist/stdio.js

@@ -4,12 +4,47 @@ import * as fs from 'fs';
 import { existsSync, mkdirSync } from 'fs';
 import * as os2 from 'os';
 import os2__default from 'os';
-import * as path6 from 'path';
-import path6__default from 'path';
+import * as path5 from 'path';
+import path5__default from 'path';
 import fs3 from 'fs/promises';
 import { MCPServer } from '@mastra/mcp';
 import { z } from 'zod';
+import { getPackageInfo } from 'local-pkg';
 
+var LOG_LEVEL_PRIORITY = {
+  debug: 0,
+  info: 1,
+  warn: 2,
+  error: 3,
+  none: 4
+  // none = disable all logs
+};
+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";
+  }
+}
+var currentLogLevel = "debug";
+function setLogLevel(level) {
+  currentLogLevel = level;
+}
+function shouldLog(level) {
+  const mappedLevel = mapToLogLevel(level);
+  return LOG_LEVEL_PRIORITY[mappedLevel] >= LOG_LEVEL_PRIORITY[currentLogLevel];
+}
 var writeErrorLog = (message, data) => {
   const now = /* @__PURE__ */ new Date();
   const timestamp = now.toISOString();
@@ -20,9 +55,9 @@ var writeErrorLog = (message, data) => {
     ...data ? typeof data === "object" ? data : { data } : {}
   };
   try {
-    const cacheDir = path6.join(os2.homedir(), ".cache", "mastra", "mcp-docs-server-logs");
+    const cacheDir = path5.join(os2.homedir(), ".cache", "mastra", "mcp-docs-server-logs");
     fs.mkdirSync(cacheDir, { recursive: true });
-    const logFile = path6.join(cacheDir, `${hourTimestamp}.log`);
+    const logFile = path5.join(cacheDir, `${hourTimestamp}.log`);
     fs.appendFileSync(logFile, JSON.stringify(logMessage) + "\n", "utf8");
   } catch (err) {
     console.error("Failed to write to log file:", err);
@@ -31,6 +66,7 @@ var writeErrorLog = (message, data) => {
 function createLogger(server2) {
   const sendLog = async (level, message, data) => {
     if (!server2) return;
+    if (!shouldLog(level)) return;
     try {
       const sdkServer = server2.getServer();
       if (!sdkServer) return;
@@ -155,7 +191,7 @@ function getUpgradeToV1Messages(area) {
    - If "${area}" doesn't end with 's', try adding 's' (e.g., "agent" \u2192 "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 ":::tip[Codemod]" in the docs. Run the codemods with "npx @mastra/codemod@beta <codemod-name> <path>" to automate all those changes. Afterwards, help me with any remaining manual changes needed.`
+6. After you find the guide, collect all the codemod calls to run to codemods. These callouts are marked with ":::tip[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.`
         }
       }
     ];
@@ -171,7 +207,7 @@ function getUpgradeToV1Messages(area) {
 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 ":::tip[Codemod]" in the docs. Run the codemods with "npx @mastra/codemod@beta v1" to automate all those changes. Afterwards, help me with any remaining manual changes needed.
+4. After the areas are confirmed, check the migration guides for callouts to codemods. These callouts are marked with ":::tip[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.`
       }
@@ -277,7 +313,7 @@ var blogInputSchema = z.object({
 });
 var blogTool = {
   name: "mastraBlog",
-  description: "Get Mastra.ai blog content. Without a URL, returns a list of all blog posts. With a URL, returns the specific blog post content in markdown format. The blog contains changelog posts as well as announcements and posts about Mastra features and AI news",
+  description: "[\u{1F310} REMOTE] Get Mastra.ai blog content. Without a URL, returns a list of all blog posts. With a URL, returns the specific blog post content in markdown format. The blog contains changelog posts as well as announcements and posts about Mastra features and AI news",
   parameters: blogInputSchema,
   execute: async (args) => {
     void logger.debug("Executing mastraBlog tool", { url: args.url });
@@ -316,7 +352,7 @@ async function listPackageChangelogs() {
 }
 async function readPackageChangelog(filename) {
   const encodedName = encodePackageName(filename.replace(".md", ""));
-  const filePath = path6__default.join(changelogsDir, `${encodedName}.md`);
+  const filePath = path5__default.join(changelogsDir, `${encodedName}.md`);
   void logger.debug(`Reading changelog: ${filename}`);
   try {
     return await fs3.readFile(filePath, "utf-8");
@@ -336,7 +372,7 @@ var changesInputSchema = z.object({
 });
 var changesTool = {
   name: "mastraChanges",
-  description: `Get changelog information for Mastra.ai packages. ${packagesListing}`,
+  description: `[\u{1F310} REMOTE] Get changelog information for Mastra.ai packages. ${packagesListing}`,
   parameters: changesInputSchema,
   execute: async (args) => {
     void logger.debug("Executing mastraChanges tool", { package: args.package });
@@ -407,11 +443,11 @@ Here is the content for this step: <StepContent>${content}</StepContent>`;
 When you're ready to continue, use the \`nextMastraCourseStep\` tool to move to the next step.`;
 }
 async function getDeviceIdPath() {
-  const cacheDir = path6__default.join(os2__default.homedir(), ".cache", "mastra");
+  const cacheDir = path5__default.join(os2__default.homedir(), ".cache", "mastra");
   if (!existsSync(cacheDir)) {
     mkdirSync(cacheDir, { recursive: true });
   }
-  return path6__default.join(cacheDir, ".device_id");
+  return path5__default.join(cacheDir, ".device_id");
 }
 async function getDeviceCredentials() {
   try {
@@ -461,13 +497,13 @@ async function readCourseStep(lessonName, stepName, _isFirstStep = false) {
   if (!lessonDir) {
     throw new Error(`Lesson "${lessonName}" not found.`);
   }
-  const lessonPath = path6__default.join(courseDir, lessonDir);
+  const lessonPath = path5__default.join(courseDir, lessonDir);
   const files = await fs3.readdir(lessonPath);
   const stepFile = files.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 = path6__default.join(courseDir, lessonDir, stepFile);
+  const filePath = path5__default.join(courseDir, lessonDir, stepFile);
   try {
     const content = await fs3.readFile(filePath, "utf-8");
     return wrapContentInPrompt(content);
@@ -513,11 +549,11 @@ async function saveCourseState(state, deviceId) {
   }
 }
 async function getCourseStatePath() {
-  const stateDirPath = path6__default.join(os2__default.homedir(), ".cache", "mastra", "course");
+  const stateDirPath = path5__default.join(os2__default.homedir(), ".cache", "mastra", "course");
   if (!existsSync(stateDirPath)) {
     mkdirSync(stateDirPath, { recursive: true });
   }
-  return path6__default.join(stateDirPath, "state.json");
+  return path5__default.join(stateDirPath, "state.json");
 }
 async function loadCourseState() {
   const statePath = await getCourseStatePath();
@@ -535,7 +571,7 @@ async function scanCourseContent() {
   const lessonDirs = await fs3.readdir(courseDir);
   const lessons = await Promise.all(
     lessonDirs.filter((dir) => !dir.startsWith(".")).sort((a, b) => a.localeCompare(b)).map(async (lessonDir) => {
-      const lessonPath = path6__default.join(courseDir, lessonDir);
+      const lessonPath = path5__default.join(courseDir, lessonDir);
       const lessonStats = await fs3.stat(lessonPath);
       if (!lessonStats.isDirectory()) return null;
       const lessonName = lessonDir.replace(/^\d+-/, "");
@@ -605,7 +641,7 @@ async function mergeCourseStates(currentState, newState) {
 }
 var startMastraCourse = {
   name: "startMastraCourse",
-  description: "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.",
+  description: "[\u{1F393} 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. ")
   }),
@@ -702,7 +738,7 @@ When you've completed this step, use the \`nextMastraCourseStep\` tool to contin
 };
 var getMastraCourseStatus = {
   name: "getMastraCourseStatus",
-  description: "Gets the current status of the Mastra Course, including which lessons and steps have been completed",
+  description: "[\u{1F393} COURSE] Gets the current status of the Mastra Course, including which lessons and steps have been completed",
   parameters: z.object({}),
   execute: async (_args) => {
     try {
@@ -779,7 +815,7 @@ Course status url: https://mastra.ai/course/${deviceId}`;
 };
 var startMastraCourseLesson = {
   name: "startMastraCourseLesson",
-  description: "Starts a specific lesson in the Mastra Course. If the lesson has been started before, it will resume from the first incomplete step",
+  description: "[\u{1F393} 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 {
@@ -822,7 +858,7 @@ When you've completed this step, use the \`nextMastraCourseStep\` tool to contin
 };
 var nextMastraCourseStep = {
   name: "nextMastraCourseStep",
-  description: "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",
+  description: "[\u{1F393} 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 {
@@ -893,7 +929,7 @@ If you'd like to review any lesson, use the \`startMastraCourseLesson\` tool wit
 };
 var clearMastraCourseHistory = {
   name: "clearMastraCourseHistory",
-  description: "Clears all Mastra Course progress history and starts over from the beginning. This action cannot be undone",
+  description: "[\u{1F393} COURSE] Clears all Mastra Course progress history and starts over from the beginning. This action cannot be undone",
   parameters: _confirmationSchema,
   execute: async (args) => {
     try {
@@ -939,8 +975,8 @@ async function listDirContents(dirPath) {
   }
 }
 async function readMdxContent(docPath, queryKeywords) {
-  const fullPath = path6__default.resolve(path6__default.join(docsBaseDir, docPath));
-  if (!fullPath.startsWith(path6__default.resolve(docsBaseDir))) {
+  const fullPath = path5__default.resolve(path5__default.join(docsBaseDir, docPath));
+  if (!fullPath.startsWith(path5__default.resolve(docsBaseDir))) {
     void logger.error(`Path traversal attempt detected`);
     return { found: false, isSecurityViolation: true };
   }
@@ -965,7 +1001,7 @@ async function readMdxContent(docPath, queryKeywords) {
       ].join("\n");
       let fileContents = "";
       for (const file of files) {
-        const filePath = path6__default.join(fullPath, file);
+        const filePath = path5__default.join(fullPath, file);
         const content2 = await fs3.readFile(filePath, "utf-8");
         fileContents += `
 
@@ -993,7 +1029,7 @@ async function findNearestDirectory(docPath, availablePaths2) {
   while (parts.length > 0) {
     const testPath = parts.join("/");
     try {
-      const fullPath = path6__default.join(docsBaseDir, testPath);
+      const fullPath = path5__default.join(docsBaseDir, testPath);
       const stats = await fs3.stat(fullPath);
       if (stats.isDirectory()) {
         const { dirs, files } = await listDirContents(fullPath);
@@ -1019,7 +1055,7 @@ async function getAvailablePaths() {
   const { dirs, files } = await listDirContents(docsBaseDir);
   let referenceDirs = [];
   if (dirs.includes("reference/")) {
-    const { dirs: refDirs } = await listDirContents(path6__default.join(docsBaseDir, "reference"));
+    const { dirs: refDirs } = await listDirContents(path5__default.join(docsBaseDir, "reference"));
     referenceDirs = refDirs.map((d) => `reference/${d}`);
   }
   return [
@@ -1046,7 +1082,7 @@ ${availablePaths}`),
 });
 var docsTool = {
   name: "mastraDocs",
-  description: `Get Mastra.ai documentation. 
+  description: `[\u{1F310} REMOTE] Get Mastra.ai 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. 
@@ -1067,34 +1103,34 @@ var docsTool = {
     try {
       const queryKeywords = args.queryKeywords ?? [];
       const results = await Promise.all(
-        args.paths.map(async (path7) => {
+        args.paths.map(async (path8) => {
           try {
-            const result = await readMdxContent(path7, queryKeywords);
+            const result = await readMdxContent(path8, queryKeywords);
             if (result.found) {
               return {
-                path: path7,
+                path: path8,
                 content: result.content,
                 error: null
               };
             }
             if (result.isSecurityViolation) {
               return {
-                path: path7,
+                path: path8,
                 content: null,
                 error: "Invalid path"
               };
             }
-            const directorySuggestions = await findNearestDirectory(path7, availablePaths);
-            const contentBasedSuggestions = await getMatchingPaths(path7, queryKeywords, docsBaseDir);
+            const directorySuggestions = await findNearestDirectory(path8, availablePaths);
+            const contentBasedSuggestions = await getMatchingPaths(path8, queryKeywords, docsBaseDir);
             return {
-              path: path7,
+              path: path8,
               content: null,
               error: [directorySuggestions, contentBasedSuggestions].join("\n\n")
             };
           } catch (error) {
-            void logger.warning(`Failed to read content for path: ${path7}`, error);
+            void logger.warning(`Failed to read content for path: ${path8}`, error);
             return {
-              path: path7,
+              path: path8,
               content: null,
               error: error instanceof Error ? error.message : "Unknown error"
             };
@@ -1124,6 +1160,647 @@ ${result.content}
     }
   }
 };
+var packageCache = /* @__PURE__ */ new Map();
+var sourceMapCache = /* @__PURE__ */ new Map();
+var packageInfoCache = /* @__PURE__ */ new Map();
+var 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: [path5__default.join(projectPath, "node_modules")]
+    });
+    if (info?.rootPath) {
+      const result = { rootPath: info.rootPath, version: info.version || "unknown" };
+      packageInfoCache.set(cacheKey, result);
+      void logger.debug("Resolved package with local-pkg", { packageName, projectPath, ...result });
+      return result;
+    }
+  } catch (err) {
+    void 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)) {
+    void logger.debug("Using cached package list", { count: packageCache.get(cacheKey).length });
+    return packageCache.get(cacheKey);
+  }
+  void 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 = path5__default.join(packageInfo.rootPath, "dist", "docs");
+      try {
+        const stats = await fs3.stat(docsPath);
+        if (stats.isDirectory()) {
+          packages.push(packageName);
+          void 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);
+  void 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 = path5__default.join(packageInfo.rootPath, "dist", "docs", "SOURCE_MAP.json");
+    const content = await fs3.readFile(sourceMapPath, "utf-8");
+    const sourceMap = JSON.parse(content);
+    sourceMapCache.set(cacheKey, sourceMap);
+    return sourceMap;
+  } catch {
+    sourceMapCache.set(cacheKey, null);
+    return null;
+  }
+}
+var getMastraHelpTool = {
+  name: "getMastraHelp",
+  description: `\u{1F680} START HERE - Complete guide to Mastra documentation tools.
+
+    This MCP server provides TWO documentation sources:
+
+    ## \u{1F4E6} LOCAL PACKAGE DOCS (Recommended for Development)
+    SOURCE: Your installed @mastra packages in node_modules
+    VERSION: Matches your installed code exactly
+
+    ADVANTAGES:
+    - \u2705 Version-matched to your code
+    - \u2705 Complete TypeScript type definitions
+    - \u2705 Works offline
+    - \u2705 SOURCE_MAP.json with exact exports
+
+    TOOLS: listMastraPackages, getMastraExports, getMastraExportDetails, readMastraDocs, searchMastraDocs
+    USE WHEN: Writing code, implementing features, checking APIs, debugging
+
+    ## \u{1F310} REMOTE WEBSITE DOCS (For Latest Info & Learning)
+    SOURCE: mastra.ai website
+    VERSION: Latest published documentation
+
+    ADVANTAGES:
+    - \u2705 Always up-to-date
+    - \u2705 Blog posts and announcements
+    - \u2705 Migration guides
+    - \u2705 Curated examples
+
+    TOOLS: mastraDocs, mastraBlog, mastraExamples, mastraChanges, mastraMigration
+    USE WHEN: Learning concepts, checking latest features, migration help
+
+    ## \u{1F393} INTERACTIVE COURSE
+    TOOLS: startMastraCourse, getMastraCourseStatus, etc.
+    USE WHEN: User wants guided learning experience
+
+    ---
+
+    RECOMMENDED WORKFLOW:
+    1. For coding: listMastraPackages \u2192 getMastraExports \u2192 getMastraExportDetails
+    2. For learning: mastraDocs
+    3. Version mismatch: mastraChanges \u2192 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) => {
+    void 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:
+
+---
+
+## \u{1F4E6} 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 \u2192 see what's installed
+2. getMastraExports \u2192 explore package API
+3. getMastraExportDetails \u2192 get type definitions
+4. readMastraDocs \u2192 learn concepts
+5. searchMastraDocs \u2192 find specific info
+
+---
+
+## \u{1F310} 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
+
+\u26A0\uFE0F **Version Note**: Remote docs show latest published version. For API reference matching YOUR code, use LOCAL tools above.
+
+---
+
+## \u{1F393} 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
+   \u2192 Start with listMastraPackages
+
+**If you're learning**: Use REMOTE tools
+   \u2192 Start with mastraDocs
+
+**If version differs**: Check changes
+   \u2192 mastraChanges \u2192 mastraMigration`;
+  }
+};
+var listInstalledPackagesTool = {
+  name: "listMastraPackages",
+  description: `[\u{1F4E6} 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) => {
+    void 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");
+  }
+};
+var readSourceMapTool = {
+  name: "getMastraExports",
+  description: `[\u{1F4E6} 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) => {
+    void 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");
+  }
+};
+var findExportTool = {
+  name: "getMastraExportDetails",
+  description: `[\u{1F4E6} 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) => {
+    void 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 = path5__default.join(packageInfo.rootPath, exportInfo.types);
+        const typesContent = await fs3.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 = path5__default.join(packageInfo.rootPath, exportInfo.implementation);
+        const implContent = await fs3.readFile(implPath, "utf-8");
+        const lines = implContent.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");
+  }
+};
+var readEmbeddedDocsTool = {
+  name: "readMastraDocs",
+  description: `[\u{1F4E6} 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) => {
+    void 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 = path5__default.join(packageInfo.rootPath, "dist", "docs");
+    try {
+      await fs3.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 fs3.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 = path5__default.join(docsPath, args.topic);
+    if (args.file) {
+      try {
+        const content = await fs3.readFile(path5__default.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 entries = await fs3.readdir(topicPath, { withFileTypes: true });
+      const files = entries.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 fs3.readFile(path5__default.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.`;
+    }
+  }
+};
+var searchEmbeddedDocsTool = {
+  name: "searchMastraDocs",
+  description: `[\u{1F4E6} 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) => {
+    void 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 = path5__default.join(packageInfo.rootPath, "dist", "docs");
+      try {
+        const findFiles = async (dir) => {
+          const entries = await fs3.readdir(dir, { withFileTypes: true });
+          const files = [];
+          for (const entry of entries) {
+            const fullPath = path5__default.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 fs3.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 contentLower = content.toLowerCase();
+              const occurrences = contentLower.split(queryLower).length - 1;
+              results.push({
+                pkg,
+                file: path5__default.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}
+
+\`\`\`
+${r.excerpt}
+\`\`\`
+`),
+      "",
+      "## 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");
+  }
+};
+var embeddedDocsTools = {
+  getMastraHelp: getMastraHelpTool,
+  listMastraPackages: listInstalledPackagesTool,
+  getMastraExports: readSourceMapTool,
+  getMastraExportDetails: findExportTool,
+  readMastraDocs: readEmbeddedDocsTool,
+  searchMastraDocs: searchEmbeddedDocsTool
+};
 var examplesDir = fromPackageRoot(".docs/organized/code-examples");
 async function listCodeExamples() {
   void logger.debug("Listing code examples");
@@ -1138,7 +1815,7 @@ async function listCodeExamples() {
   }
 }
 async function readCodeExample(filename, queryKeywords) {
-  const filePath = path6__default.join(examplesDir, filename);
+  const filePath = path5__default.join(examplesDir, filename);
   void logger.debug(`Reading example: ${filename}`);
   try {
     const content = await fs3.readFile(filePath, "utf-8");
@@ -1167,7 +1844,7 @@ var examplesInputSchema = z.object({
 });
 var examplesTool = {
   name: "mastraExamples",
-  description: `Get code examples from the Mastra.ai examples directory. 
+  description: `[\u{1F310} REMOTE] Get code examples from the Mastra.ai examples directory. 
     Without a specific example name, lists all available examples. 
     With an example name, returns the full source code of that example.
     You can also use keywords from the user query to find relevant examples, but prioritize example names.`,
@@ -1233,11 +1910,11 @@ function parseMdxSections(content) {
 }
 async function discoverMigrations(baseDir, relativePath = "") {
   const migrations = [];
-  const fullPath = path6__default.join(baseDir, relativePath);
+  const fullPath = path5__default.join(baseDir, relativePath);
   try {
     const entries = await fs3.readdir(fullPath, { withFileTypes: true });
     for (const entry of entries) {
-      const entryRelativePath = path6__default.join(relativePath, entry.name);
+      const entryRelativePath = path5__default.join(relativePath, entry.name);
       if (entry.isDirectory()) {
         migrations.push({
           path: entryRelativePath,
@@ -1247,7 +1924,7 @@ async function discoverMigrations(baseDir, relativePath = "") {
         migrations.push(...subMigrations);
       } else if (entry.isFile() && entry.name.endsWith(".mdx") && entry.name !== "_template.mdx") {
         migrations.push({
-          path: path6__default.join(relativePath, entry.name.replace(".mdx", "")),
+          path: path5__default.join(relativePath, entry.name.replace(".mdx", "")),
           type: "file"
         });
       }
@@ -1259,9 +1936,9 @@ async function discoverMigrations(baseDir, relativePath = "") {
 }
 async function listDirectoryContents(dirPath = "") {
   try {
-    const fullPath = path6__default.join(migrationsBaseDir, dirPath);
-    const resolvedPath = path6__default.resolve(fullPath);
-    const resolvedBaseDir = path6__default.resolve(migrationsBaseDir);
+    const fullPath = path5__default.join(migrationsBaseDir, dirPath);
+    const resolvedPath = path5__default.resolve(fullPath);
+    const resolvedBaseDir = path5__default.resolve(migrationsBaseDir);
     if (!resolvedPath.startsWith(resolvedBaseDir)) {
       return "Invalid path";
     }
@@ -1316,9 +1993,9 @@ async function listDirectoryContents(dirPath = "") {
 async function readMigrationContent(migrationPath) {
   try {
     let filename = migrationPath.endsWith(".mdx") ? migrationPath : `${migrationPath}.mdx`;
-    let filePath = path6__default.join(migrationsBaseDir, filename);
-    const resolvedPath = path6__default.resolve(filePath);
-    const resolvedBaseDir = path6__default.resolve(migrationsBaseDir);
+    let filePath = path5__default.join(migrationsBaseDir, filename);
+    const resolvedPath = path5__default.resolve(filePath);
+    const resolvedBaseDir = path5__default.resolve(migrationsBaseDir);
     if (!resolvedPath.startsWith(resolvedBaseDir)) {
       void logger.error("Path traversal attempt detected");
       return null;
@@ -1377,7 +2054,7 @@ var migrationInputSchema = z.object({
 });
 var migrationTool = {
   name: "mastraMigration",
-  description: `Get migration guidance for Mastra version upgrades and breaking changes.
+  description: `[\u{1F310} 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:
 
@@ -1483,7 +2160,9 @@ server = new MCPServer({
     getMastraCourseStatus,
     startMastraCourseLesson,
     nextMastraCourseStep,
-    clearMastraCourseHistory
+    clearMastraCourseHistory,
+    // Embedded docs tools for reading docs from installed packages
+    ...embeddedDocsTools
   },
   prompts: migrationPromptMessages
 });
@@ -1499,6 +2178,24 @@ async function runServer() {
 }
 
 // src/stdio.ts
+function parseLogLevel() {
+  const args = process.argv.slice(2);
+  const logLevelIndex = args.indexOf("--log-level");
+  if (logLevelIndex === -1 || logLevelIndex === args.length - 1) {
+    return void 0;
+  }
+  const level = args[logLevelIndex + 1];
+  const validLevels = ["debug", "info", "warn", "error", "none"];
+  if (validLevels.includes(level)) {
+    return level;
+  }
+  console.error(`Invalid log level: ${level}. Valid levels: ${validLevels.join(", ")}`);
+  return void 0;
+}
+var logLevel = parseLogLevel();
+if (logLevel) {
+  setLogLevel(logLevel);
+}
 runServer().catch((error) => {
   const errorMessage = "Fatal error running server";
   console.error(errorMessage, error);