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

package/dist/stdio.js

@@ -1,9 +1,356 @@
 #!/usr/bin/env node
-import { prepare } from './prepare-docs/prepare.js';
-if (process.env.REBUILD_DOCS_ON_START === 'true') {
-    await prepare();
+import { fromPackageRoot, prepare } from './chunk-YEOOTUPA.js';
+import fs2 from 'node:fs/promises';
+import { FastMCP } from 'tylerbarnes-fastmcp-fix';
+import { JSDOM } from 'jsdom';
+import { z } from 'zod';
+import path2 from 'node:path';
+
+async function fetchBlogPosts() {
+  try {
+    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");
+  } catch (error) {
+    throw new Error("Failed to fetch blog posts " + JSON.stringify(error));
+  }
 }
-const { server } = await import(`./index.js`);
+async function fetchBlogPost(url) {
+  try {
+    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;
+  } catch (error) {
+    throw new Error(`Failed to fetch blog post: ${error instanceof Error ? error.message : "Unknown error"}`);
+  }
+}
+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",
+  parameters: 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."
+    )
+  }),
+  execute: async (args) => {
+    try {
+      if (args.url !== `/blog`) {
+        return await fetchBlogPost(`https://mastra.ai${args.url}`);
+      } else {
+        return await fetchBlogPosts();
+      }
+    } catch (error) {
+      if (error instanceof Error) {
+        throw new Error("Failed to fetch blog posts");
+      }
+      throw error;
+    }
+  }
+};
+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 changesSchema = 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,
+  parameters: changesSchema,
+  execute: async (args, _context) => {
+    if (!args.package) {
+      const packages = await listPackageChangelogs();
+      return ["Available package changelogs:", "", ...packages.map((pkg) => `- ${pkg.name}`)].join("\n");
+    }
+    const content = await readPackageChangelog(args.package);
+    return content;
+  }
+};
+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 (error) {
+    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 docsSchema = 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",
+  parameters: docsSchema,
+  execute: async (args, _context) => {
+    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 output;
+    } catch (error) {
+      if (error instanceof Error) {
+        throw new Error(`Failed to fetch documentation: ${error.message}`);
+      }
+      throw error;
+    }
+  }
+};
+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 examplesSchema = 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.",
+  parameters: examplesSchema,
+  execute: async (args, _context) => {
+    if (!args.example) {
+      const examples = await listCodeExamples();
+      return ["Available code examples:", "", ...examples.map((ex) => `- ${ex.name}`)].join("\n");
+    }
+    const filename = args.example.endsWith(".md") ? args.example : `${args.example}.md`;
+    const content = await readCodeExample(filename);
+    return content;
+  }
+};
+
+// src/index.ts
+if (process.env.REBUILD_DOCS_ON_START === "true") {
+  await prepare();
+}
+var server = new FastMCP({
+  name: "Mastra Documentation Server",
+  version: JSON.parse(await fs2.readFile(fromPackageRoot(`package.json`), "utf8")).version
+});
+server.addTool(blogTool);
+server.addTool(docsTool);
+server.addTool(examplesTool);
+server.addTool(changesTool);
+
+// src/stdio.ts
 void server.start({
-    transportType: 'stdio',
+  transportType: "stdio"
 });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mastra/mcp-docs-server",
-  "version": "0.0.4-alpha.0",
+  "version": "0.0.4",
   "description": "MCP server for accessing Mastra.ai documentation, changelogs, and news.",
   "type": "module",
   "main": "dist/index.js",
@@ -16,10 +16,6 @@
       "import": {
         "types": "./dist/index.d.ts",
         "default": "./dist/index.js"
-      },
-      "require": {
-        "types": "./dist/index.d.cts",
-        "default": "./dist/index.cjs"
       }
     },
     "./package.json": "./package.json"
@@ -37,29 +33,27 @@
     "tylerbarnes-fastmcp-fix": "^1.0.0",
     "uuid": "^11.1.0",
     "zod": "^3.22.4",
-    "@mastra/core": "^0.6.4-alpha.0"
+    "@mastra/core": "^0.6.4"
   },
   "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",
     "eslint": "^9.22.0",
+    "hono": "^4.7.4",
     "tsup": "^8.4.0",
     "tsx": "^4.7.1",
     "typescript": "^5.3.3",
     "vitest": "^3.0.8",
-    "@internal/lint": "0.0.1"
+    "@internal/lint": "0.0.1",
+    "@mastra/mcp": "^0.3.5"
   },
   "scripts": {
-    "prepare-docs": "tsx src/prepare-docs/index.ts",
-    "prebuild": "pnpm prepare-docs",
-    "build": "tsc && chmod +x dist/stdio.js",
-    "predev": "pnpm prepare-docs",
-    "dev": "fastmcp dev src/index.ts",
-    "inspect": "fastmcp inspect src/index.ts",
-    "build:watch": "pnpm build --watch",
-    "pretest": "pnpm build",
+    "prepare-docs": "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 ."
   }

package/.docs/raw/deployment/logging-and-tracing.mdx

@@ -1,242 +0,0 @@
----
-title: "Logging and Tracing | Mastra Deployment Documentation"
-description: Documentation on effective logging and tracing in Mastra, crucial for understanding application behavior and improving AI accuracy.
----
-
-import Image from "next/image";
-
-# Logging and Tracing
-
-Effective logging and tracing are crucial for understanding the behavior of your application.
-
-Tracing is especially important for AI engineering. Teams building AI products find that visibility into inputs and outputs of every step of every run is crucial to improving accuracy. You get this with Mastra's telemetry.
-
-## Logging
-
-In Mastra, logs can detail when certain functions run, what input data they receive, and how they respond.
-
-### Basic Setup
-
-Here's a minimal example that sets up a **console logger** at the `INFO` level. This will print out informational messages and above (i.e., `INFO`, `WARN`, `ERROR`) to the console.
-
-```typescript filename="mastra.config.ts" showLineNumbers copy
-import { Mastra } from "@mastra/core";
-import { createLogger } from "@mastra/core/logger";
-
-export const mastra = new Mastra({
-  // Other Mastra configuration...
-  logger: createLogger({
-    name: "Mastra",
-    level: "info",
-  }),
-});
-```
-
-In this configuration:
-
-- `name: "Mastra"` specifies the name to group logs under.
-- `level: "info"` sets the minimum severity of logs to record.
-
-### Configuration
-
-- For more details on the options you can pass to `createLogger()`, see the [createLogger reference documentation](/docs/reference/observability/create-logger.mdx).
-- Once you have a `Logger` instance, you can call its methods (e.g., `.info()`, `.warn()`, `.error()`) in the [Logger instance reference documentation](/docs/reference/observability/logger.mdx).
-- If you want to send your logs to an external service for centralized collection, analysis, or storage, you can configure other logger types such as Upstash Redis. Consult the [createLogger reference documentation](/docs/reference/observability/create-logger.mdx) for details on parameters like `url`, `token`, and `key` when using the `UPSTASH` logger type.
-
-## Telemetry
-
-Mastra supports the OpenTelemetry Protocol (OTLP) for tracing and monitoring your application. When telemetry is enabled, Mastra automatically traces all core primitives including agent operations, LLM interactions, tool executions, integration calls, workflow runs, and database operations. Your telemetry data can then be exported to any OTEL collector.
-
-### Basic Configuration
-
-Here's a simple example of enabling telemetry:
-
-```ts filename="mastra.config.ts" showLineNumbers copy
-export const mastra = new Mastra({
-  // ... other config
-  telemetry: {
-    serviceName: "my-app",
-    enabled: true,
-    sampling: {
-      type: "always_on",
-    },
-    export: {
-      type: "otlp",
-      endpoint: "http://localhost:4318", // SigNoz local endpoint
-    },
-  },
-});
-```
-
-### Configuration Options
-
-The telemetry config accepts these properties:
-
-```ts
-type OtelConfig = {
-  // Name to identify your service in traces (optional)
-  serviceName?: string;
-
-  // Enable/disable telemetry (defaults to true)
-  enabled?: boolean;
-
-  // Control how many traces are sampled
-  sampling?: {
-    type: "ratio" | "always_on" | "always_off" | "parent_based";
-    probability?: number; // For ratio sampling
-    root?: {
-      probability: number; // For parent_based sampling
-    };
-  };
-
-  // Where to send telemetry data
-  export?: {
-    type: "otlp" | "console";
-    endpoint?: string;
-    headers?: Record<string, string>;
-  };
-};
-```
-
-See the [OtelConfig reference documentation](/docs/reference/observability/otel-config.mdx) for more details.
-
-### Environment Variables
-
-You can configure the OTLP endpoint and headers through environment variables:
-
-```env filename=".env" copy
-OTEL_EXPORTER_OTLP_ENDPOINT=http://localhost:4318
-OTEL_EXPORTER_OTLP_HEADERS=x-api-key=your-api-key
-```
-
-Then in your config:
-
-```ts filename="mastra.config.ts" showLineNumbers copy
-export const mastra = new Mastra({
-  // ... other config
-  telemetry: {
-    serviceName: "my-app",
-    enabled: true,
-    export: {
-      type: "otlp",
-      // endpoint and headers will be picked up from env vars
-    },
-  },
-});
-```
-
-### Example: SigNoz Integration
-
-Here's what a traced agent interaction looks like in [SigNoz](https://signoz.io):
-
-<img
-  src="/docs/signoz-telemetry-demo.png"
-  alt="Agent interaction trace showing spans, LLM calls, and tool executions"
-  style={{ maxWidth: "800px", width: "100%", margin: "8px 0" }}
-  className="nextra-image rounded-md"
-  data-zoom
-  width={800}
-  height={400}
-/>
-
-### Other Supported Providers
-
-For a complete list of supported observability providers and their configuration details, see the [Observability Providers reference](../reference/observability/providers/).
-
-## Next.js Configuration
-
-If you're using Next.js, you have two options for setting up OpenTelemetry instrumentation:
-
-#### Option 1: Using Vercel's OTEL Setup
-
-If you're deploying to Vercel, you can use their built-in OpenTelemetry setup:
-
-1. Install the required dependencies:
-
-```bash copy
-npm install @opentelemetry/api @vercel/otel
-```
-
-2. Create an instrumentation file at the root of your project (or in the src folder if using one):
-
-```ts filename="instrumentation.ts" copy
-import { registerOTel } from '@vercel/otel'
-
-export function register() {
-  registerOTel({ serviceName: 'your-project-name' })
-}
-```
-
-#### Option 2: Using Custom Exporters
-
-If you're using other observability tools (like Langfuse), you can configure a custom exporter:
-
-1. Install the required dependencies (example using Langfuse):
-
-```bash copy
-npm install @opentelemetry/api langfuse-vercel
-```
-
-2. Create an instrumentation file:
-
-```ts filename="instrumentation.ts" copy
-import {
-  NodeSDK,
-  ATTR_SERVICE_NAME,
-  Resource,
-} from '@mastra/core/telemetry/otel-vendor';
-import { LangfuseExporter } from 'langfuse-vercel';
-
-export function register() {
-  const exporter = new LangfuseExporter({
-    // ... Langfuse config
-  })
-
-  const sdk = new NodeSDK({
-    resource: new Resource({
-      [ATTR_SERVICE_NAME]: 'ai',
-    }),
-    traceExporter: exporter,
-  });
- 
-  sdk.start();
-}
-```
-
-#### Next.js Configuration
-
-For either option, enable the instrumentation hook in your Next.js config:
-
-```ts filename="next.config.ts" showLineNumbers copy
-import type { NextConfig } from "next";
-
-const nextConfig: NextConfig = {
-  experimental: {
-    instrumentationHook: true // Not required in Next.js 15+
-  }
-};
-
-export default nextConfig;
-```
-
-#### Mastra Configuration
-
-Configure your Mastra instance:
-
-```typescript filename="mastra.config.ts" copy
-import { Mastra } from "@mastra/core";
-
-export const mastra = new Mastra({
-  // ... other config
-  telemetry: {
-    serviceName: "your-project-name",
-    enabled: true
-  }
-});
-```
-
-This setup will enable OpenTelemetry tracing for your Next.js application and Mastra operations.
-
-For more details, see the documentation for:
-- [Next.js Instrumentation](https://nextjs.org/docs/app/building-your-application/optimizing/instrumentation)
-- [Vercel OpenTelemetry](https://vercel.com/docs/observability/otel-overview/quickstart)

package/dist/index.d.ts

@@ -1,3 +0,0 @@
-import { FastMCP } from 'tylerbarnes-fastmcp-fix';
-declare const server: FastMCP<undefined>;
-export { server };

package/dist/index.js

@@ -1,19 +0,0 @@
-import fs from 'node:fs/promises';
-import { FastMCP } from 'tylerbarnes-fastmcp-fix';
-import { blogTool } from './tools/blog.js';
-import { changesTool } from './tools/changes.js';
-import { docsTool } from './tools/docs.js';
-import { examplesTool } from './tools/examples.js';
-import { fromPackageRoot } from './utils.js';
-// console.error('Starting Mastra Documentation Server...');
-// console.error('Docs base dir:', path.join(__dirname, '../.docs/raw/'));
-const server = new FastMCP({
-    name: 'Mastra Documentation Server',
-    version: JSON.parse(await fs.readFile(fromPackageRoot(`package.json`), 'utf8')).version,
-});
-// Add tools
-server.addTool(blogTool);
-server.addTool(docsTool);
-server.addTool(examplesTool);
-server.addTool(changesTool);
-export { server };

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

@@ -1,4 +0,0 @@
-/**
- * Scans example directories and creates flattened code example files
- */
-export declare function prepareCodeExamples(): Promise<void>;