@mastra/mcp-docs-server 0.13.39 → 1.0.0-beta.0

package/.docs/raw/guides/guide/web-search.mdx

@@ -0,0 +1,291 @@
+---
+title: "Guide: Building an Agent that can search the web | Mastra Guide"
+description: "A step-by-step guide to creating an agent that can search the web."
+---
+
+import Steps from "@site/src/components/Steps";
+import StepItem from "@site/src/components/StepItem";
+import Tabs from "@theme/Tabs";
+import TabItem from "@theme/TabItem";
+
+# Building an Agent that can search the web
+
+When building a web search agent, you have two main strategies to consider:
+
+1. **Native search tools from the LLM**: Certain language models offer integrated web search capabilities that work out of the box.
+2. **Implement a custom search tool**: Develop your own integration with a search provider's API to handle queries and retrieve results.
+
+## Prerequisites
+
+- Node.js `v22.13.0` or later installed
+- An API key from a supported [Model Provider](/models/v1)
+- An existing Mastra project (Follow the [installation guide](/docs/v1/getting-started/installation) to set up a new project)
+
+## Using native search tools
+
+Some LLM providers include built-in web search capabilities that can be used directly without additional API integrations. OpenAI's GPT-4o-mini and Google's Gemini 2.5 Flash both offer native search tools that the model can invoke during generation.
+
+<Steps>
+
+<StepItem title="Install dependencies">
+
+Install dependencies
+
+<Tabs>
+  <TabItem value="openai" label="Open AI">
+    ```bash copy
+    npm install @ai-sdk/openai
+    ```
+  </TabItem>
+  <TabItem value="gemini" label="Gemini">
+    ```bash copy
+    npm install @ai-sdk/google
+    ```
+  </TabItem>
+</Tabs>
+
+</StepItem>
+
+<StepItem title="Define the Agent">
+
+Create a new file `src/mastra/agents/searchAgent.ts` and define your agent:
+
+<Tabs>
+    <TabItem value="openai" label="Open AI">
+
+    ```ts copy title="src/mastra/agents/searchAgent.ts"
+    import { Agent } from "@mastra/core/agent";
+
+    export const searchAgent = new Agent({
+        id: "search-agent",
+        name: "Search Agent",
+        instructions:
+            "You are a search agent that can search the web for information.",
+        model: 'openai/gpt-4o-mini',
+    });
+    ```
+
+    </TabItem>
+    <TabItem value="gemini" label="Gemini">
+
+    ```ts copy title="src/mastra/agents/searchAgent.ts"
+    import { Agent } from "@mastra/core/agent";
+
+    export const searchAgent = new Agent({
+        id: "search-agent",
+        name: "Search Agent",
+        instructions:
+            "You are a search agent that can search the web for information.",
+        model: 'google/gemini-2.5-flash',
+    });
+    ```
+
+    </TabItem>
+
+</Tabs>
+
+</StepItem>
+
+<StepItem title="Setup the tool">
+
+Setup the tool:
+
+<Tabs>
+    <TabItem value="openai" label="Open AI">
+
+    ```ts copy title="src/mastra/agents/searchAgent.ts" {9-11}
+    import { openai } from "@ai-sdk/openai";
+    import { Agent } from "@mastra/core/agent";
+
+    export const searchAgent = new Agent({
+        id: "search-agent",
+        name: "Search Agent",
+        instructions:
+            "You are a search agent that can search the web for information.",
+        model: 'openai/gpt-4o-mini',
+        tools: {
+            webSearch: openai.tools.webSearch()
+        }
+    });
+    ```
+
+    </TabItem>
+    <TabItem value="gemini" label="Gemini">
+
+    ```ts copy title="src/mastra/agents/searchAgent.ts" {9-11}
+    import { google } from "@ai-sdk/google";
+    import { Agent } from "@mastra/core/agent";
+
+    export const searchAgent = new Agent({
+        id: "search-agent",
+        name: "Search Agent",
+        instructions:
+            "You are a search agent that can search the web for information.",
+        model: 'google/gemini-2.5-flash',
+        tools: {
+            webSearch: google.tools.googleSearch()
+        }
+    });
+    ```
+
+    </TabItem>
+
+</Tabs>
+
+</StepItem>
+
+<StepItem title="Register the Agent with Mastra">
+
+In your `src/mastra/index.ts` file, register the agent:
+
+```ts copy title="src/mastra/index.ts" {2, 5}
+import { Mastra } from "@mastra/core";
+import { searchAgent } from "./agents/searchAgent";
+
+export const mastra = new Mastra({
+  agents: { searchAgent },
+});
+```
+
+</StepItem>
+
+<StepItem title="Test your agent">
+
+You can test your agent with [Studio](/docs/v1/getting-started/studio) using the `mastra dev` command:
+
+```bash copy
+mastra dev
+```
+
+Inside Studio navigate to the **"Search Agent"** and ask it: "What happened last week in AI news?"
+
+</StepItem>
+
+</Steps>
+
+## Using Search APIs
+
+For more control over search behavior, you can integrate external search APIs as custom tools. [Exa](https://exa.ai/) is a search engine built specifically for AI applications, offering semantic search, configurable filters (category, domain, date range), and the ability to retrieve full page contents. The search API is wrapped in a Mastra tool that defines the input schema, output format, and execution logic.
+
+<Steps>
+
+<StepItem title="Install dependencies">
+
+Install dependencies
+
+```bash copy
+npm install exa-js
+```
+
+</StepItem>
+
+<StepItem title="Define the Agent">
+
+Create a new file `src/mastra/agents/searchAgent.ts` and define your agent:
+
+```ts copy title="src/mastra/agents/searchAgent.ts"
+import { Agent } from "@mastra/core/agent";
+
+export const searchAgent = new Agent({
+  id: "search-agent",
+  name: "Search Agent",
+  instructions:
+    "You are a search agent that can search the web for information.",
+  model: "openai/gpt-4o-mini",
+});
+```
+
+</StepItem>
+
+<StepItem title="Setup the tool">
+
+Setup the tool
+
+```ts copy title="src/mastra/tools/searchTool.ts"
+import { createTool } from "@mastra/core/tools";
+import z from "zod";
+import Exa from "exa-js";
+
+export const exa = new Exa(process.env.EXA_API_KEY);
+
+export const webSearch = createTool({
+  id: "exa-web-search",
+  description: "Search the web",
+  inputSchema: z.object({
+    query: z.string().min(1).max(50).describe("The search query"),
+  }),
+  outputSchema: z.array(
+    z.object({
+      title: z.string().nullable(),
+      url: z.string(),
+      content: z.string(),
+      publishedDate: z.string().optional(),
+    }),
+  ),
+  execute: async (inputData) => {
+    const { results } = await exa.searchAndContents(inputData.query, {
+      livecrawl: "always",
+      numResults: 2,
+    });
+
+    return results.map((result) => ({
+      title: result.title,
+      url: result.url,
+      content: result.text.slice(0, 500),
+      publishedDate: result.publishedDate,
+    }));
+  },
+});
+```
+
+</StepItem>
+
+<StepItem title="Add to your Agent">
+
+Add to your Agent
+
+```ts copy title="src/mastra/agents/searchAgent.ts"
+import { webSearch } from "./tools/searchTool";
+
+export const searchAgent = new Agent({
+  id: "search-agent",
+  name: "Search Agent",
+  instructions:
+    "You are a search agent that can search the web for information.",
+  model: "openai/gpt-4o-mini",
+  tools: {
+    webSearch,
+  },
+});
+```
+
+</StepItem>
+
+<StepItem title="Register the Agent with Mastra">
+
+In your `src/mastra/index.ts` file, register the agent:
+
+```ts copy title="src/mastra/index.ts" {2, 5}
+import { Mastra } from "@mastra/core";
+import { searchAgent } from "./agents/searchAgent";
+
+export const mastra = new Mastra({
+  agents: { searchAgent },
+});
+```
+
+</StepItem>
+
+<StepItem title="Test your agent">
+
+You can test your agent with [Studio](/docs/v1/getting-started/studio) using the `mastra dev` command:
+
+```bash copy
+mastra dev
+```
+
+Inside Studio navigate to the **"Search Agent"** and ask it: "What happened last week in AI news?"
+
+</StepItem>
+
+</Steps>

package/.docs/raw/guides/index.mdx

@@ -0,0 +1,43 @@
+---
+title: "Overview"
+description: "Guides on building with Mastra"
+---
+
+import { CardGrid, CardGridItem } from "@site/src/components/CardGrid";
+
+# Guides
+
+While examples show quick implementations and docs explain specific features, these guides are a bit longer and designed to demonstrate core Mastra concepts:
+
+<CardGrid>
+  <CardGridItem
+    title="AI Recruiter"
+    description="Create a workflow that processes candidate resumes and conducts interviews, demonstrating branching logic and LLM integration in Mastra workflows."
+    href="/guides/v1/guide/ai-recruiter"
+  />
+  <CardGridItem
+    title="Chef Assistant"
+    description="Build an AI chef agent that helps users cook meals with available ingredients, showing how to create interactive agents with custom tools."
+    href="/guides/v1/guide/chef-michel"
+  />
+  <CardGridItem
+    title="Research Assistant"
+    description="Develop an AI research assistant that analyzes academic papers using Retrieval Augmented Generation (RAG), demonstrating document processing and question answering."
+    href="/guides/v1/guide/research-assistant"
+  />
+  <CardGridItem
+    title="Stock Agent"
+    description="Implement a simple agent that fetches stock prices, illustrating the basics of creating tools and integrating them with Mastra agents."
+    href="/guides/v1/guide/stock-agent"
+  />
+  <CardGridItem
+    title="Notes MCP Server"
+    description="Build an AI notes assistant that helps users manage their notes, showing how to create interactive agents with custom tools."
+    href="/guides/v1/guide/notes-mcp-server"
+  />
+  <CardGridItem
+    title="Web Search"
+    description="A step-by-step guide to creating an agent that can search the web."
+    href="/guides/v1/guide/web-search"
+  />
+</CardGrid>

package/.docs/raw/guides/migrations/agentnetwork.mdx

@@ -0,0 +1,114 @@
+---
+title: "Migration: AgentNetwork to .network() | Migration Guide"
+description: "Learn how to migrate from AgentNetwork primitives to .network() in Mastra."
+---
+
+# Migrate from AgentNetwork to `.network()`
+
+As of `v0.20.0` for `@mastra/core`, the following changes apply.
+
+### Upgrade from AI SDK v4 to v5
+
+- Bump all your model provider packages by a major version.
+
+:::note
+
+This will ensure that they are all v5 models now.
+
+:::
+
+### Memory is required
+
+- Memory is now required for the agent network to function properly.
+
+:::note
+
+You must configure memory for the agent.
+
+:::
+
+## Migration paths
+
+If you were using the `AgentNetwork` primitive, you can replace the `AgentNetwork` with `Agent`.
+
+Before:
+
+```typescript
+import { AgentNetwork } from "@mastra/core/network";
+
+const agent = new AgentNetwork({
+  name: "agent-network",
+  agents: [agent1, agent2],
+  tools: { tool1, tool2 },
+  model: openai("gpt-4o"),
+  instructions:
+    "You are a network agent that can help users with a variety of tasks.",
+});
+
+await agent.stream("Find me the weather in Tokyo.");
+```
+
+After:
+
+```typescript
+import { Agent } from "@mastra/core/agent";
+import { Memory } from "@mastra/memory";
+
+const memory = new Memory();
+
+const agent = new Agent({
+  id: "agent-network",
+  name: "agent-network",
+  agents: { agent1, agent2 },
+  tools: { tool1, tool2 },
+  model: openai("gpt-4o"),
+  instructions:
+    "You are a network agent that can help users with a variety of tasks.",
+  memory,
+});
+
+await agent.network("Find me the weather in Tokyo.");
+```
+
+If you were using the `NewAgentNetwork` primitive, you can replace the `NewAgentNetwork` with `Agent`.
+
+Before:
+
+```typescript
+import { NewAgentNetwork } from "@mastra/core/network/vnext";
+
+const agent = new NewAgentNetwork({
+  id: "agent-network",
+  name: "agent-network",
+  agents: { agent1, agent2 },
+  workflows: { workflow1 },
+  tools: { tool1, tool2 },
+  model: openai("gpt-4o"),
+  instructions:
+    "You are a network agent that can help users with a variety of tasks.",
+});
+
+await agent.loop("Find me the weather in Tokyo.");
+```
+
+After:
+
+```typescript
+import { Agent } from "@mastra/core/agent";
+import { Memory } from "@mastra/memory";
+
+const memory = new Memory();
+
+const agent = new Agent({
+  name: "agent-network",
+  agents: { agent1, agent2 },
+  workflows: { workflow1 },
+  tools: { tool1, tool2 },
+  model: openai("gpt-4o"),
+  instructions:
+    "You are a network agent that can help users with a variety of tasks.",
+  memory,
+});
+
+await agent.network("Find me the weather in Tokyo.");
+```

package/.docs/raw/guides/migrations/upgrade-to-v1/_template.mdx

@@ -0,0 +1,50 @@
+This template is a styleguide on how to populate individual migration guides. Use this as guidance on how to structure files in this directory. You're not allowed to deviate from this structure.
+
+Follow the `.cursor/rules/writing-documentation.mdc` instructions on how to write the prose content.
+
+After you found all the changes that need to be documented, you should group them in two big groups: "Changed" and "Removed".
+
+Example:
+
+```md
+## Changed
+
+## Removed
+```
+
+All changes MUST go under these two sections.
+
+Each change (be it "changed" or "removed") should be a h3 heading. You must follow that format exactly.
+
+Example:
+
+```md
+## Changed
+
+### `oldFunction` to `newFunction`
+```
+
+Now that the headings are in place, you need to follow an EXACT structure for each change. You're not allowed to deviate from this structure.
+
+Provide a brief description of the change in one or two sentences. Next, explain in one sentence why it was changed.
+
+The third element of each change has to be the explanation how to migrate existing code to the new version. Keep it concise but clear, try not to cut too much information. Afterwards a code block MUST be provided using the "diff" syntax. Inside the code block you need to show a "before" and "after" example of the code that needs to be changed with that diff syntax.
+
+Example:
+
+````md
+## Changed
+
+### `oldFunction` to `newFunction`
+
+The `oldFunction` has been renamed to `newFunction`. This change improves clarity and consistency across the API.
+
+To migrate, replace all instances of `oldFunction` with `newFunction` in your codebase.
+
+```diff
+- const result = oldFunction(args);
++ const result = newFunction(args);
+```
+````
+
+If the migration requires more steps than just a simple find-and-replace, you can add additional explanation before the code block. If it requires multiple steps, use a numbered list to explain each step clearly.