npm - @mastra/mcp-docs-server - Versions diffs - 0.13.32 → 0.13.33 - Mend

@mastra/mcp-docs-server 0.13.32 → 0.13.33

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (29) hide show

package/.docs/raw/server-db/local-dev-playground.mdx DELETED Viewed

@@ -1,233 +0,0 @@
----
-title: "Inspecting agents and workflows with mastra dev | Mastra Local Dev Docs"
-description: Documentation for the Mastra local development environment for Mastra applications.
----
-import YouTube from "@/components/youtube";
-import { VideoPlayer } from "@/components/video-player"
-import { Tabs, Tab } from "@/components/tabs";
-# Playground
-Mastra provides a local development environment where you can test your agents, workflows, and tools during development.
-Start the local development server by running:
-<Tabs items={["npm", "yarn", "pnpm", "bun", "Mastra CLI"]}>
-  <Tab>
-    ```bash copy
-    npm run dev
-    ```
-  </Tab>
-  <Tab>
-    ```bash copy
-    yarn run dev
-    ```
-  </Tab>
-  <Tab>
-    ```bash copy
-    pnpm run dev
-    ```
-  </Tab>
-  <Tab>
-    ```bash copy
-    bun run dev
-    ```
-  </Tab>
-  <Tab>
-    ```bash copy
-    mastra dev
-    ```
-  </Tab>
-</Tabs>
-The local development server provides access to the following interfaces:
-- Playground: [http://localhost:4111/](http://localhost:4111/)
-- Mastra API: [http://localhost:4111/api](http://localhost:4111/api)
-- OpenAPI Spec: [http://localhost:4111/openapi.json](http://localhost:4111/openapi.json)
-- Swagger UI – API explorer: [http://localhost:4111/swagger-ui](http://localhost:4111/swagger-ui)
-## Local Development Playground
-The Playground lets you interact with your agents, workflows, and tools. It provides dedicated interfaces for testing each component of your Mastra application during development and is available at: [http://localhost:4111/](http://localhost:4111/).
-<YouTube id="spGlcTEjuXY" startTime={126}/>
-### Agents
-Quickly test and debug your agents during development using the interactive chat interface in the Agent Playground.
-<VideoPlayer
-  src="https://res.cloudinary.com/mastra-assets/video/upload/v1751406022/local-dev-agents-playground_100_m3begx.mp4"
-/>
-Key features:
-- **Chat Interface**: Talk to your agent and see how it responds in real time.
-- **Model Settings**: Tweak settings like temperature and top-p to see how they affect output.
-- **Agent Endpoints**: See the available REST API routes your agent exposes and how to use them.
-- **Agent Traces**: Step through what the agent did behind the scenes, tool calls, decisions, and more.
-- **Agent Evals**: Run tests against your agent and see how well it performs.
-### Workflows
-Validate workflows by supplying defined inputs and visualizing each step within the Workflow Playground.
-<VideoPlayer
-  src="https://res.cloudinary.com/mastra-assets/video/upload/v1751406027/local-dev-workflows-playground_100_rbc466.mp4"
-/>
-Key features:
-- **Workflow Visualization**: See your workflow as a visual graph so you can follow the steps and branches at a glance.
-- **Step Inputs & Outputs**: Check the data going into and coming out of each step to see how everything flows.
-- **Run Workflows**: Test your workflow with real inputs to validate the logic and debug any issues.
-- **Execution JSON**: Get the full picture of a run as raw JSON—inputs, outputs, errors, and results included.
-- **Workflow Traces**: Dig into a detailed breakdown of each step, including data flow, tool calls, and any errors along the way.
-### Tools
-Quickly test and debug custom tools in isolation using the Tools Playground, without running a full agent or workflow.
-<VideoPlayer
-  src="https://res.cloudinary.com/mastra-assets/video/upload/v1751406316/local-dev-agents-tools_100_fe1jdt.mp4"
-/>
-Key features:
-- **Test Tools in Isolation**: Try out individual tools on their own without running a full agent or workflow.
-- **Input & Responses**: Send sample inputs to see how the tool responds.
-- **Tool Usage**: Find out which agents rely on this tool and how they’re using it.
-### MCP Servers
-Explore connection details, tool usage, and IDE configuration for local MCP server development.
-![MCP Servers Playground](/image/local-dev/local-dev-mcp-server-playground.jpg)
-Key features:
-- **Connection Details**: Access the endpoints and config needed to wire up your MCP environment.
-- **Available Tools**:  See all tools currently published, including their names, versions, and which agents use them.
-- **IDE Configuration**: Grab ready-to-use config you can drop into your local setup for testing and publishing tools.
-## REST API Endpoints
-The local development server exposes a set of REST API routes via the [Mastra Server](/docs/deployment/server-deployment), allowing you to test and interact with your agents and workflows before deployment.
-For a full overview of available API routes, including agents, tools, and workflows, visit [http://localhost:4111/swagger-ui](http://localhost:4111/swagger-ui) during `mastra dev`.
-## OpenAPI Specification
-The local development server includes an OpenAPI specification available at: [http://localhost:4111/openapi.json](http://localhost:4111/openapi.json).
-To include OpenAPI documentation in your production server, enable it in the Mastra instance:
-```typescript {6} filename="src/mastra/index.ts" copy
-import { Mastra } from "@mastra/core/mastra";
-export const mastra = new Mastra({
-  server: {
-    build: {
-      openAPIDocs: true
-    }
-  },
-});
-```
-## Swagger UI
-The local development server includes an interactive Swagger UI - API explorer available at: [http://localhost:4111/swagger-ui](http://localhost:4111/swagger-ui).
-To include Swagger UI in your production server, enable it in the Mastra instance:
-```typescript {6} filename="src/mastra/index.ts" copy
-import { Mastra } from "@mastra/core/mastra";
-export const mastra = new Mastra({
-  server: {
-    build: {
-      swaggerUI: true
-    },
-  },
-});
-```
-## Architecture
-The local development server runs fully self-contained without external dependencies or containers. It leverages:
-- **Dev Server** powered by [Hono](https://hono.dev) for the core [Mastra Server](/docs/deployment/server).
-- **In-Memory Storage** via [LibSQL](https://libsql.org/) adapters for agent memory, traces, evals, and workflow snapshots.
-- **Vector Storage** using [FastEmbed](https://github.com/qdrant/fastembed) for embeddings, vector search, and semantic retrieval.
-This setup lets you start developing immediately with production-like behavior, no database or vector store setup required.
-## Configuration
-By default, the server runs on port `4111`. You can customize the `host` and `port` through the Mastra server configuration.
-```typescript {5,6} filename="src/mastra/index.ts" copy
-import { Mastra } from "@mastra/core/mastra";
-export const mastra = new Mastra({
-  server: {
-    port: 8080,
-    host: "0.0.0.0",
-  },
-});
-```
-### Local HTTPS
-Mastra provides a way to use a local HTTPS server for `mastra dev` (through [expo/devcert](https://github.com/expo/devcert)). When you use the `--https` flag, a private key and certificate will be created and used for your project. By default, certificates are issued for `localhost` unless you defined another `host` value.
-```bash
-mastra dev --https
-```
-You can provide your own key and cert file by specifying the `server.https` option in the Mastra server configuration.
-```typescript {2,6-9} filename="src/mastra/index.ts" copy
-import { Mastra } from "@mastra/core/mastra";
-import fs from 'node:fs'
-export const mastra = new Mastra({
-  server: {
-    https: {
-      key: fs.readFileSync('path/to/key.pem'),
-      cert: fs.readFileSync('path/to/cert.pem')
-    }
-  },
-});
-```
-When you provide both `--https` and `server.https` the latter will take precedence.
-## Bundler options
-Use `transpilePackages` to compile TypeScript packages or libraries. Use `externals` to exclude dependencies resolved at runtime, and `sourcemap` to emit readable stack traces.
-```typescript filename="src/mastra/index.ts" copy
-import { Mastra } from "@mastra/core/mastra";
-export const mastra = new Mastra({
-  bundler: {
-    transpilePackages: ["utils"],
-    externals: ["ui"],
-    sourcemap: true
-  }
-});
-```
-> See [Mastra Class](../../reference/core/mastra-class.mdx) for more configuration options.
-## Next steps
-- [Mastra Cloud](/docs/mastra-cloud/overview)
-- [Deployment Overview](/docs/deployment/overview)
-- [Mastra Client SDK](/docs/client-js/overview)

package/.docs/raw/workflows/using-with-agents-and-tools.mdx DELETED Viewed

@@ -1,350 +0,0 @@
----
-title: "Using Workflows with Agents and Tools | Workflows | Mastra Docs"
-description: "Steps in Mastra workflows provide a structured way to manage operations by defining inputs, outputs, and execution logic."
----
-# Agents and Tools
-Workflow steps are composable and typically run logic directly within the `execute` function. However, there are cases where calling an agent or tool is more appropriate. This pattern is especially useful when:
-- Generating natural language responses from user input using an LLM.
-- Abstracting complex or reusable logic into a dedicated tool.
-- Interacting with third-party APIs in a structured or reusable way.
-Workflows can use Mastra agents or tools directly as steps, for example: `createStep(testAgent)` or `createStep(testTool)`.
-## Using agents in workflows
-To include an agent in a workflow, define it in the usual way, then either add it directly to the workflow using `createStep(testAgent)` or, invoke it from within a step's `execute` function using `.generate()`.
-### Example agent
-This agent uses OpenAI to generate a fact about a city, country, and timezone.
-```typescript filename="src/mastra/agents/test-agent.ts" showLineNumbers copy
-import { openai } from "@ai-sdk/openai";
-import { Agent } from "@mastra/core/agent";
-export const testAgent = new Agent({
-  name: "test-agent",
-  description: "Create facts for a country based on the city",
-  instructions: `Return an interesting fact about the country based on the city provided`,
-  model: openai("gpt-4o")
-});
-```
-### Adding an agent as a step
-In this example, `step1` uses the `testAgent` to generate an interesting fact about the country based on a given city.
-The `.map` method transforms the workflow input into a `prompt` string compatible with the `testAgent`.
-The step is composed into the workflow using `.then()`, allowing it to receive the mapped input and return the agent's structured output. The workflow is finalized with `.commit()`.
-![Agent as step](/image/workflows/workflows-agent-tools-agent-step.jpg)
-```typescript {3} filename="src/mastra/workflows/test-workflow.ts" showLineNumbers copy
-import { testAgent } from "../agents/test-agent";
-const step1 = createStep(testAgent);
-export const testWorkflow = createWorkflow({
-  id: "test-workflow",
-  description: 'Test workflow',
-  inputSchema: z.object({
-    input: z.string()
-  }),
-  outputSchema: z.object({
-    output: z.string()
-  })
-})
-  .map(({ inputData }) => {
-    const { input } = inputData;
-    return {
-      prompt: `Provide facts about the city: ${input}`
-    };
-  })
-  .then(step1)
-  .commit();
-```
-### Calling an agent with `.generate()`
-In this example, the `step1` builds a prompt using the provided `input` and passes it to the `testAgent`, which returns a plain-text response containing facts about the city and its country.
-The step is added to the workflow using the sequential `.then()` method, allowing it to receive input from the workflow and return structured output. The workflow is finalized with `.commit()`.
-```typescript {1,18, 29} filename="src/mastra/workflows/test-workflow.ts" showLineNumbers copy
-import { testAgent } from "../agents/test-agent";
-const step1 = createStep({
-  id: "step-1",
-  description: "Create facts for a country based on the city",
-  inputSchema: z.object({
-    input: z.string()
-  }),
-  outputSchema: z.object({
-    output: z.string()
-  }),
-  execute: async ({ inputData }) => {
-    const { input } = inputData;
-    const  prompt = `Provide facts about the city: ${input}`
-    const { text } = await testAgent.generate([
-      { role: "user", content: prompt }
-    ]);
-    return {
-      output: text
-    };
-  }
-});
-export const testWorkflow = createWorkflow({...})
-  .then(step1)
-  .commit();
-```
-## Using tools in workflows
-To use a tool within a workflow, define it in the usual way, then either add it directly to the workflow using `createStep(testTool)` or, invoke it from within a step's `execute` function using `.execute()`.
-### Example tool
-The example below uses the Open Meteo API to retrieve geolocation details for a city, returning its name, country, and timezone.
-```typescript filename="src/mastra/tools/test-tool.ts" showLineNumbers copy
-import { createTool } from "@mastra/core";
-import { z } from "zod";
-export const testTool = createTool({
-  id: "test-tool",
-  description: "Gets country for a city",
-  inputSchema: z.object({
-    input: z.string()
-  }),
-  outputSchema: z.object({
-    country_name: z.string()
-  }),
-  execute: async ({ context }) => {
-    const { input } = context;
-    const geocodingResponse = await fetch(`https://geocoding-api.open-meteo.com/v1/search?name=${input}`);
-    const geocodingData = await geocodingResponse.json();
-    const { country } = geocodingData.results[0];
-    return {
-      country_name: country
-    };
-  }
-});
-```
-### Adding a tool as a step
-In this example, `step1` uses the `testTool`, which performs a geocoding lookup using the provided `city` and returns the resolved `country`.
-The step is added to the workflow using the sequential `.then()` method, allowing it to receive input from the workflow and return structured output. The workflow is finalized with `.commit()`.
-![Tool as step](/image/workflows/workflows-agent-tools-tool-step.jpg)
-```typescript {1,3,6} filename="src/mastra/workflows/test-workflow.ts" showLineNumbers copy
-import { testTool } from "../tools/test-tool";
-const step1 = createStep(testTool);
-export const testWorkflow = createWorkflow({...})
-  .then(step1)
-  .commit();
-```
-### Calling a tool with `.execute()`
-In this example, `step1` directly invokes `testTool` using its `.execute()` method. The tool performs a geocoding lookup with the provided `city` and returns the corresponding `country`.
-The result is returned as structured output from the step. The step is composed into the workflow using `.then()`, enabling it to process workflow input and produce typed output. The workflow is finalized with `.commit()`
-```typescript {3,20,32} filename="src/mastra/workflows/test-workflow.ts" showLineNumbers copy
-import { RuntimeContext } from "@mastra/core/di";
-import { testTool } from "../tools/test-tool";
-const runtimeContext = new RuntimeContext();
-const step1 = createStep({
-  id: "step-1",
-  description: "Gets country for a city",
-  inputSchema: z.object({
-    input: z.string()
-  }),
-  outputSchema: z.object({
-    output: z.string()
-  }),
-  execute: async ({ inputData }) => {
-    const { input } = inputData;
-    const { country_name } = await testTool.execute({
-      context: { input },
-      runtimeContext
-    });
-    return {
-      output: country_name
-    };
-  }
-});
-export const testWorkflow = createWorkflow({...})
-  .then(step1)
-  .commit();
-```
-## Using workflows as tools
-In this example the `cityStringWorkflow` workflow has been added to the main Mastra instance.
-```typescript {7} filename="src/mastra/index.ts" showLineNumbers copy
-import { Mastra } from "@mastra/core/mastra";
-import { testWorkflow, cityStringWorkflow } from "./workflows/test-workflow";
-export const mastra = new Mastra({
-  ...
-  workflows: { testWorkflow, cityStringWorkflow },
-});
-```
-Once a workflow has been registered it can be referenced using `getWorkflow` from withing a tool.
-```typescript {10,17-27} filename="src/mastra/tools/test-tool.ts" showLineNumbers copy
-export const cityCoordinatesTool = createTool({
-  id: "city-tool",
-  description: "Convert city details",
-  inputSchema: z.object({
-    city: z.string()
-  }),
-  outputSchema: z.object({
-    outcome: z.string()
-  }),
-  execute: async ({ context, mastra }) => {
-    const { city } = context;
-    const geocodingResponse = await fetch(`https://geocoding-api.open-meteo.com/v1/search?name=${city}`);
-    const geocodingData = await geocodingResponse.json();
-    const { name, country, timezone } = geocodingData.results[0];
-    const workflow = mastra?.getWorkflow("cityStringWorkflow");
-    const run = await workflow?.createRunAsync();
-    const { result } = await run?.start({
-      inputData: {
-        city_name: name,
-        country_name: country,
-        country_timezone: timezone
-      }
-    });
-    return {
-      outcome: result.outcome
-    };
-  }
-});
-```
-## Using workflows in agents
-You can also use Workflows in Agents. This agent is able to choose between using the test tool or the test workflow.
-```typescript
-import { openai } from "@ai-sdk/openai";
-import { Agent } from "@mastra/core/agent";
-import { testTool } from "../tools/test-tool";
-import { testWorkflow } from "../workflows/test-workflow";
-export const testAgent = new Agent({
-  name: "test-agent",
-  description: "Create facts for a country based on the city",
-  instructions: `Return an interesting fact about the country based on the city provided`,
-  model: openai("gpt-4o"),
-  workflows: {
-    test_workflow: testWorkflow
-  },
-  tools: {
-    test_tool: testTool
-  },
-});
-```
-## Exposing workflows with `MCPServer`
-You can convert your workflows into tools by passing them into an instance of a Mastra `MCPServer`. This allows any MCP-compatible client to access your workflow.
-The workflow description becomes the tool description and the input schema becomes the tool's input schema.
-When you provide workflows to the server, each workflow is automatically exposed as a callable tool for example:
-- `run_testWorkflow`.
-```typescript filename="src/test-mcp-server.ts" showLineNumbers copy
-import { MCPServer } from "@mastra/mcp";
-import { testAgent } from "./mastra/agents/test-agent";
-import { testTool } from "./mastra/tools/test-tool";
-import { testWorkflow } from "./mastra/workflows/test-workflow";
-async function startServer() {
-  const server = new MCPServer({
-    name: "test-mcp-server",
-    version: "1.0.0",
-    workflows: {
-      testWorkflow
-    }
-  });
-  await server.startStdio();
-  console.log("MCPServer started on stdio");
-}
-startServer().catch(console.error);
-```
-To verify that your workflow is available on the server, you can connect with an MCPClient.
-```typescript filename="src/test-mcp-client.ts" showLineNumbers copy
-import { MCPClient } from "@mastra/mcp";
-async function main() {
-  const mcp = new MCPClient({
-    servers: {
-      local: {
-        command: "npx",
-        args: ["tsx", "src/test-mcp-server.ts"]
-      }
-    }
-  });
-  const tools = await mcp.getTools();
-  console.log(tools);
-}
-main().catch(console.error);
-```
-Run the client script to see your workflow tool.
-```bash
-npx tsx src/test-mcp-client.ts
-```
-## More resources
-- [MCPServer reference documentation](/reference/tools/mcp-server).
-- [MCPClient reference documentation](/reference/tools/mcp-client).