@mastra/mcp-docs-server 1.0.0-beta.1 → 1.0.0-beta.10

package/.docs/raw/reference/core/mastra-model-gateway.mdx

@@ -0,0 +1,227 @@
+---
+title: "Reference: MastraModelGateway | Core"
+description: "Base class for creating custom model gateways"
+---
+
+# MastraModelGateway
+
+Abstract base class for implementing custom model gateways. Gateways handle provider-specific logic for accessing language models, including provider configuration, authentication, URL construction, and model instantiation.
+
+## Class Overview
+
+```typescript
+import { MastraModelGateway, type ProviderConfig } from '@mastra/core/llm';
+import { createOpenAICompatible } from '@ai-sdk/openai-compatible-v5';
+import type { LanguageModelV2 } from '@ai-sdk/provider-v5';
+
+class MyCustomGateway extends MastraModelGateway {
+  readonly id = 'custom';
+  readonly name = 'My Custom Gateway';
+
+  async fetchProviders(): Promise<Record<string, ProviderConfig>> {
+    return {
+      'my-provider': {
+        name: 'My Provider',
+        models: ['model-1', 'model-2'],
+        apiKeyEnvVar: 'MY_API_KEY',
+        gateway: this.id,
+      },
+    };
+  }
+
+  buildUrl(modelId: string, envVars?: Record<string, string>): string {
+    return 'https://api.my-provider.com/v1';
+  }
+
+  async getApiKey(modelId: string): Promise<string> {
+    const apiKey = process.env.MY_API_KEY;
+    if (!apiKey) throw new Error('MY_API_KEY not set');
+    return apiKey;
+  }
+
+  async resolveLanguageModel({
+    modelId,
+    providerId,
+    apiKey,
+  }: {
+    modelId: string;
+    providerId: string;
+    apiKey: string;
+  }): Promise<LanguageModelV2> {
+    const baseURL = this.buildUrl(`${providerId}/${modelId}`);
+    return createOpenAICompatible({
+      name: providerId,
+      apiKey,
+      baseURL,
+    }).chatModel(modelId);
+  }
+}
+```
+
+## Required Properties
+
+<PropertiesTable
+  content={[
+    {
+      name: 'id',
+      type: 'string',
+      description: 'Unique identifier for the gateway. This ID is used as the prefix for all providers from this gateway (e.g., "netlify/anthropic"). Exception: models.dev is a provider registry and doesn\'t use a prefix.',
+    },
+    {
+      name: 'name',
+      type: 'string',
+      description: 'Human-readable name for the gateway.',
+    },
+  ]}
+/>
+
+## Required Methods
+
+### fetchProviders()
+
+Fetches provider configurations from the gateway.
+
+**Returns:** `Promise<Record<string, ProviderConfig>>`
+
+**ProviderConfig Structure:**
+<PropertiesTable
+  content={[
+    {
+      name: 'name',
+      type: 'string',
+      description: 'Display name of the provider',
+    },
+    {
+      name: 'models',
+      type: 'string[]',
+      description: 'Array of available model IDs',
+    },
+    {
+      name: 'apiKeyEnvVar',
+      type: 'string | string[]',
+      description: 'Environment variable(s) for API key',
+    },
+    {
+      name: 'gateway',
+      type: 'string',
+      description: 'Gateway identifier',
+    },
+    {
+      name: 'url',
+      type: 'string',
+      isOptional: true,
+      description: 'Optional base API URL',
+    },
+    {
+      name: 'apiKeyHeader',
+      type: 'string',
+      isOptional: true,
+      description: 'Optional custom auth header name',
+    },
+    {
+      name: 'docUrl',
+      type: 'string',
+      isOptional: true,
+      description: 'Optional documentation URL',
+    },
+  ]}
+/>
+
+### buildUrl()
+
+Builds the API URL for a specific model/provider combination.
+
+**Parameters:**
+<PropertiesTable
+  content={[
+    {
+      name: 'modelId',
+      type: 'string',
+      description: 'Full model ID (e.g., "custom/my-provider/model-1")',
+    },
+    {
+      name: 'envVars',
+      type: 'Record<string, string>',
+      isOptional: true,
+      description: 'Optional environment variables',
+    },
+  ]}
+/>
+
+**Returns:** `string | undefined | Promise<string | undefined>`
+
+### getApiKey()
+
+Retrieves the API key for authentication.
+
+**Parameters:**
+<PropertiesTable
+  content={[
+    {
+      name: 'modelId',
+      type: 'string',
+      description: 'Full model ID',
+    },
+  ]}
+/>
+
+**Returns:** `Promise<string>`
+
+### resolveLanguageModel()
+
+Creates a language model instance.
+
+**Parameters:**
+<PropertiesTable
+  content={[
+    {
+      name: 'modelId',
+      type: 'string',
+      description: 'The model ID',
+    },
+    {
+      name: 'providerId',
+      type: 'string',
+      description: 'The provider ID',
+    },
+    {
+      name: 'apiKey',
+      type: 'string',
+      description: 'The API key for authentication',
+    },
+  ]}
+/>
+
+**Returns:** `Promise<LanguageModelV2> | LanguageModelV2`
+
+## Instance Methods
+
+### getId()
+
+Returns the gateway's unique identifier.
+
+**Returns:** `string` - The gateway's `id` property
+
+## Model ID Format
+
+For true gateways, the gateway ID is used as a prefix and models are accessed using this format:
+
+```
+[gateway-id]/[provider]/[model]
+```
+
+Examples:
+- Gateway with `id = 'custom'`: `'custom/my-provider/model-1'`
+
+## Built-in Implementations
+
+- **NetlifyGateway** - Netlify AI Gateway integration
+- **ModelsDevGateway** - Registry of OpenAI-compatible providers
+
+## Related
+
+- [Custom Gateways Guide](/models/v1/gateways/custom-gateways) - Complete guide to creating custom gateways
+- [Mastra.addGateway()](/reference/v1/core/addGateway) - Add a gateway to Mastra
+- [Mastra.getGateway()](/reference/v1/core/getGateway) - Get gateway by registration key
+- [Mastra.getGatewayById()](/reference/v1/core/getGatewayById) - Get gateway by ID
+- [Mastra.listGateways()](/reference/v1/core/listGateways) - List all gateways

package/.docs/raw/reference/core/setLogger.mdx

@@ -1,5 +1,5 @@
 ---
-title: "Reference: Mastra.setLogger() | Core | Mastra Docs"
+title: "Reference: Mastra.setLogger() | Core"
 description: "Documentation for the `Mastra.setLogger()` method in Mastra, which sets the logger for all components (agents, workflows, etc.)."
 ---
 
@@ -45,5 +45,5 @@ This method does not return a value.
 
 ## Related
 
-- [Logging overview](/docs/v1/logging)
+- [Logging overview](/docs/v1/observability/logging)
 - [Logger reference](/reference/v1/logging/pino-logger)

package/.docs/raw/reference/core/setStorage.mdx

@@ -1,5 +1,5 @@
 ---
-title: "Reference: Mastra.setStorage() | Core | Mastra Docs"
+title: "Reference: Mastra.setStorage() | Core"
 description: "Documentation for the `Mastra.setStorage()` method in Mastra, which sets the storage instance for the Mastra instance."
 ---
 

package/.docs/raw/reference/core/setTelemetry.mdx

@@ -1,5 +1,5 @@
 ---
-title: "Reference: Mastra.setTelemetry() | Core | Mastra Docs"
+title: "Reference: Mastra.setTelemetry() | Core"
 description: "Documentation for the `Mastra.setTelemetry()` method in Mastra, which sets the telemetry configuration for all components."
 ---
 
@@ -32,5 +32,5 @@ This method does not return a value.
 
 ## Related
 
-- [Logging](/docs/v1/logging)
+- [Logging](/docs/v1/observability/logging)
 - [PinoLogger](/reference/v1/logging/pino-logger)

package/.docs/raw/reference/deployer/cloudflare.mdx

@@ -1,5 +1,5 @@
 ---
-title: "Reference: CloudflareDeployer | Deployer | Mastra Docs"
+title: "Reference: CloudflareDeployer | Deployer"
 description: "Documentation for the CloudflareDeployer class, which deploys Mastra applications to Cloudflare Workers."
 ---
 

package/.docs/raw/reference/deployer/deployer.mdx

@@ -1,5 +1,5 @@
 ---
-title: "Reference: Deployer | Deployer | Mastra Docs"
+title: "Reference: Deployer | Deployer"
 description: Documentation for the Deployer abstract class, which handles packaging and deployment of Mastra applications.
 asIndexPage: true
 ---

package/.docs/raw/reference/deployer/netlify.mdx

@@ -1,5 +1,5 @@
 ---
-title: "Reference: NetlifyDeployer | Deployer | Mastra Docs"
+title: "Reference: NetlifyDeployer | Deployer"
 description: "Documentation for the NetlifyDeployer class, which deploys Mastra applications to Netlify Functions."
 ---
 
@@ -9,12 +9,11 @@ The `NetlifyDeployer` class handles deployment of standalone Mastra applications
 
 ## Usage example
 
-```typescript title="src/mastra/index.ts" showLineNumbers copy
+```typescript title="src/mastra/index.ts" copy
 import { Mastra } from "@mastra/core";
 import { NetlifyDeployer } from "@mastra/deployer-netlify";
 
 export const mastra = new Mastra({
-  // ...
   deployer: new NetlifyDeployer(),
 });
 ```

package/.docs/raw/reference/deployer/vercel.mdx

@@ -1,5 +1,5 @@
 ---
-title: "Reference: VercelDeployer | Deployer | Mastra Docs"
+title: "Reference: VercelDeployer | Deployer"
 description: "Documentation for the VercelDeployer class, which deploys Mastra applications to Vercel."
 ---
 

package/.docs/raw/reference/evals/answer-relevancy.mdx

@@ -1,5 +1,5 @@
 ---
-title: "Reference: Answer Relevancy Scorer | Evals | Mastra Docs"
+title: "Reference: Answer Relevancy Scorer | Evals"
 description: Documentation for the Answer Relevancy Scorer in Mastra, which evaluates how well LLM outputs address the input query.
 ---
 
@@ -112,115 +112,45 @@ A relevancy score between 0 and 1:
 - **0.1–0.3**: The response includes minimal relevant content and largely misses the intent of the query.
 - **0.0**: The response is entirely unrelated and does not answer the query.
 
-## Examples
+## Example
 
-### High relevancy example
+Evaluate agent responses for relevancy across different scenarios:
 
-In this example, the response accurately addresses the input query with specific and relevant information.
-
-```typescript title="src/example-high-answer-relevancy.ts" showLineNumbers copy
+```typescript title="src/example-answer-relevancy.ts" showLineNumbers copy
+import { runEvals } from "@mastra/core/evals";
 import { createAnswerRelevancyScorer } from "@mastra/evals/scorers/prebuilt";
+import { myAgent } from "./agent";
 
-const scorer = createAnswerRelevancyScorer({ model: "openai/gpt-4o-mini" });
+const scorer = createAnswerRelevancyScorer({ model: "openai/gpt-4o" });
 
-const inputMessages = [
-  {
-    role: "user",
-    content: "What are the health benefits of regular exercise?",
+const result = await runEvals({
+  data: [
+    {
+      input: "What are the health benefits of regular exercise?",
+    },
+    {
+      input: "What should a healthy breakfast include?",
+    },
+    {
+      input: "What are the benefits of meditation?",
+    },
+  ],
+  scorers: [scorer],
+  target: myAgent,
+  onItemComplete: ({ scorerResults }) => {
+    console.log({
+      score: scorerResults[scorer.id].score,
+      reason: scorerResults[scorer.id].reason,
+    });
   },
-];
-const outputMessage = {
-  text: "Regular exercise improves cardiovascular health, strengthens muscles, boosts metabolism, and enhances mental well-being through the release of endorphins.",
-};
-
-const result = await scorer.run({
-  input: inputMessages,
-  output: outputMessage,
 });
 
-console.log(result);
+console.log(result.scores);
 ```
 
-#### High relevancy output
-
-The output receives a high score because it accurately answers the query without including unrelated information.
-
-```typescript
-{
-  score: 1,
-  reason: 'The score is 1 because the output directly addresses the question by providing multiple explicit health benefits of regular exercise, including improvements in cardiovascular health, muscle strength, metabolism, and mental well-being. Each point is relevant and contributes to a comprehensive understanding of the health benefits.'
-}
-```
+For more details on `runEvals`, see the [runEvals reference](/reference/v1/evals/run-evals).
 
-### Partial relevancy example
-
-In this example, the response addresses the query in part but includes additional information that isn't directly relevant.
-
-```typescript title="src/example-partial-answer-relevancy.ts" showLineNumbers copy
-import { createAnswerRelevancyScorer } from "@mastra/evals/scorers/prebuilt";
-
-const scorer = createAnswerRelevancyScorer({ model: "openai/gpt-4o-mini" });
-
-const inputMessages = [
-  { role: "user", content: "What should a healthy breakfast include?" },
-];
-const outputMessage = {
-  text: "A nutritious breakfast should include whole grains and protein. However, the timing of your breakfast is just as important - studies show eating within 2 hours of waking optimizes metabolism and energy levels throughout the day.",
-};
-
-const result = await scorer.run({
-  input: inputMessages,
-  output: outputMessage,
-});
-
-console.log(result);
-```
-
-#### Partial relevancy output
-
-The output receives a lower score because it partially answers the query. While some relevant information is included, unrelated details reduce the overall relevance.
-
-```typescript
-{
-  score: 0.25,
-  reason: 'The score is 0.25 because the output provides a direct answer by mentioning whole grains and protein as components of a healthy breakfast, which is relevant. However, the additional information about the timing of breakfast and its effects on metabolism and energy levels is not directly related to the question, leading to a lower overall relevance score.'
-}
-```
-
-## Low relevancy example
-
-In this example, the response does not address the query and contains information that is entirely unrelated.
-
-```typescript title="src/example-low-answer-relevancy.ts" showLineNumbers copy
-import { createAnswerRelevancyScorer } from "@mastra/evals/scorers/prebuilt";
-
-const scorer = createAnswerRelevancyScorer({ model: "openai/gpt-4o-mini" });
-
-const inputMessages = [
-  { role: "user", content: "What are the benefits of meditation?" },
-];
-const outputMessage = {
-  text: "The Great Wall of China is over 13,000 miles long and was built during the Ming Dynasty to protect against invasions.",
-};
-
-const result = await scorer.run({
-  input: inputMessages,
-  output: outputMessage,
-});
-
-console.log(result);
-```
-
-#### Low relevancy output
-
-The output receives a score of 0 because it fails to answer the query or provide any relevant information.
-
-```typescript
-{
-  score: 0,
-  reason: 'The score is 0 because the output about the Great Wall of China is completely unrelated to the benefits of meditation, providing no relevant information or context that addresses the input question.'
-}
-```
+To add this scorer to an agent, see the [Scorers overview](/docs/v1/evals/overview) guide.
 
 ## Related