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

package/.docs/raw/reference/core/mastra-class.mdx

@@ -0,0 +1,232 @@
+---
+title: "Mastra Core"
+description: Documentation for the Mastra Class, the core entry point for managing agents, workflows, and server endpoints.
+---
+
+# The Mastra Class
+
+The Mastra class is the core entry point for your application. It manages agents, workflows, and server endpoints.
+
+## Constructor Options
+
+<PropertiesTable
+  content={[
+    {
+      name: "agents",
+      type: "Agent[]",
+      description: "Array of Agent instances to register",
+      isOptional: true,
+      defaultValue: "[]",
+    },
+    {
+      name: "tools",
+      type: "Record<string, ToolApi>",
+      description:
+        "Custom tools to register. Structured as a key-value pair, with keys being the tool name and values being the tool function.",
+      isOptional: true,
+      defaultValue: "{}",
+    },
+    {
+      name: "storage",
+      type: "MastraStorage",
+      description: "Storage engine instance for persisting data",
+      isOptional: true,
+    },
+    {
+      name: "vectors",
+      type: "Record<string, MastraVector>",
+      description:
+        "Vector store instance, used for semantic search and vector-based tools (eg Pinecone, PgVector or Qdrant)",
+      isOptional: true,
+    },
+    {
+      name: "logger",
+      type: "Logger",
+      description: "Logger instance created with createLogger()",
+      isOptional: true,
+      defaultValue: "Console logger with INFO level",
+    },
+    {
+      name: "workflows",
+      type: "Record<string, Workflow>",
+      description: "Workflows to register. Structured as a key-value pair, with keys being the workflow name and values being the workflow instance.",
+      isOptional: true,
+      defaultValue: "{}",
+    },
+    {
+      name: "serverMiddleware",
+      type: "Array<{ handler: (c: any, next: () => Promise<void>) => Promise<Response | void>; path?: string; }>",
+      description: "Server middleware functions to be applied to API routes. Each middleware can specify a path pattern (defaults to '/api/*').",
+      isOptional: true,
+      defaultValue: "[]",
+    },
+  ]}
+/>
+
+## Initialization
+
+The Mastra class is typically initialized in your `src/mastra/index.ts` file:
+
+```typescript copy filename=src/mastra/index.ts
+import { Mastra } from "@mastra/core";
+import { createLogger } from "@mastra/core/logger";
+
+// Basic initialization
+export const mastra = new Mastra({});
+
+// Full initialization with all options
+export const mastra = new Mastra({
+  agents: {},
+  workflows: [],
+  integrations: [],
+  logger: createLogger({
+    name: "My Project",
+    level: "info",
+  }),
+  storage: {},
+  tools: {},
+  vectors: {},
+});
+```
+
+You can think of the `Mastra` class as a top-level registry. When you register tools with Mastra, your registered agents and workflows can use them. When you register integrations with Mastra, agents, workflows, and tools can use them.
+
+## Methods
+
+<PropertiesTable
+  content={[
+    {
+      name: "getAgent(name)",
+      type: "Agent",
+      description:
+        "Returns an agent instance by id. Throws if agent not found.",
+      example: 'const agent = mastra.getAgent("agentOne");',
+    },
+    {
+      name: "getAgents()",
+      type: "Record<string, Agent>",
+      description:
+        "Returns all registered agents as a key-value object.",
+      example: 'const agents = mastra.getAgents();',
+    },
+    {
+      name: "getWorkflow(id, { serialized })",
+      type: "Workflow",
+      description:
+        "Returns a workflow instance by id. The serialized option (default: false) returns a simplified representation with just the name.",
+      example: 'const workflow = mastra.getWorkflow("myWorkflow");',
+    },
+    {
+      name: "getWorkflows({ serialized })",
+      type: "Record<string, Workflow>",
+      description:
+        "Returns all registered workflows. The serialized option (default: false) returns simplified representations.",
+      example: 'const workflows = mastra.getWorkflows();',
+    },
+    {
+      name: "getVector(name)",
+      type: "MastraVector",
+      description:
+        "Returns a vector store instance by name. Throws if not found.",
+      example: 'const vectorStore = mastra.getVector("myVectorStore");',
+    },
+    {
+      name: "getVectors()",
+      type: "Record<string, MastraVector>",
+      description:
+        "Returns all registered vector stores as a key-value object.",
+      example: 'const vectorStores = mastra.getVectors();',
+    },
+    {
+      name: "getDeployer()",
+      type: "MastraDeployer | undefined",
+      description:
+        "Returns the configured deployer instance, if any.",
+      example: 'const deployer = mastra.getDeployer();',
+    },
+    {
+      name: "getStorage()",
+      type: "MastraStorage | undefined",
+      description:
+        "Returns the configured storage instance.",
+      example: 'const storage = mastra.getStorage();',
+    },
+    {
+      name: "getMemory()",
+      type: "MastraMemory | undefined",
+      description:
+        "Returns the configured memory instance. Note: This is deprecated, memory should be added to agents directly.",
+      example: 'const memory = mastra.getMemory();',
+    },
+    {
+      name: "getServerMiddleware()",
+      type: "Array<{ handler: Function; path: string; }>",
+      description:
+        "Returns the configured server middleware functions.",
+      example: 'const middleware = mastra.getServerMiddleware();',
+    },
+    {
+      name: "setStorage(storage)",
+      type: "void",
+      description:
+        "Sets the storage instance for the Mastra instance.",
+      example: 'mastra.setStorage(new DefaultStorage());',
+    },
+    {
+      name: "setLogger({ logger })",
+      type: "void",
+      description:
+        "Sets the logger for all components (agents, workflows, etc.).",
+      example: 'mastra.setLogger({ logger: createLogger({ name: "MyLogger" }) });',
+    },
+    {
+      name: "setTelemetry(telemetry)",
+      type: "void",
+      description:
+        "Sets the telemetry configuration for all components.",
+      example: 'mastra.setTelemetry({ export: { type: "console" } });',
+    },
+    {
+      name: "getLogger()",
+      type: "Logger",
+      description:
+        "Gets the configured logger instance.",
+      example: 'const logger = mastra.getLogger();',
+    },
+    {
+      name: "getTelemetry()",
+      type: "Telemetry | undefined",
+      description:
+        "Gets the configured telemetry instance.",
+      example: 'const telemetry = mastra.getTelemetry();',
+    },
+    {
+      name: "getLogsByRunId({ runId, transportId })",
+      type: "Promise<any>",
+      description:
+        "Retrieves logs for a specific run ID and transport ID.",
+      example: 'const logs = await mastra.getLogsByRunId({ runId: "123", transportId: "456" });',
+    },
+    {
+      name: "getLogs(transportId)",
+      type: "Promise<any>",
+      description:
+        "Retrieves all logs for a specific transport ID.",
+      example: 'const logs = await mastra.getLogs("transportId");',
+    },
+  ]}
+/>
+
+## Error Handling
+
+The Mastra class methods throw typed errors that can be caught:
+
+```typescript copy
+try {
+  const tool = mastra.getTool("nonexistentTool");
+} catch (error) {
+  if (error instanceof Error) {
+    console.log(error.message); // "Tool with name nonexistentTool not found"
+  }
+}
+```

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

@@ -0,0 +1,176 @@
+---
+title: "Cloudflare Deployer"
+description: "Documentation for the CloudflareDeployer class, which deploys Mastra applications to Cloudflare Workers."
+---
+
+# CloudflareDeployer
+
+The CloudflareDeployer deploys Mastra applications to Cloudflare Workers, handling configuration, environment variables, and route management. It extends the abstract Deployer class to provide Cloudflare-specific deployment functionality.
+
+## Usage Example
+
+```typescript
+import { Mastra } from '@mastra/core';
+import { CloudflareDeployer } from '@mastra/deployer-cloudflare';
+
+const mastra = new Mastra({
+  deployer: new CloudflareDeployer({
+    scope: 'your-account-id',
+    projectName: 'your-project-name',
+    routes: [
+      {
+        pattern: 'example.com/*',
+        zone_name: 'example.com',
+        custom_domain: true,
+      },
+    ],
+    workerNamespace: 'your-namespace',
+    auth: {
+      apiToken: 'your-api-token',
+      apiEmail: 'your-email',
+    },
+  }),
+  // ... other Mastra configuration options
+});
+```
+
+## Parameters
+
+### Constructor Parameters
+
+<PropertiesTable
+  content={[
+    {
+      name: "scope",
+      type: "string",
+      description: "Your Cloudflare account ID.",
+      isOptional: false,
+    },
+    {
+      name: "projectName",
+      type: "string",
+      description: "Name of your worker project.",
+      isOptional: true,
+      defaultValue: "'mastra'",
+    },
+    {
+      name: "routes",
+      type: "CFRoute[]",
+      description: "Array of route configurations for your worker.",
+      isOptional: true,
+    },
+    {
+      name: "workerNamespace",
+      type: "string",
+      description: "Namespace for your worker.",
+      isOptional: true,
+    },
+    {
+      name: "env",
+      type: "Record<string, any>",
+      description: "Environment variables to be included in the worker configuration.",
+      isOptional: true,
+    },
+    {
+      name: "auth",
+      type: "object",
+      description: "Cloudflare authentication details.",
+      isOptional: false,
+    },
+  ]}
+/>
+
+### auth Object
+
+<PropertiesTable
+  content={[
+    {
+      name: "apiToken",
+      type: "string",
+      description: "Your Cloudflare API token.",
+      isOptional: false,
+    },
+    {
+      name: "apiEmail",
+      type: "string",
+      description: "Your Cloudflare account email.",
+      isOptional: true,
+    },
+  ]}
+/>
+
+### CFRoute Object
+
+<PropertiesTable
+  content={[
+    {
+      name: "pattern",
+      type: "string",
+      description: "URL pattern to match (e.g., 'example.com/*').",
+      isOptional: false,
+    },
+    {
+      name: "zone_name",
+      type: "string",
+      description: "Domain zone name.",
+      isOptional: false,
+    },
+    {
+      name: "custom_domain",
+      type: "boolean",
+      description: "Whether to use a custom domain.",
+      isOptional: true,
+      defaultValue: "false",
+    },
+  ]}
+/>
+
+### Wrangler Configuration
+
+The CloudflareDeployer automatically generates a `wrangler.json` configuration file with the following settings:
+
+```json
+{
+  "name": "your-project-name",
+  "main": "./output/index.mjs",
+  "compatibility_date": "2024-12-02",
+  "compatibility_flags": ["nodejs_compat"],
+  "observability": {
+    "logs": {
+      "enabled": true
+    }
+  },
+  "vars": {
+    // Environment variables from .env files and configuration
+  },
+  "routes": [
+    // Route configurations if specified
+  ]
+}
+```
+
+### Route Configuration
+
+Routes can be configured to direct traffic to your worker based on URL patterns and domains:
+
+```typescript
+const routes = [
+  {
+    pattern: 'api.example.com/*',
+    zone_name: 'example.com',
+    custom_domain: true,
+  },
+  {
+    pattern: 'example.com/api/*',
+    zone_name: 'example.com',
+  },
+];
+```
+
+### Environment Variables
+
+The CloudflareDeployer handles environment variables from multiple sources:
+
+1. **Environment Files**: Variables from `.env.production` and `.env` files.
+2. **Configuration**: Variables passed through the `env` parameter.
+

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

@@ -0,0 +1,159 @@
+---
+title: "Mastra Deployer"
+description: Documentation for the Deployer abstract class, which handles packaging and deployment of Mastra applications.
+---
+
+# Deployer
+
+The Deployer handles the deployment of Mastra applications by packaging code, managing environment files, and serving applications using the Hono framework. Concrete implementations must define the deploy method for specific deployment targets.
+
+## Usage Example
+
+```typescript
+import { Deployer } from "@mastra/deployer";
+
+// Create a custom deployer by extending the abstract Deployer class
+class CustomDeployer extends Deployer {
+  constructor() {
+    super({ name: 'custom-deployer' });
+  }
+
+  // Implement the abstract deploy method
+  async deploy(outputDirectory: string): Promise<void> {
+    // Prepare the output directory
+    await this.prepare(outputDirectory);
+    
+    // Bundle the application
+    await this._bundle('server.ts', 'mastra.ts', outputDirectory);
+    
+    // Custom deployment logic
+    // ...
+  }
+}
+```
+
+## Parameters
+
+### Constructor Parameters
+
+<PropertiesTable
+  content={[
+    {
+      name: "args",
+      type: "object",
+      description: "Configuration options for the Deployer.",
+      isOptional: false,
+    },
+    {
+      name: "args.name",
+      type: "string",
+      description: "A unique name for the deployer instance.",
+      isOptional: false,
+    },
+  ]}
+/>
+
+### deploy Parameters
+
+<PropertiesTable
+  content={[
+    {
+      name: "outputDirectory",
+      type: "string",
+      description: "The directory where the bundled and deployment-ready application will be output.",
+      isOptional: false,
+    },
+  ]}
+/>
+
+## Methods
+
+<PropertiesTable
+  content={[
+    {
+      name: "getEnvFiles",
+      type: "() => Promise<string[]>",
+      description: "Returns a list of environment files to be used during deployment. By default, it looks for '.env.production' and '.env' files.",
+    },
+    {
+      name: "deploy",
+      type: "(outputDirectory: string) => Promise<void>",
+      description: "Abstract method that must be implemented by subclasses. Handles the deployment process to the specified output directory.",
+    },
+  ]}
+/>
+
+## Inherited Methods from Bundler
+
+The Deployer class inherits the following key methods from the Bundler class:
+
+<PropertiesTable
+  content={[
+    {
+      name: "prepare",
+      type: "(outputDirectory: string) => Promise<void>",
+      description: "Prepares the output directory by cleaning it and creating necessary subdirectories.",
+    },
+    {
+      name: "writeInstrumentationFile",
+      type: "(outputDirectory: string) => Promise<void>",
+      description: "Writes an instrumentation file to the output directory for telemetry purposes.",
+    },
+    {
+      name: "writePackageJson",
+      type: "(outputDirectory: string, dependencies: Map<string, string>) => Promise<void>",
+      description: "Generates a package.json file in the output directory with the specified dependencies.",
+    },
+    {
+      name: "_bundle",
+      type: "(serverFile: string, mastraEntryFile: string, outputDirectory: string, bundleLocation?: string) => Promise<void>",
+      description: "Bundles the application using the specified server and Mastra entry files.",
+    },
+  ]}
+/>
+
+## Core Concepts
+
+### Deployment Lifecycle
+
+The Deployer abstract class implements a structured deployment lifecycle:
+
+1. **Initialization**: The deployer is initialized with a name and creates a Deps instance for dependency management.
+2. **Environment Setup**: The `getEnvFiles` method identifies environment files (.env.production, .env) to be used during deployment.
+3. **Preparation**: The `prepare` method (inherited from Bundler) cleans the output directory and creates necessary subdirectories.
+4. **Bundling**: The `_bundle` method (inherited from Bundler) packages the application code and its dependencies.
+5. **Deployment**: The abstract `deploy` method is implemented by subclasses to handle the actual deployment process.
+
+### Environment File Management
+
+The Deployer class includes built-in support for environment file management through the `getEnvFiles` method. This method:
+
+- Looks for environment files in a predefined order (.env.production, .env)
+- Uses the FileService to find the first existing file
+- Returns an array of found environment files
+- Returns an empty array if no environment files are found
+
+```typescript
+getEnvFiles(): Promise<string[]> {
+  const possibleFiles = ['.env.production', '.env.local', '.env'];
+
+  try {
+    const fileService = new FileService();
+    const envFile = fileService.getFirstExistingFile(possibleFiles);
+
+    return Promise.resolve([envFile]);
+  } catch {}
+
+  return Promise.resolve([]);
+}
+```
+
+### Bundling and Deployment Relationship
+
+The Deployer class extends the Bundler class, establishing a clear relationship between bundling and deployment:
+
+1. **Bundling as a Prerequisite**: Bundling is a prerequisite step for deployment, where the application code is packaged into a deployable format.
+2. **Shared Infrastructure**: Both bundling and deployment share common infrastructure like dependency management and file system operations.
+3. **Specialized Deployment Logic**: While bundling focuses on code packaging, deployment adds environment-specific logic for deploying the bundled code.
+4. **Extensibility**: The abstract `deploy` method allows for creating specialized deployers for different target environments.
+

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

@@ -0,0 +1,88 @@
+---
+title: "Netlify Deployer"
+description: "Documentation for the NetlifyDeployer class, which deploys Mastra applications to Netlify Functions."
+---
+
+# NetlifyDeployer
+
+The NetlifyDeployer deploys Mastra applications to Netlify Functions, handling site creation, configuration, and deployment processes. It extends the abstract Deployer class to provide Netlify-specific deployment functionality.
+
+## Usage Example
+
+```typescript
+import { Mastra } from '@mastra/core';
+import { NetlifyDeployer } from '@mastra/deployer-netlify';
+
+const mastra = new Mastra({
+  deployer: new NetlifyDeployer({
+    scope: 'your-team-slug',
+    projectName: 'your-project-name',
+    token: 'your-netlify-token'
+  }),
+  // ... other Mastra configuration options
+});
+```
+
+## Parameters
+
+### Constructor Parameters
+
+<PropertiesTable
+  content={[
+    {
+      name: "scope",
+      type: "string",
+      description: "Your Netlify team slug or ID.",
+      isOptional: false,
+    },
+    {
+      name: "projectName",
+      type: "string",
+      description: "Name of your Netlify site (will be created if it doesn't exist).",
+      isOptional: false,
+    },
+    {
+      name: "token",
+      type: "string",
+      description: "Your Netlify authentication token.",
+      isOptional: false,
+    },
+  ]}
+/>
+
+### Netlify Configuration
+
+The NetlifyDeployer automatically generates a `netlify.toml` configuration file with the following settings:
+
+```toml
+[functions]
+node_bundler = "esbuild"            
+directory = "netlify/functions"
+
+[[redirects]]
+force = true
+from = "/*"
+status = 200
+to = "/.netlify/functions/api/:splat"
+```
+
+### Environment Variables
+
+The NetlifyDeployer handles environment variables from multiple sources:
+
+1. **Environment Files**: Variables from `.env.production` and `.env` files.
+2. **Configuration**: Variables passed through the Mastra configuration.
+3. **Netlify Dashboard**: Variables can also be managed through Netlify's web interface.
+
+### Project Structure
+
+The deployer creates the following structure in your output directory:
+
+```
+output-directory/
+├── netlify/
+│   └── functions/
+│       └── api/
+│           └── index.mjs    # Application entry point with Hono server integration
+└── netlify.toml             # Deployment configuration
+```