@mastra/mcp-docs-server 0.0.1 → 0.0.2-alpha.0

package/.docs/raw/local-dev/mastra-dev.mdx

@@ -1,65 +1,108 @@
 ---
 title: "Inspecting Agents with `mastra dev` | Mastra Local Dev Docs"
-description: Documentation for the mastra dev command, which launches a local development server for Mastra applications.
+description: Documentation for the Mastra local development environment for Mastra applications.
 ---
+import YouTube from "../../../components/youtube";
 
-# Inspecting agents and workflows with `mastra Dev`
+# Local Development Environment
 
-The `mastra dev` command launches a development server that serves your Mastra application locally.
+Mastra provides a local development environment where you can test your agents, workflows, and tools while developing locally.
 
-## REST API Endpoints
+<YouTube id="spGlcTEjuXY" />
 
-`mastra dev` spins up REST API endpoints for your agents and workflows, such as:
+## Launch Development Server
 
-- `POST /api/agents/:agentId/generate`
-- `POST /api/agents/:agentId/stream`
-- `POST /api/workflows/:workflowId/start`
-- `POST /api/workflows/:workflowId/:instanceId/event`
-- `GET /api/workflows/:workflowId/:instanceId/status`
+You can launch the Mastra development environment using the Mastra CLI by running:
+
+```bash
+mastra dev
+```
 
 By default, the server runs at http://localhost:4111, but you can change the port with the `--port` flag.
 
-## Using the Client SDK
+## Dev Playground
 
-The easiest way to interact with your local Mastra server is through our [TypeScript/JavaScript Client SDK](/docs/reference/client-js). Install it with:
+`mastra dev` serves a playground UI for interacting with your agents, workflows, and tools. The playground provides dedicated interfaces for testing each component of your Mastra application during development.
 
-```bash
-npm install @mastra/client-js
-```
+### Agent Playground
 
-Then configure it to point to your local server:
+The Agent playground provides an interactive chat interface where you can test and debug your agents during development. Key features include:
 
-```typescript
-import { MastraClient } from "@mastra/client-js";
+- **Chat Interface**: Directly interact with your agents to test their responses and behavior.
+- **Prompt CMS**: Experiment with different system instructions for your agent:
+  - A/B test different prompt versions.
+  - Track performance metrics for each variant.
+  - Select and deploy the most effective prompt version.
+- **Agent Traces**: View detailed execution traces to understand how your agent processes requests, including:
+  - Prompt construction.
+  - Tool usage.
+  - Decision-making steps.
+  - Response generation.
+- **Agent Evals**: When you've set up [Agent evaluation metrics](/docs/evals/00-overview), you can:
+  - Run evaluations directly from the playground.
+  - View evaluation results and metrics.
+  - Compare agent performance across different test cases.
 
-const client = new MastraClient({
-  baseUrl: "http://localhost:4111",
-});
+### Workflow Playground
 
-// Example: Interact with a local agent
-const agent = client.getAgent("my-agent");
-const response = await agent.generate({
-  messages: [{ role: "user", content: "Hello!" }],
-});
-```
+The Workflow playground helps you visualize and test your workflow implementations:
+
+- **Workflow Visualization**: Workflow graph visualization.
+
+- **Run Workflows**:
+  - Trigger test workflow runs with custom input data.
+  - Debug workflow logic and conditions.
+  - Simulate different execution paths.
+  - View detailed execution logs for each step.
 
-The client SDK provides type-safe wrappers for all API endpoints, making it much easier to develop and test your Mastra applications locally.
+- **Workflow Traces**: Examine detailed execution traces that show:
+  - Step-by-step workflow progression.
+  - State transitions and data flow.
+  - Tool invocations and their results.
+  - Decision points and branching logic.
+  - Error handling and recovery paths.
 
-## UI Playground
+### Tools Playground
 
-`mastra dev` creates a UI with an agent chat interface, a workflow visualizer and a tool playground.
+The Tools playground allows you to test your custom tools in isolation:
 
-{/* TODO: Record a quick tour video here */}
+- Test individual tools without running a full agent or workflow.
+- Input test data and view tool responses.
+- Debug tool implementation and error handling.
+- Verify tool input/output schemas.
+- Monitor tool performance and execution time.
+
+## REST API Endpoints
+
+`mastra dev` also spins up REST API routes for your agents and workflows via the local [Mastra Server](/docs/deployment/server). This allows you to test your API endpoints before deployment. See [Mastra Dev reference](http://localhost:3000/docs/reference/cli/dev#routes) for more details about all endpoints.
+
+You can then leverage the [Mastra Client](/docs/deployment/client) SDK to interact with your served REST API routes seamlessly.
 
 ## OpenAPI Specification
 
-`mastra dev` provides an OpenAPI spec at:
+`mastra dev` provides an OpenAPI spec at http://localhost:4111/openapi.json
+
+## Local Dev Architecture
+
+The local development server is designed to run without any external dependencies or containerization. This is achieved through:
+
+- **Dev Server**: Uses [Hono](https://hono.dev) as the underlying framework to power the [Mastra Server](/docs/deployment/server).
+
+- **In-Memory Storage**: Uses [LibSQL](https://libsql.org/) memory adapters for:
+  - Agent memory management.
+  - Trace storage.
+  - Evals storage.
+  - Workflow snapshots.
+
+- **Vector Storage**: Uses [FastEmbed](https://github.com/qdrant/fastembed) for:
+  - Default embedding generation.
+  - Vector storage and retrieval.
+  - Semantic search capabilities.
 
-- `GET /openapi.json`
+This architecture allows you to start developing immediately without setting up databases or vector stores, while still maintaining production-like behavior in your local environment.
 
 ## Summary
 
 `mastra dev` makes it easy to develop, debug, and iterate on your AI logic in a self-contained environment before deploying to production.
 
-- [Mastra Dev reference](../reference/cli/dev.mdx)
-- [Client SDK documentation](/docs/reference/client-js)
+- [Mastra Dev reference](../reference/cli/dev.mdx)

package/.docs/raw/reference/agents/createTool.mdx

@@ -5,140 +5,162 @@ description: Documentation for the createTool function in Mastra, which creates
 
 # `createTool()`
 
-Tools are typed functions that can be executed by agents or workflows, with built-in integration access and parameter validation. Each tool has a schema that defines its inputs, an executor function that implements its logic, and access to configured integrations.
+The `createTool()` function creates typed tools that can be executed by agents or workflows. Tools have built-in schema validation, execution context, and integration with the Mastra ecosystem.
 
-```ts filename="src/mastra/tools/index.ts" showLineNumbers copy
-import { createTool } from "@mastra/core/logger";
+## Overview
+
+Tools are a fundamental building block in Mastra that allow agents to interact with external systems, perform computations, and access data. Each tool has:
+
+- A unique identifier
+- A description that helps the AI understand when and how to use the tool
+- Optional input and output schemas for validation
+- An execution function that implements the tool's logic
+
+## Example Usage
+
+```ts filename="src/tools/stock-tools.ts" showLineNumbers copy
+import { createTool } from "@mastra/core/tools";
 import { z } from "zod";
 
+// Helper function to fetch stock data
 const getStockPrice = async (symbol: string) => {
-  const data = await fetch(
-    `https://mastra-stock-data.vercel.app/api/stock-data?symbol=${symbol}`,
-  ).then((r) => r.json());
+  const response = await fetch(
+    `https://mastra-stock-data.vercel.app/api/stock-data?symbol=${symbol}`
+  );
+  const data = await response.json();
   return data.prices["4. close"];
 };
 
-export const stockPrices = createTool({
-  id: "Get Stock Price",
+// Create a tool to get stock prices
+export const stockPriceTool = createTool({
+  id: "getStockPrice",
+  description: "Fetches the current stock price for a given ticker symbol",
   inputSchema: z.object({
+    symbol: z.string().describe("The stock ticker symbol (e.g., AAPL, MSFT)")
+  }),
+  outputSchema: z.object({
     symbol: z.string(),
+    price: z.number(),
+    currency: z.string(),
+    timestamp: z.string()
   }),
-  description: `Fetches the last day's closing stock price for a given symbol`,
   execute: async ({ context }) => {
-    console.log("Using tool to fetch stock price for", context.symbol);
+    const price = await getStockPrice(context.symbol);
+    
     return {
       symbol: context.symbol,
-      currentPrice: await getStockPrice(context.symbol),
+      price: parseFloat(price),
+      currency: "USD",
+      timestamp: new Date().toISOString()
     };
-  },
+  }
 });
 
-export const threadInfo = createTool({
-  id: "Get Thread Info",
+// Create a tool that uses the thread context
+export const threadInfoTool = createTool({
+  id: "getThreadInfo",
+  description: "Returns information about the current conversation thread",
   inputSchema: z.object({
-    includeResource: z.boolean().optional(),
+    includeResource: z.boolean().optional().default(false)
   }),
-  description: `Gets information about the current conversation thread`,
   execute: async ({ context, threadId, resourceId }) => {
-    console.log("Current thread:", threadId);
-    console.log("Current resource:", resourceId);
-
     return {
       threadId,
       resourceId: context.includeResource ? resourceId : undefined,
+      timestamp: new Date().toISOString()
     };
-  },
+  }
 });
 ```
 
-## API Signature
+## API Reference
 
 ### Parameters
 
+`createTool()` accepts a single object with the following properties:
+
 <PropertiesTable
   content={[
     {
-      name: "label",
+      name: "id",
       type: "string",
       required: true,
-      description: 'Name of the tool (e.g., "Get Stock Prices")',
-    },
-    {
-      name: "schema",
-      type: "ZodSchema",
-      required: true,
-      description: "Zod schema for validating inputs",
+      description: "Unique identifier for the tool. This should be descriptive of the tool's function."
     },
     {
       name: "description",
       type: "string",
       required: true,
-      description: "Clear explanation of what market data the tool provides",
+      description: "Detailed description of what the tool does, when it should be used, and what inputs it requires. This helps the AI understand how to use the tool effectively."
     },
     {
-      name: "executor",
-      type: "(params: ExecutorParams) => Promise<any>",
-      required: true,
-      description: "Async function that fetches the requested market data",
+      name: "execute",
+      type: "(context: ToolExecutionContext, options?: any) => Promise<any>",
+      required: false,
+      description: "Async function that implements the tool's logic. Receives the execution context and optional configuration.",
       properties: [
         {
-          type: "ExecutorParams",
+          type: "ToolExecutionContext",
           parameters: [
             {
-              name: "data",
+              name: "context",
               type: "object",
-              description: "The validated input data (in this case, symbol)",
-            },
-            {
-              name: "integrationsRegistry",
-              type: "function",
-              description: "Function to get connected integrations",
+              description: "The validated input data that matches the inputSchema"
             },
             {
-              name: "runId",
+              name: "threadId",
               type: "string",
               isOptional: true,
-              description: "The runId of the current run",
+              description: "Identifier for the conversation thread, if available"
             },
             {
-              name: "threadId",
+              name: "resourceId",
               type: "string",
               isOptional: true,
-              description:
-                "Identifier for the conversation thread. Allows for maintaining context across multiple interactions.",
+              description: "Identifier for the user or resource interacting with the tool"
             },
             {
-              name: "resourceId",
-              type: "string",
+              name: "mastra",
+              type: "Mastra",
               isOptional: true,
-              description:
-                "Identifier for the user or resource interacting with the tool.",
+              description: "Reference to the Mastra instance, if available"
             },
+          ]
+        },
+        {
+          type: "ToolOptions",
+          parameters: [
             {
-              name: "agents",
-              type: "Map<string, Agent<any>>",
-              description: "Map of registered agents",
+              name: "toolCallId",
+              type: "string",
+              description: "The ID of the tool call. You can use it e.g. when sending tool-call related information with stream data."
             },
             {
-              name: "engine",
-              isOptional: true,
-              type: "MastraEngine",
-              description: "Mastra engine instance",
+              name: "messages",
+              type: "CoreMessage[]",
+              description: "Messages that were sent to the language model to initiate the response that contained the tool call. The messages do not include the system prompt nor the assistant response that contained the tool call."
             },
             {
-              name: "llm",
-              type: "LLM",
-              description: "LLM instance",
+              name: "abortSignal",
+              type: "AbortSignal",
+              isOptional: true,
+              description: "An optional abort signal that indicates that the overall operation should be aborted."
             },
-          ],
-        },
-      ],
+          ]
+        }
+      ]
+    },
+    {
+      name: "inputSchema",
+      type: "ZodSchema",
+      required: false,
+      description: "Zod schema that defines and validates the tool's input parameters. If not provided, the tool will accept any input."
     },
     {
       name: "outputSchema",
       type: "ZodSchema",
-      isOptional: true,
-      description: "Zod schema for validating outputs",
+      required: false,
+      description: "Zod schema that defines and validates the tool's output. Helps ensure the tool returns data in the expected format."
     },
   ]}
 />
@@ -148,43 +170,60 @@ export const threadInfo = createTool({
 <PropertiesTable
   content={[
     {
-      name: "ToolApi",
-      type: "object",
-      description:
-        "The tool API object that includes the schema, label, description, and executor function.",
+      name: "Tool",
+      type: "Tool<TSchemaIn, TSchemaOut>",
+      description: "A Tool instance that can be used with agents, workflows, or directly executed.",
       properties: [
         {
-          type: "ToolApi",
+          type: "Tool",
           parameters: [
             {
-              name: "schema",
-              type: "ZodSchema<IN>",
-              description: "Zod schema for validating inputs.",
-            },
-            {
-              name: "label",
+              name: "id",
               type: "string",
-              description: "Name of the tool.",
+              description: "The tool's unique identifier"
             },
             {
               name: "description",
               type: "string",
-              description: "Description of the tool's functionality.",
+              description: "Description of the tool's functionality"
+            },
+            {
+              name: "inputSchema",
+              type: "ZodSchema | undefined",
+              description: "Schema for validating inputs"
             },
             {
               name: "outputSchema",
-              type: "ZodSchema<OUT>",
-              isOptional: true,
-              description: "Zod schema for validating outputs.",
+              type: "ZodSchema | undefined",
+              description: "Schema for validating outputs"
             },
             {
               name: "execute",
-              type: "(params: IntegrationApiExcutorParams<IN>) => Promise<OUT>",
-              description: "Async function that executes the tool's logic.",
-            },
-          ],
-        },
-      ],
-    },
+              type: "Function",
+              description: "The tool's execution function"
+            }
+          ]
+        }
+      ]
+    }
   ]}
 />
+
+## Type Safety
+
+The `createTool()` function provides full type safety through TypeScript generics:
+
+- Input types are inferred from the `inputSchema`
+- Output types are inferred from the `outputSchema`
+- The execution context is properly typed based on the input schema
+
+This ensures that your tools are type-safe throughout your application.
+
+## Best Practices
+
+1. **Descriptive IDs**: Use clear, action-oriented IDs like `getWeatherForecast` or `searchDatabase`
+2. **Detailed Descriptions**: Provide comprehensive descriptions that explain when and how to use the tool
+3. **Input Validation**: Use Zod schemas to validate inputs and provide helpful error messages
+4. **Error Handling**: Implement proper error handling in your execute function
+5. **Idempotency**: When possible, make your tools idempotent (same input always produces same output)
+6. **Performance**: Keep tools lightweight and fast to execute

package/.docs/raw/reference/agents/stream.mdx

@@ -238,12 +238,6 @@ Settings for telemetry collection during streaming:
 
 <PropertiesTable
   content={[
-    {
-      name: "functionId",
-      type: "string",
-      isOptional: true,
-      description: "Identifier for this function. Used to group telemetry data by function.",
-    },
     {
       name: "isEnabled",
       type: "boolean",
@@ -251,12 +245,6 @@ Settings for telemetry collection during streaming:
       defaultValue: "false",
       description: "Enable or disable telemetry. Disabled by default while experimental.",
     },
-    {
-      name: "metadata",
-      type: "Record<string, AttributeValue>",
-      isOptional: true,
-      description: "Additional information to include in the telemetry data. AttributeValue can be string, number, boolean, array of these types, or null.",
-    },
     {
       name: "recordInputs",
       type: "boolean",
@@ -271,6 +259,18 @@ Settings for telemetry collection during streaming:
       defaultValue: "true",
       description: "Enable or disable output recording. You might want to disable this to avoid recording sensitive information, reduce data transfers, or increase performance.",
     },
+    {
+      name: "functionId",
+      type: "string",
+      isOptional: true,
+      description: "Identifier for this function. Used to group telemetry data by function.",
+    },
+    {
+      name: "metadata",
+      type: "Record<string, AttributeValue>",
+      isOptional: true,
+      description: "Additional information to include in the telemetry data. AttributeValue can be string, number, boolean, array of these types, or null.",
+    },
     {
       name: "tracer",
       type: "Tracer",
@@ -289,10 +289,10 @@ The return value of the `stream()` method depends on the options provided, speci
 <PropertiesTable
   content={[
     {
-      name: "object",
-      type: "Promise<object>",
+      name: "textStream",
+      type: "AsyncIterable<string>",
       isOptional: true,
-      description: "Promise that resolves to the final structured output. Present when using either `output` or `experimental_output` options.",
+      description: "Stream of text chunks. Present when output is 'text' (no schema provided) or when using `experimental_output`.",
     },
     {
       name: "objectStream",
@@ -307,10 +307,10 @@ The return value of the `stream()` method depends on the options provided, speci
       description: "Stream of structured data. Present only when using `experimental_output` option.",
     },
     {
-      name: "textStream",
-      type: "AsyncIterable<string>",
+      name: "object",
+      type: "Promise<object>",
       isOptional: true,
-      description: "Stream of text chunks. Present when output is 'text' (no schema provided) or when using `experimental_output`.",
+      description: "Promise that resolves to the final structured output. Present when using either `output` or `experimental_output` options.",
     }
   ]}
 />
@@ -359,3 +359,4 @@ console.log("Final structured result:", result);
 ```
 
 The key difference between Agent's `stream()` and LLM's `stream()` is that Agents maintain conversation context through `threadId`, can access tools, and integrate with the agent's memory system.
+

package/.docs/raw/reference/cli/dev.mdx

@@ -5,7 +5,7 @@ description: Documentation for the mastra dev command, which starts a developmen
 
 # `mastra dev` Reference
 
-The `mastra dev` command starts a development server that exposes REST endpoints for your agents, tools, and workflows,
+The `mastra dev` command starts a development server that exposes REST routes for your agents, tools, and workflows,
 
 ## Parameters
 
@@ -37,39 +37,81 @@ The `mastra dev` command starts a development server that exposes REST endpoints
 
 ## Routes
 
-Starting the server with `mastra dev` exposes a set of REST endpoints by default:
+Starting the server with `mastra dev` exposes a set of REST routes by default:
+
+### System Routes
+- **GET `/api`**: Get API status.
 
 ### Agent Routes
 
 Agents are expected to be exported from `src/mastra/agents`.
 
-• `GET /api/agents`
-  - Lists the registered agents found in your Mastra folder.
-• `POST /api/agents/:agentId/generate`
-  - Sends a text-based prompt to the specified agent, returning the agent's response.
+- **GET `/api/agents`**: Lists the registered agents found in your Mastra folder.
+- **GET `/api/agents/:agentId`**: Get agent by ID.
+- **GET `/api/agents/:agentId/evals/ci`**: Get CI evals by agent ID.
+- **GET `/api/agents/:agentId/evals/live`**: Get live evals by agent ID.
+- **POST `/api/agents/:agentId/generate`**: Sends a text-based prompt to the specified agent, returning the agent's response.
+- **POST `/api/agents/:agentId/stream`**: Stream a response from an agent.
+- **POST `/api/agents/:agentId/instructions`**: Update an agent's instructions.
+- **POST `/api/agents/:agentId/instructions/enhance`**: Generate an improved system prompt from instructions.
+- **GET `/api/agents/:agentId/speakers`**: Get available speakers for an agent.
+- **POST `/api/agents/:agentId/speak`**: Convert text to speech using the agent's voice provider.
+- **POST `/api/agents/:agentId/listen`**: Convert speech to text using the agent's voice provider.
+- **POST `/api/agents/:agentId/tools/:toolId/execute`**: Execute a tool through an agent.
 
 ### Tool Routes
 
 Tools are expected to be exported from `src/mastra/tools` (or the configured tools directory).
 
-• `POST /api/tools/:toolName`
-  - Invokes a specific tool by name, passing input data in the request body.
+- **GET `/api/tools`**: Get all tools.
+- **GET `/api/tools/:toolId`**: Get tool by ID.
+- **POST `/api/tools/:toolId/execute`**: Invokes a specific tool by name, passing input data in the request body.
 
 ### Workflow Routes
 
 Workflows are expected to be exported from `src/mastra/workflows` (or the configured workflows directory).
 
-• `POST /api/workflows/:workflowName/start`
-  - Starts the specified workflow.
-• `POST /api/workflows/:workflowName/:instanceId/event`
-  - Sends an event or trigger signal to an existing workflow instance.
-• `GET /api/workflows/:workflowName/:instanceId/status`
-  - Returns status info for a running workflow instance.
+- **GET `/api/workflows`**: Get all workflows.
+- **GET `/api/workflows/:workflowId`**: Get workflow by ID.
+- **POST `/api/workflows/:workflowName/start`**: Starts the specified workflow.
+- **POST `/api/workflows/:workflowName/:instanceId/event`**: Sends an event or trigger signal to an existing workflow instance.
+- **GET `/api/workflows/:workflowName/:instanceId/status`**: Returns status info for a running workflow instance.
+- **POST `/api/workflows/:workflowId/resume`**: Resume a suspended workflow step.
+- **POST `/api/workflows/:workflowId/resumeAsync`**: Resume a suspended workflow step asynchronously.
+- **POST `/api/workflows/:workflowId/createRun`**: Create a new workflow run.
+- **POST `/api/workflows/:workflowId/startAsync`**: Execute/Start a workflow asynchronously.
+- **GET `/api/workflows/:workflowId/watch`**: Watch workflow transitions in real-time.
+
+### Memory Routes
+- **GET `/api/memory/status`**: Get memory status.
+- **GET `/api/memory/threads`**: Get all threads.
+- **GET `/api/memory/threads/:threadId`**: Get thread by ID.
+- **GET `/api/memory/threads/:threadId/messages`**: Get messages for a thread.
+- **POST `/api/memory/threads`**: Create a new thread.
+- **PATCH `/api/memory/threads/:threadId`**: Update a thread.
+- **DELETE `/api/memory/threads/:threadId`**: Delete a thread.
+- **POST `/api/memory/save-messages`**: Save messages.
+
+### Telemetry Routes
+- **GET `/api/telemetry`**: Get all traces.
+
+### Log Routes
+- **GET `/api/logs`**: Get all logs.
+- **GET `/api/logs/transports`**: List of all log transports.
+- **GET `/api/logs/:runId`**: Get logs by run ID.
+
+### Vector Routes
+- **POST `/api/vector/:vectorName/upsert`**: Upsert vectors into an index.
+- **POST `/api/vector/:vectorName/create-index`**: Create a new vector index.
+- **POST `/api/vector/:vectorName/query`**: Query vectors from an index.
+- **GET `/api/vector/:vectorName/indexes`**: List all indexes for a vector store.
+- **GET `/api/vector/:vectorName/indexes/:indexName`**: Get details about a specific index.
+- **DELETE `/api/vector/:vectorName/indexes/:indexName`**: Delete a specific index.
 
 ### OpenAPI Specification
 
-• `GET /openapi.json`
-  - Returns an auto-generated OpenAPI specification for your project's endpoints.
+- **GET `/openapi.json`**: Returns an auto-generated OpenAPI specification for your project's routes.
+- **GET `/swagger-ui`**: Access Swagger UI for API documentation.
 
 ## Additional Notes
 
@@ -90,8 +132,3 @@ curl -X POST http://localhost:4111/api/agents/myAgent/generate \
     ]
   }'
 ```
-
-## Related Docs
-
-- [REST Endpoints Overview](../../local-dev/mastra-dev.mdx) – More detailed usage of the dev server and agent endpoints.
-- [mastra deploy](../../deployment/deployment.mdx) – Deploy your project to Vercel or Cloudflare.