@mastra/mcp-docs-server 0.13.0 → 0.13.1-alpha.2

package/.docs/raw/workflows/suspend-and-resume.mdx

@@ -29,19 +29,18 @@ When running a workflow, its `status` can be one of the following:
 
 When the state is `suspended`, you can identify any and all steps that have been suspended by looking at the `suspended` array of the workflow.
 
-
 ```typescript {17} filename="src/mastra/workflows/test-workflow.ts" showLineNumbers copy
-const cityCoordinatesStep = createStep({
-  id: "city-step",
-  description: "Gets details about a city",
+const step1 = createStep({
+  id: "step-1",
+  description: "Test suspend",
   inputSchema: z.object({
-    suggestions: z.array(z.string())
+    input: z.array(z.string())
   }),
   resumeSchema: z.object({
     city: z.string()
   }),
   outputSchema: z.object({
-    outcome: z.string()
+    output: z.string()
   }),
   execute: async ({ resumeData, suspend }) => {
     const { city } = resumeData ?? {};
@@ -53,32 +52,19 @@ const cityCoordinatesStep = createStep({
       };
     }
 
-    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];
-
     return {
-      outcome: `${name} | ${country} | ${timezone}`
+      output: ""
     };
   }
 });
 
-export const testWorkflow = createWorkflow({
-  id: "test-workflow",
-  description: 'Test workflow',
-  inputSchema: z.object({
-    suggestions: z.array(z.string()),
-  }),
-  outputSchema: z.object({
-    outcome: z.string(),
-  })
-})
-  .then(cityCoordinatesStep)
+export const testWorkflow = createWorkflow({})
+  .then(step1)
   .commit();
-
 ```
 
+> See [Define Suspendable workflow](/examples/workflows/human-in-the-loop#define-suspendable-workflow) for more information.
+
 ## Resume
 
 A workflow can be resumed by calling `resume` and providing the required `resumeData`.
@@ -96,7 +82,7 @@ console.log(JSON.stringify(result, null, 2));
 
 if (result.status === "suspended") {
   const resumedResult = await run.resume({
-    step: 'city-step',
+    step: 'step-1',
     resumeData: { city: "New York" }
   });
 
@@ -115,10 +101,40 @@ npx tsx src/test-workflow.ts
 To resume a suspended nested workflow pass the workflow instance to the `step` parameter of the `resume` function.
 
 ```typescript {3} filename="src/test-workflow.ts" showLineNumbers copy
+const dowhileWorkflow = createWorkflow({
+  id: 'dowhile-workflow',
+  inputSchema: z.object({ value: z.number() }),
+  outputSchema: z.object({ value: z.number() }),
+})
+  .dountil(
+    createWorkflow({
+      id: 'simple-resume-workflow',
+      inputSchema: z.object({ value: z.number() }),
+      outputSchema: z.object({ value: z.number() }),
+      steps: [incrementStep, resumeStep],
+    })
+      .then(incrementStep)
+      .then(resumeStep)
+      .commit(),
+    async ({ inputData }) => inputData.value >= 10,
+  )
+  .then(
+    createStep({
+      id: 'final',
+      inputSchema: z.object({ value: z.number() }),
+      outputSchema: z.object({ value: z.number() }),
+      execute: async ({ inputData }) => ({ value: inputData.value }),
+    }),
+  )
+  .commit();
+
+const run = dowhileWorkflow.createRun();
+const result = await run.start({ inputData: { value: 0 } });
+
 if (result.status === "suspended") {
-  const resumedResult = await workflowRun.resume({
-    step: [nestedWorkflow],
-    resumeData: { city: "New York" }
+  const resumedResult = await run.resume({
+    resumeData: { value: 2 },
+    step: ['simple-resume-workflow', 'resume'],
   });
 
   console.log(JSON.stringify(resumedResult, null, 2));
@@ -130,7 +146,7 @@ if (result.status === "suspended") {
 When using suspend/resume with `RuntimeContext`, you can create the instance yourself, and pass it to the `start` and `resume` functions.
 `RuntimeContext` is not automatically shared on a workflow run.
 
-```typescript {1,9,18} filename="src/test-workflow.ts" showLineNumbers copy
+```typescript {1,4,9,16} filename="src/test-workflow.ts" showLineNumbers copy
 import { RuntimeContext } from "@mastra/core/di";
 import { mastra } from "./mastra";
 
@@ -142,15 +158,11 @@ const result = await run.start({
   runtimeContext
 });
 
-console.log(JSON.stringify(result, null, 2));
-
 if (result.status === "suspended") {
   const resumedResult = await run.resume({
-    step: 'city-step',
+    step: 'step-1',
     resumeData: { city: "New York" },
     runtimeContext
   });
-
-  console.log(JSON.stringify(resumedResult, null, 2));
 }
 ```

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

@@ -28,144 +28,82 @@ import { Agent } from "@mastra/core/agent";
 
 export const testAgent = new Agent({
   name: "test-agent",
-  description: "Create facts for input city, country and timezone",
-  instructions: `
-You are a helpful and factual assistant.
-
-You will be given a city, country, and timezone. Return exactly one interesting fact about each of the three values.
-
-Your response must follow this exact format:
-
-City Fact: <a short paragraph about the city>
-Country Fact: <a short paragraph about the country>
-Timezone Fact: <a short paragraph about the timezone>
-
-Only return the three facts in plain text, with each label clearly marked. No additional commentary or formatting.
-Ensure all facts are accurate and sourced from reputable references.
-`,
+  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")
 });
 ```
 
 ### Agents As Step
 
-In this example the `cityCoordinatesStep` performs a geocoding lookup using the provided `city`, then returns the resolved `city`, `country`, and `timezone`.
+In this example, `step1` uses the `testAgent` to generate an interesting fact about the country based on a given city.
 
-The `.map` function transforms the object output into a `prompt` string that can be used by the `testAgent`.
+The `.map` method transforms the workflow input into a `prompt` string compatible with the `testAgent`.
 
-The step is composed into the workflow using the sequential `.then()` method, allowing it to receive input from the workflow and return structured output.
+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()`.
 
-```typescript {1,29,42,52} filename="src/mastra/workflows/test-workflow.ts" showLineNumbers copy
-import { testAgent } from "../agents/test-agent";
 
-const cityCoordinatesStep = createStep({
-  id: "city-step",
-  description: "Gets details about a city",
-  inputSchema: z.object({
-    city: z.string()
-  }),
-  outputSchema: z.object({
-    city_name: z.string(),
-    country_name: z.string(),
-    country_timezone: z.string()
-  }),
-  execute: async ({ inputData }) => {
-    const { city } = inputData;
-    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];
-
-    return {
-      city_name: name,
-      country_name: country,
-      country_timezone: timezone
-    };
-  }
-});
+```typescript {3} filename="src/mastra/workflows/test-workflow.ts" showLineNumbers copy
+import { testAgent } from "../agents/test-agent";
 
-const cityFactsStep = createStep(testAgent);
+const step1 = createStep(testAgent);
 
 export const testWorkflow = createWorkflow({
   id: "test-workflow",
   description: 'Test workflow',
   inputSchema: z.object({
-    city: z.string()
+    input: z.string()
   }),
   outputSchema: z.object({
-    outcome: z.string()
+    output: z.string()
   })
 })
-  .then(cityCoordinatesStep)
   .map(({ inputData }) => {
-    const { city_name, country_name, country_timezone } = inputData;
+    const { input } = inputData;
     return {
-      prompt: `
-        Provide facts about the city: ${city_name},
-        country: ${country_name}
-        and timezone: ${country_timezone}
-      `
+      prompt: `Provide facts about the city: ${input}`
     };
   })
-  .then(cityFactsStep)
+  .then(step1)
   .commit();
 ```
 
 ### Agent Generate
 
-In this example, the `cityFactsStep` performs a geocoding lookup using the provided `city`, then builds a prompt combining the resolved `city`, `country`, and `timezone`.
-
-This prompt is passed to the `testAgent`, which generates a plain-text response with one fact for each.
+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 composed into the workflow using the sequential `.then()` method, allowing it to receive input from the workflow and return structured output.
+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,26,46} filename="src/mastra/workflows/test-workflow.ts" showLineNumbers copy
+```typescript {1,18, 29} filename="src/mastra/workflows/test-workflow.ts" showLineNumbers copy
 import { testAgent } from "../agents/test-agent";
 
-const cityFactsStep = createStep({
-  id: "city-facts-step",
-  description: "Returns facts about city, country and timezone from the agent",
+const step1 = createStep({
+  id: "step-1",
+  description: "Create facts for a country based on the city",
   inputSchema: z.object({
-    city: z.string()
+    input: z.string()
   }),
   outputSchema: z.object({
-    outcome: z.string()
+    output: z.string()
   }),
 
   execute: async ({ inputData }) => {
-    const { city } = inputData;
-    const geocodingResponse = await fetch(`https://geocoding-api.open-meteo.com/v1/search?name=${city}`);
-    const geocodingData = await geocodingResponse.json();
+    const { input } = inputData;
 
-    const { name, country, timezone } = geocodingData.results[0];
-
-    const prompt = `
-      Provide facts about the city: ${city_name},
-      country: ${country_name}
-      and timezone: ${country_timezone}
-    `;
+    const  prompt = `Provide facts about the city: ${input}`
 
     const { text } = await testAgent.generate([
       { role: "user", content: prompt }
     ]);
 
     return {
-      outcome: text
+      output: text
     };
   }
 });
 
-export const testWorkflow = createWorkflow({
-  id: "test-workflow",
-  description: 'Test workflow',
-  inputSchema: z.object({
-    city: z.string()
-  }),
-  outputSchema: z.object({
-    outcome: z.string()
-  })
-})
-  .then(cityFactsStep)
+export const testWorkflow = createWorkflow({...})
+  .then(step1)
   .commit();
 ```
 
@@ -182,158 +120,84 @@ import { createTool } from "@mastra/core";
 import { z } from "zod";
 
 export const testTool = createTool({
-  id: "city-tool",
-  description: "Gets coordinates for city",
+  id: "test-tool",
+  description: "Gets country for a city",
   inputSchema: z.object({
-    city: z.string()
+    input: z.string()
   }),
   outputSchema: z.object({
-    city_name: z.string(),
-    country_name: z.string(),
-    country_timezone: z.string()
+    country_name: z.string()
   }),
   execute: async ({ context }) => {
-    const { city } = context;
-    const geocodingResponse = await fetch(`https://geocoding-api.open-meteo.com/v1/search?name=${city}`);
+    const { input } = context;
+    const geocodingResponse = await fetch(`https://geocoding-api.open-meteo.com/v1/search?name=${input}`);
     const geocodingData = await geocodingResponse.json();
 
-    const { name, country, timezone } = geocodingData.results[0];
+    const { country } = geocodingData.results[0];
 
     return {
-      city_name: name,
-      country_name: country,
-      country_timezone: timezone
+      country_name: country
     };
   }
 });
 ```
 
 
-### Tools As Step
-
-In this example, the `cityCoordinatesStep` uses the above example `testTool` which performs a geocoding lookup using the provided `city`, then returns the resolved `city`, `country`, and `timezone`.
+### Tools as Step
 
+In this example, `step1` uses the `testTool`, which performs a geocoding lookup using the provided `city` and returns the resolved `country`.
 
-The `.map` function transforms the object output into a prompt string that can be used by the testAgent.
+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()`.
 
-The step is composed into the workflow using the sequential `.then()` method, allowing it to receive input from the workflow and return structured output.
-
-```typescript {2,4,40,51} filename="src/mastra/workflows/test-workflow.ts" showLineNumbers copy
-import { testAgent } from "../agents/test-agent";
+```typescript {1,3,6} filename="src/mastra/workflows/test-workflow.ts" showLineNumbers copy
 import { testTool } from "../tools/test-tool";
 
-const cityCoordinatesStep = createStep(testTool);
-
-const cityFactsStep = createStep({
-  id: "city-facts-step",
-  description: "Returns facts about city, country and timezone from the agent",
-  inputSchema: z.object({
-    prompt: z.string()
-  }),
-  outputSchema: z.object({
-    outcome: z.string()
-  }),
-
-  execute: async ({ inputData }) => {
-    const { prompt } = inputData;
+const step1 = createStep(testTool);
 
-    const { text } = await testAgent.generate([
-      { role: "user", content: prompt }
-    ]);
-
-    return {
-      outcome: text
-    };
-  }
-});
-
-export const testWorkflow = createWorkflow({
-  id: "test-workflow",
-  description: "Test workflow",
-  inputSchema: z.object({
-    city: z.string()
-  }),
-  outputSchema: z.object({
-    outcome: z.string()
-  })
-})
-  .then(cityCoordinatesStep)
-  .map(({ inputData }) => {
-    const { city_name, country_name, country_timezone } = inputData;
-
-    return {
-      prompt: `
-        Provide facts about the city: ${city_name},
-        country: ${country_name}
-        and timezone: ${country_timezone}
-      `
-    };
-  })
-  .then(cityFactsStep)
+export const testWorkflow = createWorkflow({...})
+  .then(step1)
   .commit();
 ```
 
 ### Tool Execute
 
-In this example, the `cityFactsStep` uses the above example `testTool` which performs a geocoding lookup using the provided `city`, then builds a prompt combining the resolved `city`, `country`, and `timezone`.
-
-This prompt is passed to the `testAgent`, which generates a plain-text response with one fact for each.
+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 step is composed into the workflow using the sequential `.then()` method, allowing it to receive input from the workflow and return structured output.
+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 {4,21,33,52} filename="src/mastra/workflows/test-workflow.ts" showLineNumbers copy
+```typescript {3,20,32} filename="src/mastra/workflows/test-workflow.ts" showLineNumbers copy
 import { RuntimeContext } from "@mastra/core/di";
 
-import { testAgent } from "../agents/test-agent";
 import { testTool } from "../tools/test-tool";
 
 const runtimeContext = new RuntimeContext();
 
-const cityFactsStep = createStep({
-  id: "city-facts-step",
-  description: "Returns facts about city, country and timezone from the agent",
+const step1 = createStep({
+  id: "step-1",
+  description: "Gets country for a city",
   inputSchema: z.object({
-    city: z.string()
+    input: z.string()
   }),
   outputSchema: z.object({
-    outcome: z.string()
+    output: z.string()
   }),
 
   execute: async ({ inputData }) => {
-    const { city } = inputData;
+    const { input } = inputData;
 
-    const { city_name, country_name, country_timezone } = await testTool.execute({
-      context: { city },
+    const { country_name } = await testTool.execute({
+      context: { input },
       runtimeContext
     });
 
-    const prompt = `
-      Provide facts about the city: ${city_name},
-      country: ${country_name}
-      and timezone: ${country_timezone}
-    `;
-
-    const { text } = await testAgent.generate([
-      { role: "user", content: prompt }
-    ]);
-
     return {
-      outcome: text
+      output: country_name
     };
   }
 });
 
-export const testWorkflow = createWorkflow({
-  id: "test-workflow",
-  description: 'Test workflow',
-  inputSchema: z.object({
-    city: z.string()
-  }),
-  outputSchema: z.object({
-    outcome: z.string()
-  })
-})
-  .then(cityFactsStep)
+export const testWorkflow = createWorkflow({...})
+  .then(step1)
   .commit();
 ```
 

package/dist/_tsup-dts-rollup.d.ts

@@ -100,10 +100,13 @@ export declare type DocsInput = z.infer<typeof docsInputSchema>;
 
 export declare const docsInputSchema: z.ZodObject<{
     paths: z.ZodArray<z.ZodString, "many">;
+    queryKeywords: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
 }, "strip", z.ZodTypeAny, {
     paths: string[];
+    queryKeywords?: string[] | undefined;
 }, {
     paths: string[];
+    queryKeywords?: string[] | undefined;
 }>;
 
 export declare const docsTool: {
@@ -111,10 +114,13 @@ export declare const docsTool: {
     description: string;
     parameters: z.ZodObject<{
         paths: z.ZodArray<z.ZodString, "many">;
+        queryKeywords: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
     }, "strip", z.ZodTypeAny, {
         paths: string[];
+        queryKeywords?: string[] | undefined;
     }, {
         paths: string[];
+        queryKeywords?: string[] | undefined;
     }>;
     execute: (args: DocsInput) => Promise<string>;
 };
@@ -123,9 +129,12 @@ export declare type ExamplesInput = z.infer<typeof examplesInputSchema>;
 
 export declare const examplesInputSchema: z.ZodObject<{
     example: z.ZodOptional<z.ZodString>;
+    queryKeywords: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
 }, "strip", z.ZodTypeAny, {
+    queryKeywords?: string[] | undefined;
     example?: string | undefined;
 }, {
+    queryKeywords?: string[] | undefined;
     example?: string | undefined;
 }>;
 
@@ -134,9 +143,12 @@ export declare const examplesTool: {
     description: string;
     parameters: z.ZodObject<{
         example: z.ZodOptional<z.ZodString>;
+        queryKeywords: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
     }, "strip", z.ZodTypeAny, {
+        queryKeywords?: string[] | undefined;
         example?: string | undefined;
     }, {
+        queryKeywords?: string[] | undefined;
         example?: string | undefined;
     }>;
     execute: (args: ExamplesInput) => Promise<string>;
@@ -153,6 +165,8 @@ export declare const getMastraCourseStatus: {
     execute: (_args: Record<string, never>) => Promise<string>;
 };
 
+export declare function getMatchingPaths(path: string, queryKeywords: string[], baseDir: string): Promise<string>;
+
 export declare const log: {
     (...data: any[]): void;
     (message?: any, ...optionalParams: any[]): void;