Mastra × MCPでドキュメント作成を自動化してみる

$ pnpm create mastra@latest docs-creator

$ cd docs-creator
$ pnpm run dev

src/mastra/
├── index.ts              # Mastraメイン設定
├── agents/               # AIエージェント定義
├── workflow/             # ワークフロー定義
└── tools/                # 外部ツール連携

src/mastra/index.ts

import { Mastra } from '@mastra/core/mastra';
import { PinoLogger } from '@mastra/loggers';
import { LibSQLStore } from '@mastra/libsql';
import { weatherWorkflow } from './workflows/weather-workflow';
import { weatherAgent } from './agents/weather-agent';

export const mastra = new Mastra({
  workflows: { weatherWorkflow },
  agents: { weatherAgent },
  
  
  
  
  
  
  
  
  
  
});

$ claude mcp add mastra -- npx -y @mastra/mcp-docs-server@latest

src/mastra/agents/myAgent.ts

import { Agent } from "@mastra/core/agent";
import { openai } from "@ai-sdk/openai";

export const myAgent = new Agent({
  name: "my-agent",
  instructions: "あなたは親切なアシスタントです。",
  
  model: openai("gpt-4o-mini"),
});

src/mastra/index.ts

import { Mastra } from "@mastra/core";
import { weatherWorkflow } from "./workflows/weather-workflow";
import { myAgent } from "./agents/myAgent";

export const mastra = new Mastra({
  workflows: { weatherWorkflow },
  agents: { myAgent },
});

import { z } from "zod";

const response1 = await myAgent.generate([
  { role: "user", content: "元気ですか？" },
]);

console.log(response1.text);


const sampleSchema = z.object({
  prefecture: z.string().describe("都道府県名"),
  city: z.string().describe("市区町村名"),
  yomigana: z.string().describe("よみがな"),
});

const response2 = await myAgent.generate(
  [
    {
      role: "user",
      content:
        "「長万部」はどの都道府県のどの市区町村にありますか？またなんと読みますか？",
    },
  ],
  { output: sampleSchema }
);

console.log(response2.object);

src/mastra/tools/github.ts

import { MCPClient } from "@mastra/mcp";

export const githubMcp = new MCPClient({
  servers: {
    "github-mcp": {
      url: new URL("https://api.githubcopilot.com/mcp/"),
      requestInit: {
        headers: {
          
          Authorization: `Bearer ${process.env.GITHUB_PERSONAL_ACCESS_TOKEN || ""}`,
        },
      },
    },
  },
});


export const githubMcpTools = await githubMcp.getTools();

export const readOnlyGithubMcpTools = Object.fromEntries(
  Object.entries(githubMcpTools).filter(([toolName]) =>
    toolName.includes("_get_")
  )
);

src/mastra/tools/esa.ts

import { MCPClient } from "@mastra/mcp";

export const esaMcp = new MCPClient({
  servers: {
    "esa-mcp": {
      command: "node",
      args: ["/path/to/directory/esa-mcp-server/build/index.js"],
      env: {
        ESA_ACCESS_TOKEN: process.env.ESA_ACCESS_TOKEN || "",
      },
    },
  },
});


export const esaMcpTools = await esaMcp.getTools();
export const readOnlyEsaMcpTools = Object.fromEntries(
  Object.entries(esaMcpTools).filter(([toolName]) => toolName.includes("get-"))
);

src/mastra/agents/toolsAgent.ts

import { openai } from "@ai-sdk/openai";
import { Agent } from "@mastra/core";
import { readOnlyEsaMcpTools } from "../tools/esa";
import { readOnlyGithubMcpTools } from "../tools/github";

const instructions = `
あなたは、与えられたツールを使用して、ユーザーの質問に答えるエージェントです。
ツールが使えない際は、その旨をユーザーに伝えてください。
日本語で回答してください。
`;

export const toolsAgent = new Agent({
  name: "tools-agent",
  model: openai("gpt-4o"),
  instructions,
  tools: {
    ...readOnlyEsaMcpTools,
    ...readOnlyGithubMcpTools,
  },
});

src/mastra/index.ts

import { Mastra } from "@mastra/core/mastra";
import { weatherWorkflow } from "./workflows/weather-workflow";
import { myAgent } from "./agents/myAgent";
import { toolsAgent } from "./agents/toolsAgent";

export const mastra = new Mastra({
  workflows: { weatherWorkflow },
  agents: { myAgent, toolsAgent },
});

src/mastra/utils/getSlackThreadMessage.ts

import { WebClient } from "@slack/web-api";

export const getSlackThreadMessage = async (url: string) => {
  try {
    const urlPattern =
      /https:\/\/[\w-]+\.slack\.com\/archives\/([A-Z0-9]+)\/p(\d+)/;
    const match = url.match(urlPattern);
    const [, channelId, timestamp] = match;
    const formattedTimestamp = `${timestamp.slice(0, 10)}.${timestamp.slice(10)}`;
    const client = new WebClient(process.env.SLACK_USER_TOKEN);
    const threadResult = await client.conversations.replies({
      channel: channelId,
      ts: formattedTimestamp,
      inclusive: true,
    });

    

    return threadMessage;

  } catch (error) {
    throw new Error("メッセージの取得に失敗しました");
  }
}

src/mastra/tools/slack.ts

import { createTool } from "@mastra/core";
import z from "zod";
import { getSlackThreadMessage } from "../utils/getSlackThreadMessage";


export const slackTool = createTool({
  id: "getSlackThreadMessage",
  description: "SlackのスレッドURLからメッセージ内容を取得",
  inputSchema: z.object({
    url: z.string().describe("SlackスレッドのURL"),
  }),
  outputSchema: z.string().describe("取得されたSlackメッセージの内容"),
  execute: async ({ context }) => {
    return await getSlackThreadMessage(context.url);
  },
});

src/mastra/agents/toolsAgent.ts

import { slackTool } from "../tools/slack";


export const toolsAgent = new Agent({
  
  tools: {
    ...readOnlyEsaMcpTools,
    ...readOnlyGithubMcpTools,
    slackTool 
  },
});

src/mastra/agents/documentAgent.ts

import { Agent } from "@mastra/core/agent";
import { openai } from "@ai-sdk/openai";
import { readOnlyEsaMcpTools } from "../tools/esa";
import { readOnlyGithubMcpTools } from "../tools/github";
import { slackTool } from "../tools/slack";

export const contextExtractionAgent = new Agent({
  name: "context-extraction-agent",
  model: openai("gpt-4o-mini"),
  instructions: `あなたは、与えられたツールを使用して、ユーザーの質問に答えるエージェントです。
  ツールが使えない際は、その旨をユーザーに伝えてください。`,
  tools: {
    ...readOnlyEsaMcpTools,
    ...readOnlyGithubMcpTools,
    slackTool,
  },
});

export const documentTemplateAgent = new Agent({
  name: "document-template-agent",
  description: "文書のテンプレートを生成するエージェント",
  model: openai("gpt-4o"),
  instructions: `あなたは、与えられた文書とユーザーから与えられた指示を元に、これから作成する文書のテンプレートを生成するエージェントです。
  
  **重要な指示：**
  - 生成するテンプレートの大見出し(#)とそのタイトル、中見出し(##)とそのタイトルだけ出力してください。
  - テンプレートはマークダウン形式で出力してください。
  - 与えられた文書の内容を参考にしながら、ユーザーの指示に従ってテンプレートを生成してください。 
  - 見出しのタイトルは日本語にしてください`,
});

export const documentSummaryAgent = new Agent({
  name: "document-summary-agent",
  description: "文書の要約を生成するエージェント",
  model: openai("gpt-4o"),
	instructions: `あなたは、Slackのチャットログをもとに、**事実ベース**の詳細な技術文書を作成するエージェントです。プロンプトには「Slackメッセージ内容」「コンテキスト情報」「テンプレート」が含まれます。コンテキスト情報はSlackメッセージ内に現れるURLのリンク先の情報を取得したものです。指定されたテンプレートに従い、Slackメッセージ内容をまとめてください。Slackメッセージだけで補えない部分を、コンテキスト情報から補完してください。

 **重要な指示：**
  - テンプレートで指定されたテンプレートに従う。必要に応じて小見出し(###)を追加してもよい
  -  **ソースコードはできる限り含める** -
  コンテキスト情報にソースコードがある場合は、コードブロックで積極的に記載
  -  **事実のみを記載** - 推測や一般論は避け、具体的な事実（エラー内容、コード変更、設定値など）を記載する
  -  **技術的詳細を省略しない** - エラーメッセージ、設定ファイル、コマンド例などを具体的に記載
  -  **時系列を明確に** -
  何がいつ起こったか、誰が何をしたかを詳細に記録
  **記載すべき内容の例**
  - 具体的なエラーメッセージとスタックトレース
  - ファイルの変更内容（変更前後の差分）
  - 実行されたコマンドとその結果
  - 散逸的に散らばっている情報を整理し、構造化する
  - Slackメッセージ内容をメインに文書を作成し、コンテキスト情報  中に含まれるテキストも大量に取り入れる
  - 根本原因の技術的詳細

  出力は必ずマークダウン形式で行ってください。`,
});

src/mastra/defenition/schema.ts

import { z } from "zod";


export const inputSchema = z.object({
  slackUrl: z.string().url(),
  userInstructions: z.string().optional(),
});

export const messageSchema = z.object({
  message: z.string(),
});

export const contextExtractionSchema = z.object({
  message: z.string(),
  context: z.string(),
});

export const documentTemplateSchema = z.object({
  template: z.string(),
});

export const documentSchema = z.object({
  document: z.string(),
});

src/mastra/workflows/documentGenerationWorkflow.ts

import { createStep } from "@mastra/core";
import { z } from "zod";
import { getSlackThreadMessage } from "../utils/getSlackThreadMessage";
import {
  contextExtractionAgent,
  documentSummaryAgent,
  documentTemplateAgent,
} from "../agents/documentAgent";
import {
  contextExtractionSchema,
  documentSchema,
  documentTemplateSchema,
  inputSchema,
  messageSchema,
} from "../defenition/schema";

const slackMessageRetrievalStep = createStep({
  id: "slackMessageRetrieval",
  description: "SlackのURLを受け取り、スレッドの内容を全て取得するステップ",
  inputSchema: inputSchema,
  outputSchema: messageSchema,
  execute: async ({ inputData }) => {
    const message = await getSlackThreadMessage(inputData.slackUrl);
    return { message };
  },
});

const contextExtractionStep = createStep({
  id: "contextExtraction",
  description: "メッセージからURLを抽出し、各URLから情報を取得するステップ",
  inputSchema: messageSchema,
  outputSchema: contextExtractionSchema,
  execute: async ({ inputData }) => {
    const { message } = inputData;

    const urlPattern = /(https?:\/\/[\w/:%#$&?()~.=+-]+)/g;
    
    const urlList = inputData.message.match(urlPattern) || [];

    const contextList = await Promise.all(
      urlList.map(async (url) => {
        const agentResult = await contextExtractionAgent.generate([
          {
            role: "user",
            content: url,
          },
        ]);

        return `
        {
          "url": "${url}",
          "content": "${agentResult.text}"
        }
        `;
      })
    );

    
    const context = contextList.join("\n");

    return {
      message: inputData.message,
      context,
    };
  },
});

export const templateCreationStep = createStep({
  id: "templateCreation",
  description: "文書のテンプレートを作るステップ",
  inputSchema: messageSchema,
  outputSchema: documentTemplateSchema,
  execute: async ({ inputData, getInitData }) => {
    
    const { userInstructions } = getInitDatatypeof inputSchema>();

    const prompt = `
      【文書】
      ${inputData.message}
      
      ${userInstructions ? `【ユーザーからの指示】\n${userInstructions}` : ""}
      `;

    const result = await documentTemplateAgent.generate(
      [{ role: "user", content: prompt }],
      { output: documentTemplateSchema }
    );

    return { template: result.object.template };
  },
});

const summarizationStep = createStep({
  id: "summarization",
  description: "メッセージ内容とコンテキスト情報をもとに文書を要約するステップ",
  
  inputSchema: z.object({
    
    contextExtraction: contextExtractionSchema,
    templateCreation: documentTemplateSchema,
  }),
  outputSchema: documentSchema,
  execute: async ({ inputData: { contextExtraction, templateCreation } }) => {
    const { message, context } = contextExtraction;
    const { template } = templateCreation;

    const prompt = `
      【Slackメッセージ内容】
      ${message}

      【コンテキスト情報】
      ${context}

      【テンプレート】
      ${template}
      `;

    const result = await documentSummaryAgent.generate(
      [{ role: "user", content: prompt }],
      { output: documentSchema }
    );

    
    const document = result.object.document;
    
    await outputToLogFile(`文書要約`, result.object.document);

    return { document: result.object.document };
  },
});

import { createStep, createWorkflow } from "@mastra/core";


export const documentGenerationWorkflow = createWorkflow({
  id: "slack-documentation-workflow-ver2",
  inputSchema: inputSchema,
  outputSchema: documentSchema,
})
  .then(slackMessageRetrievalStep)
  .parallel([contextExtractionStep, templateCreationStep])
  .then(summarizationStep)
  .commit();