@mastra/mcp-docs-server 0.13.1-alpha.0 → 0.13.1

package/dist/{chunk-QWIXFGFR.js → chunk-P5AHYMUI.js}

@@ -1,8 +1,9 @@
+import fs2 from 'fs/promises';
 import path4, { dirname } from 'path';
 import { fileURLToPath } from 'url';
-import fs from 'fs/promises';
 
 // src/utils.ts
+var mdxFileCache = /* @__PURE__ */ new Map();
 var __dirname = dirname(fileURLToPath(import.meta.url));
 function fromRepoRoot(relative) {
   return path4.resolve(__dirname, `../../../`, relative);
@@ -11,22 +12,127 @@ function fromPackageRoot(relative) {
   return path4.resolve(__dirname, `../`, relative);
 }
 var log = console.error;
+async function* walkMdxFiles(dir) {
+  if (mdxFileCache.has(dir)) {
+    for (const file of mdxFileCache.get(dir)) yield file;
+    return;
+  }
+  const filesInDir = [];
+  const entries = await fs2.readdir(dir, { withFileTypes: true });
+  for (const entry of entries) {
+    const fullPath = path4.join(dir, entry.name);
+    if (entry.isDirectory()) {
+      for await (const file of walkMdxFiles(fullPath)) {
+        filesInDir.push(file);
+        yield file;
+      }
+    } else if (entry.isFile() && entry.name.endsWith(".mdx")) {
+      filesInDir.push(fullPath);
+      yield fullPath;
+    }
+  }
+  mdxFileCache.set(dir, filesInDir);
+}
+async function searchDocumentContent(keywords, baseDir) {
+  if (keywords.length === 0) return [];
+  const fileScores = /* @__PURE__ */ new Map();
+  for await (const filePath of walkMdxFiles(baseDir)) {
+    let content;
+    try {
+      content = await fs2.readFile(filePath, "utf-8");
+    } catch {
+      continue;
+    }
+    const lines = content.split("\n");
+    lines.forEach((lineText) => {
+      const lowerLine = lineText.toLowerCase();
+      for (const keyword of keywords) {
+        if (lowerLine.includes(keyword.toLowerCase())) {
+          const relativePath = path4.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++;
+          }
+        }
+      }
+    });
+  }
+  const validFiles = Array.from(fileScores.values()).sort((a, b) => calculateFinalScore(b, keywords.length) - calculateFinalScore(a, keywords.length)).slice(0, 10);
+  return validFiles.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;
+  });
+  const highValueDirs = ["rag", "memory", "agents", "workflows"];
+  if (highValueDirs.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(path5) {
+  const filename = path5.split("/").pop()?.replace(/\.(mdx|md)$/, "") || "";
+  const keywords = /* @__PURE__ */ new Set();
+  const splitParts = filename.split(/[-_]|(?=[A-Z])/);
+  splitParts.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(path5, queryKeywords, baseDir) {
+  const pathKeywords = extractKeywordsFromPath(path5);
+  const allKeywords = normalizeKeywords([...pathKeywords, ...queryKeywords || []]);
+  if (allKeywords.length === 0) {
+    return "";
+  }
+  const suggestedPaths = await searchDocumentContent(allKeywords, baseDir);
+  if (suggestedPaths.length === 0) {
+    return "";
+  }
+  const pathList = suggestedPaths.map((path6) => `- ${path6}`).join("\n");
+  return `Here are some paths that might be relevant based on your query:
+
+${pathList}`;
+}
 var EXAMPLES_SOURCE = fromRepoRoot("examples");
 var OUTPUT_DIR = fromPackageRoot(".docs/organized/code-examples");
 async function prepareCodeExamples() {
   try {
-    await fs.rm(OUTPUT_DIR, { recursive: true, force: true });
+    await fs2.rm(OUTPUT_DIR, { recursive: true, force: true });
   } catch {
   }
-  await fs.mkdir(OUTPUT_DIR, { recursive: true });
-  const examples = await fs.readdir(EXAMPLES_SOURCE, { withFileTypes: true });
+  await fs2.mkdir(OUTPUT_DIR, { recursive: true });
+  const examples = await fs2.readdir(EXAMPLES_SOURCE, { withFileTypes: true });
   const exampleDirs = examples.filter((entry) => entry.isDirectory());
   for (const dir of exampleDirs) {
     const examplePath = path4.join(EXAMPLES_SOURCE, dir.name);
     const outputFile = path4.join(OUTPUT_DIR, `${dir.name}.md`);
     const files = [];
     try {
-      const packageJson = await fs.readFile(path4.join(examplePath, "package.json"), "utf-8");
+      const packageJson = await fs2.readFile(path4.join(examplePath, "package.json"), "utf-8");
       files.push({
         path: "package.json",
         content: packageJson
@@ -50,20 +156,20 @@ ${file.content}
         log(`Skipping ${dir.name}: ${totalLines} lines exceeds limit of ${limit}`);
         continue;
       }
-      await fs.writeFile(outputFile, output, "utf-8");
+      await fs2.writeFile(outputFile, output, "utf-8");
       log(`Generated ${dir.name}.md with ${totalLines} lines`);
     }
   }
 }
 async function scanDirectory(basePath, currentPath, files) {
-  const entries = await fs.readdir(currentPath, { withFileTypes: true });
+  const entries = await fs2.readdir(currentPath, { withFileTypes: true });
   for (const entry of entries) {
     const fullPath = path4.join(currentPath, entry.name);
     const relativePath = path4.relative(basePath, fullPath);
     if (entry.isDirectory()) {
       await scanDirectory(basePath, fullPath, files);
     } else if (entry.isFile() && entry.name.endsWith(".ts")) {
-      const content = await fs.readFile(fullPath, "utf-8");
+      const content = await fs2.readFile(fullPath, "utf-8");
       files.push({
         path: relativePath,
         content
@@ -83,22 +189,22 @@ var DOCS_DEST = fromPackageRoot(".docs/raw");
 var REFERENCE_DEST = path4.join(DOCS_DEST, "reference");
 var COURSE_DEST = path4.join(DOCS_DEST, "course");
 async function copyDir(src, dest) {
-  await fs.mkdir(dest, { recursive: true });
-  const entries = await fs.readdir(src, { withFileTypes: true });
+  await fs2.mkdir(dest, { recursive: true });
+  const entries = await fs2.readdir(src, { withFileTypes: true });
   for (const entry of entries) {
     const srcPath = path4.join(src, entry.name);
     const destPath = path4.join(dest, entry.name);
     if (entry.isDirectory()) {
       await copyDir(srcPath, destPath);
     } else if (entry.isFile() && (entry.name.endsWith(".mdx") || entry.name.endsWith(".md"))) {
-      await fs.copyFile(srcPath, destPath);
+      await fs2.copyFile(srcPath, destPath);
     }
   }
 }
 async function copyRaw() {
   try {
     try {
-      await fs.rm(DOCS_DEST, { recursive: true });
+      await fs2.rm(DOCS_DEST, { recursive: true });
     } catch {
     }
     await copyDir(DOCS_SOURCE, DOCS_DEST);
@@ -128,7 +234,7 @@ async function processPackageDir(packagePath, outputDir) {
   let packageName;
   try {
     const packageJsonPath = path4.join(packagePath, "package.json");
-    const packageJson = JSON.parse(await fs.readFile(packageJsonPath, "utf-8"));
+    const packageJson = JSON.parse(await fs2.readFile(packageJsonPath, "utf-8"));
     packageName = packageJson.name;
     if (!packageName) {
       log(`Skipping ${path4.basename(packagePath)}: No package name found in package.json`);
@@ -142,13 +248,13 @@ async function processPackageDir(packagePath, outputDir) {
     const changelogPath = path4.join(packagePath, "CHANGELOG.md");
     let changelog;
     try {
-      changelog = await fs.readFile(changelogPath, "utf-8");
+      changelog = await fs2.readFile(changelogPath, "utf-8");
       changelog = truncateContent(changelog, MAX_LINES);
     } catch {
       changelog = "No changelog available.";
     }
     const outputFile = path4.join(outputDir, `${encodeURIComponent(packageName)}.md`);
-    await fs.writeFile(outputFile, changelog, "utf-8");
+    await fs2.writeFile(outputFile, changelog, "utf-8");
     log(`Generated changelog for ${packageName}`);
   } catch (error) {
     console.error(`Error processing changelog for ${packageName}:`, error);
@@ -157,15 +263,15 @@ async function processPackageDir(packagePath, outputDir) {
 async function preparePackageChanges() {
   const outputDir = path4.resolve(process.cwd(), CHANGELOGS_DEST);
   try {
-    await fs.rm(outputDir, { recursive: true, force: true });
+    await fs2.rm(outputDir, { recursive: true, force: true });
   } catch {
   }
-  await fs.mkdir(outputDir, { recursive: true });
+  await fs2.mkdir(outputDir, { recursive: true });
   for (const sourceDir of SOURCE_DIRS) {
     const fullSourceDir = path4.resolve(process.cwd(), sourceDir);
     try {
-      await fs.access(fullSourceDir);
-      const entries = await fs.readdir(fullSourceDir, { withFileTypes: true });
+      await fs2.access(fullSourceDir);
+      const entries = await fs2.readdir(fullSourceDir, { withFileTypes: true });
       const packageDirs = entries.filter((entry) => entry.isDirectory()).filter((entry) => entry.name !== "docs-mcp" && entry.name !== "_config");
       for (const dir of packageDirs) {
         const packagePath = path4.join(fullSourceDir, dir.name);
@@ -196,4 +302,4 @@ if (process.env.PREPARE === `true`) {
   }
 }
 
-export { fromPackageRoot, prepare };
+export { fromPackageRoot, getMatchingPaths, prepare };

package/dist/prepare-docs/prepare.js

@@ -1 +1 @@
-export { prepare } from '../chunk-QWIXFGFR.js';
+export { prepare } from '../chunk-P5AHYMUI.js';

package/dist/stdio.js

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-import { fromPackageRoot, prepare } from './chunk-QWIXFGFR.js';
+import { fromPackageRoot, prepare, getMatchingPaths } from './chunk-P5AHYMUI.js';
 import * as fs from 'fs';
 import { existsSync, mkdirSync } from 'fs';
 import * as os2 from 'os';
@@ -800,7 +800,7 @@ async function listDirContents(dirPath) {
     throw error;
   }
 }
-async function readMdxContent(docPath) {
+async function readMdxContent(docPath, queryKeywords) {
   const fullPath = path3__default.join(docsBaseDir, docPath);
   void logger.debug(`Reading MDX content from: ${fullPath}`);
   try {
@@ -831,7 +831,9 @@ async function readMdxContent(docPath) {
 
 ${content2}`;
       }
-      return { found: true, content: dirListing + fileContents };
+      const contentBasedSuggestions = await getMatchingPaths(docPath, queryKeywords, docsBaseDir);
+      const suggestions = ["---", "", contentBasedSuggestions, ""].join("\n");
+      return { found: true, content: dirListing + fileContents + suggestions };
     }
     const content = await fs3.readFile(fullPath, "utf-8");
     return { found: true, content };
@@ -895,19 +897,37 @@ var availablePaths = await getAvailablePaths();
 var docsInputSchema = z.object({
   paths: z.array(z.string()).min(1).describe(`One or more documentation paths to fetch
 Available paths:
-${availablePaths}`)
+${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."
+  )
 });
 var docsTool = {
   name: "mastraDocs",
-  description: "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. 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 evals check in evals/ and in reference/evals/. Provide code examples so the user understands. If you build a URL from the path, only paths ending in .mdx exist. Note that docs about MCP are currently in reference/tools/. 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",
+  description: `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. 
+    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 evals check in evals/ and in reference/evals/. 
+    Provide code examples so the user understands. 
+    If you build a URL from the path, only paths ending in .mdx exist. 
+    Note that docs about MCP are currently in reference/tools/. 
+    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 (e.g., 'Found in "path/to/file.mdx"') so users know where this documentation lives.`,
   parameters: docsInputSchema,
   execute: async (args) => {
     void logger.debug("Executing mastraDocs tool", { args });
     try {
+      const queryKeywords = args.queryKeywords ?? [];
       const results = await Promise.all(
         args.paths.map(async (path6) => {
           try {
-            const result = await readMdxContent(path6);
+            const result = await readMdxContent(path6, queryKeywords);
             if (result.found) {
               return {
                 path: path6,
@@ -915,11 +935,12 @@ var docsTool = {
                 error: null
               };
             }
-            const suggestions = await findNearestDirectory(path6, availablePaths);
+            const directorySuggestions = await findNearestDirectory(path6, availablePaths);
+            const contentBasedSuggestions = await getMatchingPaths(path6, queryKeywords, docsBaseDir);
             return {
               path: path6,
               content: null,
-              error: suggestions
+              error: [directorySuggestions, contentBasedSuggestions].join("\n\n")
             };
           } catch (error) {
             void logger.warning(`Failed to read content for path: ${path6}`, error);
@@ -967,7 +988,7 @@ async function listCodeExamples() {
     return [];
   }
 }
-async function readCodeExample(filename) {
+async function readCodeExample(filename, queryKeywords) {
   const filePath = path3__default.join(examplesDir, filename);
   void logger.debug(`Reading example: ${filename}`);
   try {
@@ -976,10 +997,13 @@ async function readCodeExample(filename) {
   } catch {
     const examples = await listCodeExamples();
     const availableExamples = examples.map((ex) => `- ${ex.name}`).join("\n");
+    const contentBasedSuggestions = await getMatchingPaths(filename, queryKeywords, examplesDir);
     return `Example "${filename}" not found.
 
 Available examples:
-${availableExamples}`;
+${availableExamples}
+
+${contentBasedSuggestions}`;
   }
 }
 var initialExamples = await listCodeExamples();
@@ -987,11 +1011,17 @@ var examplesListing = initialExamples.length > 0 ? "\n\nAvailable examples: " +
 var examplesInputSchema = z.object({
   example: z.string().optional().describe(
     "Name of the specific example to fetch. If not provided, lists all available examples." + examplesListing
+  ),
+  queryKeywords: z.array(z.string()).optional().describe(
+    "Keywords from user query to use for matching examples. Each keyword should be a single word or short phrase; any whitespace-separated keywords will be split automatically."
   )
 });
 var examplesTool = {
   name: "mastraExamples",
-  description: "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.",
+  description: `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.`,
   parameters: examplesInputSchema,
   execute: async (args) => {
     void logger.debug("Executing mastraExamples tool", { example: args.example });
@@ -1001,7 +1031,7 @@ var examplesTool = {
         return ["Available code examples:", "", ...examples.map((ex) => `- ${ex.name}`)].join("\n");
       }
       const filename = args.example.endsWith(".md") ? args.example : `${args.example}.md`;
-      const result = await readCodeExample(filename);
+      const result = await readCodeExample(filename, args.queryKeywords || []);
       return result;
     } catch (error) {
       void logger.error("Failed to execute mastraExamples tool", error);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mastra/mcp-docs-server",
-  "version": "0.13.1-alpha.0",
+  "version": "0.13.1",
   "description": "MCP server for accessing Mastra.ai documentation, changelogs, and news.",
   "type": "module",
   "main": "dist/index.js",
@@ -32,7 +32,7 @@
     "uuid": "^11.1.0",
     "zod": "^3.25.57",
     "zod-to-json-schema": "^3.24.5",
-    "@mastra/mcp": "^0.10.4-alpha.0"
+    "@mastra/mcp": "^0.10.4"
   },
   "devDependencies": {
     "@hono/node-server": "^1.14.4",
@@ -47,8 +47,8 @@
     "tsx": "^4.19.4",
     "typescript": "^5.8.3",
     "vitest": "^3.2.3",
-    "@mastra/core": "0.10.6-alpha.0",
-    "@internal/lint": "0.0.12"
+    "@internal/lint": "0.0.13",
+    "@mastra/core": "0.10.6"
   },
   "peerDependencies": {
     "@mastra/core": "^0.10.0-alpha.0"

package/.docs/raw/course/03-agent-memory/15-configuring-semantic-recall.md

@@ -1,46 +0,0 @@
-# Configuring Semantic Recall
-
-Semantic recall is enabled by default when you create a Memory instance. However, you can customize its behavior with the following parameters:
-
-1. **topK**: How many semantically similar messages to retrieve
-2. **messageRange**: How much surrounding context to include with each match
-
-Let's update our agent with custom semantic recall settings:
-
-```typescript
-import { Agent } from "@mastra/core/agent";
-import { Memory } from "@mastra/memory";
-import { openai } from "@ai-sdk/openai";
-
-// Create a memory instance with semantic recall configuration
-const memory = new Memory({
-  options: {
-    lastMessages: 20, // Include the last 20 messages in the context
-    semanticRecall: {
-      topK: 3, // Retrieve 3 most similar messages
-      messageRange: {
-        before: 2, // Include 2 messages before each match
-        after: 1, // Include 1 message after each match
-      },
-    },
-  },
-});
-
-// Create an agent with the configured memory
-export const memoryAgent = new Agent({
-  name: "MemoryAgent",
-  instructions: `
-    You are a helpful assistant with advanced memory capabilities.
-    You can remember previous conversations and user preferences.
-    When a user shares information about themselves, acknowledge it and remember it for future reference.
-    If asked about something mentioned earlier in the conversation, recall it accurately.
-    You can also recall relevant information from older conversations when appropriate.
-  `,
-  model: openai("gpt-4o"),
-  memory: memory,
-});
-```
-
-The `topK` parameter controls how many semantically similar messages are retrieved. A higher value will retrieve more messages, which can be helpful for complex topics but may also include less relevant information.
-
-The `messageRange` parameter controls how much context is included with each match. This is important because the matching message alone might not provide enough context to understand the conversation. Including messages before and after the match helps the agent understand the context of the matched message.

package/.docs/raw/course/03-agent-memory/16-vector-store-configuration.md

@@ -1,37 +0,0 @@
-# Vector Store Configuration
-
-By default, semantic recall uses an in-memory vector store for development purposes. For production applications, you'll want to use a persistent vector store. Mastra supports several options:
-
-```typescript
-import { Memory } from "@mastra/memory";
-import { ChromaVectorStore } from "@mastra/chroma";
-
-const memory = new Memory({
-  options: {
-    semanticRecall: {
-      topK: 3,
-      messageRange: {
-        before: 2,
-        after: 1,
-      },
-      // Configure a persistent vector store
-      vectorStore: new ChromaVectorStore({
-        collectionName: "memory",
-        url: "http://localhost:8000",
-      }),
-    },
-  },
-});
-```
-
-Mastra supports several vector store options, including:
-
-- In-memory (default for development)
-- Chroma
-- Pinecone
-- Qdrant
-- Postgres (with pgvector)
-
-The vector store is responsible for storing and retrieving the vector embeddings used for semantic search. The in-memory vector store is sufficient for development and testing, but it doesn't persist data between application restarts and isn't suitable for production use.
-
-For production applications, you'll want to use a persistent vector store like Chroma, Pinecone, Qdrant, or Postgres with pgvector. These options provide durable storage for your vector embeddings and can scale to handle large amounts of conversation data.

package/.docs/raw/course/03-agent-memory/18-disabling-semantic-recall.md

@@ -1,24 +0,0 @@
-# Disabling Semantic Recall
-
-In some cases, you might want to disable semantic recall, for example, if you're building a simple chatbot that doesn't need to recall older conversations. You can do this by setting `enabled: false`:
-
-```typescript
-const memory = new Memory({
-  options: {
-    semanticRecall: {
-      enabled: false, // Disable semantic recall
-    },
-  },
-});
-```
-
-Disabling semantic recall can be useful in several scenarios:
-
-1. When building simple chatbots that only need to maintain context within the current conversation
-2. When working with sensitive information that shouldn't be retrieved from past conversations
-3. When optimizing for performance and reducing the computational overhead of semantic search
-4. When testing the behavior of your agent without the influence of semantic recall
-
-Even with semantic recall disabled, your agent will still have access to recent conversation history through the `lastMessages` option, so it can maintain context within the current conversation.
-
-In the next step, we'll explore working memory, which allows your agent to maintain persistent information about users across interactions.