@mastra/mcp-docs-server 0.13.3 → 0.13.4

package/.docs/raw/frameworks/agentic-uis/assistant-ui.mdx

@@ -10,180 +10,11 @@ import { Callout, FileTree, Steps } from 'nextra/components'
 [Assistant UI](https://assistant-ui.com) is the TypeScript/React library for AI Chat.
 Built on shadcn/ui and Tailwind CSS, it enables developers to create beautiful, enterprise-grade chat experiences in minutes.
 
-## Integrating with Next.js and Assistant UI
-
-There are two primary ways to integrate Mastra into your Next.js project when using Assistant UI:
-
-1. **Full-Stack Integration**: Integrate Mastra directly into your Next.js application's API routes. This approach keeps your backend and frontend code within the same project. [Learn how to set up Full-Stack Integration](#full-stack-integration)
-2. **Separate Backend Integration**: Run Mastra as a standalone server and connect your Next.js frontend to its API endpoints. This approach separates concerns and allows for independent scaling. [Learn how to set up Separate Backend Integration](#separate-backend-integration)
-
-## Full-Stack Integration
-
-<Steps>
-### Initialize Assistant UI
-
-There are two options when setting up Assistant UI using the `assistant-ui` CLI:
-
-1. **New Project**: Create a new Next.js project with Assistant UI.
-2. **Existing Project**: Initialize Assistant UI into an existing React project.
-
-#### New Project
-
-```bash copy
-npx assistant-ui@latest create
-```
-
-#### Existing Project
-
-```bash copy
-npx assistant-ui@latest init
-```
-
-<Callout>For detailed setup instructions, including adding API keys, basic configuration, and manual setup steps, please refer to [assistant-ui's official documentation](https://assistant-ui.com/docs).</Callout>
-
-
-### Install Mastra Packages
-
-Install the required Mastra packages:
-
-```bash copy
-npm install @mastra/core@latest @mastra/memory@latest @mastra/libsql@latest
-```
-
-### Configure Next.js
-
-To ensure Next.js correctly bundles your application when using Mastra directly in API routes, you need to configure `serverExternalPackages`.
-
-Update your `next.config.js` file to include `@mastra/`:
-
-```js showLineNumbers copy {3}
-/** @type {import('next').NextConfig} */
-const nextConfig = {
-  serverExternalPackages: ["@mastra/*"],
-  // ... your other Next.js config
-};
-
-module.exports = nextConfig;
-```
-
-### Configure Mastra Memory and Storage
-
-```typescript showLineNumbers copy filename="mastra/memory.ts" {4,8}
-import { LibSQLStore } from "@mastra/libsql";
-import { Memory } from "@mastra/memory";
-
-export const storage = new LibSQLStore({
-    url: 'file:./memory.db',
-})
-
-export const memory = new Memory({
-    storage,
-})
-```
-
-<Callout>
-If deploying to the edge, you should use a compatible storage solution and not a file-based storage.
+<Callout type="info">
+For a full-stack integration approach where Mastra runs directly in your Next.js API routes, see the [Full-Stack Integration Guide](https://www.assistant-ui.com/docs/runtimes/mastra/full-stack-integration) on Assistant UI's documentation site.
 </Callout>
 
-### Define Mastra Agent
-
-```typescript showLineNumbers copy filename="mastra/agents/chef-agent.ts" {5-12}
-import { openai } from "@ai-sdk/openai";
-import { Agent } from "@mastra/core/agent";
-import { memory} from "../memory";
-
-export const chefAgent = new Agent({
-  name: "chefAgent",
-  instructions:
-    "You are Michel, a practical and experienced home chef. " +
-    "You help people cook with whatever ingredients they have available.",
-  model: openai("gpt-4o-mini"),
-  memory,
-});
-```
-
-### Register Agent to Mastra Instance
-
-```typescript showLineNumbers copy filename="mastra/index.ts" {4-5}
-import { Mastra } from "@mastra/core";
-import { chefAgent } from "./agents/chef-agent";
-
-export const mastra = new Mastra({
-    agents: { chefAgent },
-    // ... other config
-});
-```
-
-This initializes Mastra and makes the `chefAgent` available for use.
-
-### Modify the Chat API endpoints
-
-The initial bootstrapped Next.js project has a `app/api/chat/route.ts` file that exports a `POST` handler. The initial implementation may look like this:
-
-```typescript showLineNumbers copy filename="app/api/chat/route.ts" {11-21}
-import { openai } from "@ai-sdk/openai";
-import { frontendTools } from "@assistant-ui/react-ai-sdk";
-import { streamText } from "ai";
-
-export const runtime = "edge";
-export const maxDuration = 30;
-
-export async function POST(req: Request) {
-  const { messages, system, tools } = await req.json();
-
-  const result = streamText({
-    model: openai("gpt-4o"),
-    messages,
-    // forward system prompt and tools from the frontend
-    toolCallStreaming: true,
-    system,
-    tools: {
-      ...frontendTools(tools),
-    },
-    onError: console.log,
-  });
-
-  return result.toDataStreamResponse();
-}
-```
-
-Now we need to modify the `POST` handler to use the `chefAgent` instead of this implementation.
-
-```typescript showLineNumbers copy filename="app/api/chat/route.ts" {1,6,8}
-import { mastra } from "@/mastra";
-
-export async function POST(req: Request) {
-  const { messages } = await req.json();
-
-  const agent = mastra.getAgent("chefAgent");
-
-  const stream = await agent.stream(messages);
-
-  return stream.toDataStreamResponse();
-}
-```
-
-Key changes
-- We import the `mastra` instance we created.
-- We use the `mastra.getAgent("chefAgent")` to get the agent we want to use.
-- We use the `agent.stream(messages)` to get the stream of messages from the agent.
-- We return the stream as a data stream response which is compatible with `assistant-ui`.
-
-### Run the application
-
-You're all set! Start your Next.js development server:
-
-```bash copy
-npm run dev
-```
-
-You should now be able to chat with your agent in the browser.
-
-</Steps>
-
-Congratulations! You have successfully integrated Mastra into your Next.js application using the full-stack approach. Your Assistant UI frontend now communicates with a Mastra agent running in your Next.js backend API route.
-
-## Separate Backend Integration
+## Integration Guide
 
 Run Mastra as a standalone server and connect your Next.js frontend (with Assistant UI) to its API endpoints.
 
@@ -215,41 +46,29 @@ npx create-mastra@latest
 This command will launch an interactive wizard to help you scaffold a new Mastra project, including prompting you for a project name and setting up basic configurations.
 Follow the prompts to create your server project.
 
-You now have a basic Mastra server project ready.
+You now have a basic Mastra server project ready. You should have the following files and folders:
+
+<FileTree>
+    <FileTree.Folder name="src" defaultOpen>
+      <FileTree.Folder name="mastra" defaultOpen>
+        <FileTree.File name="index.ts" />
+        <FileTree.Folder name="agents" defaultOpen>
+          <FileTree.File name="weather-agent.ts" />
+        </FileTree.Folder>
+        <FileTree.Folder name="tools" defaultOpen>
+          <FileTree.File name="weather-tool.ts" />
+        </FileTree.Folder>
+        <FileTree.Folder name="workflows" defaultOpen>
+          <FileTree.File name="weather-workflow.ts" />
+        </FileTree.Folder>
+      </FileTree.Folder>
+    </FileTree.Folder>
+</FileTree>
 
 <Callout>
 Ensure that you have set the appropriate environment variables for your LLM provider in the `.env` file.
 </Callout>
 
-### Define Mastra Agent
-
-```typescript showLineNumbers copy filename="mastra/agents/chef-agent.ts" {5-12}
-import { openai } from "@ai-sdk/openai";
-import { Agent } from "@mastra/core/agent";
-import { memory} from "../memory";
-
-export const chefAgent = new Agent({
-  name: "chefAgent",
-  instructions:
-    "You are Michel, a practical and experienced home chef. " +
-    "You help people cook with whatever ingredients they have available.",
-  model: openai("gpt-4o-mini"),
-  memory,
-});
-```
-
-### Register Agent to Mastra Instance
-
-```typescript copy filename="mastra/index.ts" showLineNumbers
-import { Mastra } from "@mastra/core";
-import { chefAgent } from "./agents/chef-agent";
-
-export const mastra = new Mastra({
-    agents: { chefAgent },
-    // ... other config
-});
-```
-
 ### Run the Mastra Server
 
 Run the Mastra server using the following command:
@@ -258,38 +77,27 @@ Run the Mastra server using the following command:
 npm run dev
 ```
 
-By default, the Mastra server will run on http://localhost:4111. Your chefAgent should now be accessible via a POST request endpoint, typically http://localhost:4111/api/agents/chefAgent/stream. Keep this server running for the next steps where we'll set up the Assistant UI frontend to connect to it.
+By default, the Mastra server will run on `http://localhost:4111`. Your `weatherAgent` should now be accessible via a POST request endpoint, typically `http://localhost:4111/api/agents/weatherAgent/stream`. Keep this server running for the next steps where we'll set up the Assistant UI frontend to connect to it.
 
 ### Initialize Assistant UI
 
-There are two options when setting up Assistant UI using the `assistant-ui` CLI:
-
-1. **New Project**: Create a new Next.js project with Assistant UI.
-2. **Existing Project**: Initialize Assistant UI into an existing React project.
-
-#### New Project
+Create a new `assistant-ui` project with the following command.
 
 ```bash copy
 npx assistant-ui@latest create
 ```
 
-#### Existing Project
-
-```bash copy
-npx assistant-ui@latest init
-```
-
 <Callout>For detailed setup instructions, including adding API keys, basic configuration, and manual setup steps, please refer to [assistant-ui's official documentation](https://assistant-ui.com/docs).</Callout>
 
 ### Configure Frontend API Endpoint
 
 The default Assistant UI setup configures the chat runtime to use a local API route (`/api/chat`) within the Next.js project. Since our Mastra agent is running on a separate server, we need to update the frontend to point to that server's endpoint.
 
-Open the main page file in your Assistant UI frontend project (usually `app/page.tsx` or `src/app/page.tsx`). Find the `useChatRuntime` hook and change the `api` property to the full URL of your Mastra agent's stream endpoint:
+Find the `useChatRuntime` hook in the `assistant-ui` project, typically at `app/assistant.tsx` and change the `api` property to the full URL of your Mastra agent's stream endpoint:
 
-```typescript showLineNumbers copy filename="app/page.tsx" {2}
+```typescript showLineNumbers copy filename="app/assistant.tsx" {2}
 const runtime = useChatRuntime({
-    api: "http://localhost:4111/api/agents/chefAgent/stream",
+    api: "http://localhost:4111/api/agents/weatherAgent/stream",
 });
 ```
 
@@ -307,4 +115,4 @@ You should now be able to chat with your agent in the browser.
 
 </Steps>
 
-Congratulations! You have successfully integrated Mastra with Assistant UI using a separate server approach. Your Assistant UI frontend now communicates with a standalone Mastra agent server.
+Congratulations! You have successfully integrated Mastra with Assistant UI using a separate server approach. Your Assistant UI frontend now communicates with a standalone Mastra agent server.

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

@@ -1,7 +1,7 @@
 import { MCPClient } from '@mastra/mcp';
 import { MCPServer } from '@mastra/mcp';
 import { ServerType } from '@hono/node-server/.';
-import { z } from 'zod';
+import z from 'zod';
 
 export declare type BlogInput = z.infer<typeof blogInputSchema>;
 
@@ -13,6 +13,60 @@ export declare const blogInputSchema: z.ZodObject<{
     url: string;
 }>;
 
+export declare const blogPostSchema: z.ZodObject<{
+    slug: z.ZodString;
+    content: z.ZodString;
+    metadata: z.ZodObject<{
+        title: z.ZodString;
+        publishedAt: z.ZodString;
+        summary: z.ZodString;
+        image: z.ZodOptional<z.ZodString>;
+        author: z.ZodOptional<z.ZodString>;
+        draft: z.ZodDefault<z.ZodOptional<z.ZodBoolean>>;
+        categories: z.ZodUnion<[z.ZodArray<z.ZodString, "many">, z.ZodString]>;
+    }, "strip", z.ZodTypeAny, {
+        title: string;
+        publishedAt: string;
+        summary: string;
+        draft: boolean;
+        categories: string | string[];
+        image?: string | undefined;
+        author?: string | undefined;
+    }, {
+        title: string;
+        publishedAt: string;
+        summary: string;
+        categories: string | string[];
+        image?: string | undefined;
+        author?: string | undefined;
+        draft?: boolean | undefined;
+    }>;
+}, "strip", z.ZodTypeAny, {
+    content: string;
+    slug: string;
+    metadata: {
+        title: string;
+        publishedAt: string;
+        summary: string;
+        draft: boolean;
+        categories: string | string[];
+        image?: string | undefined;
+        author?: string | undefined;
+    };
+}, {
+    content: string;
+    slug: string;
+    metadata: {
+        title: string;
+        publishedAt: string;
+        summary: string;
+        categories: string | string[];
+        image?: string | undefined;
+        author?: string | undefined;
+        draft?: boolean | undefined;
+    };
+}>;
+
 export declare const blogTool: {
     name: string;
     description: string;

package/dist/{chunk-7QXT2IEP.js → chunk-TUAHUTTB.js}

@@ -1,6 +1,7 @@
 import fs2 from 'fs/promises';
 import path4, { dirname } from 'path';
 import { fileURLToPath } from 'url';
+import z from 'zod';
 
 // src/utils.ts
 var mdxFileCache = /* @__PURE__ */ new Map();
@@ -117,6 +118,19 @@ async function getMatchingPaths(path5, queryKeywords, baseDir) {
 
 ${pathList}`;
 }
+var blogPostSchema = z.object({
+  slug: z.string(),
+  content: z.string(),
+  metadata: z.object({
+    title: z.string(),
+    publishedAt: z.string(),
+    summary: z.string(),
+    image: z.string().optional(),
+    author: z.string().optional(),
+    draft: z.boolean().optional().default(false),
+    categories: z.array(z.string()).or(z.string())
+  })
+});
 var EXAMPLES_SOURCE = fromRepoRoot("examples");
 var OUTPUT_DIR = fromPackageRoot(".docs/organized/code-examples");
 async function loadExampleConfig(examplePath) {
@@ -339,4 +353,4 @@ if (process.env.PREPARE === `true`) {
   }
 }
 
-export { fromPackageRoot, getMatchingPaths, prepare };
+export { blogPostSchema, fromPackageRoot, getMatchingPaths, prepare };

package/dist/prepare-docs/prepare.js

@@ -1 +1 @@
-export { prepare } from '../chunk-7QXT2IEP.js';
+export { prepare } from '../chunk-TUAHUTTB.js';

package/dist/stdio.js

@@ -1,5 +1,5 @@
 #!/usr/bin/env node
-import { fromPackageRoot, prepare, getMatchingPaths } from './chunk-7QXT2IEP.js';
+import { fromPackageRoot, prepare, getMatchingPaths, blogPostSchema } from './chunk-TUAHUTTB.js';
 import * as fs from 'fs';
 import { existsSync, mkdirSync } from 'fs';
 import * as os2 from 'os';
@@ -8,7 +8,6 @@ import * as path3 from 'path';
 import path3__default from 'path';
 import fs3 from 'fs/promises';
 import { MCPServer } from '@mastra/mcp';
-import { JSDOM } from 'jsdom';
 import { z } from 'zod';
 
 var writeErrorLog = (message, data) => {
@@ -76,22 +75,20 @@ var logger = createLogger();
 var BLOG_BASE_URL = process.env.BLOG_URL || "https://mastra.ai";
 async function fetchBlogPosts() {
   void logger.debug("Fetching list of blog posts");
-  const response = await fetch(`${BLOG_BASE_URL}/blog`);
+  const response = await fetch(`${BLOG_BASE_URL}/api/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");
+  const blogData = await response.json();
+  const blogPosts = blogPostSchema.array().safeParse(blogData);
+  if (!blogPosts.success) {
+    return "Failed to parse blog posts";
+  }
+  const blogLinks = blogPosts.data.map((post) => {
+    const title = post.metadata.title;
+    const href = post.slug;
     if (title && href) {
-      return `[${title}](${href})`;
+      return `[${title}](${BLOG_BASE_URL}/blog/${href}) | [Markdown URL](${BLOG_BASE_URL}/api/blog/${href})`;
     }
     return null;
   }).filter(Boolean);
@@ -121,12 +118,12 @@ ${blogPosts}`;
 
 ${blogList}`;
   }
-  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() || "";
+  const blogData = await response.json();
+  const blogPost = blogPostSchema.safeParse(blogData);
+  if (!blogPost.success) {
+    return "Failed to parse blog post";
+  }
+  const content = blogPost.data.content;
   if (!content) {
     throw new Error("No content found in blog post");
   }
@@ -134,7 +131,7 @@ ${blogList}`;
 }
 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."
+    "URL of a specific blog post to fetch. If the string /api/blog is passed as the url it returns a list of all blog posts. The markdownUrl is the URL of a single blog post which can be used to fetch the blog post content in markdown format."
   )
 });
 var blogTool = {
@@ -145,8 +142,8 @@ var blogTool = {
     void logger.debug("Executing mastraBlog tool", { url: args.url });
     try {
       let content;
-      if (args.url !== `/blog`) {
-        content = await fetchBlogPost(`${BLOG_BASE_URL}${args.url}`);
+      if (args.url.trim() !== `/api/blog`) {
+        content = await fetchBlogPost(args.url);
       } else {
         content = await fetchBlogPosts();
       }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mastra/mcp-docs-server",
-  "version": "0.13.3",
+  "version": "0.13.4",
   "description": "MCP server for accessing Mastra.ai documentation, changelogs, and news.",
   "type": "module",
   "main": "dist/index.js",
@@ -47,8 +47,8 @@
     "tsx": "^4.19.4",
     "typescript": "^5.8.3",
     "vitest": "^3.2.4",
-    "@internal/lint": "0.0.16",
-    "@mastra/core": "0.10.9"
+    "@internal/lint": "0.0.17",
+    "@mastra/core": "0.10.10"
   },
   "peerDependencies": {
     "@mastra/core": "^0.10.0-alpha.0"