@mastra/mcp-docs-server 0.0.13 → 0.0.14-alpha.1

package/.docs/organized/code-examples/openapi-spec-writer.md

@@ -0,0 +1,588 @@
+### package.json
+```json
+{
+  "name": "examples-openapi-spec-writer",
+  "type": "module",
+  "private": true,
+  "scripts": {
+    "dev": "next dev --turbopack",
+    "build": "next build",
+    "start": "next start",
+    "lint": "next lint"
+  },
+  "dependencies": {
+    "@ai-sdk/openai": "^1.3.22",
+    "@mastra/core": "latest",
+    "@mastra/firecrawl": "latest",
+    "@mastra/github": "latest",
+    "@mastra/loggers": "latest",
+    "@mastra/rag": "latest",
+    "@radix-ui/react-accordion": "^1.2.3",
+    "@radix-ui/react-dialog": "^1.1.6",
+    "@radix-ui/react-select": "^2.1.6",
+    "@radix-ui/react-slot": "^1.1.2",
+    "class-variance-authority": "^0.7.1",
+    "clsx": "^2.1.1",
+    "lucide-react": "^0.454.0",
+    "next": "15.2.3",
+    "react": "^19.0.0",
+    "react-dom": "^19.0.0",
+    "react-syntax-highlighter": "^15.6.1",
+    "sharp": "^0.33.5",
+    "tailwind-merge": "^2.6.0",
+    "tailwindcss-animate": "^1.0.7",
+    "vaul": "^1.1.2",
+    "zod": "^3.24.3"
+  },
+  "devDependencies": {
+    "@libsql/client": "^0.15.4",
+    "@types/js-yaml": "^4.0.9",
+    "@types/node": "^20.17.24",
+    "@types/react": "^19.0.10",
+    "@types/react-dom": "^19.0.4",
+    "@types/react-syntax-highlighter": "^15.5.13",
+    "eslint": "^8.57.1",
+    "eslint-config-next": "15.0.2",
+    "postcss": "^8.5.3",
+    "tailwindcss": "^3.4.17",
+    "typescript": "^5.8.2"
+  },
+  "peerDependencies": {
+    "react": ">= 0.14.0 || 19",
+    "react-dom": ">= 0.14.0 || 19"
+  },
+  "version": "0.0.1",
+  "pnpm": {
+    "overrides": {
+      "@mastra/core": "link:../../packages/core",
+      "@mastra/firecrawl": "link:../../integrations/firecrawl",
+      "@mastra/github": "link:../../integrations/github",
+      "@mastra/loggers": "link:../../packages/loggers",
+      "@mastra/rag": "link:../../packages/rag"
+    }
+  },
+  "packageManager": "pnpm@10.10.0+sha512.d615db246fe70f25dcfea6d8d73dee782ce23e2245e3c4f6f888249fb568149318637dca73c2c5c8ef2a4ca0d5657fb9567188bfab47f566d1ee6ce987815c39"
+}
+
+```
+
+### lib/hooks/useCopyToClipboard.ts
+```typescript
+"use client";
+
+import * as React from "react";
+
+export interface useCopyToClipboardProps {
+  timeout?: number;
+}
+
+export function useCopyToClipboard({
+  timeout = 2000,
+}: useCopyToClipboardProps) {
+  const [isCopied, setIsCopied] = React.useState<Boolean>(false);
+
+  const copyToClipboard = (value: string) => {
+    if (typeof window === "undefined" || !navigator.clipboard?.writeText) {
+      return;
+    }
+
+    if (!value) {
+      return;
+    }
+
+    navigator.clipboard.writeText(value).then(() => {
+      setIsCopied(true);
+
+      setTimeout(() => {
+        setIsCopied(false);
+      }, timeout);
+    });
+  };
+
+  return { isCopied, copyToClipboard };
+}
+
+```
+
+### lib/utils.ts
+```typescript
+import { clsx, type ClassValue } from "clsx";
+import { twMerge } from "tailwind-merge";
+
+export function cn(...inputs: ClassValue[]) {
+  return twMerge(clsx(inputs));
+}
+
+```
+
+### mastra/agents/index.ts
+```typescript
+import { Agent } from "@mastra/core/agent";
+import { openai } from "@ai-sdk/openai";
+
+export const agentOne = new Agent({
+  name: "openapi-spec-gen-agent",
+  instructions:
+    "You are an expert Open API spec writer. You can take markdown documentation and extract all the information you can to generate an amazing Open API spec. You are also able to merge multiple fragmented Open API specs from the same source into a single compliant spec.",
+  model: openai("gpt-3.5-turbo"),
+});
+
+```
+
+### mastra/index.ts
+```typescript
+import { createLogger } from "@mastra/core/logger";
+import { Mastra } from "@mastra/core/mastra";
+import { UpstashTransport } from "@mastra/loggers/upstash";
+import { agentOne } from "./agents";
+import { makePRToMastraWorkflow, openApiSpecGenWorkflow } from "./workflows";
+
+export const mastra = new Mastra({
+  logger: createLogger({
+    name: "OPENAPI_SPEC_WRITER",
+    level: "debug",
+    transports: {
+      upstash: new UpstashTransport({
+        upstashToken: process.env.UPSTASH_API_KEY!,
+        upstashUrl: process.env.UPSTASH_URL!,
+      }),
+    },
+  }),
+  agents: { "openapi-spec-gen-agent": agentOne },
+  telemetry: {
+    serviceName: "mastra-vnext",
+    sampling: {
+      type: "always_on",
+    },
+    enabled: true,
+    export: {
+      type: "otlp",
+    },
+  },
+  workflows: {
+    openApiSpecGenWorkflow,
+    makePRToMastraWorkflow,
+  },
+});
+
+```
+
+### mastra/integrations/index.ts
+```typescript
+import { GithubIntegration } from "@mastra/github";
+import { FirecrawlIntegration } from "@mastra/firecrawl";
+
+export const github = new GithubIntegration({
+  config: {
+    PERSONAL_ACCESS_TOKEN: process.env.GITHUB_API_KEY!,
+  },
+})
+
+export const firecrawl = new FirecrawlIntegration({
+  config: {
+    API_KEY: process.env.FIRECRAWL_API_KEY!,
+  },
+})
+
+```
+
+### mastra/tools/index.ts
+```typescript
+import { createTool } from "@mastra/core/tools";
+import { z } from "zod";
+import { firecrawl, github } from "../integrations";
+import { randomUUID } from "crypto";
+
+export const siteCrawlTool = createTool({
+  id: "site-crawl",
+  label: "Site Crawl",
+  inputSchema: z.object({
+    url: z.string(),
+    pathRegex: z.string(),
+    limit: z.number(),
+  }),
+  description: "Crawl a website and extract the markdown content",
+  outputSchema: z.object({
+    success: z.boolean(),
+    crawlData: z.array(
+      z.object({
+        markdown: z.string(),
+        metadata: z.object({
+          sourceURL: z.string(),
+        }),
+      })
+    ),
+    entityType: z.string(),
+  }),
+  execute: async ({ context }) => {
+    const client = await firecrawl.getApiClient();
+
+    console.log("Starting crawl", context.url);
+
+    const res = await client.crawlUrls({
+      body: {
+        url: context.url,
+        limit: context.limit || 3,
+        includePaths: [context.pathRegex],
+        scrapeOptions: {
+          formats: ["markdown"],
+          includeTags: ["main"],
+          excludeTags: [
+            "img",
+            "footer",
+            "nav",
+            "header",
+            "#navbar",
+            ".table-of-contents-content",
+          ],
+          onlyMainContent: true,
+        },
+      },
+    });
+
+    if (res.error) {
+      console.error({ error: JSON.stringify(res.error, null, 2) });
+      throw new Error(res.error.error);
+    }
+
+    const crawlId = res.data?.id;
+
+    let crawl = await client.getCrawlStatus({
+      path: {
+        id: crawlId!,
+      },
+    });
+
+    while (crawl.data?.status === "scraping") {
+      await new Promise((resolve) => setTimeout(resolve, 5000));
+
+      crawl = await client.getCrawlStatus({
+        path: {
+          id: crawlId!,
+        },
+      });
+    }
+
+    const entityType = `CRAWL_${context.url}`;
+
+    return {
+      success: true,
+      crawlData: (crawl?.data?.data || []).map((item) => ({
+        markdown: item.markdown || "",
+        metadata: {
+          sourceURL: item?.metadata?.sourceURL || "",
+          ...item.metadata,
+        },
+      })),
+      entityType: entityType,
+    };
+  },
+});
+
+export const generateSpecTool = createTool({
+  id: "generate-spec",
+  label: "Generate Spec",
+  inputSchema: z.object({
+    mastra_entity_type: z.string(),
+  }),
+  outputSchema: z.object({
+    success: z.boolean(),
+    mergedSpec: z.string(),
+  }),
+  description: "Generate a spec from a website",
+  execute: async ({ context, runId, mastra }) => {
+    const crawledData =
+      context?.steps?.["site-crawl"]?.status === "success"
+        ? context?.steps?.["site-crawl"]?.output
+            ?.crawlData
+        : [];
+
+    if (!crawledData) {
+      throw new Error("No crawled data found");
+    }
+
+    const agent = mastra?.agents?.["openapi-spec-gen-agent"];
+
+    if (!agent) {
+      throw new Error("Agent not found");
+    }
+
+    const openapiResponses = [];
+    let mergedSpecAnswer = "";
+
+    for (const d of crawledData) {
+      const data = await agent.generate(
+        `I wrote another page of docs, turn this into an Open API spec: ${d.data.markdown}`,
+        { runId }
+      );
+
+      openapiResponses.push(data.text);
+    }
+
+    console.log(
+      "inspect this, openapiResponses used to come back in structured output yaml"
+    );
+
+    const mergedSpec = await agent?.generate(
+      `I have generated the following Open API specs: ${openapiResponses
+        .map((r) => r)
+        .join("\n\n")} - merge them into a single spec,
+          `,
+      { runId }
+    );
+
+    mergedSpecAnswer = mergedSpec.text
+      .replace(/```yaml/g, "")
+      .replace(/```/g, "");
+
+    console.log(
+      "MERGED SPEC ==================",
+      JSON.stringify(mergedSpecAnswer, null, 2)
+    );
+
+    return { success: true, mergedSpec: mergedSpecAnswer };
+  },
+});
+
+export const addToGitHubTool = createTool({
+  id: "add-to-github",
+  label: "Add to Git",
+  inputSchema: z.object({
+    yaml: z.string(),
+    integration_name: z.string(),
+    owner: z.string(),
+    repo: z.string(),
+    site_url: z.string(),
+  }),
+  outputSchema: z.object({
+    success: z.boolean(),
+    pr_url: z.string().optional(),
+  }),
+  description: "Commit the spec to GitHub",
+  execute: async ({ context, runId, mastra }) => {
+    const client = await github.getApiClient();
+
+    const content = context.yaml;
+    const integrationName = context.integration_name.toLowerCase();
+
+    console.log("Writing to Github for", context.integration_name);
+    const agent = mastra?.agents?.["openapi-spec-gen-agent"];
+
+    const d = await agent?.generate(
+      `Can you take this text blob and format it into proper YAML? ${content}`,
+      { runId }
+    );
+
+    if (!d) {
+      console.error("Agent failed to process the text blob");
+      return { success: false };
+    }
+
+    if (Array.isArray(d.toolCalls)) {
+      const answer = d.text;
+      const strippedYaml = answer.replace(/```yaml/g, "").replace(/```/g, "");
+
+      const base64Content = Buffer.from(strippedYaml).toString("base64");
+
+      const reposPathMap = {
+        [`integrations-next/${integrationName}/openapi.yaml`]: base64Content,
+        [`integrations-next/${integrationName}/README.md`]: Buffer.from(
+          `# ${integrationName}\n\nThis repo contains the Open API spec for the ${integrationName} integration`
+        ).toString("base64"),
+      };
+
+      const mainRef = await client.gitGetRef({
+        path: {
+          ref: "heads/main",
+          owner: context.owner,
+          repo: context.repo,
+        },
+      });
+
+      console.log({ context, mainRef });
+
+      const mainSha = mainRef.data?.object?.sha;
+
+      console.log("Main SHA", mainSha);
+
+      const branchName = `open-api-spec-writer/${integrationName}-${randomUUID()}`;
+
+      console.log("Branch name", branchName);
+
+      if (mainSha) {
+        await client.gitCreateRef({
+          body: {
+            ref: `refs/heads/${branchName}`,
+            sha: mainSha,
+          },
+          path: {
+            owner: context.owner,
+            repo: context.repo,
+          },
+        });
+
+        for (const [path, content] of Object.entries(reposPathMap)) {
+          console.log({ path, content });
+          await client.reposCreateOrUpdateFileContents({
+            body: {
+              message: `Add open api spec from ${context.site_url}`,
+              content,
+              branch: branchName,
+            },
+            path: {
+              owner: context.owner,
+              repo: context.repo,
+              path,
+            },
+          });
+        }
+
+        const pullData = await client.pullsCreate({
+          body: {
+            title: `Add open api spec from ${context.site_url} for ${integrationName}`,
+            head: branchName,
+            base: "main",
+          },
+          path: {
+            owner: context.owner,
+            repo: context.repo,
+          },
+        });
+
+        return { success: true, pr_url: pullData.data?.html_url };
+      }
+    }
+
+    return { success: true };
+  },
+});
+
+```
+
+### mastra/workflows/index.ts
+```typescript
+import { Workflow, Step } from "@mastra/core/workflows";
+import { z } from "zod";
+import { addToGitHubTool, generateSpecTool, siteCrawlTool } from "../tools";
+// import { MDocument } from "@mastra/rag";
+
+const syncStep = new Step({
+  id: "site-crawl-sync-step",
+  outputSchema: z.object({
+    success: z.boolean(),
+    crawlData: z.array(
+      z.object({
+        markdown: z.string(),
+        metadata: z.object({
+          sourceURL: z.string(),
+        }),
+      })
+    ),
+    entityType: z.string(),
+  }),
+  description:
+    "Crawl a website and extract the markdown content and sync it to the database",
+  execute: async ({ context, runId, suspend }) => {
+    const toolResult = await siteCrawlTool.execute({
+      context: context?.triggerData,
+      runId,
+      suspend,
+    });
+
+    const { crawlData, entityType } = toolResult;
+
+    if (!crawlData) {
+      return {
+        success: false,
+        crawlData: [],
+        entityType: "",
+      };
+    }
+
+    // const recordsToPersist = await Promise.all(
+    //   crawlData?.flatMap(async ({ markdown, metadata }) => {
+    //     const doc = MDocument.fromMarkdown(markdown, metadata);
+
+    //     await doc.chunk({
+    //       strategy: "markdown",
+    //       maxSize: 8190,
+    //     });
+
+    //     const chunks = doc.getDocs();
+
+    //     return chunks.map((c, i) => {
+    //       return {
+    //         externalId: `${c.metadata?.sourceURL}_chunk_${i}`,
+    //         data: { markdown: c.text },
+    //       };
+    //     });
+    //   })
+    // );
+
+    return {
+      success: true,
+      crawlData,
+      entityType,
+    };
+  },
+});
+
+export const openApiSpecGenWorkflow = new Workflow({
+  name: "openApiSpecGenWorkflow",
+  triggerSchema: z.object({
+    url: z.string().describe("The URL of the website to crawl"),
+    pathRegex: z.string().optional().describe("The regex to match the paths"),
+  }),
+})
+  .step(syncStep, {
+    variables: {
+      pathRegex: {
+        path: "pathRegex",
+        step: "trigger",
+      },
+      url: {
+        path: "url",
+        step: "trigger",
+      },
+    },
+  })
+  .then(generateSpecTool, {
+    variables: {
+      mastra_entity_type: {
+        step: syncStep,
+        path: "entityType",
+      },
+    },
+  });
+
+openApiSpecGenWorkflow.commit();
+
+export const makePRToMastraWorkflow = new Workflow({
+  name: "makePRToMastra",
+  triggerSchema: z.object({
+    integration_name: z.string(),
+    site_url: z.string().describe("The URL of the website to crawl"),
+    owner: z.string().describe("Owner of the repo"),
+    repo: z.string().describe("Name of the repo"),
+    yaml: z.string().describe("The Open API spec in YAML format"),
+  }),
+}).step(addToGitHubTool, {
+  variables: {
+    yaml: {
+      path: "yaml",
+      step: "trigger",
+    },
+    integration_name: {
+      path: "integration_name",
+      step: "trigger",
+    },
+    site_url: {
+      path: "site_url",
+      step: "trigger",
+    },
+  },
+});
+
+makePRToMastraWorkflow.commit();
+
+```

package/.docs/organized/code-examples/quick-start.md

@@ -19,7 +19,7 @@
     "zod": "^3.24.3"
   },
   "dependencies": {
-    "@ai-sdk/anthropic": "^1.1.15",
+    "@ai-sdk/anthropic": "^1.2.11",
     "@ai-sdk/groq": "latest",
     "@ai-sdk/openai": "latest",
     "@mastra/core": "latest",

package/.docs/raw/agents/dynamic-agents.mdx

@@ -0,0 +1,47 @@
+---
+
+title: Dynamic Agents | Agents | Mastra Docs
+description: Dynamically configure your agent's instruction, model and tools using runtime context.
+
+# Dynamic Agents
+
+Dynamic agents use [runtime context](./runtime-variables), like user IDs and other important parameters, to adjust their settings in real-time. This means they can change the model they use, update their instructions, and select different tools as needed. By using this context, agents can better respond to each user's needs. They can also call any API to gather more information, which helps improve what the agents can do.
+
+## Key Benefits
+
+- **Flexibility**: Adjust agent behavior dynamically without altering the core code.
+- **Efficiency**: Consolidate multiple agents into a single dynamic agent.
+- **Scalability**: Easily scale agent capabilities by modifying runtime context.
+
+### Example Configuration
+
+Here's an example of how to configure a dynamic agent with model, instructions, and tools:
+
+```typescript
+const dynamicAgent = new Agent({
+  name: "Master Chef Agent",
+  instructions: async ({ runtimeContext }) => {
+    // Fetch user preferences from API using user ID from runtime context
+    const userId = runtimeContext.get("userId");
+    const userPreferences = await fetchUserPreferences(userId);
+
+    return `You are a master chef specializing in personalized recipes. 
+    The current user (${userId}) has the following dietary preferences:
+    - Allergies: ${userPreferences.allergies.join(", ") || "None"}
+    - Preferred cuisines: ${userPreferences.cuisines.join(", ")}
+    - Dietary restrictions: ${userPreferences.restrictions.join(", ") || "None"}
+    
+    Tailor your cooking advice and recipes to match these preferences.`;
+  },
+  model: ({ runtimeContext }) => openai("gpt-4o-mini"),
+  tools: ({ runtimeContext }) => {
+    return {
+      recipeDatabase,
+      ingredientSubstitutions,
+      nutritionalCalculator,
+    };
+  },
+});
+```
+
+In this example, the agent's instructions, model, and tools are configured using the runtime context, allowing for a highly adaptable and responsive agent.

package/.docs/raw/agents/using-tools-and-mcp.mdx

@@ -107,3 +107,22 @@ const agent = new Agent({
 ```
 
 For more details on configuring `MCPClient` and the difference between static and dynamic MCP server configurations, see the [MCP Overview](/docs/tools-mcp/mcp-overview).
+
+## Accessing MCP Resources
+
+In addition to tools, MCP servers can also expose resources - data or content that can be retrieved and used in your application.
+
+```typescript filename="src/mastra/resources.ts" {3-8}
+import { mcp } from "./mcp";
+
+// Get resources from all connected MCP servers
+const resources = await mcp.getResources();
+
+// Access resources from a specific server
+if (resources.filesystem) {
+  const resource = resources.filesystem.find(r => r.uri === 'filesystem://Downloads');
+  console.log(`Resource: ${resource?.name}`);
+}
+```
+
+Each resource has a URI, name, description, and MIME type. The `getResources()` method handles errors gracefully - if a server fails or doesn't support resources, it will be omitted from the results.