@mastra/mcp-docs-server 1.1.4 → 1.1.5

package/.docs/guides/guide/research-assistant.md

@@ -1,349 +0,0 @@
-# Building a Research Paper Assistant with RAG
-
-In this guide, you'll create an AI research assistant that can analyze academic papers and answer specific questions about their content using Retrieval Augmented Generation (RAG).
-
-You'll use the foundational Transformer paper ["Attention Is All You Need"](https://arxiv.org/html/1706.03762) as your example. As a database you'll use a local libSQL database.
-
-## 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)
-
-## How RAG works
-
-Let's understand how RAG works and how you'll implement each component.
-
-### Knowledge Store/Index
-
-- Converting text into vector representations
-- Creating numerical representations of content
-- **Implementation**: You'll use OpenAI's `text-embedding-3-small` to create embeddings and store them in LibSQLVector
-
-### Retriever
-
-- Finding relevant content via similarity search
-- Matching query embeddings with stored vectors
-- **Implementation**: You'll use LibSQLVector to perform similarity searches on the stored embeddings
-
-### Generator
-
-- Processing retrieved content with an LLM
-- Creating contextually informed responses
-- **Implementation**: You'll use GPT-4o-mini to generate answers based on retrieved content
-
-Your implementation will:
-
-1. Process the Transformer paper into embeddings
-2. Store them in LibSQLVector for quick retrieval
-3. Use similarity search to find relevant sections
-4. Generate accurate responses using retrieved context
-
-## Creating the Agent
-
-Let's define the agent's behavior, connect it to your Mastra project, and create the vector store.
-
-1. Install additional dependencies
-
-   After running the [installation guide](https://mastra.ai/guides/getting-started/quickstart) you'll need to install additional dependencies:
-
-   **npm**:
-
-   ```bash
-   npm install @mastra/rag@latest ai
-   ```
-
-   **pnpm**:
-
-   ```bash
-   pnpm add @mastra/rag@latest ai
-   ```
-
-   **Yarn**:
-
-   ```bash
-   yarn add @mastra/rag@latest ai
-   ```
-
-   **Bun**:
-
-   ```bash
-   bun add @mastra/rag@latest ai
-   ```
-
-2. Now you'll create your RAG-enabled research assistant. The agent uses:
-
-   - A [Vector Query Tool](https://mastra.ai/reference/tools/vector-query-tool) for performing semantic search over the vector store to find relevant content in papers
-   - GPT-4o-mini for understanding queries and generating responses
-   - Custom instructions that guide the agent on how to analyze papers, use retrieved content effectively, and acknowledge limitations
-
-   Create a new file `src/mastra/agents/researchAgent.ts` and define your agent:
-
-   ```ts
-   import { Agent } from "@mastra/core/agent";
-   import { ModelRouterEmbeddingModel } from "@mastra/core/llm";
-   import { createVectorQueryTool } from "@mastra/rag";
-
-   // Create a tool for semantic search over the paper embeddings
-   const vectorQueryTool = createVectorQueryTool({
-     vectorStoreName: "libSqlVector",
-     indexName: "papers",
-     model: new ModelRouterEmbeddingModel("openai/text-embedding-3-small"),
-   });
-
-   export const researchAgent = new Agent({
-     id: "research-agent",
-     name: "Research Assistant",
-     instructions: `You are a helpful research assistant that analyzes academic papers and technical documents.
-       Use the provided vector query tool to find relevant information from your knowledge base,
-       and provide accurate, well-supported answers based on the retrieved content.
-       Focus on the specific content available in the tool and acknowledge if you cannot find sufficient information to answer a question.
-       Base your responses only on the content provided, not on general knowledge.`,
-     model: "openai/gpt-5.1",
-     tools: {
-       vectorQueryTool,
-     },
-   });
-   ```
-
-3. In the root of your project, grab the absolute path with the `pwd` command. The path might be similar to this:
-
-   ```bash
-   > pwd
-   /Users/your-name/guides/research-assistant
-   ```
-
-   In your `src/mastra/index.ts` file, add the following to your existing file and configuration:
-
-   ```ts
-   import { Mastra } from "@mastra/core";
-   import { LibSQLVector } from "@mastra/libsql";
-
-   const libSqlVector = new LibSQLVector({
-     id: 'research-vectors',
-     url: "file:/Users/your-name/guides/research-assistant/vector.db",
-   });
-
-   export const mastra = new Mastra({
-     vectors: { libSqlVector },
-   });
-   ```
-
-   For the `url` use the absolute path you got from the `pwd` command. This way the `vector.db` file is created at the root of your project.
-
-   > **Note:** For the purpose of this guide you are using a hardcoded absolute path to your local libSQL file, however for production usage this won't work. You should use a remote persistent database then.
-
-4. In the `src/mastra/index.ts` file, add the agent to Mastra:
-
-   ```ts
-   import { Mastra } from "@mastra/core";
-   import { LibSQLVector } from "@mastra/libsql";
-   import { researchAgent } from "./agents/researchAgent";
-
-   const libSqlVector = new LibSQLVector({
-     id: 'research-vectors',
-     url: "file:/Users/your-name/guides/research-assistant/vector.db",
-   });
-
-   export const mastra = new Mastra({
-     agents: { researchAgent },
-     vectors: { libSqlVector },
-   });
-   ```
-
-## Processing documents
-
-In the following steps you'll fetch the research paper, split it into smaller chunks, generate embeddings for them, and store these chunks of information into the vector database.
-
-1. In this step the research paper is retrieved by providing an URL, then converted to a document object, and split into smaller, manageable chunks. By splitting into chunks the processing is faster and more efficient.
-
-   Create a new file `src/store.ts` and add the following:
-
-   ```ts
-   import { MDocument } from "@mastra/rag";
-
-   // Load the paper
-   const paperUrl = "https://arxiv.org/html/1706.03762";
-   const response = await fetch(paperUrl);
-   const paperText = await response.text();
-
-   // Create document and chunk it
-   const doc = MDocument.fromText(paperText);
-   const chunks = await doc.chunk({
-     strategy: "recursive",
-     maxSize: 512,
-     overlap: 50,
-     separators: ["\n\n", "\n", " "],
-   });
-
-   console.log("Number of chunks:", chunks.length);
-   ```
-
-   Run the file in your terminal:
-
-   ```bash
-   npx bun src/store.ts
-   ```
-
-   You should get back this response:
-
-   ```bash
-   Number of chunks: 892
-   ```
-
-2. Finally, you'll prepare the content for RAG by:
-
-   1. Generating embeddings for each chunk of text
-   2. Creating a vector store index to hold the embeddings
-   3. Storing both the embeddings and metadata (original text and source information) in the vector database
-
-   > **Note:** This metadata is crucial as it allows for returning the actual content when the vector store finds relevant matches.
-
-   This allows the agent to efficiently search and retrieve relevant information.
-
-   Open the `src/store.ts` file and add the following:
-
-   ```ts
-   import { MDocument } from "@mastra/rag";
-   import { embedMany } from "ai";
-   import { mastra } from "./mastra";
-
-   // Load the paper
-   const paperUrl = "https://arxiv.org/html/1706.03762";
-   const response = await fetch(paperUrl);
-   const paperText = await response.text();
-
-   // Create document and chunk it
-   const doc = MDocument.fromText(paperText);
-   const chunks = await doc.chunk({
-     strategy: "recursive",
-     maxSize: 512,
-     overlap: 50,
-     separators: ["\n\n", "\n", " "],
-   });
-
-   // Generate embeddings
-   const { embeddings } = await embedMany({
-     model: new ModelRouterEmbeddingModel("openai/text-embedding-3-small"),
-     values: chunks.map((chunk) => chunk.text),
-   });
-
-   // Get the vector store instance from Mastra
-   const vectorStore = mastra.getVector("libSqlVector");
-
-   // Create an index for paper chunks
-   await vectorStore.createIndex({
-     indexName: "papers",
-     dimension: 1536,
-   });
-
-   // Store embeddings
-   await vectorStore.upsert({
-     indexName: "papers",
-     vectors: embeddings,
-     metadata: chunks.map((chunk) => ({
-       text: chunk.text,
-       source: "transformer-paper",
-     })),
-   });
-   ```
-
-   Lastly, you'll now need to store the embeddings by running the script again:
-
-   ```bash
-   npx bun src/store.ts
-   ```
-
-   If the operation was successful you should see no output/errors in your terminal.
-
-## Test the Assistant
-
-Now that the vector database has all embeddings, you can test the research assistant with different types of queries.
-
-Create a new file `src/ask-agent.ts` and add different types of queries:
-
-```ts
-import { mastra } from "./mastra";
-const agent = mastra.getAgent("researchAgent");
-
-// Basic query about concepts
-const query1 =
-  "What problems does sequence modeling face with neural networks?";
-const response1 = await agent.generate(query1);
-console.log("\nQuery:", query1);
-console.log("Response:", response1.text);
-```
-
-Run the script:
-
-```bash
-npx bun src/ask-agent.ts
-```
-
-You should see output like:
-
-```bash
-Query: What problems does sequence modeling face with neural networks?
-Response: Sequence modeling with neural networks faces several key challenges:
-1. Vanishing and exploding gradients during training, especially with long sequences
-2. Difficulty handling long-term dependencies in the input
-3. Limited computational efficiency due to sequential processing
-4. Challenges in parallelizing computations, resulting in longer training times
-```
-
-Try another question:
-
-```ts
-import { mastra } from "./mastra";
-const agent = mastra.getAgent("researchAgent");
-
-// Query about specific findings
-const query2 = "What improvements were achieved in translation quality?";
-const response2 = await agent.generate(query2);
-console.log("\nQuery:", query2);
-console.log("Response:", response2.text);
-```
-
-Output:
-
-```text
-Query: What improvements were achieved in translation quality?
-Response: The model showed significant improvements in translation quality, achieving more than 2.0
-BLEU points improvement over previously reported models on the WMT 2014 English-to-German translation
-task, while also reducing training costs.
-```
-
-### Serve the Application
-
-Start the Mastra server to expose your research assistant via API:
-
-```bash
-mastra dev
-```
-
-Your research assistant will be available at:
-
-```text
-http://localhost:4111/api/agents/researchAgent/generate
-```
-
-Test with curl:
-
-```bash
-curl -X POST http://localhost:4111/api/agents/researchAgent/generate \
-  -H "Content-Type: application/json" \
-  -d '{
-    "messages": [
-      { "role": "user", "content": "What were the main findings about model parallelization?" }
-    ]
-  }'
-```
-
-## Advanced RAG Examples
-
-Explore these examples for more advanced RAG techniques:
-
-- [Filter RAG](https://github.com/mastra-ai/mastra/tree/main/examples/basics/rag/filter-rag) for filtering results using metadata
-- [Cleanup RAG](https://github.com/mastra-ai/mastra/tree/main/examples/basics/rag/cleanup-rag) for optimizing information density
-- [Chain of Thought RAG](https://github.com/mastra-ai/mastra/tree/main/examples/basics/rag/cot-rag) for complex reasoning queries using workflows
-- [Rerank RAG](https://github.com/mastra-ai/mastra/tree/main/examples/basics/rag/rerank-rag) for improved result relevance

package/.docs/guides/guide/stock-agent.md

@@ -1,134 +0,0 @@
-# Building an AI Stock Agent
-
-In this guide, you're going to create a simple agent that fetches the last day's closing stock price for a given symbol. You'll learn how to create a tool, add it to an agent, and use the agent to fetch stock prices.
-
-[YouTube video player](https://www.youtube-nocookie.com/embed/rIaZ4l7y9wo)
-
-## 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)
-
-## Creating the Agent
-
-To create an agent in Mastra use the `Agent` class to define it and then register it with Mastra.
-
-1. Create a new file `src/mastra/agents/stockAgent.ts` and define your agent:
-
-   ```ts
-   import { Agent } from "@mastra/core/agent";
-
-   export const stockAgent = new Agent({
-     id: "stock-agent",
-     name: "Stock Agent",
-     instructions:
-       "You are a helpful assistant that provides current stock prices. When asked about a stock, use the stock price tool to fetch the stock price.",
-     model: "openai/gpt-5.1",
-   });
-   ```
-
-2. In your `src/mastra/index.ts` file, register the agent:
-
-   ```ts
-   import { Mastra } from "@mastra/core";
-   import { stockAgent } from "./agents/stockAgent";
-
-   export const mastra = new Mastra({
-     agents: { stockAgent },
-   });
-   ```
-
-## Creating the Stock Price Tool
-
-So far the Stock Agent doesn't know anything about the current stock prices. To change this, create a tool and add it to the agent.
-
-1. Create a new file `src/mastra/tools/stockPrices.ts`. Inside, add a `stockPrices` tool that will fetch the last day's closing stock price for a given symbol:
-
-   ```ts
-   import { createTool } from "@mastra/core/tools";
-   import { z } from "zod";
-
-   const getStockPrice = async (symbol: string) => {
-     const data = await fetch(
-       `https://mastra-stock-data.vercel.app/api/stock-data?symbol=${symbol}`,
-     ).then((r) => r.json());
-     return data.prices["4. close"];
-   };
-
-   export const stockPrices = createTool({
-     id: "Get Stock Price",
-     inputSchema: z.object({
-       symbol: z.string(),
-     }),
-     description: `Fetches the last day's closing stock price for a given symbol`,
-     execute: async (inputData) => {
-       console.log("Using tool to fetch stock price for", inputData.symbol);
-       return {
-         symbol: inputData.symbol,
-         currentPrice: await getStockPrice(inputData.symbol),
-       };
-     },
-   });
-   ```
-
-2. Inside `src/mastra/agents/stockAgent.ts` import your newly created `stockPrices` tool and add it to the agent.
-
-   ```ts
-   import { Agent } from "@mastra/core/agent";
-   import { stockPrices } from "../tools/stockPrices";
-
-   export const stockAgent = new Agent({
-     id: "stock-agent",
-     name: "Stock Agent",
-     instructions:
-       "You are a helpful assistant that provides current stock prices. When asked about a stock, use the stock price tool to fetch the stock price.",
-     model: "openai/gpt-5.1",
-     tools: {
-       stockPrices,
-     },
-   });
-   ```
-
-## Running the Agent Server
-
-Learn how to interact with your agent through Mastra's API.
-
-1. You can run your agent as a service using the `mastra dev` command:
-
-   ```bash
-   mastra dev
-   ```
-
-   This will start a server exposing endpoints to interact with your registered agents. Within [Studio](https://mastra.ai/docs/getting-started/studio) you can test your `stockAgent` and `stockPrices` tool through a UI.
-
-2. By default, `mastra dev` runs on `http://localhost:4111`. Your Stock agent will be available at:
-
-   ```text
-   POST http://localhost:4111/api/agents/stockAgent/generate
-   ```
-
-3. You can interact with the agent using `curl` from the command line:
-
-   ```bash
-   curl -X POST http://localhost:4111/api/agents/stockAgent/generate \
-     -H "Content-Type: application/json" \
-     -d '{
-       "messages": [
-         { "role": "user", "content": "What is the current stock price of Apple (AAPL)?" }
-       ]
-     }'
-   ```
-
-   **Expected Response:**
-
-   You should receive a JSON response similar to:
-
-   ```json
-   {
-     "text": "The current price of Apple (AAPL) is $174.55.",
-     "agent": "Stock Agent"
-   }
-   ```
-
-   This indicates that your agent successfully processed the request, used the `stockPrices` tool to fetch the stock price, and returned the result.