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

package/LICENSE.md

@@ -0,0 +1,46 @@
+# Elastic License 2.0 (ELv2)
+
+Copyright (c) 2025 Mastra AI, Inc.
+
+**Acceptance**
+By using the software, you agree to all of the terms and conditions below.
+
+**Copyright License**
+The licensor grants you a non-exclusive, royalty-free, worldwide, non-sublicensable, non-transferable license to use, copy, distribute, make available, and prepare derivative works of the software, in each case subject to the limitations and conditions below
+
+**Limitations**
+You may not provide the software to third parties as a hosted or managed service, where the service provides users with access to any substantial set of the features or functionality of the software.
+
+You may not move, change, disable, or circumvent the license key functionality in the software, and you may not remove or obscure any functionality in the software that is protected by the license key.
+
+You may not alter, remove, or obscure any licensing, copyright, or other notices of the licensor in the software. Any use of the licensor’s trademarks is subject to applicable law.
+
+**Patents**
+The licensor grants you a license, under any patent claims the licensor can license, or becomes able to license, to make, have made, use, sell, offer for sale, import and have imported the software, in each case subject to the limitations and conditions in this license. This license does not cover any patent claims that you cause to be infringed by modifications or additions to the software. If you or your company make any written claim that the software infringes or contributes to infringement of any patent, your patent license for the software granted under these terms ends immediately. If your company makes such a claim, your patent license ends immediately for work on behalf of your company.
+
+**Notices**
+You must ensure that anyone who gets a copy of any part of the software from you also gets a copy of these terms.
+
+If you modify the software, you must include in any modified copies of the software prominent notices stating that you have modified the software.
+
+**No Other Rights**
+These terms do not imply any licenses other than those expressly granted in these terms.
+
+**Termination**
+If you use the software in violation of these terms, such use is not licensed, and your licenses will automatically terminate. If the licensor provides you with a notice of your violation, and you cease all violation of this license no later than 30 days after you receive that notice, your licenses will be reinstated retroactively. However, if you violate these terms after such reinstatement, any additional violation of these terms will cause your licenses to terminate automatically and permanently.
+
+**No Liability**
+As far as the law allows, the software comes as is, without any warranty or condition, and the licensor will not be liable to you for any damages arising out of these terms or the use or nature of the software, under any kind of legal claim.
+
+**Definitions**
+The _licensor_ is the entity offering these terms, and the _software_ is the software the licensor makes available under these terms, including any portion of it.
+
+_you_ refers to the individual or entity agreeing to these terms.
+
+_your company_ is any legal entity, sole proprietorship, or other kind of organization that you work for, plus all organizations that have control over, are under the control of, or are under common control with that organization. _control_ means ownership of substantially all the assets of an entity, or the power to direct its management and policies by vote, contract, or otherwise. Control can be direct or indirect.
+
+_your licenses_ are all the licenses granted to you for the software under these terms.
+
+_use_ means anything you do with the software requiring one of your licenses.
+
+_trademark_ means trademarks, service marks, and similar rights.

package/README.md

@@ -0,0 +1,129 @@
+# @mastra/mcp-docs-server
+
+A Model Context Protocol (MCP) server that provides AI assistants with direct access to Mastra.ai's complete knowledge base. This includes comprehensive documentation with MDX support, a collection of production-ready code examples, technical blog posts, and detailed package changelogs. The server integrates with popular AI development environments like Cursor and Windsurf, as well as Mastra agents, making it easy to build documentation-aware AI assistants that can provide accurate, up-to-date information about Mastra.ai's ecosystem.
+
+## Installation
+
+### In Cursor
+
+Create or update `.cursor/mcp.json` in your project root:
+
+MacOS/Linux
+
+```json
+{
+  "mcpServers": {
+    "mastra": {
+      "command": "npx",
+      "args": ["-y", "@mastra/mcp-docs-server@latest"]
+    }
+  }
+}
+```
+
+Windows
+
+```json
+{
+  "mcpServers": {
+    "mastra": {
+      "command": "cmd",
+      "args": ["/c", "npx", "-y", "@mastra/mcp-docs-server@latest"]
+    }
+  }
+}
+```
+
+This will make all Mastra documentation tools available in your Cursor workspace.
+Note that the MCP server wont be enabled by default. You'll need to go to Cursor settings -> MCP settings and click "enable" on the Mastra MCP server.
+
+### In Windsurf
+
+Create or update `~/.codeium/windsurf/mcp_config.json`:
+
+MacOS/Linux
+
+```json
+{
+  "mcpServers": {
+    "mastra": {
+      "command": "npx",
+      "args": ["-y", "@mastra/mcp-docs-server@latest"]
+    }
+  }
+}
+```
+
+Windows
+
+```json
+{
+  "mcpServers": {
+    "mastra": {
+      "command": "cmd",
+      "args": ["/c", "npx", "-y", "@mastra/mcp-docs-server@latest"]
+    }
+  }
+}
+```
+
+This will make all Mastra documentation tools available in your Windsurf workspace.
+Note that Windsurf MCP tool calling doesn't work very well. You will need to fully quit and re-open Windsurf after adding this.
+If a tool call fails you will need to go into Windsurf MCP settings and re-start the MCP server.
+
+### In a Mastra Agent
+
+```typescript
+import { MCPConfiguration } from '@mastra/mcp';
+import { Agent } from '@mastra/core/agent';
+import { openai } from '@ai-sdk/openai';
+
+// Configure MCP with the docs server
+const mcp = new MCPConfiguration({
+  servers: {
+    mastra: {
+      command: 'npx',
+      args: ['-y', '@mastra/mcp-docs-server@latest'],
+    },
+  },
+});
+
+// Create an agent with access to all documentation tools
+const agent = new Agent({
+  name: 'Documentation Assistant',
+  instructions: 'You help users find and understand Mastra.ai documentation.',
+  model: openai('gpt-4'),
+  tools: await mcp.getTools(),
+});
+
+// Or use toolsets dynamically in generate/stream
+const response = await agent.stream('Show me the quick start example', {
+  toolsets: await mcp.getToolsets(),
+});
+```
+
+## Tools
+
+### Documentation Tool (`mastraDocs`)
+
+- Get Mastra.ai documentation by requesting specific paths
+- Explore both general guides and API reference documentation
+- Automatically lists available paths when a requested path isn't found
+
+### Examples Tool (`mastraExamples`)
+
+- Access code examples showing Mastra.ai implementation patterns
+- List all available examples
+- Get detailed source code for specific examples
+
+### Blog Tool (`mastraBlog`)
+
+- Access technical blog posts and articles
+- Posts are properly formatted with code block handling
+- Supports various date formats in blog metadata
+
+### Changes Tool (`mastraChanges`)
+
+- Access package changelogs
+- List all available package changelogs
+- Get detailed changelog content for specific packages

package/dist/_tsup-dts-rollup.d.ts

@@ -0,0 +1,149 @@
+import { MCPConfiguration } from '@mastra/mcp';
+import { Server } from '@modelcontextprotocol/sdk/server/index.js';
+import { ServerType } from '@hono/node-server/.';
+import { z } from 'zod';
+
+export declare type BlogInput = z.infer<typeof blogInputSchema>;
+
+export declare const blogInputSchema: z.ZodObject<{
+    url: z.ZodString;
+}, "strip", z.ZodTypeAny, {
+    url: string;
+}, {
+    url: string;
+}>;
+
+export declare const blogTool: {
+    name: string;
+    description: string;
+    execute: (args: BlogInput) => Promise<{
+        content: {
+            type: string;
+            text: string;
+        }[];
+        isError: boolean;
+    }>;
+};
+
+export declare function callTool(tool: any, args: any): Promise<string>;
+
+export declare type ChangesInput = z.infer<typeof changesInputSchema>;
+
+export declare const changesInputSchema: z.ZodObject<{
+    package: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    package?: string | undefined;
+}, {
+    package?: string | undefined;
+}>;
+
+export declare const changesTool: {
+    name: string;
+    description: string;
+    execute: (args: ChangesInput) => Promise<{
+        content: {
+            type: string;
+            text: string;
+        }[];
+        isError: boolean;
+    }>;
+};
+
+export declare function copyRaw(): Promise<void>;
+
+export declare type DocsInput = z.infer<typeof docsInputSchema>;
+
+export declare const docsInputSchema: z.ZodObject<{
+    paths: z.ZodArray<z.ZodString, "many">;
+}, "strip", z.ZodTypeAny, {
+    paths: string[];
+}, {
+    paths: string[];
+}>;
+
+export declare const docsTool: {
+    name: string;
+    description: string;
+    execute: (args: DocsInput) => Promise<{
+        content: {
+            type: string;
+            text: string;
+        }[];
+        isError: boolean;
+    }>;
+};
+
+export declare type ExamplesInput = z.infer<typeof examplesInputSchema>;
+
+export declare const examplesInputSchema: z.ZodObject<{
+    example: z.ZodOptional<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    example?: string | undefined;
+}, {
+    example?: string | undefined;
+}>;
+
+export declare const examplesTool: {
+    name: string;
+    description: string;
+    execute: (args: ExamplesInput) => Promise<{
+        content: {
+            type: string;
+            text: string;
+        }[];
+        isError: boolean;
+    }>;
+};
+
+export declare function fromPackageRoot(relative: string): string;
+
+export declare function fromRepoRoot(relative: string): string;
+
+export declare const log: {
+    (...data: any[]): void;
+    (message?: any, ...optionalParams: any[]): void;
+};
+
+export declare const mcp: MCPConfiguration;
+
+export declare function prepare(): Promise<void>;
+
+/**
+ * Scans example directories and creates flattened code example files
+ */
+export declare function prepareCodeExamples(): Promise<void>;
+
+/**
+ * Scans package directories and creates organized changelog files
+ */
+export declare function preparePackageChanges(): Promise<void>;
+
+export declare function runServer(): Promise<void>;
+
+export declare const server: Server<{
+    method: string;
+    params?: {
+        [x: string]: unknown;
+        _meta?: {
+            [x: string]: unknown;
+            progressToken?: string | number | undefined;
+        } | undefined;
+    } | undefined;
+}, {
+    method: string;
+    params?: {
+        [x: string]: unknown;
+        _meta?: {
+            [x: string]: unknown;
+        } | undefined;
+    } | undefined;
+}, {
+    [x: string]: unknown;
+    _meta?: {
+        [x: string]: unknown;
+    } | undefined;
+}>;
+
+export declare const server_alias_1: ServerType;
+
+export { }

package/dist/chunk-QWYMT5LP.js

@@ -0,0 +1,194 @@
+import path from 'path';
+import fs from 'node:fs/promises';
+import path4 from 'node:path';
+
+// src/utils.ts
+function fromRepoRoot(relative) {
+  return path.resolve(import.meta.dirname, `../../../`, relative);
+}
+function fromPackageRoot(relative) {
+  return path.resolve(import.meta.dirname, `../`, relative);
+}
+var log = console.error;
+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 });
+  } catch {
+  }
+  await fs.mkdir(OUTPUT_DIR, { recursive: true });
+  const examples = await fs.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");
+      files.push({
+        path: "package.json",
+        content: packageJson
+      });
+    } catch {
+    }
+    try {
+      const srcPath = path4.join(examplePath, "src");
+      await scanDirectory(srcPath, srcPath, files);
+    } catch {
+    }
+    if (files.length > 0) {
+      const output = files.map((file) => `### ${file.path}
+\`\`\`${getFileType(file.path)}
+${file.content}
+\`\`\`
+`).join("\n");
+      const totalLines = output.split("\n").length;
+      if (totalLines > 500) {
+        log(`Skipping ${dir.name}: ${totalLines} lines exceeds limit of 500`);
+        continue;
+      }
+      await fs.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 });
+  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");
+      files.push({
+        path: relativePath,
+        content
+      });
+    }
+  }
+}
+function getFileType(filePath) {
+  if (filePath === "package.json") return "json";
+  if (filePath.endsWith(".ts")) return "typescript";
+  return "";
+}
+var DOCS_SOURCE = fromRepoRoot("docs/src/content/docs");
+var REFERENCE_SOURCE = fromRepoRoot("docs/src/content/reference");
+var DOCS_DEST = fromPackageRoot(".docs/raw");
+var REFERENCE_DEST = path4.join(DOCS_DEST, "reference");
+async function copyDir(src, dest) {
+  await fs.mkdir(dest, { recursive: true });
+  const entries = await fs.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")) {
+      await fs.copyFile(srcPath, destPath);
+    }
+  }
+}
+async function copyRaw() {
+  try {
+    try {
+      await fs.rm(DOCS_DEST, { recursive: true });
+    } catch {
+    }
+    await copyDir(DOCS_SOURCE, DOCS_DEST);
+    await copyDir(REFERENCE_SOURCE, REFERENCE_DEST);
+    log("\u2705 Documentation files copied successfully");
+  } catch (error) {
+    console.error("\u274C Failed to copy documentation files:", error);
+    process.exit(1);
+  }
+}
+var SOURCE_DIRS = ["packages", "speech", "stores", "voice", "integrations", "deployers", "client-sdks"].map(
+  fromRepoRoot
+);
+var CHANGELOGS_DEST = fromPackageRoot(".docs/organized/changelogs");
+var MAX_LINES = 300;
+function truncateContent(content, maxLines) {
+  const lines = content.split("\n");
+  if (lines.length <= maxLines) return content;
+  const visibleLines = lines.slice(0, maxLines);
+  const hiddenCount = lines.length - maxLines;
+  return visibleLines.join("\n") + `
+
+... ${hiddenCount} more lines hidden. See full changelog in package directory.`;
+}
+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"));
+    packageName = packageJson.name;
+    if (!packageName) {
+      log(`Skipping ${path4.basename(packagePath)}: No package name found in package.json`);
+      return;
+    }
+  } catch {
+    console.error(`Skipping ${path4.basename(packagePath)}: No valid package.json found`);
+    return;
+  }
+  try {
+    const changelogPath = path4.join(packagePath, "CHANGELOG.md");
+    let changelog;
+    try {
+      changelog = await fs.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");
+    log(`Generated changelog for ${packageName}`);
+  } catch (error) {
+    console.error(`Error processing changelog for ${packageName}:`, error);
+  }
+}
+async function preparePackageChanges() {
+  const outputDir = path4.resolve(process.cwd(), CHANGELOGS_DEST);
+  try {
+    await fs.rm(outputDir, { recursive: true, force: true });
+  } catch {
+  }
+  await fs.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 });
+      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);
+        await processPackageDir(packagePath, outputDir);
+      }
+    } catch {
+      console.error(`Skipping ${sourceDir}: Directory not found or not accessible`);
+    }
+  }
+}
+
+// src/prepare-docs/prepare.ts
+async function prepare() {
+  log("Preparing documentation...");
+  await copyRaw();
+  log("Preparing code examples...");
+  await prepareCodeExamples();
+  log("Preparing package changelogs...");
+  await preparePackageChanges();
+  log("Documentation preparation complete!");
+}
+if (process.env.PREPARE === `true`) {
+  try {
+    await prepare();
+  } catch (error) {
+    console.error("Error preparing documentation:", error);
+    process.exit(1);
+  }
+}
+
+export { fromPackageRoot, prepare };

package/dist/prepare-docs/prepare.d.ts

@@ -0,0 +1 @@
+export { prepare } from '../_tsup-dts-rollup.js';

package/dist/prepare-docs/prepare.js

@@ -0,0 +1 @@
+export { prepare } from '../chunk-QWYMT5LP.js';

package/dist/stdio.d.ts

@@ -0,0 +1 @@
+export {};