@mastra/mcp-docs-server 1.0.0-beta.6 → 1.0.0-beta.8

package/.docs/raw/reference/server/routes.mdx

@@ -0,0 +1,250 @@
+---
+title: "Reference: Server Routes | Server"
+description: "API reference for HTTP routes registered by Mastra server adapters."
+---
+
+# Server Routes
+
+Server adapters register these routes when you call `server.init()`. All routes are prefixed with the `prefix` option if configured.
+
+## Agents
+
+| Method | Path | Description |
+|--------|------|-------------|
+| `GET` | `/api/agents` | List all agents |
+| `GET` | `/api/agents/:agentId` | Get agent by ID |
+| `POST` | `/api/agents/:agentId/generate` | Generate agent response |
+| `POST` | `/api/agents/:agentId/stream` | Stream agent response |
+| `GET` | `/api/agents/:agentId/tools` | List agent tools |
+| `POST` | `/api/agents/:agentId/tools/:toolId/execute` | Execute agent tool |
+
+### Generate request body
+
+```typescript
+{
+  messages: CoreMessage[] | string;       // Required
+  instructions?: string;                   // System instructions
+  system?: string;                         // System prompt
+  context?: CoreMessage[];                 // Additional context
+  memory?: { key: string } | boolean;      // Memory config
+  resourceId?: string;                     // Resource identifier
+  threadId?: string;                       // Thread identifier
+  runId?: string;                          // Run identifier
+  maxSteps?: number;                       // Max tool steps
+  activeTools?: string[];                  // Tools to enable
+  toolChoice?: ToolChoice;                 // Tool selection mode
+  requestContext?: Record<string, unknown>; // Request context
+  output?: ZodSchema;                      // Structured output schema
+}
+```
+
+### Generate response
+
+```typescript
+{
+  text: string;
+  toolCalls?: ToolCall[];
+  finishReason: string;
+  usage?: {
+    promptTokens: number;
+    completionTokens: number;
+  };
+}
+```
+
+## Workflows
+
+| Method | Path | Description |
+|--------|------|-------------|
+| `GET` | `/api/workflows` | List all workflows |
+| `GET` | `/api/workflows/:workflowId` | Get workflow by ID |
+| `POST` | `/api/workflows/:workflowId/stream` | Stream workflow execution |
+| `POST` | `/api/workflows/:workflowId/resume` | Resume suspended workflow |
+| `POST` | `/api/workflows/:workflowId/resume-async` | Resume asynchronously |
+| `GET` | `/api/workflows/:workflowId/runs` | List workflow runs |
+| `GET` | `/api/workflows/:workflowId/runs/:runId` | Get specific run |
+
+### Stream workflow request body
+
+```typescript
+{
+  inputData?: unknown;
+  initialState?: unknown;
+  requestContext?: Record<string, unknown>;
+  closeOnSuspend?: boolean;
+}
+```
+
+### Resume request body
+
+```typescript
+{
+  step?: string | string[];
+  resumeData?: unknown;
+  requestContext?: Record<string, unknown>;
+}
+```
+
+## Tools
+
+| Method | Path | Description |
+|--------|------|-------------|
+| `GET` | `/api/tools` | List all tools |
+| `GET` | `/api/tools/:toolId` | Get tool by ID |
+| `POST` | `/api/tools/:toolId/execute` | Execute tool |
+
+### Execute tool request body
+
+```typescript
+{
+  data: unknown;  // Tool input data
+  requestContext?: Record<string, unknown>;
+}
+```
+
+## Memory
+
+| Method | Path | Description |
+|--------|------|-------------|
+| `GET` | `/api/memory/threads` | List threads |
+| `GET` | `/api/memory/threads/:threadId` | Get thread |
+| `POST` | `/api/memory/threads` | Create thread |
+| `DELETE` | `/api/memory/threads/:threadId` | Delete thread |
+| `GET` | `/api/memory/threads/:threadId/messages` | Get thread messages |
+| `POST` | `/api/memory/threads/:threadId/messages` | Add message |
+
+### Create thread request body
+
+```typescript
+{
+  resourceId: string;
+  title?: string;
+  metadata?: Record<string, unknown>;
+}
+```
+
+## Vectors
+
+| Method | Path | Description |
+|--------|------|-------------|
+| `POST` | `/api/vectors/:vectorName/upsert` | Upsert vectors |
+| `POST` | `/api/vectors/:vectorName/query` | Query vectors |
+| `POST` | `/api/vectors/:vectorName/delete` | Delete vectors |
+
+### Upsert request body
+
+```typescript
+{
+  vectors: Array<{
+    id: string;
+    values: number[];
+    metadata?: Record<string, unknown>;
+  }>;
+}
+```
+
+### Query request body
+
+```typescript
+{
+  vector: number[];
+  topK?: number;
+  filter?: Record<string, unknown>;
+  includeMetadata?: boolean;
+}
+```
+
+## MCP
+
+| Method | Path | Description |
+|--------|------|-------------|
+| `GET` | `/api/mcp/servers` | List MCP servers |
+| `GET` | `/api/mcp/servers/:serverId/tools` | List server tools |
+| `POST` | `/api/mcp/:serverId` | MCP HTTP transport |
+| `GET` | `/api/mcp/:serverId/sse` | MCP SSE transport |
+
+## Logs
+
+| Method | Path | Description |
+|--------|------|-------------|
+| `GET` | `/api/logs` | List logs |
+| `GET` | `/api/logs/:runId` | Get logs by run ID |
+
+### Query parameters
+
+```typescript
+{
+  page?: number;
+  perPage?: number;
+  transportId?: string;
+}
+```
+
+## Telemetry
+
+| Method | Path | Description |
+|--------|------|-------------|
+| `GET` | `/api/telemetry/traces` | List traces |
+| `GET` | `/api/telemetry/traces/:traceId` | Get trace |
+| `GET` | `/api/telemetry/traces/:traceId/spans` | Get trace spans |
+
+## Common query parameters
+
+### Pagination
+
+Most list endpoints support:
+
+```typescript
+{
+  page?: number;   // Page number (0-indexed)
+  perPage?: number; // Items per page (default: 10)
+}
+```
+
+Or offset-based:
+
+```typescript
+{
+  offset?: number; // Skip N items
+  limit?: number;  // Max items (default: 50)
+}
+```
+
+### Filtering
+
+Workflow runs support:
+
+```typescript
+{
+  fromDate?: string;  // ISO date string
+  toDate?: string;    // ISO date string
+  status?: string;    // Run status filter
+  resourceId?: string; // Filter by resource
+}
+```
+
+## Error responses
+
+All routes return errors in this format:
+
+```typescript
+{
+  error: string;      // Error message
+  details?: unknown;  // Additional details
+}
+```
+
+Common status codes:
+
+| Code | Meaning |
+|------|---------|
+| 400 | Bad Request - Invalid parameters |
+| 401 | Unauthorized - Missing/invalid auth |
+| 403 | Forbidden - Insufficient permissions |
+| 404 | Not Found - Resource doesn't exist |
+| 500 | Internal Server Error |
+
+## Related
+
+- [createRoute()](/reference/v1/server/create-route) - Creating custom routes
+- [Server Adapters](/docs/v1/server-db/server-adapters) - Using adapters

package/.docs/raw/reference/streaming/workflows/timeTravelStream.mdx

@@ -0,0 +1,170 @@
+---
+title: "Reference: Run.timeTravelStream() | Streaming"
+description: Documentation for the `Run.timeTravelStream()` method for streaming workflow time travel execution.
+---
+
+# Run.timeTravelStream()
+
+The `.timeTravelStream()` method re-executes a workflow starting from any specific step with streaming events. This allows you to receive real-time updates during time travel execution while maintaining full visibility into each step's progress.
+
+## Usage example
+
+```typescript showLineNumbers copy
+const run = await workflow.createRun();
+
+const output = run.timeTravelStream({
+  step: "step2",
+  inputData: { value: 10 },
+});
+
+// Process events as they arrive
+for await (const event of output.fullStream) {
+  console.log(event.type, event.payload);
+}
+
+// Get the final result
+const result = await output.result;
+```
+
+## Parameters
+
+All parameters are the same as [`Run.timeTravel()`](../../workflows/run-methods/timeTravel#parameters). See the [timeTravel reference](../../workflows/run-methods/timeTravel#parameters) for detailed parameter documentation.
+
+## Returns
+
+<PropertiesTable
+  content={[
+    {
+      name: "output",
+      type: "WorkflowRunOutput<WorkflowResult<TState, TInput, TOutput, TSteps>>",
+      description:
+        "An object containing both the stream and result promise",
+    },
+    {
+      name: "output.fullStream",
+      type: "ReadableStream<WorkflowStreamEvent>",
+      description:
+        "A readable stream that emits workflow events as execution progresses",
+    },
+    {
+      name: "output.result",
+      type: "Promise<WorkflowResult<TState, TInput, TOutput, TSteps>>",
+      description:
+        "A promise that resolves to the final workflow execution result",
+    },
+    {
+      name: "output.traceId",
+      type: "string",
+      isOptional: true,
+      description:
+        "The trace ID associated with this execution when Tracing is enabled",
+    },
+  ]}
+/>
+
+## Stream events
+
+The stream emits various workflow events during execution:
+
+- `workflow-step-start`: Emitted when a step begins execution
+- `workflow-step-finish`: Emitted when a step completes successfully
+- `workflow-step-error`: Emitted when a step encounters an error
+- `workflow-step-suspended`: Emitted when a step suspends
+- Additional events depending on step types (agents, tools, etc.)
+
+## Extended usage examples
+
+### Processing events during time travel
+
+```typescript showLineNumbers copy
+const run = await workflow.createRun();
+
+const output = run.timeTravelStream({
+  step: "step2",
+  inputData: { value: 10 },
+});
+
+for await (const event of output.fullStream) {
+  switch (event.type) {
+    case "workflow-step-start":
+      console.log(`Starting step: ${event.payload.stepName}`);
+      break;
+    case "workflow-step-finish":
+      console.log(`Completed step: ${event.payload.stepName}`);
+      break;
+    case "workflow-step-error":
+      console.error(`Error in step: ${event.payload.stepName}`, event.payload.error);
+      break;
+  }
+}
+
+const result = await output.result;
+console.log("Time travel completed:", result);
+```
+
+### Time travel stream with context
+
+```typescript showLineNumbers copy
+const output = run.timeTravelStream({
+  step: "step2",
+  context: {
+    step1: {
+      status: "success",
+      payload: { value: 0 },
+      output: { step1Result: 2 },
+      startedAt: Date.now(),
+      endedAt: Date.now(),
+    },
+  },
+});
+
+for await (const event of output.fullStream) {
+  // Handle events
+  console.log(event);
+}
+
+const result = await output.result;
+```
+
+### Time travel stream with nested workflows
+
+```typescript showLineNumbers copy
+const output = run.timeTravelStream({
+  step: ["nestedWorkflow", "step3"],
+  inputData: { value: 10 },
+  nestedStepsContext: {
+    nestedWorkflow: {
+      step2: {
+        status: "success",
+        payload: { step1Result: 2 },
+        output: { step2Result: 3 },
+        startedAt: Date.now(),
+        endedAt: Date.now(),
+      },
+    },
+  },
+});
+
+for await (const event of output.fullStream) {
+  console.log(event.type, event.payload);
+}
+
+const result = await output.result;
+```
+
+## Notes
+
+- The stream closes automatically when time travel execution completes or encounters an error
+- You can process events from the stream while the workflow is still executing
+- The `result` promise resolves only after all steps have completed
+- Stream events follow the same format as regular workflow streaming
+- Time travel streaming requires storage to be configured since it relies on persisted workflow snapshots
+
+## Related
+
+- [Run.timeTravel()](../../workflows/run-methods/timeTravel)
+- [Time Travel](/docs/v1/workflows/time-travel)
+- [Workflow Streaming](/docs/v1/streaming/workflow-streaming)
+- [Run.stream()](./stream)
+- [Run.resumeStream()](./resumeStream)
+

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

@@ -99,6 +99,13 @@ Each server in the `servers` map is configured using the `MastraMCPServerDefinit
       description:
         "For SSE fallback: Custom fetch configuration for SSE connections. Required when using custom headers with SSE.",
     },
+    {
+      name: "fetch",
+      type: "FetchLike",
+      isOptional: true,
+      description:
+        "For HTTP servers: Custom fetch implementation used for all network requests. When provided, this function will be used for all HTTP requests, allowing you to add dynamic authentication headers (e.g., refreshing bearer tokens), customize request behavior per-request, or intercept and modify requests/responses. When `fetch` is provided, `requestInit`, `eventSourceInit`, and `authProvider` become optional, as you can handle these concerns within your custom fetch function.",
+    },
     {
       name: "logger",
       type: "LogHandler",
@@ -854,11 +861,40 @@ MCPClient handles server connections gracefully:
 2. Graceful server shutdown to prevent error messages during development
 3. Proper cleanup of resources when disconnecting
 
+## Using Custom Fetch for Dynamic Authentication
+
+For HTTP servers, you can provide a custom `fetch` function to handle dynamic authentication, request interception, or other custom behavior. This is particularly useful when you need to refresh tokens on each request or customize request behavior.
+
+When `fetch` is provided, `requestInit`, `eventSourceInit`, and `authProvider` become optional, as you can handle these concerns within your custom fetch function.
+
+```typescript
+const mcpClient = new MCPClient({
+  servers: {
+    apiServer: {
+      url: new URL("https://api.example.com/mcp"),
+      fetch: async (url, init) => {
+        // Refresh token on each request
+        const token = await getAuthToken(); // Your token refresh logic
+        
+        return fetch(url, {
+          ...init,
+          headers: {
+            ...init?.headers,
+            Authorization: `Bearer ${token}`,
+          },
+        });
+      },
+    },
+  },
+});
+```
+
 ## Using SSE Request Headers
 
-When using the legacy SSE MCP transport, you must configure both `requestInit` and `eventSourceInit` due to a bug in the MCP SDK:
+When using the legacy SSE MCP transport, you must configure both `requestInit` and `eventSourceInit` due to a bug in the MCP SDK. Alternatively, you can use a custom `fetch` function which will be automatically used for both POST requests and SSE connections:
 
 ```ts
+// Option 1: Using requestInit and eventSourceInit (required for SSE)
 const sseClient = new MCPClient({
   servers: {
     exampleServer: {
@@ -883,6 +919,23 @@ const sseClient = new MCPClient({
     },
   },
 });
+
+// Option 2: Using custom fetch (simpler, works for both Streamable HTTP and SSE)
+const sseClientWithFetch = new MCPClient({
+  servers: {
+    exampleServer: {
+      url: new URL("https://your-mcp-server.com/sse"),
+      fetch: async (url, init) => {
+        const headers = new Headers(init?.headers || {});
+        headers.set("Authorization", "Bearer your-token");
+        return fetch(url, {
+          ...init,
+          headers,
+        });
+      },
+    },
+  },
+});
 ```
 
 ## Related Information