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

package/.docs/raw/reference/client-js/error-handling.mdx

@@ -0,0 +1,38 @@
+# Error Handling
+
+The Mastra Client SDK includes built-in retry mechanism and error handling capabilities.
+
+## Error Handling
+
+All API methods can throw errors that you can catch and handle:
+
+```typescript
+try {
+  const agent = client.getAgent("agent-id");
+  const response = await agent.generate({
+    messages: [{ role: "user", content: "Hello" }],
+  });
+} catch (error) {
+  console.error("An error occurred:", error.message);
+}
+```
+
+## Retry Mechanism
+
+The client automatically retries failed requests with exponential backoff:
+
+```typescript
+const client = new MastraClient({
+  baseUrl: "http://localhost:4111",
+  retries: 3, // Number of retry attempts
+  backoffMs: 300, // Initial backoff time
+  maxBackoffMs: 5000, // Maximum backoff time
+});
+```
+
+### How Retries Work
+
+1. First attempt fails → Wait 300ms
+2. Second attempt fails → Wait 600ms
+3. Third attempt fails → Wait 1200ms
+4. Final attempt fails → Throw error

package/.docs/raw/reference/client-js/logs.mdx

@@ -0,0 +1,24 @@
+# Logs API
+
+The Logs API provides methods to access and query system logs and debugging information in Mastra.
+
+## Getting Logs
+
+Retrieve system logs with optional filtering:
+
+```typescript
+const logs = await client.getLogs({
+  transportId: "transport-1",
+});
+```
+
+## Getting Logs for a Specific Run
+
+Retrieve logs for a specific execution run:
+
+```typescript
+const runLogs = await client.getLogForRun({
+  runId: "run-1",
+  transportId: "transport-1",
+});
+```

package/.docs/raw/reference/client-js/memory.mdx

@@ -0,0 +1,97 @@
+# Memory API
+
+The Memory API provides methods to manage conversation threads and message history in Mastra.
+
+## Memory Thread Operations
+
+### Get All Threads
+
+Retrieve all memory threads for a specific resource:
+
+```typescript
+const threads = await client.getMemoryThreads({
+  resourceId: "resource-1",
+  agentId: "agent-1"
+});
+```
+
+### Create a New Thread
+
+Create a new memory thread:
+
+```typescript
+const thread = await client.createMemoryThread({
+  title: "New Conversation",
+  metadata: { category: "support" },
+  resourceid: "resource-1",
+  agentId: "agent-1"
+});
+```
+
+### Working with a Specific Thread
+
+Get an instance of a specific memory thread:
+
+```typescript
+const thread = client.getMemoryThread("thread-id", "agent-id");
+```
+
+## Thread Methods
+
+### Get Thread Details
+
+Retrieve details about a specific thread:
+
+```typescript
+const details = await thread.get();
+```
+
+### Update Thread
+
+Update thread properties:
+
+```typescript
+const updated = await thread.update({
+  title: "Updated Title",
+  metadata: { status: "resolved" },
+  resourceid: "resource-1",
+});
+```
+
+### Delete Thread
+
+Delete a thread and its messages:
+
+```typescript
+await thread.delete();
+```
+
+## Message Operations
+
+### Save Messages
+
+Save messages to memory:
+
+```typescript
+const savedMessages = await client.saveMessageToMemory({
+  messages: [
+    {
+      role: "user",
+      content: "Hello!",
+      id: "1",
+      threadId: "thread-1",
+      createdAt: new Date(),
+      type: "text",
+    },
+  ],
+  agentId: "agent-1"
+});
+```
+
+### Get Memory Status
+
+Check the status of the memory system:
+
+```typescript
+const status = await client.getMemoryStatus("agent-id");
+```

package/.docs/raw/reference/client-js/telemetry.mdx

@@ -0,0 +1,20 @@
+# Telemetry API
+
+The Telemetry API provides methods to retrieve and analyze traces from your Mastra application. This helps you monitor and debug your application's behavior and performance.
+
+## Getting Traces
+
+Retrieve traces with optional filtering and pagination:
+
+```typescript
+const telemetry = await client.getTelemetry({
+  name: "trace-name", // Optional: Filter by trace name
+  scope: "scope-name", // Optional: Filter by scope
+  page: 1, // Optional: Page number for pagination
+  perPage: 10, // Optional: Number of items per page
+  attribute: {
+    // Optional: Filter by custom attributes
+    key: "value",
+  },
+});
+```

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

@@ -0,0 +1,44 @@
+# Tools API
+
+The Tools API provides methods to interact with and execute tools available in the Mastra platform.
+
+## Getting All Tools
+
+Retrieve a list of all available tools:
+
+```typescript
+const tools = await client.getTools();
+```
+
+## Working with a Specific Tool
+
+Get an instance of a specific tool:
+
+```typescript
+const tool = client.getTool("tool-id");
+```
+
+## Tool Methods
+
+### Get Tool Details
+
+Retrieve detailed information about a tool:
+
+```typescript
+const details = await tool.details();
+```
+
+### Execute Tool
+
+Execute a tool with specific arguments:
+
+```typescript
+const result = await tool.execute({
+  args: {
+    param1: "value1",
+    param2: "value2",
+  },
+  threadId: "thread-1", // Optional: Thread context
+  resourceid: "resource-1", // Optional: Resource identifier
+});
+```

package/.docs/raw/reference/client-js/vectors.mdx

@@ -0,0 +1,79 @@
+# Vectors API
+
+The Vectors API provides methods to work with vector embeddings for semantic search and similarity matching in Mastra.
+
+## Working with Vectors
+
+Get an instance of a vector store:
+
+```typescript
+const vector = client.getVector("vector-name");
+```
+
+## Vector Methods
+
+### Get Vector Index Details
+
+Retrieve information about a specific vector index:
+
+```typescript
+const details = await vector.details("index-name");
+```
+
+### Create Vector Index
+
+Create a new vector index:
+
+```typescript
+const result = await vector.createIndex({
+  indexName: "new-index",
+  dimension: 128,
+  metric: "cosine", // 'cosine', 'euclidean', or 'dotproduct'
+});
+```
+
+### Upsert Vectors
+
+Add or update vectors in an index:
+
+```typescript
+const ids = await vector.upsert({
+  indexName: "my-index",
+  vectors: [
+    [0.1, 0.2, 0.3], // First vector
+    [0.4, 0.5, 0.6], // Second vector
+  ],
+  metadata: [{ label: "first" }, { label: "second" }],
+  ids: ["id1", "id2"], // Optional: Custom IDs
+});
+```
+
+### Query Vectors
+
+Search for similar vectors:
+
+```typescript
+const results = await vector.query({
+  indexName: "my-index",
+  queryVector: [0.1, 0.2, 0.3],
+  topK: 10,
+  filter: { label: "first" }, // Optional: Metadata filter
+  includeVector: true, // Optional: Include vectors in results
+});
+```
+
+### Get All Indexes
+
+List all available indexes:
+
+```typescript
+const indexes = await vector.getIndexes();
+```
+
+### Delete Index
+
+Delete a vector index:
+
+```typescript
+const result = await vector.delete("index-name");
+```

package/.docs/raw/reference/client-js/workflows.mdx

@@ -0,0 +1,136 @@
+# Workflows API
+
+The Workflows API provides methods to interact with and execute automated workflows in Mastra.
+
+## Getting All Workflows
+
+Retrieve a list of all available workflows:
+
+```typescript
+const workflows = await client.getWorkflows();
+```
+
+## Working with a Specific Workflow
+
+Get an instance of a specific workflow:
+
+```typescript
+const workflow = client.getWorkflow("workflow-id");
+```
+
+## Workflow Methods
+
+### Get Workflow Details
+
+Retrieve detailed information about a workflow:
+
+```typescript
+const details = await workflow.details();
+```
+
+### Start workflow run asynchronously
+
+Start a workflow run with triggerData and await full run results:
+
+```typescript
+const {runId} = workflow.createRun()
+
+const result = await workflow.startAsync({
+  runId,
+  triggerData: {
+    param1: "value1",
+    param2: "value2",
+  },
+});
+```
+
+### Resume Workflow run asynchronously
+
+Resume a suspended workflow step and await full run result:
+
+```typescript
+const {runId} = createRun({runId: prevRunId})
+
+const result = await workflow.resumeAsync({
+  runId,
+  stepId: "step-id",
+  contextData: { key: "value" },
+});
+```
+
+### Watch Workflow
+
+Watch workflow transitions
+
+```typescript
+try{
+  // Get workflow instance
+  const workflow = client.getWorkflow("workflow-id");
+
+  // Create a workflow run
+  const {runId} = workflow.createRun()
+
+  // Watch workflow run 
+     workflow.watch({runId},(record)=>{
+       // Every new record is the latest transition state of the workflow run
+
+        console.log({
+          activePaths: record.activePaths,
+          results: record.results,
+          timestamp: record.timestamp,
+          runId: record.runId
+        });
+     });
+
+  // Start workflow run
+     workflow.start({
+      runId,
+      triggerData: {
+        city: 'New York',
+      },
+    });
+}catch(e){
+  console.error(e);
+}
+```
+### Resume Workflow
+
+Resume workflow run and watch workflow step transitions
+
+```typescript
+try{
+  //To resume a workflow run, when a step is suspended
+  const {run} = createRun({runId: prevRunId})
+
+  //Watch run
+   workflow.watch({runId},(record)=>{
+   // Every new record is the latest transition state of the workflow run
+
+        console.log({
+          activePaths: record.activePaths,
+          results: record.results,
+          timestamp: record.timestamp,
+          runId: record.runId
+        });
+   })
+
+   //resume run
+   workflow.resume({
+      runId,
+      stepId: "step-id",
+      contextData: { key: "value" },
+    });
+}catch(e){
+  console.error(e);
+}
+```
+
+### Workflow run result
+A workflow run result yields the following:
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `activePaths` | `Record<string, { status: string; suspendPayload?: any; stepPath: string[] }>` | Currently active paths in the workflow with their execution status |
+| `results` | `CoreWorkflowRunResult<any, any, any>['results']` | Results from the workflow execution |
+| `timestamp` | `number` | Unix timestamp of when this transition occurred |
+| `runId` | `string` | Unique identifier for this workflow run instance |

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"
+  }
+}
+```