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

package/.docs/raw/reference/rag/vectorize.mdx

@@ -0,0 +1,298 @@
+---
+title: "Reference: Cloudflare Vector Store | Vector Databases | RAG | Mastra Docs"
+description: Documentation for the CloudflareVector class in Mastra, which provides vector search using Cloudflare Vectorize.
+---
+
+# Cloudflare Vector Store
+
+The CloudflareVector class provides vector search using [Cloudflare Vectorize](https://developers.cloudflare.com/vectorize/), a vector database service integrated with Cloudflare's edge network.
+
+## Constructor Options
+
+<PropertiesTable
+  content={[
+    {
+      name: "accountId",
+      type: "string",
+      description: "Cloudflare account ID",
+    },
+    {
+      name: "apiToken",
+      type: "string",
+      description: "Cloudflare API token with Vectorize permissions",
+    },
+  ]}
+/>
+
+## Methods
+
+### createIndex()
+
+<PropertiesTable
+  content={[
+    {
+      name: "indexName",
+      type: "string",
+      description: "Name of the index to create",
+    },
+    {
+      name: "dimension",
+      type: "number",
+      description: "Vector dimension (must match your embedding model)",
+    },
+    {
+      name: "metric",
+      type: "'cosine' | 'euclidean' | 'dotproduct'",
+      isOptional: true,
+      defaultValue: "cosine",
+      description:
+        "Distance metric for similarity search (dotproduct maps to dot-product)",
+    },
+  ]}
+/>
+
+### upsert()
+
+<PropertiesTable
+  content={[
+    {
+      name: "indexName",
+      type: "string",
+      description: "Name of the index to upsert into",
+    },
+    {
+      name: "vectors",
+      type: "number[][]",
+      description: "Array of embedding vectors",
+    },
+    {
+      name: "metadata",
+      type: "Record<string, any>[]",
+      isOptional: true,
+      description: "Metadata for each vector",
+    },
+    {
+      name: "ids",
+      type: "string[]",
+      isOptional: true,
+      description: "Optional vector IDs (auto-generated if not provided)",
+    },
+  ]}
+/>
+
+### query()
+
+<PropertiesTable
+  content={[
+    {
+      name: "indexName",
+      type: "string",
+      description: "Name of the index to query",
+    },
+    {
+      name: "queryVector",
+      type: "number[]",
+      description: "Query vector to find similar vectors",
+    },
+    {
+      name: "topK",
+      type: "number",
+      isOptional: true,
+      defaultValue: "10",
+      description: "Number of results to return",
+    },
+    {
+      name: "filter",
+      type: "Record<string, any>",
+      isOptional: true,
+      description: "Metadata filters for the query",
+    },
+    {
+      name: "includeVector",
+      type: "boolean",
+      isOptional: true,
+      defaultValue: "false",
+      description: "Whether to include vectors in the results",
+    },
+  ]}
+/>
+
+### listIndexes()
+
+Returns an array of index names as strings.
+
+### describeIndex()
+
+<PropertiesTable
+  content={[
+    {
+      name: "indexName",
+      type: "string",
+      description: "Name of the index to describe",
+    },
+  ]}
+/>
+
+Returns:
+
+```typescript copy
+interface IndexStats {
+  dimension: number;
+  count: number;
+  metric: "cosine" | "euclidean" | "dotproduct";
+}
+```
+
+### deleteIndex()
+
+<PropertiesTable
+  content={[
+    {
+      name: "indexName",
+      type: "string",
+      description: "Name of the index to delete",
+    },
+  ]}
+/>
+
+### createMetadataIndex()
+
+Creates an index on a metadata field to enable filtering.
+
+<PropertiesTable
+  content={[
+    {
+      name: "indexName",
+      type: "string",
+      description: "Name of the index containing the metadata field",
+    },
+    {
+      name: "propertyName",
+      type: "string",
+      description: "Name of the metadata field to index",
+    },
+    {
+      name: "indexType",
+      type: "'string' | 'number' | 'boolean'",
+      description: "Type of the metadata field",
+    },
+  ]}
+/>
+
+### deleteMetadataIndex()
+
+Removes an index from a metadata field.
+
+<PropertiesTable
+  content={[
+    {
+      name: "indexName",
+      type: "string",
+      description: "Name of the index containing the metadata field",
+    },
+    {
+      name: "propertyName",
+      type: "string",
+      description: "Name of the metadata field to remove indexing from",
+    },
+  ]}
+/>
+
+### listMetadataIndexes()
+
+Lists all metadata field indexes for an index.
+
+<PropertiesTable
+  content={[
+    {
+      name: "indexName",
+      type: "string",
+      description: "Name of the index to list metadata indexes for",
+    },
+  ]}
+/>
+
+### updateIndexById()
+
+Updates a vector or metadata for a specific ID within an index.
+
+<PropertiesTable
+  content={[
+    {
+      name: "indexName",
+      type: "string",
+      description: "Name of the index containing the ID to update",
+    },
+    {
+      name: "id",
+      type: "string",
+      description: "Unique identifier of the vector or metadata to update",
+    },
+    {
+      name: "update",
+      type: "{ vector?: number[]; metadata?: Record<string, any>; }",
+      description: "Object containing the vector and/or metadata to update",
+    },
+  ]}
+/>
+
+### deleteIndexById()
+
+Deletes a vector and its associated metadata for a specific ID within an index.
+
+<PropertiesTable
+  content={[
+    {
+      name: "indexName",
+      type: "string",
+      description: "Name of the index containing the ID to delete",
+    },
+    {
+      name: "id",
+      type: "string",
+      description: "Unique identifier of the vector and metadata to delete",
+    },
+  ]}
+/>
+
+## Response Types
+
+Query results are returned in this format:
+
+```typescript copy
+interface QueryResult {
+  id: string;
+  score: number;
+  metadata: Record<string, any>;
+  vector?: number[];
+}
+```
+
+## Error Handling
+
+The store throws typed errors that can be caught:
+
+```typescript copy
+try {
+  await store.query({
+    indexName: "index_name",
+    queryVector: queryVector,
+  });
+} catch (error) {
+  if (error instanceof VectorStoreError) {
+    console.log(error.code); // 'connection_failed' | 'invalid_dimension' | etc
+    console.log(error.details); // Additional error context
+  }
+}
+```
+
+## Environment Variables
+
+Required environment variables:
+
+- `CLOUDFLARE_ACCOUNT_ID`: Your Cloudflare account ID
+- `CLOUDFLARE_API_TOKEN`: Your Cloudflare API token with Vectorize permissions
+
+## Related
+
+- [Metadata Filters](./metadata-filters)

package/.docs/raw/reference/storage/libsql.mdx

@@ -0,0 +1,74 @@
+---
+title: "LibSQL Storage | Storage System | Mastra Core"
+description: Documentation for the LibSQL storage implementation in Mastra.
+---
+
+# LibSQL Storage
+
+The LibSQL storage implementation provides a SQLite-compatible storage solution that can run both in-memory and as a persistent database.
+
+## Installation
+
+```bash
+npm install @mastra/storage-libsql
+```
+
+## Usage
+
+```typescript copy showLineNumbers
+import { LibSQLStore } from "@mastra/core/storage/libsql";
+
+// File database (development)
+const storage = new LibSQLStore({
+    config: {
+        url: 'file:storage.db',
+    }
+});
+
+// Persistent database (production)
+const storage = new LibSQLStore({
+    config: {
+        url: process.env.DATABASE_URL,
+    }
+});
+```
+
+## Parameters
+
+<PropertiesTable
+  content={[
+    {
+      name: "url",
+      type: "string",
+      description:
+        "Database URL. Use ':memory:' for in-memory database, 'file:filename.db' for a file database, or any LibSQL-compatible connection string for persistent storage.",
+      isOptional: false,
+    },
+    {
+      name: "authToken",
+      type: "string",
+      description: "Authentication token for remote LibSQL databases.",
+      isOptional: true,
+    },
+  ]}
+/>
+
+## Additional Notes
+
+### In-Memory vs Persistent Storage
+
+The file configuration (`file:storage.db`) is useful for:
+
+- Development and testing
+- Temporary storage
+- Quick prototyping
+
+For production use cases, use a persistent database URL: `libsql://your-database.turso.io`
+
+### Schema Management
+
+The storage implementation handles schema creation and updates automatically. It creates the following tables:
+
+- `threads`: Stores conversation threads
+- `messages`: Stores individual messages
+- `metadata`: Stores additional metadata for threads and messages

package/.docs/raw/reference/storage/postgresql.mdx

@@ -0,0 +1,48 @@
+---
+title: "PostgreSQL Storage | Storage System | Mastra Core"
+description: Documentation for the PostgreSQL storage implementation in Mastra.
+---
+
+# PostgreSQL Storage
+
+The PostgreSQL storage implementation provides a production-ready storage solution using PostgreSQL databases.
+
+## Installation
+
+```bash
+npm install @mastra/pg
+```
+
+## Usage
+
+```typescript copy showLineNumbers
+import { PostgresStore } from "@mastra/pg";
+
+const storage = new PostgresStore({
+  connectionString: process.env.DATABASE_URL,
+});
+```
+
+## Parameters
+
+<PropertiesTable
+  content={[
+    {
+      name: "connectionString",
+      type: "string",
+      description:
+        "PostgreSQL connection string (e.g., postgresql://user:pass@host:5432/dbname)",
+      isOptional: false,
+    },
+  ]}
+/>
+
+## Additional Notes
+
+### Schema Management
+
+The storage implementation handles schema creation and updates automatically. It creates the following tables:
+
+- `threads`: Stores conversation threads
+- `messages`: Stores individual messages
+- `metadata`: Stores additional metadata for threads and messages

package/.docs/raw/reference/storage/upstash.mdx

@@ -0,0 +1,86 @@
+---
+title: "Upstash Storage | Storage System | Mastra Core"
+description: Documentation for the Upstash storage implementation in Mastra.
+---
+
+# Upstash Storage
+
+The Upstash storage implementation provides a serverless-friendly storage solution using Upstash's Redis-compatible key-value store.
+
+## Installation
+
+```bash
+npm install @mastra/upstash
+```
+
+## Usage
+
+```typescript copy showLineNumbers
+import { UpstashStore } from "@mastra/upstash";
+
+const storage = new UpstashStore({
+  url: process.env.UPSTASH_URL,
+  token: process.env.UPSTASH_TOKEN,
+});
+```
+
+## Parameters
+
+<PropertiesTable
+  content={[
+    {
+      name: "url",
+      type: "string",
+      description: "Upstash Redis URL",
+      isOptional: false,
+    },
+    {
+      name: "token",
+      type: "string",
+      description: "Upstash Redis authentication token",
+      isOptional: false,
+    },
+    {
+      name: "prefix",
+      type: "string",
+      description: "Key prefix for all stored items",
+      isOptional: true,
+      defaultValue: "mastra:",
+    },
+  ]}
+/>
+
+## Additional Notes
+
+### Key Structure
+
+The Upstash storage implementation uses a key-value structure:
+
+- Thread keys: `{prefix}thread:{threadId}`
+- Message keys: `{prefix}message:{messageId}`
+- Metadata keys: `{prefix}metadata:{entityId}`
+
+### Serverless Benefits
+
+Upstash storage is particularly well-suited for serverless deployments:
+
+- No connection management needed
+- Pay-per-request pricing
+- Global replication options
+- Edge-compatible
+
+### Data Persistence
+
+Upstash provides:
+
+- Automatic data persistence
+- Point-in-time recovery
+- Cross-region replication options
+
+### Performance Considerations
+
+For optimal performance:
+
+- Use appropriate key prefixes to organize data
+- Monitor Redis memory usage
+- Consider data expiration policies if needed

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

@@ -0,0 +1,207 @@
+---
+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 = {},
+    timeout = 60000,
+}: {
+    name: string;
+    server: StdioServerParameters | SSEClientParameters;
+    capabilities?: ClientCapabilities;
+    version?: string;
+    timeout?: number;
+})
+```
+
+### 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.",
+    },
+    {
+      name: "timeout",
+      type: "number",
+      isOptional: true,
+      defaultValue: 60000,
+      description: "The timeout duration, in milliseconds, for client tool calls.",
+    },
+  ]}
+/>
+
+## 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 - Note: requestInit alone isn't enough for SSE
+    requestInit: {
+      headers: {
+        Authorization: "Bearer your-token",
+      },
+    },
+    // Required for SSE connections with custom headers
+    eventSourceInit: {
+      fetch(input: Request | URL | string, init?: RequestInit) {
+        const headers = new Headers(init?.headers || {});
+        headers.set('Authorization', 'Bearer your-token');
+        return fetch(input, {
+          ...init,
+          headers,
+        });
+      },
+    },
+  },
+});
+
+// The rest of the usage is identical to the stdio example
+```
+
+### Important Note About SSE Authentication
+
+When using SSE connections with authentication or custom headers, you need to configure both `requestInit` and `eventSourceInit`. This is because SSE connections use the browser's EventSource API, which doesn't support custom headers directly. 
+
+
+The `eventSourceInit` configuration allows you to customize the underlying fetch request used for the SSE connection, ensuring your authentication headers are properly included.
+Without `eventSourceInit`, authentication headers specified in `requestInit` won't be included in the connection request, leading to 401 Unauthorized errors.
+
+## Related Information
+
+- For managing multiple MCP servers in your application, see the [MCPConfiguration documentation](./mcp-configuration)
+- For more details about the Model Context Protocol, see the [@modelcontextprotocol/sdk documentation](https://github.com/modelcontextprotocol/typescript-sdk).