@mastra/mcp-docs-server 1.2.15 → 1.2.16-alpha.3

package/.docs/guides/deployment/mastra-workers.md

@@ -1,578 +0,0 @@
-> Discover all available pages from the documentation index: https://mastra.ai/llms.txt
-
-# Deploy Mastra workers
-
-Run [Mastra workers](https://mastra.ai/docs/deployment/workers) as separate processes so you can scale orchestration, scheduling, and background tasks independently from the API. This guide walks through a fully split deployment using Docker Compose or Kubernetes.
-
-> **Beta:** Breaking changes may occur without a major version bump until the API is stable.
-
-> **Note:** This guide covers splitting workers into their own containers. If you only need workers to run in-process alongside the API, see [Workers](https://mastra.ai/docs/deployment/workers). No extra setup is required.
-
-## Before you begin
-
-You'll need:
-
-- A [Mastra application](https://mastra.ai/guides/getting-started/quickstart)
-- [Docker](https://docs.docker.com/get-docker/) and [Docker Compose](https://docs.docker.com/compose/), or a [Kubernetes](https://kubernetes.io/docs/setup/) cluster with [`kubectl`](https://kubernetes.io/docs/tasks/tools/)
-- A distributed PubSub backend: [Redis](https://redis.io/) for [`RedisStreamsPubSub`](https://mastra.ai/reference/pubsub/redis-streams), or a [Google Cloud](https://cloud.google.com/) project for [`GoogleCloudPubSub`](https://mastra.ai/reference/pubsub/google-cloud-pubsub)
-- A shared database reachable from every container. See [supported storage backends](https://mastra.ai/reference/workers/overview) for the full list.
-
-> **Warning:** The default in-memory PubSub can't deliver events across processes. You must configure a distributed PubSub backend before splitting workers into separate containers.
-
-## Configure shared infrastructure
-
-Point the `Mastra` instance at a distributed PubSub backend and a shared database. Use environment variables so the same image runs in every container.
-
-**Redis Streams + PostgreSQL**:
-
-```typescript
-import { Mastra } from '@mastra/core/mastra'
-import { RedisStreamsPubSub } from '@mastra/redis-streams'
-import { PostgresStore } from '@mastra/pg'
-
-export const mastra = new Mastra({
-  storage: new PostgresStore({
-    connectionString: process.env.DATABASE_URL!,
-  }),
-  pubsub: new RedisStreamsPubSub({
-    url: process.env.REDIS_URL!,
-  }),
-})
-```
-
-**Google Cloud Pub/Sub + LibSQL**:
-
-```typescript
-import { Mastra } from '@mastra/core/mastra'
-import { GoogleCloudPubSub } from '@mastra/google-cloud-pubsub'
-import { LibSQLStore } from '@mastra/libsql'
-
-export const mastra = new Mastra({
-  storage: new LibSQLStore({
-    url: process.env.DATABASE_URL!,
-  }),
-  pubsub: new GoogleCloudPubSub({
-    projectId: process.env.GCP_PROJECT_ID!,
-  }),
-})
-```
-
-Any [supported storage backend](https://mastra.ai/reference/workers/overview) works. Swap the storage adapter for your preferred database.
-
-## Deploy
-
-1. Build your Mastra application. The output runs in every container.
-
-   ```bash
-   mastra build
-   ```
-
-   This produces a self-contained `.mastra/output/` directory. See [Deploy a Mastra server](https://mastra.ai/docs/deployment/mastra-server) for details on the build output.
-
-2. Create a Dockerfile that copies the pre-built output and installs production dependencies:
-
-   ```dockerfile
-   FROM node:22-alpine
-
-   WORKDIR /app
-
-   COPY .mastra/output/package.json .mastra/output/.npmrc* ./
-   RUN npm install --omit=dev
-
-   COPY .mastra/output/ .
-
-   EXPOSE 4111
-   CMD ["node", "index.mjs"]
-   ```
-
-3. Define the fully split topology. The setup runs six services: a database, a PubSub backend, the API server, and three workers. Each worker runs the same image with a different `MASTRA_WORKERS` value to control which worker starts.
-
-   The API sets `MASTRA_WORKERS: "false"` to disable all event processing. The orchestration worker sets `MASTRA_STEP_EXECUTION_URL` to point step execution requests at the API's internal URL. See [step execution URL](#step-execution-url) for details.
-
-   All services share a `MASTRA_WORKER_AUTH_TOKEN`. Workers include this token in requests to the API so the API can verify the caller is a trusted internal service. See [worker authentication](https://mastra.ai/docs/server/auth/workers) for details.
-
-   **Docker Compose**:
-
-   ```yaml
-   services:
-     postgres:
-       image: postgres:16-alpine
-       environment:
-         POSTGRES_USER: mastra
-         POSTGRES_PASSWORD: ${POSTGRES_PASSWORD}
-         POSTGRES_DB: mastra
-       ports:
-         - '5432:5432'
-       volumes:
-         - pgdata:/var/lib/postgresql/data
-       healthcheck:
-         test: ['CMD-SHELL', 'pg_isready -U mastra']
-         interval: 5s
-         timeout: 3s
-         retries: 5
-
-     redis:
-       image: redis:7-alpine
-       ports:
-         - '6379:6379'
-       healthcheck:
-         test: ['CMD', 'redis-cli', 'ping']
-         interval: 5s
-         timeout: 3s
-         retries: 5
-
-     api:
-       build: ./app
-       ports:
-         - '4111:4111'
-       environment:
-         DATABASE_URL: postgres://mastra:${POSTGRES_PASSWORD}@postgres:5432/mastra
-         REDIS_URL: redis://redis:6379
-         MASTRA_WORKERS: 'false'
-         MASTRA_WORKER_AUTH_TOKEN: ${MASTRA_WORKER_AUTH_TOKEN}
-       depends_on:
-         postgres:
-           condition: service_healthy
-         redis:
-           condition: service_healthy
-       healthcheck:
-         test: ['CMD', 'wget', '-qO-', 'http://localhost:4111/api/agents']
-         interval: 5s
-         timeout: 3s
-         retries: 5
-
-     orchestration-worker:
-       build: ./app
-       environment:
-         DATABASE_URL: postgres://mastra:${POSTGRES_PASSWORD}@postgres:5432/mastra
-         REDIS_URL: redis://redis:6379
-         MASTRA_WORKERS: orchestration
-         MASTRA_STEP_EXECUTION_URL: http://api:4111/api
-         MASTRA_WORKER_AUTH_TOKEN: ${MASTRA_WORKER_AUTH_TOKEN}
-       depends_on:
-         api:
-           condition: service_healthy
-
-     scheduler-worker:
-       build: ./app
-       environment:
-         DATABASE_URL: postgres://mastra:${POSTGRES_PASSWORD}@postgres:5432/mastra
-         REDIS_URL: redis://redis:6379
-         MASTRA_WORKERS: scheduler
-         MASTRA_WORKER_AUTH_TOKEN: ${MASTRA_WORKER_AUTH_TOKEN}
-       depends_on:
-         api:
-           condition: service_healthy
-
-     background-task-worker:
-       build: ./app
-       environment:
-         DATABASE_URL: postgres://mastra:${POSTGRES_PASSWORD}@postgres:5432/mastra
-         REDIS_URL: redis://redis:6379
-         MASTRA_WORKERS: backgroundTasks
-         MASTRA_WORKER_AUTH_TOKEN: ${MASTRA_WORKER_AUTH_TOKEN}
-       depends_on:
-         api:
-           condition: service_healthy
-
-   volumes:
-     pgdata:
-   ```
-
-   Create a `.env` file next to your `docker-compose.yml`:
-
-   ```bash
-   POSTGRES_PASSWORD=your-secure-password
-   MASTRA_WORKER_AUTH_TOKEN=your-shared-secret-token
-   ```
-
-   > **Note:** Remember to set any other environment variables your application needs (e.g., your [model provider](https://mastra.ai/models/providers) API key).
-
-   **Kubernetes**:
-
-   Create a namespace and a Secret with your connection strings:
-
-   ```yaml
-   apiVersion: v1
-   kind: Namespace
-   metadata:
-     name: mastra-workers
-   ```
-
-   ```bash
-   kubectl apply -f k8s/namespace.yaml
-   kubectl create secret generic mastra-secrets -n mastra-workers \
-     --from-literal=POSTGRES_PASSWORD='your-password' \
-     --from-literal=DATABASE_URL='postgresql://mastra:your-password@postgres:5432/mastra' \
-     --from-literal=REDIS_URL='redis://redis:6379' \
-     --from-literal=MASTRA_WORKER_AUTH_TOKEN='your-shared-token'
-   ```
-
-   > **Note:** Add any other environment variables your application needs (e.g., your [model provider](https://mastra.ai/models/providers) API key) to the Secret or as additional `--from-literal` entries.
-
-   Build and push the Docker image to a registry your cluster can pull from:
-
-   ```bash
-   docker build -t your-registry/mastra-workers:latest ./app
-   docker push your-registry/mastra-workers:latest
-   ```
-
-   Apply Deployments and Services for the database, PubSub backend, API, and three workers. The example below uses in-cluster Postgres and Redis. In production, use managed services (e.g., Amazon RDS, Cloud SQL, ElastiCache, Memorystore).
-
-   ```yaml
-   apiVersion: apps/v1
-   kind: Deployment
-   metadata:
-     name: postgres
-     namespace: mastra-workers
-   spec:
-     replicas: 1
-     selector:
-       matchLabels:
-         app: postgres
-     template:
-       metadata:
-         labels:
-           app: postgres
-       spec:
-         containers:
-           - name: postgres
-             image: postgres:16-alpine
-             ports:
-               - containerPort: 5432
-             env:
-               - name: POSTGRES_USER
-                 value: mastra
-               - name: POSTGRES_PASSWORD
-                 valueFrom:
-                   secretKeyRef:
-                     name: mastra-secrets
-                     key: POSTGRES_PASSWORD
-               - name: POSTGRES_DB
-                 value: mastra
-             volumeMounts:
-               - name: pgdata
-                 mountPath: /var/lib/postgresql/data
-         volumes:
-           - name: pgdata
-             emptyDir: {}
-   ---
-   apiVersion: v1
-   kind: Service
-   metadata:
-     name: postgres
-     namespace: mastra-workers
-   spec:
-     selector:
-       app: postgres
-     ports:
-       - port: 5432
-         targetPort: 5432
-   ```
-
-   > **Caution:** The Postgres example above uses `emptyDir` for storage, which means data is lost when the pod restarts. In production, replace it with a `PersistentVolumeClaim` or use a managed database service.
-
-   ```yaml
-   apiVersion: apps/v1
-   kind: Deployment
-   metadata:
-     name: redis
-     namespace: mastra-workers
-   spec:
-     replicas: 1
-     selector:
-       matchLabels:
-         app: redis
-     template:
-       metadata:
-         labels:
-           app: redis
-       spec:
-         containers:
-           - name: redis
-             image: redis:7-alpine
-             args: ['--appendonly', 'yes']
-             ports:
-               - containerPort: 6379
-   ---
-   apiVersion: v1
-   kind: Service
-   metadata:
-     name: redis
-     namespace: mastra-workers
-   spec:
-     selector:
-       app: redis
-     ports:
-       - port: 6379
-         targetPort: 6379
-   ```
-
-   ```yaml
-   apiVersion: apps/v1
-   kind: Deployment
-   metadata:
-     name: api
-     namespace: mastra-workers
-   spec:
-     replicas: 1
-     selector:
-       matchLabels:
-         app: api
-     template:
-       metadata:
-         labels:
-           app: api
-       spec:
-         containers:
-           - name: api
-             image: your-registry/mastra-workers:latest
-             ports:
-               - containerPort: 4111
-             env:
-               - name: MASTRA_WORKERS
-                 value: 'false'
-             envFrom:
-               - secretRef:
-                   name: mastra-secrets
-             readinessProbe:
-               httpGet:
-                 path: /api/agents
-                 port: 4111
-               initialDelaySeconds: 10
-               periodSeconds: 5
-             livenessProbe:
-               httpGet:
-                 path: /api/agents
-                 port: 4111
-               initialDelaySeconds: 15
-               periodSeconds: 10
-             resources:
-               requests:
-                 cpu: 500m
-                 memory: 512Mi
-   ---
-   apiVersion: v1
-   kind: Service
-   metadata:
-     name: api
-     namespace: mastra-workers
-   spec:
-     selector:
-       app: api
-     ports:
-       - port: 4111
-         targetPort: 4111
-   ```
-
-   ```yaml
-   apiVersion: apps/v1
-   kind: Deployment
-   metadata:
-     name: orchestration-worker
-     namespace: mastra-workers
-   spec:
-     replicas: 1
-     selector:
-       matchLabels:
-         app: orchestration-worker
-     template:
-       metadata:
-         labels:
-           app: orchestration-worker
-       spec:
-         containers:
-           - name: worker
-             image: your-registry/mastra-workers:latest
-             env:
-               - name: MASTRA_WORKERS
-                 value: orchestration
-               - name: MASTRA_STEP_EXECUTION_URL
-                 value: http://api:4111/api
-             envFrom:
-               - secretRef:
-                   name: mastra-secrets
-             resources:
-               requests:
-                 cpu: 250m
-                 memory: 256Mi
-   ```
-
-   ```yaml
-   apiVersion: apps/v1
-   kind: Deployment
-   metadata:
-     name: scheduler-worker
-     namespace: mastra-workers
-   spec:
-     replicas: 1
-     selector:
-       matchLabels:
-         app: scheduler-worker
-     template:
-       metadata:
-         labels:
-           app: scheduler-worker
-       spec:
-         containers:
-           - name: worker
-             image: your-registry/mastra-workers:latest
-             env:
-               - name: MASTRA_WORKERS
-                 value: scheduler
-             envFrom:
-               - secretRef:
-                   name: mastra-secrets
-             resources:
-               requests:
-                 cpu: 250m
-                 memory: 256Mi
-   ```
-
-   ```yaml
-   apiVersion: apps/v1
-   kind: Deployment
-   metadata:
-     name: background-task-worker
-     namespace: mastra-workers
-   spec:
-     replicas: 1
-     selector:
-       matchLabels:
-         app: background-task-worker
-     template:
-       metadata:
-         labels:
-           app: background-task-worker
-       spec:
-         containers:
-           - name: worker
-             image: your-registry/mastra-workers:latest
-             env:
-               - name: MASTRA_WORKERS
-                 value: backgroundTasks
-             envFrom:
-               - secretRef:
-                   name: mastra-secrets
-             resources:
-               requests:
-                 cpu: 250m
-                 memory: 256Mi
-   ```
-
-   Apply all manifests and wait for the API to become ready:
-
-   ```bash
-   kubectl apply -f k8s/
-   kubectl wait -n mastra-workers --for=condition=ready pod -l app=api --timeout=90s
-   kubectl wait -n mastra-workers --for=condition=ready pod -l app=orchestration-worker --timeout=60s
-   kubectl wait -n mastra-workers --for=condition=ready pod -l app=scheduler-worker --timeout=60s
-   kubectl wait -n mastra-workers --for=condition=ready pod -l app=background-task-worker --timeout=60s
-   ```
-
-4. Verify the stack is running and the API responds:
-
-   **Docker Compose**:
-
-   ```bash
-   docker compose up -d
-   docker compose ps
-   curl http://localhost:4111/api/agents
-   ```
-
-   **Kubernetes**:
-
-   ```bash
-   kubectl get pods -n mastra-workers
-   kubectl port-forward -n mastra-workers svc/api 4111:4111
-   ```
-
-   In a separate terminal:
-
-   ```bash
-   curl http://localhost:4111/api/agents
-   ```
-
-   A JSON list of your agents confirms the API and workers are running.
-
-## Step execution URL
-
-In a fully split deployment, the orchestration worker runs in a separate container from the API. When it processes a workflow event, it delegates step execution to the API over HTTP.
-
-Set `MASTRA_STEP_EXECUTION_URL` to the API's internal URL, including the `/api` prefix:
-
-```bash
-MASTRA_STEP_EXECUTION_URL=http://api:4111/api
-```
-
-The orchestration worker sends a `POST` request to `${MASTRA_STEP_EXECUTION_URL}/workflows/:workflowId/runs/:runId/steps/execute` for each step. The API resolves the workflow and executes the step locally.
-
-Without this variable, the orchestration worker attempts to execute steps in-process. That works when the worker runs alongside the API, but fails in split deployments where the worker doesn't have access to the full Mastra runtime.
-
-## Scaling
-
-The orchestration and background task workers are safe to scale horizontally. PubSub consumer groups distribute events across instances, so each event is processed once:
-
-**Docker Compose**:
-
-```bash
-docker compose up -d --scale orchestration-worker=3
-docker compose up -d --scale background-task-worker=2
-```
-
-**Kubernetes**:
-
-```bash
-kubectl scale deployment/orchestration-worker -n mastra-workers --replicas=3
-kubectl scale deployment/background-task-worker -n mastra-workers --replicas=2
-```
-
-For automatic scaling, add a HorizontalPodAutoscaler:
-
-```yaml
-apiVersion: autoscaling/v2
-kind: HorizontalPodAutoscaler
-metadata:
-  name: orchestration-worker
-  namespace: mastra-workers
-spec:
-  scaleTargetRef:
-    apiVersion: apps/v1
-    kind: Deployment
-    name: orchestration-worker
-  minReplicas: 1
-  maxReplicas: 10
-  metrics:
-    - type: Resource
-      resource:
-        name: cpu
-        target:
-          type: Utilization
-          averageUtilization: 70
-```
-
-> **Note:** CPU-based autoscaling needs the [metrics-server](https://github.com/kubernetes-sigs/metrics-server) running in the cluster. Managed clusters like GKE, EKS, and AKS include it by default.
-
-The API can also scale horizontally behind a load balancer.
-
-**Don't scale the scheduler worker.** Run exactly one instance. Multiple schedulers polling the same storage fire duplicate events for the same schedule.
-
-## Crash recovery
-
-Workers recover from crashes because the distributed PubSub backend persists unacknowledged events:
-
-- **Orchestration worker**: Pending events stay in the PubSub backend. When the worker restarts, it picks up where it left off.
-- **Scheduler worker**: No events are missed permanently. The scheduler computes the next fire time from the current time on restart, not from where it left off.
-- **API during step execution**: The orchestration worker's HTTP request fails. The event is nacked and redelivered on the next attempt.
-
-> **Warning:** If the API crashes while a step is already executing (e.g., mid-sleep), that step's work is lost. The workflow run may remain stuck in a `running` state. Mastra doesn't yet have automatic timeout-based recovery for this scenario.
-
-## Related
-
-- [Workers](https://mastra.ai/docs/deployment/workers): What workers are and when to use them
-- [Worker authentication](https://mastra.ai/docs/server/auth/workers): Secure worker-to-API communication
-- [Workers reference](https://mastra.ai/reference/workers/overview): Configuration details for all worker types
-- [CLI reference](https://mastra.ai/reference/cli/mastra): `mastra worker build` and `mastra worker start`
-- [PubSub](https://mastra.ai/docs/server/pubsub): Event delivery backends
-- [Deploy a Mastra server](https://mastra.ai/docs/deployment/mastra-server): Build output and server configuration
-- [Deploy Mastra to Kubernetes](https://mastra.ai/integrations/deploy/kubernetes): Multi-pod deployment with durable agents

package/.docs/guides/getting-started/quickstart.md

@@ -1,88 +0,0 @@
-> Discover all available pages from the documentation index: https://mastra.ai/llms.txt
-
-# Mastra Quickstart
-
-**For AI agents:** Create a new Mastra project non-interactively with `npm create mastra@latest <project-name> -- --llm <provider>`, replacing `<provider>` with `openai`, `anthropic`, `google`, or `xai`. For a minimal project without an agent or model provider, use `npm create mastra@latest <project-name> -- --empty`. To build a Mastra project from scratch, see the [manual installation guide](https://mastra.ai/reference/manual-install).
-
-The `create-mastra` CLI is the quickest way to start a Mastra project. It creates an agent harness with workspace tools, memory, task tracking, web access, schedules, storage, and observability.
-
-For more control, see the [manual installation guide](https://mastra.ai/reference/manual-install). To add Mastra to an existing project, use [`mastra init`](https://mastra.ai/reference/cli/mastra).
-
-> **📹 Watch:** Watch the [Mastra AI agent course](https://www.youtube.com/watch?v=lCmf_qrGfGA) for a guided introduction to building agents with Mastra.
-
-## Before you begin
-
-You'll need an API key from OpenAI, Anthropic, Google Gemini, or xAI. You can skip entering it during setup and add it to `.env` later.
-
-## Create the project
-
-Run the interactive setup:
-
-**npm**:
-
-```bash
-npm create mastra@latest
-```
-
-**pnpm**:
-
-```bash
-pnpm create mastra@latest
-```
-
-**Yarn**:
-
-```bash
-yarn create mastra
-```
-
-**Bun**:
-
-```bash
-bunx create-mastra
-```
-
-The command asks for a project name, model provider, and optional API key. It then installs dependencies, installs Mastra skills for your coding assistants, and creates an initial Git commit when you aren't already inside a repository.
-
-The generated `src/mastra` directory contains the Mastra entry point, agent, workspace tools, and supporting code. See the [project structure reference](https://mastra.ai/reference/project-structure) for the standard Mastra layout.
-
-> **Tip:** Use `--template <template>` to start from a template, or `--empty` to create a minimal provider-free project. Use `--no-skills` or `--no-git` to skip automatic setup. See the [`create-mastra` reference](https://mastra.ai/reference/cli/create-mastra) for all flags.
-
-## Test your agent
-
-Follow the terminal instructions to enter the project directory and start the development server:
-
-**npm**:
-
-```bash
-npm run dev
-```
-
-**pnpm**:
-
-```bash
-pnpm run dev
-```
-
-**Yarn**:
-
-```bash
-yarn dev
-```
-
-**Bun**:
-
-```bash
-bun run dev
-```
-
-Open [Studio at localhost:4111](http://localhost:4111), select the agent, and send a message. Add the provider API key named in `.env.example` to an `.env` file if you skipped it during setup.
-
-[Studio](https://mastra.ai/docs/studio/overview) lets you build and test agents without creating a separate UI.
-
-## Next steps
-
-- Integrate Mastra with [Next.js](https://mastra.ai/integrations/frameworks/next-js), [React](https://mastra.ai/integrations/frameworks/vite-react), or [Astro](https://mastra.ai/integrations/frameworks/astro)
-- Learn how to [build Mastra with AI](https://mastra.ai/reference/build-with-ai)
-- Build an agent from scratch with a [guide](https://mastra.ai/guides)
-- Watch the [Mastra YouTube channel](https://www.youtube.com/@mastra-ai)