@mastra/mcp-docs-server 0.0.0-commonjs-20250414101718

package/dist/stdio.js

@@ -0,0 +1,518 @@
+#!/usr/bin/env node
+import { fromPackageRoot, prepare } from './chunk-QWYMT5LP.js';
+import fs2 from 'node:fs/promises';
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
+import { ListToolsRequestSchema, CallToolRequestSchema } from '@modelcontextprotocol/sdk/types.js';
+import { z } from 'zod';
+import { zodToJsonSchema } from 'zod-to-json-schema';
+import { JSDOM } from 'jsdom';
+import path2 from 'node:path';
+
+async function fetchBlogPosts() {
+  const response = await fetch("https://mastra.ai/blog");
+  if (!response.ok) {
+    throw new Error("Failed to fetch blog posts");
+  }
+  const html = await response.text();
+  const dom = new JSDOM(html);
+  const document = dom.window.document;
+  const blogLinks = Array.from(document.querySelectorAll('a[href^="/blog/"]')).filter((link) => {
+    const href = link.getAttribute("href");
+    return href !== "/blog" && !href?.includes("authors");
+  }).map((link) => {
+    const h2 = link.querySelector("h2");
+    const title = h2?.textContent?.trim();
+    const href = link.getAttribute("href");
+    if (title && href) {
+      return `[${title}](${href})`;
+    }
+    return null;
+  }).filter(Boolean);
+  return "Mastra.ai Blog Posts:\n\n" + blogLinks.join("\n");
+}
+async function fetchBlogPost(url) {
+  const response = await fetch(url);
+  if (!response.ok) {
+    throw new Error("Failed to fetch blog post");
+  }
+  const html = await response.text();
+  const dom = new JSDOM(html);
+  const document = dom.window.document;
+  const scripts = document.querySelectorAll("script");
+  scripts.forEach((script) => script.remove());
+  const content = document.body.textContent?.trim() || "";
+  if (!content) {
+    throw new Error("No content found in blog post");
+  }
+  return content;
+}
+var blogInputSchema = z.object({
+  url: z.string().describe(
+    "URL of a specific blog post to fetch. If the string /blog is passed as the url it returns a list of all blog posts."
+  )
+});
+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",
+  execute: async (args) => {
+    try {
+      let content;
+      if (args.url !== `/blog`) {
+        content = await fetchBlogPost(`https://mastra.ai${args.url}`);
+      } else {
+        content = await fetchBlogPosts();
+      }
+      return {
+        content: [
+          {
+            type: "text",
+            text: content
+          }
+        ],
+        isError: false
+      };
+    } catch (error) {
+      return {
+        content: [
+          {
+            type: "text",
+            text: `Error: ${error instanceof Error ? error.message : String(error)}`
+          }
+        ],
+        isError: true
+      };
+    }
+  }
+};
+function encodePackageName(name) {
+  return encodeURIComponent(name);
+}
+function decodePackageName(name) {
+  return decodeURIComponent(name);
+}
+var changelogsDir = fromPackageRoot(".docs/organized/changelogs");
+async function listPackageChangelogs() {
+  try {
+    const files = await fs2.readdir(changelogsDir);
+    return files.filter((f) => f.endsWith(".md")).map((f) => ({
+      name: decodePackageName(f.replace(".md", "")),
+      path: f
+    })).sort((a, b) => a.name.localeCompare(b.name));
+  } catch {
+    return [];
+  }
+}
+async function readPackageChangelog(filename) {
+  const encodedName = encodePackageName(filename.replace(".md", ""));
+  const filePath = path2.join(changelogsDir, `${encodedName}.md`);
+  try {
+    return await fs2.readFile(filePath, "utf-8");
+  } catch {
+    const packages = await listPackageChangelogs();
+    const availablePackages = packages.map((pkg) => `- ${pkg.name}`).join("\n");
+    throw new Error(
+      `Changelog for "${filename.replace(".md", "")}" not found.
+
+Available packages:
+${availablePackages}`
+    );
+  }
+}
+var initialPackages = await listPackageChangelogs();
+var packagesListing = initialPackages.length > 0 ? "\n\nAvailable packages: " + initialPackages.map((pkg) => pkg.name).join(", ") : "\n\nNo package changelogs available yet. Run the documentation preparation script first.";
+var changesInputSchema = z.object({
+  package: z.string().optional().describe("Name of the specific package to fetch changelog for. If not provided, lists all available packages.")
+});
+var changesTool = {
+  name: "mastraChanges",
+  description: `Get changelog information for Mastra.ai packages. ${packagesListing}`,
+  execute: async (args) => {
+    try {
+      if (!args.package) {
+        const packages = await listPackageChangelogs();
+        return {
+          content: [
+            {
+              type: "text",
+              text: ["Available package changelogs:", "", ...packages.map((pkg) => `- ${pkg.name}`)].join("\n")
+            }
+          ],
+          isError: false
+        };
+      }
+      const content = await readPackageChangelog(args.package);
+      return {
+        content: [
+          {
+            type: "text",
+            text: content
+          }
+        ],
+        isError: false
+      };
+    } catch (error) {
+      return {
+        content: [
+          {
+            type: "text",
+            text: `Error: ${error instanceof Error ? error.message : String(error)}`
+          }
+        ],
+        isError: true
+      };
+    }
+  }
+};
+var docsBaseDir = fromPackageRoot(".docs/raw/");
+async function listDirContents(dirPath) {
+  const entries = await fs2.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(".mdx")) {
+      files.push(entry.name);
+    }
+  }
+  return {
+    dirs: dirs.sort(),
+    files: files.sort()
+  };
+}
+async function readMdxContent(docPath) {
+  const fullPath = path2.join(docsBaseDir, docPath);
+  try {
+    const stats = await fs2.stat(fullPath);
+    if (stats.isDirectory()) {
+      const { dirs, files } = await listDirContents(fullPath);
+      const dirListing = [
+        `Directory contents of ${docPath}:`,
+        "",
+        dirs.length > 0 ? "Subdirectories:" : "No subdirectories.",
+        ...dirs.map((d) => `- ${d}`),
+        "",
+        files.length > 0 ? "Files in this directory:" : "No files in this directory.",
+        ...files.map((f) => `- ${f}`),
+        "",
+        "---",
+        "",
+        "Contents of all files in this directory:",
+        ""
+      ].join("\n");
+      let fileContents = "";
+      for (const file of files) {
+        const filePath = path2.join(fullPath, file);
+        const content = await fs2.readFile(filePath, "utf-8");
+        fileContents += `
+
+# ${file}
+
+${content}`;
+      }
+      return dirListing + fileContents;
+    }
+    return fs2.readFile(fullPath, "utf-8");
+  } catch {
+    throw new Error(`Path not found: ${docPath}`);
+  }
+}
+async function findNearestDirectory(docPath, availablePaths2) {
+  const parts = docPath.split("/");
+  while (parts.length > 0) {
+    const testPath = parts.join("/");
+    try {
+      const fullPath = path2.join(docsBaseDir, testPath);
+      const stats = await fs2.stat(fullPath);
+      if (stats.isDirectory()) {
+        const { dirs, files } = await listDirContents(fullPath);
+        return [
+          `Path "${docPath}" not found.`,
+          `Here are the available paths in "${testPath}":`,
+          "",
+          dirs.length > 0 ? "Directories:" : "No subdirectories.",
+          ...dirs.map((d) => `- ${testPath}/${d}`),
+          "",
+          files.length > 0 ? "Files:" : "No files.",
+          ...files.map((f) => `- ${testPath}/${f}`)
+        ].join("\n");
+      }
+    } catch {
+    }
+    parts.pop();
+  }
+  return [`Path "${docPath}" not found.`, "Here are all available paths:", "", availablePaths2].join("\n");
+}
+async function getAvailablePaths() {
+  const { dirs, files } = await listDirContents(docsBaseDir);
+  let referenceDirs = [];
+  if (dirs.includes("reference/")) {
+    const { dirs: refDirs } = await listDirContents(path2.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:",
+    ...files.map((f) => `- ${f}`)
+  ].filter(Boolean).join("\n");
+}
+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}`)
+});
+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",
+  execute: async (args) => {
+    try {
+      const results = await Promise.all(
+        args.paths.map(async (path4) => {
+          try {
+            const content = await readMdxContent(path4);
+            return {
+              path: path4,
+              content,
+              error: null
+            };
+          } catch (error) {
+            if (error instanceof Error && error.message.includes("Path not found")) {
+              const suggestions = await findNearestDirectory(path4, availablePaths);
+              return {
+                path: path4,
+                content: null,
+                error: suggestions
+              };
+            }
+            return {
+              path: path4,
+              content: null,
+              error: error instanceof Error ? error.message : "Unknown error"
+            };
+          }
+        })
+      );
+      const output = results.map((result) => {
+        if (result.error) {
+          return `## ${result.path}
+
+${result.error}
+
+---
+`;
+        }
+        return `## ${result.path}
+
+${result.content}
+
+---
+`;
+      }).join("\n");
+      return {
+        content: [
+          {
+            type: "text",
+            text: output
+          }
+        ],
+        isError: false
+      };
+    } catch (error) {
+      return {
+        content: [
+          {
+            type: "text",
+            text: `Error: ${error instanceof Error ? error.message : String(error)}`
+          }
+        ],
+        isError: true
+      };
+    }
+  }
+};
+var examplesDir = fromPackageRoot(".docs/organized/code-examples");
+async function listCodeExamples() {
+  try {
+    const files = await fs2.readdir(examplesDir);
+    return files.filter((f) => f.endsWith(".md")).map((f) => ({
+      name: f.replace(".md", ""),
+      path: f
+    })).sort((a, b) => a.name.localeCompare(b.name));
+  } catch {
+    return [];
+  }
+}
+async function readCodeExample(filename) {
+  const filePath = path2.join(examplesDir, filename);
+  try {
+    return await fs2.readFile(filePath, "utf-8");
+  } catch {
+    const examples = await listCodeExamples();
+    const availableExamples = examples.map((ex) => `- ${ex.name}`).join("\n");
+    throw new Error(`Example "${filename}" not found.
+
+Available examples:
+${availableExamples}`);
+  }
+}
+var initialExamples = await listCodeExamples();
+var examplesListing = initialExamples.length > 0 ? "\n\nAvailable examples: " + initialExamples.map((ex) => ex.name).join(", ") : "\n\nNo examples available yet. Run the documentation preparation script first.";
+var examplesInputSchema = z.object({
+  example: z.string().optional().describe(
+    "Name of the specific example to fetch. If not provided, lists all available examples." + examplesListing
+  )
+});
+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.",
+  execute: async (args) => {
+    try {
+      if (!args.example) {
+        const examples = await listCodeExamples();
+        return {
+          content: [
+            {
+              type: "text",
+              text: ["Available code examples:", "", ...examples.map((ex) => `- ${ex.name}`)].join("\n")
+            }
+          ],
+          isError: false
+        };
+      }
+      const filename = args.example.endsWith(".md") ? args.example : `${args.example}.md`;
+      const content = await readCodeExample(filename);
+      return {
+        content: [
+          {
+            type: "text",
+            text: content
+          }
+        ],
+        isError: false
+      };
+    } catch (error) {
+      return {
+        content: [
+          {
+            type: "text",
+            text: `Error: ${error instanceof Error ? error.message : String(error)}`
+          }
+        ],
+        isError: true
+      };
+    }
+  }
+};
+
+// src/index.ts
+if (process.env.REBUILD_DOCS_ON_START === "true") {
+  await prepare();
+}
+var server = new Server(
+  {
+    name: "Mastra Documentation Server",
+    version: JSON.parse(await fs2.readFile(fromPackageRoot(`package.json`), "utf8")).version
+  },
+  {
+    capabilities: {
+      tools: {}
+    }
+  }
+);
+server.setRequestHandler(ListToolsRequestSchema, async () => ({
+  tools: [
+    {
+      name: "mastraBlog",
+      description: blogTool.description,
+      inputSchema: zodToJsonSchema(blogInputSchema)
+    },
+    {
+      name: "mastraDocs",
+      description: docsTool.description,
+      inputSchema: zodToJsonSchema(docsInputSchema)
+    },
+    {
+      name: "mastraExamples",
+      description: examplesTool.description,
+      inputSchema: zodToJsonSchema(examplesInputSchema)
+    },
+    {
+      name: "mastraChanges",
+      description: changesTool.description,
+      inputSchema: zodToJsonSchema(changesInputSchema)
+    }
+  ]
+}));
+server.setRequestHandler(CallToolRequestSchema, async (request) => {
+  try {
+    switch (request.params.name) {
+      case "mastraBlog": {
+        const args = blogInputSchema.parse(request.params.arguments);
+        return await blogTool.execute(args);
+      }
+      case "mastraDocs": {
+        const args = docsInputSchema.parse(request.params.arguments);
+        return await docsTool.execute(args);
+      }
+      case "mastraExamples": {
+        const args = examplesInputSchema.parse(request.params.arguments);
+        return await examplesTool.execute(args);
+      }
+      case "mastraChanges": {
+        const args = changesInputSchema.parse(request.params.arguments);
+        return await changesTool.execute(args);
+      }
+      default:
+        return {
+          content: [
+            {
+              type: "text",
+              text: `Unknown tool: ${request.params.name}`
+            }
+          ],
+          isError: true
+        };
+    }
+  } catch (error) {
+    if (error instanceof z.ZodError) {
+      return {
+        content: [
+          {
+            type: "text",
+            text: `Invalid arguments: ${error.errors.map((e) => `${e.path.join(".")}: ${e.message}`).join(", ")}`
+          }
+        ],
+        isError: true
+      };
+    }
+    return {
+      content: [
+        {
+          type: "text",
+          text: `Error: ${error instanceof Error ? error.message : String(error)}`
+        }
+      ],
+      isError: true
+    };
+  }
+});
+async function runServer() {
+  const transport = new StdioServerTransport();
+  await server.connect(transport);
+  console.error("Mastra Docs MCP Server running on stdio");
+}
+
+// src/stdio.ts
+runServer().catch((error) => {
+  console.error("Fatal error running server:", error);
+  process.exit(1);
+});

package/package.json

@@ -0,0 +1,60 @@
+{
+  "name": "@mastra/mcp-docs-server",
+  "version": "0.0.0-commonjs-20250414101718",
+  "description": "MCP server for accessing Mastra.ai documentation, changelogs, and news.",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "bin": "dist/stdio.js",
+  "files": [
+    "dist",
+    ".docs",
+    "README.md"
+  ],
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.js"
+      }
+    },
+    "./package.json": "./package.json"
+  },
+  "keywords": [],
+  "author": "",
+  "license": "Elastic-2.0",
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.9.0",
+    "date-fns": "^4.1.0",
+    "exit-hook": "^4.0.0",
+    "jsdom": "^26.0.0",
+    "turndown": "^7.1.2",
+    "uuid": "^11.1.0",
+    "zod": "^3.22.4",
+    "zod-to-json-schema": "^3.22.4",
+    "@mastra/core": "0.0.0-commonjs-20250414101718"
+  },
+  "devDependencies": {
+    "@hono/node-server": "^1.13.8",
+    "@types/jsdom": "^21.1.7",
+    "@types/node": "^20.11.24",
+    "@types/turndown": "^5.0.5",
+    "@wong2/mcp-cli": "^1.6.0",
+    "cross-env": "^7.0.3",
+    "eslint": "^9.23.0",
+    "hono": "^4.7.4",
+    "tsup": "^8.4.0",
+    "tsx": "^4.19.3",
+    "typescript": "^5.3.3",
+    "vitest": "^3.0.9",
+    "@internal/lint": "0.0.0-commonjs-20250414101718",
+    "@mastra/mcp": "0.0.0-commonjs-20250414101718"
+  },
+  "scripts": {
+    "prepare-docs": "cross-env PREPARE=true node dist/prepare-docs/prepare.js",
+    "build:cli": "tsup src/stdio.ts src/prepare-docs/prepare.ts --format esm --experimental-dts --treeshake=smallest --splitting",
+    "pretest": "pnpm turbo build --filter @mastra/mcp-docs-server",
+    "test": "vitest run",
+    "lint": "eslint ."
+  }
+}