@mastra/mcp-docs-server 1.1.4 → 1.1.5-alpha.0

package/.docs/guides/getting-started/vite-react.md

@@ -1,439 +0,0 @@
-# Integrate Mastra in your React + Vite project
-
-In this guide, you'll build a tool-calling AI agent using Mastra, then connect it to React by calling the agent directly from Mastra's standalone server.
-
-You'll use [AI SDK UI](https://ai-sdk.dev/docs/ai-sdk-ui/overview) and [AI Elements](https://ai-sdk.dev/elements) to create a beautiful, interactive chat experience.
-
-## Before you begin
-
-- You'll need an API key from a supported [model provider](https://mastra.ai/models). If you don't have a preference, use [OpenAI](https://mastra.ai/models/providers/openai).
-- Install Node.js `v22.13.0` or later
-
-## Create a new React + Vite app (optional)
-
-If you already have a React + Vite app using Tailwind, skip to the next step.
-
-### Project scaffold
-
-Run the following command to [create a new React + Vite app](https://vite.dev/guide/#scaffolding-your-first-vite-project):
-
-**npm**:
-
-```bash
-npm create vite@latest mastra-react -- --template react-ts
-```
-
-**pnpm**:
-
-```bash
-pnpm create vite mastra-react --template react-ts
-```
-
-**Yarn**:
-
-```bash
-yarn create vite mastra-react --template react-ts
-```
-
-**Bun**:
-
-```bash
-bunx create-vite mastra-react --template react-ts
-```
-
-This creates a project called `mastra-react`, but you can replace it with any name you want.
-
-Navigate to your project directory:
-
-```bash
-cd mastra-react
-```
-
-### Tailwind
-
-Next, install Tailwind:
-
-**npm**:
-
-```bash
-npm install tailwindcss @tailwindcss/vite
-```
-
-**pnpm**:
-
-```bash
-pnpm add tailwindcss @tailwindcss/vite
-```
-
-**Yarn**:
-
-```bash
-yarn add tailwindcss @tailwindcss/vite
-```
-
-**Bun**:
-
-```bash
-bun add tailwindcss @tailwindcss/vite
-```
-
-Configure the Vite plugins:
-
-```typescript
-import { defineConfig } from 'vite'
-import react from '@vitejs/plugin-react'
-import path from "path"
-import tailwindcss from '@tailwindcss/vite'
-
-export default defineConfig({
-  plugins: [react(), tailwindcss()],
-  resolve: {
-    alias: {
-      "@": path.resolve(__dirname, "./src"),
-    },
-  },
-})
-```
-
-Replace everything in `src/index.css` with the following:
-
-```css
-@import "tailwindcss";
-```
-
-Add these `compilerOptions` to `tsconfig.json`:
-
-```ts
-{
-  // ...
-  "compilerOptions": {
-    "baseUrl": ".",
-    "paths": {
-      "@/*": ["./src/*"]
-    }
-  }
-}
-```
-
-Edit `tsconfig.app.json` to resolve paths:
-
-```ts
-{
-  "compilerOptions": {
-    // ...
-    "baseUrl": ".",
-    "paths": {
-      "@/*": [
-        "./src/*"
-      ]
-    }
-    // ...
-  }
-}
-```
-
-## Initialize Mastra
-
-Run [`mastra init`](https://mastra.ai/reference/cli/mastra). When prompted, choose a provider (e.g. OpenAI) and enter your key:
-
-**npm**:
-
-```bash
-npx mastra@latest init
-```
-
-**pnpm**:
-
-```bash
-pnpm dlx mastra@latest init
-```
-
-**Yarn**:
-
-```bash
-yarn dlx mastra@latest init
-```
-
-**Bun**:
-
-```bash
-bun x mastra@latest init
-```
-
-This creates a `src/mastra` folder with an example weather agent and the following files:
-
-- `index.ts` - Mastra config, including memory
-- `tools/weather-tool.ts` - a tool to fetch weather for a given location
-- `agents/weather-agent.ts`- a weather agent with a prompt that uses the tool
-
-You'll call `weather-agent.ts` from your chat UI in the next steps.
-
-## Install AI SDK UI & AI Elements
-
-Install AI SDK UI along with the Mastra adapter:
-
-**npm**:
-
-```bash
-npm install @mastra/ai-sdk@latest @ai-sdk/react ai
-```
-
-**pnpm**:
-
-```bash
-pnpm add @mastra/ai-sdk@latest @ai-sdk/react ai
-```
-
-**Yarn**:
-
-```bash
-yarn add @mastra/ai-sdk@latest @ai-sdk/react ai
-```
-
-**Bun**:
-
-```bash
-bun add @mastra/ai-sdk@latest @ai-sdk/react ai
-```
-
-Next, initialize AI Elements. When prompted, choose the default options:
-
-**npm**:
-
-```bash
-npx ai-elements@latest
-```
-
-**pnpm**:
-
-```bash
-pnpm dlx ai-elements@latest
-```
-
-**Yarn**:
-
-```bash
-yarn dlx ai-elements@latest
-```
-
-**Bun**:
-
-```bash
-bun x ai-elements@latest
-```
-
-This downloads the entire AI Elements UI component library into a `@/components/ai-elements` folder.
-
-## Create a chat route
-
-Open ⁠`src/mastra/index.ts` and add a [⁠chatRoute()](https://mastra.ai/reference/ai-sdk/chat-route) to your config. This creates an API route your React frontend can call for AI SDK-compatible chat responses, which you’ll use with ⁠useChat() next.
-
-```ts
-import { Mastra } from '@mastra/core/mastra';
-// Existing imports...
-import { chatRoute } from "@mastra/ai-sdk"
-
-export const mastra = new Mastra({
-  // Existing config...
-  server: {
-    apiRoutes: [
-      chatRoute({
-        path: '/chat/:agentId'
-      })
-    ]
-  }
-});
-```
-
-## Add the chat UI
-
-Replace the `src/App.tsx` file to create a chat interface:
-
-```tsx
-import * as React from 'react';
-import { DefaultChatTransport, type ToolUIPart } from 'ai';
-import { useChat } from '@ai-sdk/react';
-
-import {
-  PromptInput,
-  PromptInputBody,
-  PromptInputTextarea,
-} from '@/components/ai-elements/prompt-input';
-
-import {
-  Conversation,
-  ConversationContent,
-  ConversationScrollButton,
-} from '@/components/ai-elements/conversation';
-
-import {
-  Message,
-  MessageContent,
-  MessageResponse
-} from '@/components/ai-elements/message';
-
-import {
-  Tool,
-  ToolHeader,
-  ToolContent,
-  ToolInput,
-  ToolOutput,
-} from '@/components/ai-elements/tool';
-
-export default function App() {
-  const [input, setInput] = React.useState<string>('');
-
-  const { messages, sendMessage, status } = useChat({
-    transport: new DefaultChatTransport({
-      api: 'http://localhost:4111/chat/weather-agent',
-    }),
-  });
-
-  const handleSubmit = async () => {
-    if (!input.trim()) return;
-
-    sendMessage({ text: input });
-    setInput('');
-  };
-
-  return (
-    <div className="max-w-4xl mx-auto p-6 relative size-full h-screen">
-      <div className="flex flex-col h-full">
-        <Conversation className="h-full">
-          <ConversationContent>
-            {messages.map((message) => (
-              <div key={message.id}>
-                {message.parts?.map((part, i) => {
-                  if (part.type === 'text') {
-                    return (
-                      <Message
-                        key={`${message.id}-${i}`}
-                        from={message.role}>
-                          <MessageContent>
-                            <MessageResponse>{part.text}</MessageResponse>
-                          </MessageContent>
-                      </Message>
-                    );
-                  }
-
-                  if (part.type?.startsWith('tool-')) {
-                    return (
-                      <Tool key={`${message.id}-${i}`}>
-                        <ToolHeader
-                          type={(part as ToolUIPart).type}
-                          state={(part as ToolUIPart).state || 'output-available'}
-                          className="cursor-pointer"
-                        />
-                        <ToolContent>
-                          <ToolInput input={(part as ToolUIPart).input || {}} />
-                          <ToolOutput
-                            output={(part as ToolUIPart).output}
-                            errorText={(part as ToolUIPart).errorText}
-                          />
-                        </ToolContent>
-                      </Tool>
-                    );
-                  }
-
-                  return null;
-                })}
-              </div>
-            ))}
-            <ConversationScrollButton />
-          </ConversationContent>
-        </Conversation>
-        <PromptInput onSubmit={handleSubmit} className="mt-20">
-          <PromptInputBody>
-            <PromptInputTextarea
-              onChange={(e) => setInput(e.target.value)}
-              className="md:leading-10"
-              value={input}
-              placeholder="Ask about the weather..."
-              disabled={status !== 'ready'}
-            />
-          </PromptInputBody>
-        </PromptInput>
-      </div>
-    </div>
-  );
-}
-```
-
-This component connects [`useChat()`](https://ai-sdk.dev/docs/reference/ai-sdk-ui/use-chat) to the `chat/weather-agent` endpoint, sending prompts there and streaming the response back in chunks.
-
-It renders the response text using the [`<MessageResponse>`](https://ai-sdk.dev/elements/components/message#messageresponse-) component, and shows any tool invocations with the [`<Tool>`](https://ai-sdk.dev/elements/components/tool) component.
-
-## Test your agent
-
-In order to test your agent with the chat interface, you need to run both the Mastra server and the Vite development server.
-
-1. Start the Mastra development server:
-
-   **npm**:
-
-   ```bash
-   npx mastra dev
-   ```
-
-   **pnpm**:
-
-   ```bash
-   pnpm dlx mastra dev
-   ```
-
-   **Yarn**:
-
-   ```bash
-   yarn dlx mastra dev
-   ```
-
-   **Bun**:
-
-   ```bash
-   bun x mastra dev
-   ```
-
-2. In a separate terminal window, start the Vite development server:
-
-   **npm**:
-
-   ```bash
-   npm run dev
-   ```
-
-   **pnpm**:
-
-   ```bash
-   pnpm run dev
-   ```
-
-   **Yarn**:
-
-   ```bash
-   yarn dev
-   ```
-
-   **Bun**:
-
-   ```bash
-   bun run dev
-   ```
-
-3. Open your application at <http://localhost:5173>
-
-4. Try asking about the weather. If your API key is set up correctly, you'll get a response
-
-## Next steps
-
-Congratulations on building your Mastra agent with React! 🎉
-
-From here, you can extend the project with your own tools and logic:
-
-- Learn more about [agents](https://mastra.ai/docs/agents/overview)
-- Give your agent its own [tools](https://mastra.ai/docs/agents/using-tools)
-- Add human-like [memory](https://mastra.ai/docs/agents/agent-memory) to your agent
-
-When you're ready, read more about how Mastra integrates with AI SDK UI and React, and how to deploy your agent anywhere:
-
-- Integrate Mastra with [AI SDK UI](https://mastra.ai/guides/build-your-ui/ai-sdk-ui)
-- Deploy your agent [anywhere](https://mastra.ai/docs/deployment/overview)

package/.docs/guides/guide/ai-recruiter.md

@@ -1,227 +0,0 @@
-# Building an AI Recruiter
-
-In this guide, you'll learn how Mastra helps you build workflows with LLMs.
-
-You'll create a workflow that gathers information from a candidate's resume, then branches to either a technical or behavioral question based on the candidate's profile. Along the way, you'll see how to structure workflow steps, handle branching, and integrate LLM calls.
-
-## Prerequisites
-
-- Node.js `v22.13.0` or later installed
-- An API key from a supported [Model Provider](https://mastra.ai/models)
-- An existing Mastra project (Follow the [installation guide](https://mastra.ai/guides/getting-started/quickstart) to set up a new project)
-
-## Building the Workflow
-
-Set up the Workflow, define steps to extract and classify candidate data, and then ask suitable follow-up questions.
-
-1. Create a new file `src/mastra/workflows/candidate-workflow.ts` and define your workflow:
-
-   ```ts
-   import { createWorkflow, createStep } from "@mastra/core/workflows";
-   import { z } from "zod";
-
-   export const candidateWorkflow = createWorkflow({
-     id: "candidate-workflow",
-     inputSchema: z.object({
-       resumeText: z.string(),
-     }),
-     outputSchema: z.object({
-       askAboutSpecialty: z.object({
-         question: z.string(),
-       }),
-       askAboutRole: z.object({
-         question: z.string(),
-       }),
-     }),
-   }).commit();
-   ```
-
-2. You want to extract candidate details from the resume text and classify the person as "technical" or "non-technical". This step calls an LLM to parse the resume and returns structured JSON, including the name, technical status, specialty, and the original resume text. Defined through the `inputSchema` you get access to the `resumeText` inside `execute()`. Use it to prompt an LLM and return the organized fields.
-
-   To the existing `src/mastra/workflows/candidate-workflow.ts` file add the following:
-
-   ```ts
-   import { Agent } from "@mastra/core/agent";
-
-   const recruiter = new Agent({
-     id: "recruiter-agent",
-     name: "Recruiter Agent",
-     instructions: `You are a recruiter.`,
-     model: "openai/gpt-5.1",
-   });
-
-   const gatherCandidateInfo = createStep({
-     id: "gatherCandidateInfo",
-     inputSchema: z.object({
-       resumeText: z.string(),
-     }),
-     outputSchema: z.object({
-       candidateName: z.string(),
-       isTechnical: z.boolean(),
-       specialty: z.string(),
-       resumeText: z.string(),
-     }),
-     execute: async ({ inputData }) => {
-       const resumeText = inputData?.resumeText;
-
-       const prompt = `Extract details from the resume text:
-   "${resumeText}"`;
-
-       const res = await recruiter.generate(prompt, {
-         structuredOutput: {
-           schema: z.object({
-             candidateName: z.string(),
-             isTechnical: z.boolean(),
-             specialty: z.string(),
-             resumeText: z.string(),
-           }),
-         },
-       });
-
-       return res.object;
-     },
-   });
-   ```
-
-   Since you're using a Recruiter agent inside `execute()` you need to define it above the step and add the necessary imports.
-
-3. This step prompts a candidate who is identified as "technical" for more information about how they got into their specialty. It uses the entire resume text so the LLM can craft a relevant follow-up question.
-
-   To the existing `src/mastra/workflows/candidate-workflow.ts` file add the following:
-
-   ```ts
-   const askAboutSpecialty = createStep({
-     id: "askAboutSpecialty",
-     inputSchema: z.object({
-       candidateName: z.string(),
-       isTechnical: z.boolean(),
-       specialty: z.string(),
-       resumeText: z.string(),
-     }),
-     outputSchema: z.object({
-       question: z.string(),
-     }),
-     execute: async ({ inputData: candidateInfo }) => {
-       const prompt = `You are a recruiter. Given the resume below, craft a short question
-   for ${candidateInfo?.candidateName} about how they got into "${candidateInfo?.specialty}".
-   Resume: ${candidateInfo?.resumeText}`;
-       const res = await recruiter.generate(prompt);
-
-       return { question: res?.text?.trim() || "" };
-     },
-   });
-   ```
-
-4. If the candidate is "non-technical", you want a different follow-up question. This step asks what interests them most about the role, again referencing their complete resume text. The `execute()` function solicits a role-focused query from the LLM.
-
-   To the existing `src/mastra/workflows/candidate-workflow.ts` file add the following:
-
-   ```ts
-   const askAboutRole = createStep({
-     id: "askAboutRole",
-     inputSchema: z.object({
-       candidateName: z.string(),
-       isTechnical: z.boolean(),
-       specialty: z.string(),
-       resumeText: z.string(),
-     }),
-     outputSchema: z.object({
-       question: z.string(),
-     }),
-     execute: async ({ inputData: candidateInfo }) => {
-       const prompt = `You are a recruiter. Given the resume below, craft a short question
-   for ${candidateInfo?.candidateName} asking what interests them most about this role.
-   Resume: ${candidateInfo?.resumeText}`;
-       const res = await recruiter.generate(prompt);
-       return { question: res?.text?.trim() || "" };
-     },
-   });
-   ```
-
-5. You now combine the steps to implement branching logic based on the candidate's technical status. The workflow first gathers candidate data, then either asks about their specialty or about their role, depending on `isTechnical`. This is done by chaining `gatherCandidateInfo` with `askAboutSpecialty` and `askAboutRole`.
-
-   To the existing `src/mastra/workflows/candidate-workflow.ts` file change the `candidateWorkflow` like so:
-
-   ```ts
-   export const candidateWorkflow = createWorkflow({
-     id: "candidate-workflow",
-     inputSchema: z.object({
-       resumeText: z.string(),
-     }),
-     outputSchema: z.object({
-       askAboutSpecialty: z.object({
-         question: z.string(),
-       }),
-       askAboutRole: z.object({
-         question: z.string(),
-       }),
-     }),
-   })
-     .then(gatherCandidateInfo)
-     .branch([
-       [async ({ inputData: { isTechnical } }) => isTechnical, askAboutSpecialty],
-       [async ({ inputData: { isTechnical } }) => !isTechnical, askAboutRole],
-     ])
-     .commit();
-   ```
-
-6. In your `src/mastra/index.ts` file, register the workflow:
-
-   ```ts
-   import { Mastra } from "@mastra/core";
-   import { candidateWorkflow } from "./workflows/candidate-workflow";
-
-   export const mastra = new Mastra({
-     workflows: { candidateWorkflow },
-   });
-   ```
-
-## Testing the Workflow
-
-You can test your workflow inside [Studio](https://mastra.ai/docs/getting-started/studio) by starting the development server:
-
-```bash
-mastra dev
-```
-
-In the sidebar, navigate to **Workflows** and select **candidate-workflow**. In the middle you'll see a graph view of your workflow and on the right sidebar the **Run** tab is selected by default. Inside this tab you can enter a resume text, for example:
-
-```text
-Knowledgeable Software Engineer with more than 10 years of experience in software development. Proven expertise in the design and development of software databases and optimization of user interfaces.
-```
-
-After entering the resume text, press the **Run** button. You should now see two status boxes (`GatherCandidateInfo` and `AskAboutSpecialty`) which contain the output of the workflow steps.
-
-You can also test the workflow programmatically by calling [`.createRun()`](https://mastra.ai/reference/workflows/workflow-methods/create-run) and [`.start()`](https://mastra.ai/reference/workflows/run-methods/start). Create a new file `src/test-workflow.ts` and add the following:
-
-```ts
-import { mastra } from "./mastra";
-
-const run = await mastra.getWorkflow("candidateWorkflow").createRun();
-
-const res = await run.start({
-  inputData: {
-    resumeText:
-      "Knowledgeable Software Engineer with more than 10 years of experience in software development. Proven expertise in the design and development of software databases and optimization of user interfaces.",
-  },
-});
-
-// Dump the complete workflow result (includes status, steps and result)
-console.log(JSON.stringify(res, null, 2));
-
-// Get the workflow output value
-if (res.status === "success") {
-  const question =
-    res.result.askAboutRole?.question ?? res.result.askAboutSpecialty?.question;
-
-  console.log(`Output value: ${question}`);
-}
-```
-
-Now, run the workflow and get output in your terminal:
-
-```bash
-npx tsx src/test-workflow.ts
-```
-
-You've just built a workflow to parse a resume and decide which question to ask based on the candidate's technical abilities. Congrats and happy hacking!