@mastra/mcp-docs-server 0.0.1-alpha.1

package/.docs/organized/code-examples/bird-checker-with-nextjs-and-eval.md

@@ -0,0 +1,360 @@
+### package.json
+```json
+{
+  "name": "examples-bird-checker-with-nextjs-and-eval",
+  "type": "module",
+  "private": true,
+  "scripts": {
+    "dev": "next dev --turbopack",
+    "build": "next build",
+    "start": "next start",
+    "lint": "next lint",
+    "mastra:init": "pnpm dlx mastra init",
+    "mastra:dev": "pnpm dlx mastra dev",
+    "braintrust:eval": "npx braintrust eval src/lib/evals"
+  },
+  "dependencies": {
+    "@ai-sdk/anthropic": "latest",
+    "@mastra/core": "workspace:*",
+    "braintrust": "^0.0.168",
+    "class-variance-authority": "^0.7.1",
+    "clsx": "^2.1.1",
+    "lucide-react": "^0.454.0",
+    "next": "15.0.2",
+    "next-themes": "^0.4.5",
+    "nuqs": "^2.4.1",
+    "react": "19.0.0-rc-02c0e824-20241028",
+    "react-dom": "19.0.0-rc-02c0e824-20241028",
+    "sonner": "^1.7.4",
+    "tailwind-merge": "^2.6.0",
+    "tailwindcss-animate": "^1.0.7",
+    "zod": "^3.24.2"
+  },
+  "devDependencies": {
+    "@types/node": "^20.17.24",
+    "@types/react": "^18.3.18",
+    "@types/react-dom": "^18.3.5",
+    "eslint": "^8.57.1",
+    "eslint-config-next": "15.0.2",
+    "postcss": "^8.5.3",
+    "tailwindcss": "^3.4.17",
+    "typescript": "^5.8.2"
+  },
+  "version": "0.0.1"
+}
+
+```
+
+### lib/evals/data.ts
+```typescript
+export const IMAGES = {
+  notBird: {
+    bird: false,
+    species: "Panthera leo",
+    image:
+      "https://images.unsplash.com/photo-1470848051974-964b789cb6fa?crop=entropy&cs=tinysrgb&fit=max&fm=jpg&ixid=M3w2NzI1Mzd8MHwxfHNlYXJjaHwzNXx8d2lsZGxpZmV8ZW58MHx8fHwxNzMyMTIwMTMyfDA&ixlib=rb-4.0.3&q=80&w=1080",
+  },
+  isBird: {
+    bird: true,
+    species: "Ardea herodias",
+    image:
+      "https://images.unsplash.com/photo-1730510011925-e064a259f722?crop=entropy&cs=tinysrgb&fit=max&fm=jpg&ixid=M3w2NzI1Mzd8MHwxfHNlYXJjaHwxN3x8ZmVhdGhlcnN8ZW58MHx8Mnx8MTczMTQyMjI5MXww&ixlib=rb-4.0.3&q=80&w=1080",
+  },
+};
+
+```
+
+### lib/evals/index.eval.ts
+```typescript
+import { Eval } from "braintrust";
+import { IMAGES } from "./data";
+import { BirdResponse, promptClaude } from "../mastra/actions";
+
+const containsScorer = ({
+  output,
+  expected,
+}: {
+  output: BirdResponse;
+  expected: Omit<BirdResponse, "location">;
+}) => {
+  const birdDataCorrect = output?.bird === expected?.bird;
+
+  const speciesDataCorrect = output?.species
+    ?.toLocaleLowerCase()
+    ?.includes(expected?.species?.toLocaleLowerCase());
+
+  return {
+    name: "containsScorer",
+    score: birdDataCorrect && speciesDataCorrect ? 1 : 0,
+  };
+};
+
+Eval("Is a bird", {
+  data: () => {
+    return [
+      {
+        input: IMAGES.isBird.image,
+        expected: IMAGES.isBird,
+      },
+      {
+        input: IMAGES.notBird.image,
+        expected: IMAGES.notBird,
+      },
+    ];
+  },
+  task: async (input) => {
+    const claudeResponse = await promptClaude({ imageUrl: input });
+    if (!claudeResponse.ok) {
+      return { bird: false, location: "", species: "" };
+    }
+
+    return claudeResponse.data;
+  },
+  scores: [containsScorer],
+});
+
+```
+
+### lib/mastra/actions.ts
+```typescript
+"use server";
+
+import { mastra } from "@/mastra";
+import { getRandomImage, Image, ImageResponse } from "./system-tools";
+import { z } from "zod";
+
+export type ImageQuery = "wildlife" | "feathers" | "flying" | "birds";
+
+export type BirdResponse = {
+  bird: boolean;
+  species: string;
+  location: string;
+};
+
+export const getImage = async ({
+  query,
+}: {
+  query: ImageQuery;
+}): Promise<ImageResponse<Image, string>> => {
+  console.log("get image ============", "got here");
+
+  const response = await getRandomImage({
+    query,
+  });
+
+  return response;
+};
+
+export const promptClaude = async ({
+  imageUrl,
+}: {
+  imageUrl: string;
+}): Promise<ImageResponse<BirdResponse, string>> => {
+  try {
+    const birdAgent = mastra.getAgent("birdAgent");
+
+    console.log("calling bird checker agent");
+
+    const response = await birdAgent.generate(
+      [
+        {
+          role: "user",
+          content: [
+            {
+              type: "image",
+              image: imageUrl,
+            },
+            {
+              type: "text",
+              text: "view this image and let me know if it's a bird or not, and the scientific name of the bird without any explanation. Also summarize the location for this picture in one or two short sentences understandable by a high school student",
+            },
+          ],
+        },
+      ],
+      {
+        output: z.object({
+          bird: z.boolean(),
+          species: z.string(),
+          location: z.string(),
+        }),
+      },
+    );
+
+    const { object } = response || {};
+
+    console.log("prompt claude response====", JSON.stringify(object, null, 2));
+
+    return { ok: true, data: object as BirdResponse };
+  } catch (err) {
+    console.error("Error prompting claude:", err);
+    return { ok: false, error: "Could not fetch image metadata" };
+  }
+};
+
+```
+
+### lib/mastra/system-tools.ts
+```typescript
+export type Image = {
+  alt_description: string;
+  urls: {
+    regular: string;
+    raw: string;
+  };
+  user: {
+    first_name: string;
+    links: {
+      html: string;
+    };
+  };
+};
+
+export type ImageResponse<T, K> =
+  | {
+      ok: true;
+      data: T;
+    }
+  | {
+      ok: false;
+      error: K;
+    };
+
+export type ImageQuery = "wildlife" | "feathers" | "flying" | "birds";
+
+// Executor functions
+export const getRandomImage = async ({
+  query,
+}: {
+  query: ImageQuery;
+}): Promise<ImageResponse<Image, string>> => {
+  const page = Math.floor(Math.random() * 20);
+  const order_by = Math.random() < 0.5 ? "relevant" : "latest";
+  try {
+    const res = await fetch(
+      `https://api.unsplash.com/search/photos?query=${query}&page=${page}&order_by=${order_by}`,
+      {
+        method: "GET",
+        headers: {
+          Authorization: `Client-ID ${process.env.NEXT_PUBLIC_UNSPLASH_ACCESS_KEY}`,
+          "Accept-Version": "v1",
+        },
+        cache: "no-store",
+      },
+    );
+
+    console.log("res in get_random_image api executor===", res);
+
+    if (!res.ok) {
+      return {
+        ok: false,
+        error: "Failed to fetch image",
+      };
+    }
+
+    const data = (await res.json()) as {
+      results: Array<Image>;
+    };
+    const randomNo = Math.floor(Math.random() * data.results.length);
+
+    return {
+      ok: true,
+      data: data.results[randomNo] as Image,
+    };
+  } catch (err) {
+    console.log("Error in get_random_image api executor===", err);
+    return {
+      ok: false,
+      error: "Error fetching image",
+    };
+  }
+};
+
+```
+
+### lib/utils.ts
+```typescript
+import { clsx, type ClassValue } from "clsx";
+import { twMerge } from "tailwind-merge";
+
+export function cn(...inputs: ClassValue[]) {
+  return twMerge(clsx(inputs));
+}
+
+export type BirdObj = {
+  bird: string;
+  location: string;
+  species: string;
+};
+
+export function getObjectFromString(text: string): BirdObj {
+  // First approach: using match()
+  const regex =
+    /(?<=bird:).*?(?=,|\n)|(?<=location:).*?(?=,|\n)|(?<=species:).*(?=\n|})/g;
+  const matches = text.match(regex);
+
+  if (!matches) {
+    return {
+      bird: "no",
+      location: text,
+      species: "",
+    };
+  }
+
+  const [bird, location, species] = matches;
+  console.log("Bird:", bird);
+  console.log("Location:", location);
+  console.log("Species:", species);
+
+  return {
+    bird: bird?.trim(),
+    location: location?.trim(),
+    species: species?.split("}")?.join("")?.trim(),
+  };
+}
+
+```
+
+### mastra/agents/index.ts
+```typescript
+import { anthropic } from "@ai-sdk/anthropic";
+import { Agent } from "@mastra/core/agent";
+
+export const birdAgent = new Agent({
+  name: "birdAgent",
+  instructions:
+    "You can view an image and figure out if it is a bird or not. You can also figure out the species of the bird and where the picture was taken.",
+  model: anthropic("claude-3-haiku-20240307"),
+});
+
+```
+
+### mastra/index.ts
+```typescript
+import { Mastra } from "@mastra/core";
+
+import { birdAgent } from "./agents";
+
+export const mastra = new Mastra({
+  agents: { birdAgent },
+});
+
+```
+
+### mastra/tools/index.ts
+```typescript
+import { getRandomImage } from "@/lib/mastra/system-tools";
+import { createTool } from "@mastra/core/tools";
+import { z } from "zod";
+
+export const getRandomImageTool = createTool({
+  id: "Get a random image from unsplash",
+  description: "Gets a random image from unsplash based on the selected option",
+  inputSchema: z.object({
+    query: z.enum(["wildlife", "feathers", "flying", "birds"]),
+  }),
+  execute: async ({ context }) => {
+    return getRandomImage(context);
+  },
+});
+
+```

package/.docs/organized/code-examples/bird-checker-with-nextjs.md

@@ -0,0 +1,250 @@
+### package.json
+```json
+{
+  "name": "examples-bird-checker-with-nextjs",
+  "type": "module",
+  "private": true,
+  "version": "0.0.1",
+  "scripts": {
+    "dev": "next dev --turbopack",
+    "build": "next build",
+    "start": "next start",
+    "lint": "next lint"
+  },
+  "dependencies": {
+    "@ai-sdk/anthropic": "latest",
+    "@mastra/core": "workspace:*",
+    "class-variance-authority": "^0.7.1",
+    "clsx": "^2.1.1",
+    "lucide-react": "^0.454.0",
+    "next": "15.0.2",
+    "next-themes": "^0.4.5",
+    "nuqs": "^2.4.1",
+    "react": "19.0.0-rc-02c0e824-20241028",
+    "react-dom": "19.0.0-rc-02c0e824-20241028",
+    "sonner": "^1.7.4",
+    "tailwind-merge": "^2.6.0",
+    "tailwindcss-animate": "^1.0.7",
+    "zod": "^3.24.2"
+  },
+  "devDependencies": {
+    "@types/node": "^20.17.24",
+    "@types/react": "^19.0.10",
+    "@types/react-dom": "^19.0.4",
+    "eslint": "^8.57.1",
+    "eslint-config-next": "15.0.2",
+    "postcss": "^8.5.3",
+    "tailwindcss": "^3.4.17",
+    "typescript": "^5.8.2"
+  }
+}
+
+```
+
+### lib/mastra/actions.ts
+```typescript
+"use server";
+
+import { mastra } from "@/mastra";
+import { getRandomImage, Image, ImageResponse } from "./system-tools";
+import { z } from "zod";
+
+export type ImageQuery = "wildlife" | "feathers" | "flying" | "birds";
+
+export type BirdResponse = {
+  bird: boolean;
+  species: string;
+  location: string;
+};
+
+export const getImage = async ({
+  query,
+}: {
+  query: ImageQuery;
+}): Promise<ImageResponse<Image, string>> => {
+  console.log("get image ============", "got here");
+  const response = await getRandomImage({ query });
+
+  return response as ImageResponse<Image, string>;
+};
+
+export const promptClaude = async ({
+  imageUrl,
+}: {
+  imageUrl: string;
+}): Promise<ImageResponse<BirdResponse, string>> => {
+  try {
+    const birdAgent = mastra.getAgent("birdAgent");
+
+    console.log("calling bird checker agent");
+
+    const response = await birdAgent.generate(
+      [
+        {
+          role: "user",
+          content: [
+            {
+              type: "image",
+              image: imageUrl,
+            },
+            {
+              type: "text",
+              text: "view this image and let me know if it's a bird or not, and the scientific name of the bird without any explanation. Also summarize the location for this picture in one or two short sentences understandable by a high school student",
+            },
+          ],
+        },
+      ],
+      {
+        output: z.object({
+          bird: z.boolean(),
+          species: z.string(),
+          location: z.string(),
+        }),
+      },
+    );
+
+    const { object } = response;
+
+    console.log("prompt claude response====", JSON.stringify(object, null, 2));
+
+    return { ok: true, data: object as BirdResponse };
+  } catch (err) {
+    console.error("Error prompting claude:", err);
+    return { ok: false, error: "Could not fetch image metadata" };
+  }
+};
+
+```
+
+### lib/mastra/system-tools.ts
+```typescript
+export type Image = {
+  alt_description: string;
+  urls: {
+    regular: string;
+    raw: string;
+  };
+  user: {
+    first_name: string;
+    links: {
+      html: string;
+    };
+  };
+};
+
+export type ImageResponse<T, K> =
+  | {
+      ok: true;
+      data: T;
+    }
+  | {
+      ok: false;
+      error: K;
+    };
+
+export type ImageQuery = "wildlife" | "feathers" | "flying" | "birds";
+
+export const getRandomImage = async ({
+  query,
+}: {
+  query: ImageQuery;
+}): Promise<ImageResponse<Image, string>> => {
+  const page = Math.floor(Math.random() * 20);
+  const order_by = Math.random() < 0.5 ? "relevant" : "latest";
+  try {
+    const res = await fetch(
+      `https://api.unsplash.com/search/photos?query=${query}&page=${page}&order_by=${order_by}`,
+      {
+        method: "GET",
+        headers: {
+          Authorization: `Client-ID ${process.env.NEXT_PUBLIC_UNSPLASH_ACCESS_KEY}`,
+          "Accept-Version": "v1",
+        },
+        cache: "no-store",
+      },
+    );
+
+    console.log("res in get_random_image api executor===", res);
+
+    if (!res.ok) {
+      return {
+        ok: false,
+        error: "Failed to fetch image",
+      };
+    }
+
+    const data = (await res.json()) as {
+      results: Array<Image>;
+    };
+    const randomNo = Math.floor(Math.random() * data.results.length);
+    console.log("data ====", JSON.stringify(data.results[randomNo], null, 2));
+
+    return {
+      ok: true,
+      data: data.results[randomNo] as Image,
+    };
+  } catch (err) {
+    console.log("Error in get_random_image api executor===", err);
+    return {
+      ok: false,
+      error: "Error fetching image",
+    };
+  }
+};
+
+```
+
+### 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 { anthropic } from "@ai-sdk/anthropic";
+import { Agent } from "@mastra/core/agent";
+
+export const birdAgent = new Agent({
+  name: "Bird checker",
+  instructions:
+    "You can view an image and figure out if it is a bird or not. You can also figure out the species of the bird and where the picture was taken.",
+  model: anthropic("claude-3-haiku-20240307"),
+});
+
+```
+
+### mastra/index.ts
+```typescript
+import { Mastra } from "@mastra/core";
+import { birdAgent } from "./agents";
+
+export const mastra = new Mastra({
+  agents: { birdAgent },
+});
+
+```
+
+### mastra/tools/index.ts
+```typescript
+import { getRandomImage } from "@/lib/mastra/system-tools";
+import { createTool } from "@mastra/core/tools";
+import { z } from "zod";
+
+export const getRandomImageTool = createTool({
+  id: "Get a random image from unsplash",
+  description: "Gets a random image from unsplash based on the selected option",
+  inputSchema: z.object({
+    query: z.enum(["wildlife", "feathers", "flying", "birds"]),
+  }),
+  execute: async ({ context }) => {
+    return getRandomImage(context);
+  },
+});
+
+```

package/.docs/organized/code-examples/crypto-chatbot.md

@@ -0,0 +1,96 @@
+### package.json
+```json
+{
+  "name": "examples-crypto-chatbot",
+  "type": "module",
+  "private": true,
+  "scripts": {
+    "dev": "next dev --turbo",
+    "build": "tsx db/migrate && next build",
+    "start": "next start",
+    "lint": "next lint",
+    "db:generate": "drizzle-kit generate",
+    "db:migrate": "npx tsx ./db/migrate.ts"
+  },
+  "dependencies": {
+    "@ai-sdk/openai": "latest",
+    "@ai-sdk/react": "^1.1.21",
+    "@mastra/core": "workspace:^",
+    "@mastra/memory": "workspace:^",
+    "@mastra/pg": "workspace:^",
+    "@next/env": "^15.2.2",
+    "@radix-ui/react-alert-dialog": "^1.1.6",
+    "@radix-ui/react-dialog": "^1.1.6",
+    "@radix-ui/react-dropdown-menu": "^2.1.6",
+    "@radix-ui/react-icons": "^1.3.2",
+    "@radix-ui/react-label": "^2.1.2",
+    "@radix-ui/react-select": "^2.1.6",
+    "@radix-ui/react-separator": "^1.1.2",
+    "@radix-ui/react-slot": "^1.1.2",
+    "@radix-ui/react-tooltip": "^1.1.8",
+    "@radix-ui/react-visually-hidden": "^1.1.2",
+    "@vercel/analytics": "^1.5.0",
+    "@vercel/blob": "^0.24.1",
+    "@vercel/postgres": "^0.10.0",
+    "ai": "latest",
+    "bcrypt-ts": "^5.0.3",
+    "class-variance-authority": "^0.7.1",
+    "classnames": "^2.5.1",
+    "clsx": "^2.1.1",
+    "date-fns": "^4.1.0",
+    "diff-match-patch": "^1.0.5",
+    "dotenv": "^16.4.7",
+    "drizzle-orm": "^0.37.0",
+    "framer-motion": "^11.18.2",
+    "geist": "^1.3.1",
+    "lucide-react": "^0.446.0",
+    "next": "15.0.3-canary.2",
+    "next-auth": "5.0.0-beta.25",
+    "next-themes": "^0.3.0",
+    "orderedmap": "^2.1.1",
+    "pg": "^8.13.3",
+    "postgres": "^3.4.5",
+    "prosemirror-example-setup": "^1.2.3",
+    "prosemirror-inputrules": "^1.4.0",
+    "prosemirror-markdown": "^1.13.1",
+    "prosemirror-model": "^1.24.1",
+    "prosemirror-schema-basic": "^1.2.3",
+    "prosemirror-schema-list": "^1.5.1",
+    "prosemirror-state": "^1.4.3",
+    "prosemirror-view": "^1.38.1",
+    "react": "19.0.0-rc-45804af1-20241021",
+    "react-dom": "19.0.0-rc-45804af1-20241021",
+    "react-markdown": "^9.1.0",
+    "remark-gfm": "^4.0.1",
+    "server-only": "^0.0.1",
+    "sonner": "^1.7.4",
+    "swr": "^2.3.3",
+    "tailwind-merge": "^2.6.0",
+    "tailwindcss-animate": "^1.0.7",
+    "usehooks-ts": "^3.1.1",
+    "zod": "^3.24.2"
+  },
+  "devDependencies": {
+    "@tailwindcss/typography": "^0.5.16",
+    "@types/d3-scale": "^4.0.9",
+    "@types/node": "^20.17.24",
+    "@types/pdf-parse": "^1.1.4",
+    "@types/react": "^19.0.10",
+    "@types/react-dom": "^19.0.4",
+    "drizzle-kit": "^0.25.0",
+    "eslint": "^8.57.1",
+    "eslint-config-next": "14.2.5",
+    "eslint-config-prettier": "^9.1.0",
+    "eslint-import-resolver-typescript": "^3.8.4",
+    "eslint-plugin-import": "^2.31.0",
+    "eslint-plugin-tailwindcss": "^3.18.0",
+    "postcss": "^8.5.3",
+    "prettier": "^3.5.3",
+    "tailwindcss": "^3.4.17",
+    "tsx": "^4.19.3",
+    "typescript": "^5.8.2"
+  },
+  "version": "0.0.1"
+}
+
+```