@mastra/mcp-docs-server 0.0.1-alpha.1

package/.docs/raw/reference/tools/client.mdx

@@ -0,0 +1,180 @@
+---
+title: "Reference: MastraMCPClient | Tool Discovery | Mastra Docs"
+description: API Reference for MastraMCPClient - A client implementation for the Model Context Protocol.
+---
+
+# MastraMCPClient
+
+The `MastraMCPClient` class provides a client implementation for interacting with Model Context Protocol (MCP) servers. It handles connection management, resource discovery, and tool execution through the MCP protocol.
+
+## Constructor
+
+Creates a new instance of the MastraMCPClient.
+
+```typescript
+constructor({
+    name,
+    version = '1.0.0',
+    server,
+    capabilities = {},
+}: {
+    name: string;
+    server: StdioServerParameters | SSEClientParameters;
+    capabilities?: ClientCapabilities;
+    version?: string;
+})
+```
+
+### Parameters
+
+<PropertiesTable
+  content={[
+    {
+      name: "name",
+      type: "string",
+      description: "The name identifier for this client instance.",
+    },
+    {
+      name: "version",
+      type: "string",
+      isOptional: true,
+      defaultValue: "1.0.0",
+      description: "The version of the client.",
+    },
+    {
+      name: "server",
+      type: "StdioServerParameters | SSEClientParameters",
+      description:
+        "Configuration parameters for either a stdio server connection or an SSE server connection.",
+    },
+    {
+      name: "capabilities",
+      type: "ClientCapabilities",
+      isOptional: true,
+      defaultValue: "{}",
+      description: "Optional capabilities configuration for the client.",
+    },
+  ]}
+/>
+
+## Methods
+
+### connect()
+
+Establishes a connection with the MCP server.
+
+```typescript
+async connect(): Promise<void>
+```
+
+### disconnect()
+
+Closes the connection with the MCP server.
+
+```typescript
+async disconnect(): Promise<void>
+```
+
+### resources()
+
+Retrieves the list of available resources from the server.
+
+```typescript
+async resources(): Promise<ListResourcesResult>
+```
+
+### tools()
+
+Fetches and initializes available tools from the server, converting them into Mastra-compatible tool formats.
+
+```typescript
+async tools(): Promise<Record<string, Tool>>
+```
+
+Returns an object mapping tool names to their corresponding Mastra tool implementations.
+
+## Examples
+
+### Using with Mastra Agent
+
+#### Example with Stdio Server
+
+```typescript
+import { Agent } from "@mastra/core/agent";
+import { MastraMCPClient } from "@mastra/mcp";
+import { openai } from "@ai-sdk/openai";
+
+// Initialize the MCP client using mcp/fetch as an example https://hub.docker.com/r/mcp/fetch
+// Visit https://github.com/docker/mcp-servers for other reference docker mcp servers
+const fetchClient = new MastraMCPClient({
+  name: "fetch",
+  server: {
+    command: "docker",
+    args: ["run", "-i", "--rm", "mcp/fetch"],
+  },
+});
+
+// Create a Mastra Agent
+const agent = new Agent({
+  name: "Fetch agent",
+  instructions:
+    "You are able to fetch data from URLs on demand and discuss the response data with the user.",
+  model: openai("gpt-4o-mini"),
+});
+
+try {
+  // Connect to the MCP server
+  await fetchClient.connect();
+
+  // Gracefully handle process exits so the docker subprocess is cleaned up
+  process.on("exit", () => {
+    fetchClient.disconnect();
+  });
+
+  // Get available tools
+  const tools = await fetchClient.tools();
+
+  // Use the agent with the MCP tools
+  const response = await agent.generate(
+    "Tell me about mastra.ai/docs. Tell me generally what this page is and the content it includes.",
+    {
+      toolsets: {
+        fetch: tools,
+      },
+    },
+  );
+
+  console.log("\n\n" + response.text);
+} catch (error) {
+  console.error("Error:", error);
+} finally {
+  // Always disconnect when done
+  await fetchClient.disconnect();
+}
+```
+
+#### Example with SSE Server
+
+```typescript
+// Initialize the MCP client using an SSE server
+const sseClient = new MastraMCPClient({
+  name: "sse-client",
+  server: {
+    url: new URL("https://your-mcp-server.com/sse"),
+    // Optional fetch request configuration
+    requestInit: {
+      headers: {
+        Authorization: "Bearer your-token",
+      },
+    },
+  },
+});
+
+// The rest of the usage is identical to the stdio example
+```
+
+## Related Information
+
+- For managing multiple MCP servers in your application, see the [MCPConfiguration documentation](./configuration)
+- For more details about the Model Context Protocol, see the [@modelcontextprotocol/sdk documentation](https://github.com/modelcontextprotocol/typescript-sdk).
+

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)