@mastra/mcp-docs-server 0.0.0-commonjs-20250414101718

package/.docs/raw/reference/tools/document-chunker-tool.mdx

@@ -0,0 +1,141 @@
+---
+title: "Reference: createDocumentChunkerTool() | Tools | Mastra Docs"
+description: Documentation for the Document Chunker Tool in Mastra, which splits documents into smaller chunks for efficient processing and retrieval.
+---
+
+# createDocumentChunkerTool()
+
+The `createDocumentChunkerTool()` function creates a tool for splitting documents into smaller chunks for efficient processing and retrieval. It supports different chunking strategies and configurable parameters.
+
+## Basic Usage
+
+```typescript
+import { createDocumentChunkerTool, MDocument } from "@mastra/rag";
+
+const document = new MDocument({
+  text: "Your document content here...",
+  metadata: { source: "user-manual" }
+});
+
+const chunker = createDocumentChunkerTool({
+  doc: document,
+  params: {
+    strategy: "recursive",
+    size: 512,
+    overlap: 50,
+    separator: "\n"
+  }
+});
+
+const { chunks } = await chunker.execute();
+```
+
+## Parameters
+
+<PropertiesTable
+  content={[
+    {
+      name: "doc",
+      type: "MDocument",
+      description: "The document to be chunked",
+      isOptional: false,
+    },
+    {
+      name: "params",
+      type: "ChunkParams",
+      description: "Configuration parameters for chunking",
+      isOptional: true,
+      defaultValue: "Default chunking parameters",
+    }
+  ]}
+/>
+
+### ChunkParams
+
+<PropertiesTable
+  content={[
+    {
+      name: "strategy",
+      type: "'recursive'",
+      description: "The chunking strategy to use",
+      isOptional: true,
+      defaultValue: "'recursive'",
+    },
+    {
+      name: "size",
+      type: "number",
+      description: "Target size of each chunk in tokens/characters",
+      isOptional: true,
+      defaultValue: "512",
+    },
+    {
+      name: "overlap",
+      type: "number",
+      description: "Number of overlapping tokens/characters between chunks",
+      isOptional: true,
+      defaultValue: "50",
+    },
+    {
+      name: "separator",
+      type: "string",
+      description: "Character(s) to use as chunk separator",
+      isOptional: true,
+      defaultValue: "'\\n'",
+    }
+  ]}
+/>
+
+## Returns
+
+<PropertiesTable
+  content={[
+    {
+      name: "chunks",
+      type: "DocumentChunk[]",
+      description: "Array of document chunks with their content and metadata",
+    }
+  ]}
+/>
+
+## Example with Custom Parameters
+
+```typescript
+const technicalDoc = new MDocument({
+  text: longDocumentContent,
+  metadata: {
+    type: "technical",
+    version: "1.0"
+  }
+});
+
+const chunker = createDocumentChunkerTool({
+  doc: technicalDoc,
+  params: {
+    strategy: "recursive",
+    size: 1024,      // Larger chunks
+    overlap: 100,    // More overlap
+    separator: "\n\n" // Split on double newlines
+  }
+});
+
+const { chunks } = await chunker.execute();
+
+// Process the chunks
+chunks.forEach((chunk, index) => {
+  console.log(`Chunk ${index + 1} length: ${chunk.content.length}`);
+});
+```
+
+## Tool Details
+
+The chunker is created as a Mastra tool with the following properties:
+
+- **Tool ID**: `Document Chunker {strategy} {size}`
+- **Description**: `Chunks document using {strategy} strategy with size {size} and {overlap} overlap`
+- **Input Schema**: Empty object (no additional inputs required)
+- **Output Schema**: Object containing the chunks array
+
+## Related
+
+- [MDocument](../rag/document.mdx)
+- [createVectorQueryTool](./vector-query-tool) 

package/.docs/raw/reference/tools/graph-rag-tool.mdx

@@ -0,0 +1,154 @@
+---
+title: "Reference: createGraphRAGTool() | RAG | Mastra Tools Docs"
+description: Documentation for the Graph RAG Tool in Mastra, which enhances RAG by building a graph of semantic relationships between documents.
+---
+
+# createGraphRAGTool()
+
+The `createGraphRAGTool()` creates a tool that enhances RAG by building a graph of semantic relationships between documents. It uses the `GraphRAG` system under the hood to provide graph-based retrieval, finding relevant content through both direct similarity and connected relationships.
+
+## Usage Example
+
+```typescript
+import { openai } from "@ai-sdk/openai";
+import { createGraphRAGTool } from "@mastra/rag";
+
+const graphTool = createGraphRAGTool({
+  vectorStoreName: "pinecone",
+  indexName: "docs",
+  model: openai.embedding('text-embedding-3-small'),
+  graphOptions: {
+    dimension: 1536,
+    threshold: 0.7,
+    randomWalkSteps: 100,
+    restartProb: 0.15
+  }
+});
+```
+
+## Parameters
+
+<PropertiesTable
+  content={[
+    {
+      name: "vectorStoreName",
+      type: "string",
+      description: "Name of the vector store to query",
+      isOptional: false,
+    },
+    {
+      name: "indexName",
+      type: "string",
+      description: "Name of the index within the vector store",
+      isOptional: false,
+    },
+    {
+      name: "model",
+      type: "EmbeddingModel",
+      description: "Embedding model to use for vector search",
+      isOptional: false,
+    },
+    {
+      name: "graphOptions",
+      type: "GraphOptions",
+      description: "Configuration for the graph-based retrieval",
+      isOptional: true,
+      defaultValue: "Default graph options",
+    },
+    {
+      name: "description",
+      type: "string",
+      description: "Custom description for the tool. By default: 'Access and analyze relationships between information in the knowledge base to answer complex questions about connections and patterns'",
+      isOptional: true,
+    }
+  ]}
+/>
+
+### GraphOptions
+
+<PropertiesTable
+  content={[
+    {
+      name: "dimension",
+      type: "number",
+      description: "Dimension of the embedding vectors",
+      isOptional: true,
+      defaultValue: "1536",
+    },
+    {
+      name: "threshold",
+      type: "number",
+      description: "Similarity threshold for creating edges between nodes (0-1)",
+      isOptional: true,
+      defaultValue: "0.7",
+    },
+    {
+      name: "randomWalkSteps",
+      type: "number",
+      description: "Number of steps in random walk for graph traversal",
+      isOptional: true,
+      defaultValue: "100",
+    },
+    {
+      name: "restartProb",
+      type: "number",
+      description: "Probability of restarting random walk from query node",
+      isOptional: true,
+      defaultValue: "0.15",
+    }
+  ]}
+/>
+
+## Returns
+The tool returns an object with:
+
+<PropertiesTable
+  content={[
+    {
+      name: "relevantContext",
+      type: "string",
+      description: "Combined text from the most relevant document chunks, retrieved using graph-based ranking",
+    }
+  ]}
+/>
+
+## Default Tool Description
+
+The default description focuses on:
+- Analyzing relationships between documents
+- Finding patterns and connections
+- Answering complex queries
+
+## Advanced Example
+
+```typescript
+const graphTool = createGraphRAGTool({
+  vectorStoreName: "pinecone",
+  indexName: "docs",
+  model: openai.embedding('text-embedding-3-small'),
+  graphOptions: {
+    dimension: 1536,
+    threshold: 0.8,        // Higher similarity threshold
+    randomWalkSteps: 200,  // More exploration steps
+    restartProb: 0.2      // Higher restart probability
+  }
+});
+```
+
+## Example with Custom Description
+
+```typescript
+const graphTool = createGraphRAGTool({
+  vectorStoreName: "pinecone",
+  indexName: "docs",
+  model: openai.embedding('text-embedding-3-small'),
+  description: "Analyze document relationships to find complex patterns and connections in our company's historical data"
+});
+```
+
+This example shows how to customize the tool description for a specific use case while maintaining its core purpose of relationship analysis.
+
+## Related
+
+- [createVectorQueryTool](./vector-query-tool)
+- [GraphRAG](../rag/graph-rag)

package/.docs/raw/reference/tools/mcp-configuration.mdx

@@ -0,0 +1,206 @@
+---
+title: "Reference: MCPConfiguration | Tool Management | Mastra Docs"
+description: API Reference for MCPConfiguration - A class for managing multiple Model Context Protocol servers and their tools.
+---
+
+# MCPConfiguration
+
+The `MCPConfiguration` class provides a way to manage multiple MCP server connections and their tools in a Mastra application. It handles connection lifecycle, tool namespacing, and provides convenient access to tools across all configured servers.
+
+## Constructor
+
+Creates a new instance of the MCPConfiguration class.
+
+```typescript
+constructor({
+    id?: string;
+    servers: Record<string, MastraMCPServerDefinition>
+}: {
+    servers: {
+        [serverName: string]: {
+            // For stdio-based servers
+            command?: string;
+            args?: string[];
+            env?: Record<string, string>;
+            // For SSE-based servers
+            url?: URL;
+            requestInit?: RequestInit;
+        }
+    }
+})
+```
+
+### Parameters
+
+<PropertiesTable
+  content={[
+    {
+      name: "id",
+      type: "string",
+      description:
+        "Optional unique identifier for the configuration instance. Use this to prevent memory leaks when creating multiple instances with identical configurations.",
+    },
+    {
+      name: "servers",
+      type: "Record<string, MastraMCPServerDefinition>",
+      description:
+        "A map of server configurations, where each key is a unique server identifier and the value is the server configuration.",
+    },
+  ]}
+/>
+
+## Methods
+
+### getTools()
+
+Retrieves all tools from all configured servers, with tool names namespaced by their server name (in the format `serverName_toolName`) to prevent conflicts.
+Intended to be passed onto an Agent definition.
+
+```ts
+new Agent({ tools: await mcp.getTools() });
+```
+
+### getToolsets()
+
+Returns an object mapping namespaced tool names (in the format `serverName.toolName`) to their tool implementations.
+Intended to be passed dynamically into the generate or stream method.
+
+```typescript
+const res = await agent.stream(prompt, {
+  toolsets: await mcp.getToolsets(),
+});
+```
+
+## Examples
+
+### Basic Usage
+
+```typescript
+import { MCPConfiguration } from "@mastra/mcp";
+import { Agent } from "@mastra/core/agent";
+import { openai } from "@ai-sdk/openai";
+
+const mcp = new MCPConfiguration({
+  servers: {
+    stockPrice: {
+      command: "npx",
+      args: ["tsx", "stock-price.ts"],
+      env: {
+        API_KEY: "your-api-key",
+      },
+    },
+    weather: {
+      url: new URL("http://localhost:8080/sse"),
+    },
+  },
+});
+
+// Create an agent with access to all tools
+const agent = new Agent({
+  name: "Multi-tool Agent",
+  instructions: "You have access to multiple tool servers.",
+  model: openai("gpt-4"),
+  tools: await mcp.getTools(),
+});
+```
+
+### Using Toolsets in generate() or stream()
+
+```typescript
+import { Agent } from "@mastra/core/agent";
+import { MCPConfiguration } from "@mastra/mcp";
+import { openai } from "@ai-sdk/openai";
+
+// Create the agent first, without any tools
+const agent = new Agent({
+  name: "Multi-tool Agent",
+  instructions: "You help users check stocks and weather.",
+  model: openai("gpt-4"),
+});
+
+// Later, configure MCP with user-specific settings
+const mcp = new MCPConfiguration({
+  servers: {
+    stockPrice: {
+      command: "npx",
+      args: ["tsx", "stock-price.ts"],
+      env: {
+        API_KEY: "user-123-api-key",
+      },
+    },
+    weather: {
+      url: new URL("http://localhost:8080/sse"),
+      requestInit: {
+        headers: {
+          Authorization: `Bearer user-123-token`,
+        },
+      },
+    },
+  },
+});
+
+// Pass all toolsets to stream() or generate()
+const response = await agent.stream(
+  "How is AAPL doing and what is the weather?",
+  {
+    toolsets: await mcp.getToolsets(),
+  },
+);
+```
+
+## Resource Management
+
+The `MCPConfiguration` class includes built-in memory leak prevention for managing multiple instances:
+
+1. Creating multiple instances with identical configurations without an `id` will throw an error to prevent memory leaks
+2. If you need multiple instances with identical configurations, provide a unique `id` for each instance
+3. Call `await configuration.disconnect()` before recreating an instance with the same configuration
+4. If you only need one instance, consider moving the configuration to a higher scope to avoid recreation
+
+For example, if you try to create multiple instances with the same configuration without an `id`:
+
+```typescript
+// First instance - OK
+const mcp1 = new MCPConfiguration({
+  servers: {
+    /* ... */
+  },
+});
+
+// Second instance with same config - Will throw an error
+const mcp2 = new MCPConfiguration({
+  servers: {
+    /* ... */
+  },
+});
+
+// To fix, either:
+// 1. Add unique IDs
+const mcp3 = new MCPConfiguration({
+  id: "instance-1",
+  servers: {
+    /* ... */
+  },
+});
+
+// 2. Or disconnect before recreating
+await mcp1.disconnect();
+const mcp4 = new MCPConfiguration({
+  servers: {
+    /* ... */
+  },
+});
+```
+
+## Server Lifecycle
+
+MCPConfiguration handles server connections gracefully:
+
+1. Automatic connection management for multiple servers
+2. Graceful server shutdown to prevent error messages during development
+3. Proper cleanup of resources when disconnecting
+
+## Related Information
+
+- For details about individual MCP client configuration, see the [MastraMCPClient documentation](./client)
+- For more about the Model Context Protocol, see the [@modelcontextprotocol/sdk documentation](https://github.com/modelcontextprotocol/typescript-sdk)

package/.docs/raw/reference/tools/vector-query-tool.mdx

@@ -0,0 +1,212 @@
+---
+title: "Reference: createVectorQueryTool() | RAG | Mastra Tools Docs"
+description: Documentation for the Vector Query Tool in Mastra, which facilitates semantic search over vector stores with filtering and reranking capabilities.
+---
+
+# createVectorQueryTool()
+
+The `createVectorQueryTool()` function creates a tool for semantic search over vector stores. It supports filtering, reranking, and integrates with various vector store backends.
+
+## Basic Usage
+
+```typescript
+import { openai } from '@ai-sdk/openai';
+import { createVectorQueryTool } from "@mastra/rag";
+
+const queryTool = createVectorQueryTool({
+  vectorStoreName: "pinecone",
+  indexName: "docs",
+  model: openai.embedding('text-embedding-3-small'),
+});
+```
+
+## Parameters
+
+<PropertiesTable
+  content={[
+    {
+      name: "vectorStoreName",
+      type: "string",
+      description: "Name of the vector store to query (must be configured in Mastra)",
+      isOptional: false,
+    },
+    {
+      name: "indexName",
+      type: "string",
+      description: "Name of the index within the vector store",
+      isOptional: false,
+    },
+    {
+      name: "model",
+      type: "EmbeddingModel",
+      description: "Embedding model to use for vector search",
+      isOptional: false,
+    },
+    {
+      name: "reranker",
+      type: "RerankConfig",
+      description: "Options for reranking results",
+      isOptional: true,
+    },
+    {
+      name: "id",
+      type: "string",
+      description: "Custom ID for the tool (defaults to 'VectorQuery {vectorStoreName} {indexName} Tool')",
+      isOptional: true,
+    },
+    {
+      name: "description",
+      type: "string",
+      description: "Custom description for the tool. By default: 'Access the knowledge base to find information needed to answer user questions'",
+      isOptional: true,
+    }
+  ]}
+/>
+
+### RerankConfig
+
+<PropertiesTable
+  content={[
+    {
+      name: "model",
+      type: "MastraLanguageModel",
+      description: "Language model to use for reranking",
+      isOptional: false,
+    },
+    {
+      name: "options",
+      type: "RerankerOptions",
+      description: "Options for the reranking process",
+      isOptional: true,
+      properties: [
+        {
+          type: "object",
+          parameters: [
+            {
+              name: "weights",
+              description: "Weights for scoring components (semantic: 0.4, vector: 0.4, position: 0.2)",
+              isOptional: true,
+              type: "WeightConfig",
+            },
+            {
+              name: "topK",
+              description: "Number of top results to return",
+              isOptional: true,
+              type: "number",
+              defaultValue: "3"
+            }
+          ]
+        }
+      ]
+    }
+  ]}
+/>
+
+## Returns
+
+The tool returns an object with:
+
+<PropertiesTable
+  content={[
+    {
+      name: "relevantContext",
+      type: "string",
+      description: "Combined text from the most relevant document chunks",
+    }
+  ]}
+/>
+
+## Default Tool Description
+
+The default description focuses on:
+- Finding relevant information in stored knowledge
+- Answering user questions
+- Retrieving factual content
+
+## Result Handling
+
+The tool determines the number of results to return based on the user's query, with a default of 10 results. This can be adjusted based on the query requirements.
+
+## Example with Filters
+
+```typescript
+const queryTool = createVectorQueryTool({
+  vectorStoreName: "pinecone",
+  indexName: "docs",
+  model: openai.embedding('text-embedding-3-small'),
+  enableFilters: true,
+});
+```
+
+With filtering enabled, the tool processes queries to construct metadata filters that combine with semantic search. The process works as follows:
+
+1. A user makes a query with specific filter requirements like "Find content where the 'version' field is greater than 2.0"
+2. The agent analyzes the query and constructs the appropriate filters:
+   ```typescript
+   {
+      "version": { "$gt": 2.0 }
+   }
+   ```
+
+This agent-driven approach:
+- Processes natural language queries into filter specifications
+- Implements vector store-specific filter syntax
+- Translates query terms to filter operators
+
+For detailed filter syntax and store-specific capabilities, see the [Metadata Filters](../rag/metadata-filters) documentation.
+
+For an example of how agent-driven filtering works, see the [Agent-Driven Metadata Filtering](../../../examples/rag/usage/filter-rag) example.
+
+## Example with Reranking
+
+```typescript
+const queryTool = createVectorQueryTool({
+  vectorStoreName: "milvus",
+  indexName: "documentation",
+  model: openai.embedding('text-embedding-3-small'),
+  reranker: {
+    model: openai('gpt-4o-mini'),
+    options: {
+      weights: {
+        semantic: 0.5,  // Semantic relevance weight
+        vector: 0.3,    // Vector similarity weight
+        position: 0.2   // Original position weight
+      },
+      topK: 5
+    }
+  }
+});
+```
+
+Reranking improves result quality by combining:
+- Semantic relevance: Using LLM-based scoring of text similarity
+- Vector similarity: Original vector distance scores
+- Position bias: Consideration of original result ordering
+- Query analysis: Adjustments based on query characteristics
+
+The reranker processes the initial vector search results and returns a reordered list optimized for relevance.
+
+## Example with Custom Description
+
+```typescript
+const queryTool = createVectorQueryTool({
+  vectorStoreName: "pinecone",
+  indexName: "docs",
+  model: openai.embedding('text-embedding-3-small'),
+  description: "Search through document archives to find relevant information for answering questions about company policies and procedures"
+});
+```
+
+This example shows how to customize the tool description for a specific use case while maintaining its core purpose of information retrieval.
+
+## Tool Details
+
+The tool is created with:
+- **ID**: `VectorQuery {vectorStoreName} {indexName} Tool`
+- **Input Schema**: Requires queryText and filter objects
+- **Output Schema**: Returns relevantContext string
+
+## Related
+
+- [rerank()](../rag/rerank) 
+- [createGraphRAGTool](./graph-rag-tool)