Zenn
😸

Cursor、Windsurf、ClineがMastraの公式ドキュメントを読めるようにする

2025/03/24に公開
Cursor
ai駆動開発
Cline
windsurf
Mastra
tech

はじめに

こんにちは、Kevinです。

この記事では、Cursor、Windsurf、ClineとMastraを連携させる方法について説明します。

Mastraについてはこちらの記事が詳しいので、まずはこちらを読んでみることをお勧めします。
https://zenn.dev/serinuntius/books/4346a0fc6818f3

本記事では、Mastraの概要、インストール方法、そしてCursor、Windsurf、ClineなどのIDEとの連携方法について解説します。

記事を作成するに至った経緯

最近Mastraが人気なので、僕も触ってみようと思いました。

Clineを使ってプロジェクトのセットアップをしていたのですが、その際にClineから以下の質問がありました。

Mastraについて、もう少し詳細な情報を教えていただけますか？
具体的には：

1. Mastraはどのようなフレームワークですか？（例：LangChain、AutoGenなどと比較して）
2. Mastraのインストール方法や基本的な使い方について、何か参考資料やドキュメントはありますか？
3. Mastraを使用する際の主な特徴や利点は何ですか？

Mastraの公式ドキュメントやリポジトリをClineに読んでもらってセットアップを進めようとしたのですが、分量が多すぎてうまくいかなかったので結局自分でセットアップすることにしました。

Mastraのセットアップ及びMCP Serverの設定は自分でやった方がスムーズに進めると思いましたので、セットアップの方法が皆様の参考になればと思い記事にした次第です。

Mastraとは

Mastraは、AIエージェント開発のためのTypeScriptフレームワークです。以下の特徴を持っています：

  • エージェント作成: LLMを活用した自律的なエージェントを簡単に作成できます
  • ツール統合: エージェントが外部システムと連携するためのツールを簡単に実装できます
  • ワークフロー管理: 複雑なタスクを一連のステップとして定義し、実行できます
  • メモリ管理: 会話履歴や重要な情報を保存し、長期的なコンテキストを維持できます
  • マルチモーダル対応: テキスト、画像、音声などの多様な入出力形式をサポートします

Mastraは、OpenAI、Anthropic、Google Geminiなどの主要なLLMプロバイダーと連携し、強力なAIエージェントを構築するための基盤を提供します。

公式ドキュメントはこちらです。
https://mastra.ai/docs

Mastraのインストール方法

前提条件

  • Node.js v20.0 以上
  • サポートされているLLM（OpenAI、Anthropic、Google Gemini等）へのアクセス権限

自動インストール（推奨）

最も簡単な方法は、create-mastraコマンドを使用することです：

npx create-mastra@latest

インストール時に以下の設定を行います：

  1. プロジェクト名の設定：例えば「my-mastra-app」
  2. インストールするコンポーネントの選択：
    • Agents（推奨）
    • Tools
    • Workflows
  3. デフォルトのLLMプロバイダーの選択：
    • OpenAI（推奨）
    • Anthropic
    • Groq
    • その他
  4. サンプルコードの含有有無：初めての場合は「Yes」がおすすめ
  5. IDEのMCP server設定：Cursor、Windsurfなどを選択

API Keyの設定

プロジェクトルートの.envファイルに選択したLLMプロバイダーのAPI Keyを設定します。

以下、３種類例を挙げていますが、どれか好きなものでいいです。

.envファイルは絶対にGitHubなどにアップロードしないようにしましょう。

OPENAI_API_KEY=あなたのopenAIAPIキーをここに
GOOGLE_API_KEY=あなたのGoogleAPIキーをここに
OPENROUTER_API_KEY=あなたのOpenRouterAPIキーをここに

手動インストール

より詳細な設定が必要な場合は、手動でインストールすることもできます：

  1. プロジェクトディレクトリの作成：
mkdir hello-mastra
cd hello-mastra
  1. パッケージのインストール：
npm init -y
npm install typescript tsx @types/node mastra --save-dev
npm install @mastra/core zod @ai-sdk/openai
npx tsc --init

  1. TypeScriptの設定：tsconfig.jsonを適切に設定

  2. API Keyの設定：.envファイルにAPI Keyを設定

MCP Docs Serverとは

CursorやWindsurf, Clineを使って開発する際は、MCPを使ってMastraのドキュメントを読み込めるようにすると便利です。

https://mastra.ai/blog/introducing-mastra-mcp

MCP（Model Context Protocol）は、AIモデルが構造化された形式で外部知識ベースやドキュメントにリアルタイムにアクセスするための標準プロトコルです。
Mastra MCP Docs Serverを使うことで、AIアシスタントやIDEがMastraの完全な知識ベースに直接アクセスできるようになります。

MCP Docs Serverの主な利点：

  • コンテキスト効率: 必要な情報だけをクエリできるため、コンテキストウィンドウを効率的に使用できます
  • 最新情報へのアクセス: Mastraの最新ドキュメント、例、変更履歴にアクセスできます
  • 問題解決の効率化: コードの問題に遭遇した場合、関連するドキュメントや例を簡単に検索できます

Cursor、Windsurf、ClineでのMCP Serverのセットアップ

自動セットアップ（推奨）

npx create-mastra@latest実行時にCursorまたはWindsurfを選択することで、MCP serverが自動的にインストールされます。

手動セットアップ

Cursorの場合

プロジェクトレベルの設定（.cursor/mcp.json）またはグローバル設定（~/.cursor/mcp.json）に以下を追加：

{
  "mcpServers": {
    "mastra": {
      "command": "npx",
      "args": ["-y", "@mastra/mcp-docs-server@latest"]
    }
  }
}

Windsurfの場合

グローバル設定ファイル（~/.codeium/windsurf/mcp_config.json）に以下を追加：

{
  "mcpServers": {
    "mastra": {
      "command": "npx",
      "args": ["-y", "@mastra/mcp-docs-server@latest"]
    }
  }
}

Clineの場合

Clineの設定ファイル（~/Library/Application Support/Cursor/User/globalStorage/saoudrizwan.claude-dev/settings/cline_mcp_settings.json）に以下を追加：

{
  "mcpServers": {
    "mastra": {
      "command": "npx",
      "args": ["-y", "@mastra/mcp-docs-server@latest"]
    }
  }
}

設定後の手順

Cursor

  1. Cursorの設定を開く
  2. MCPの設定に移動
  3. Mastra MCP serverを有効化
  4. エージェントチャットを再起動

Windsurf

  1. Windsurfを完全に終了して再起動
  2. ツール呼び出しが失敗する場合は、WindsurfのMCP設定でMCP serverを再起動

Cline

  1. Clineを再起動
  2. MCP serverが自動的に有効化されます

有効化されない場合、以下の方法を試してみて下さい。

  1. MCP Serversの設定を開く
  2. Installedタブをクリック
  3. Configure MCP Serversをクリック
  4. ファイルに以下のように入力
    {
   "mcpServers": {
     "mastra": {
        "command": "npx",
        "args": ["-y", "@mastra/mcp-docs-server@latest"]
        }
    }
 }

使用例

MCP Docs Serverを設定したら、以下のようなプロンプトでMastraに関する情報を取得できます：

  • 「Mastraでエージェントを作成する方法を教えて」
  • 「Mastraのツールの作成方法は？」
  • 「Mastraのメモリ機能について説明して」
  • 「Mastraのワークフローの例を示して」

例えば、以下のようなシンプルなエージェントを作成できます：

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

export const myAgent = new Agent({
  name: "My Agent",
  instructions: "You are a helpful assistant.",
  model: openai("gpt-4o-mini"),
});

ちなみにCursorにMCP Serverを使ってみてと言った時の反応はこちら。

Cursorの返答

MCP Docs Serverが使えるかどうかを確認するために、まずMastraのツールリストを取得してみましょう。

Ran tool
次に、Mastraのドキュメントを確認してみましょう。

Ran tool
MCPの設定に関する重要な情報が見つかりました。MCPの設定には主に2つの方法があります：

  1. 自動設定:
  • pnpm create mastra@latest コマンド実行時にCursorまたはWindsurfを選択すると、MCPサーバーが自動的にインストールされます。
  1. 手動設定:
  • Cursorの場合は、設定ファイルに以下のような設定を追加します：
{
  "servers": {
    "stockPrice": {
      "command": "npx",
      "args": ["tsx", "stock-price.ts"],
      "env": {
        "API_KEY": "your-api-key"
      }
    },
    "weather": {
      "url": "<http://localhost:8080/sse>"
    }
  }
}

MCPサーバーの状態を確認するために、利用可能なツールのリストを取得してみましょう。

Ran tool
MCPサーバーが正常に動作していることを確認できました。利用可能なツールには以下のようなものがあります：

  1. Brave関連:
  • web_search
  • news_search
  • images_search
  • videos_search
  1. Slack関連:
  • send_dm
  • post_message
  • list_channels
  • reply_in_thread
    など
  1. GitHub関連:
  • get_blob
  • get_issue
  • create_file
  • update_file
    など
  1. Notion関連:
  • search
  • get_page
  • create_page
  • update_page
    など
  1. Firecrawl関連:
  • crawl
  • scrape
  • search
  • extract
    など

次に、Mastraのドキュメントを確認して、MCPの設定に関する詳細情報を取得してみましょう。

Ran tool
MCPクライアントの設定について、より詳細な情報を確認するために、設定ファイルに関するドキュメントも確認してみましょう。

Ran tool
ドキュメントの確認結果から、MCPの設定について以下のようにまとめることができます：

  1. 基本的な設定方法:
const mcp = new MCPConfiguration({
  servers: {
    // サーバー設定をここに記述
  }
});
  1. サーバータイプ:
    • Stdioサーバー: コマンドラインベースのサーバー
    • SSEサーバー: Server-Sent Eventsベースのサーバー
  2. 設定例:
const mcp = new MCPConfiguration({
  servers: {
    stockPrice: {
      command: "npx",
      args: ["tsx", "stock-price.ts"],
      env: {
        API_KEY: "your-api-key"
      }
    },
    weather: {
      url: new URL("<http://localhost:8080/sse>")
    }
  }
});
  1. 重要な注意点:
    • 同一設定での複数インスタンス作成を防ぐため、必要な場合はidを指定する
    • disconnect()を適切に呼び出してリソースを解放する
    • サーバー接続は自動的に管理される
  2. ツールの使用方法:
    • getTools(): すべてのツールを取得（Agent定義用）
    • getToolsets(): 名前空間付きのツールセットを取得（generate/stream用）

これらの設定が正しく行われていることを確認するために、現在の設定を確認してみましょう。

Ran tool
MCPの設定ファイルを確認するために、.cursorディレクトリの内容を確認してみましょう。

Ran tool
mcp.jsonファイルの内容を確認してみましょう。

Read file: .cursor/mcp.json
現在のMCP設定は正しく構成されており、@mastra/mcp-docs-serverが設定されています。この設定により、Mastraのドキュメントサーバーにアクセスできる状態になっています。

設定の要点：

  1. サーバー名: mastra
  2. 使用コマンド: npx
  3. 引数: y @mastra/mcp-docs-server@latest

この設定により、以下の機能が利用可能です：

  • Mastraのドキュメント検索
  • コード例の参照
  • チェンジログの確認
  • ブログ記事の閲覧

MCPサーバーは正常に動作しており、必要なツールやドキュメントにアクセスできる状態です。何か特定の情報やツールについて確認したい場合は、お申し付けください。

Clineの返答はこちら

Clineの返答

ClineでのMastraのドキュメントサーバーの使用方法について確認してみましょう。

ClineでMastraのドキュメントサーバーを使用するための手順をまとめます：

  1. インストール方法:

    • 自動インストール:

      pnpm create mastra@latest

      インストール時にClineを選択してください。

    • 手動インストール:

      1. Clineの設定ファイルを編集します（.cline/mcp.json）
      2. 以下の設定を追加します：

      MacOS/Linuxの場合：

      {
  "mcpServers": {
    "mastra": {
      "command": "npx",
      "args": ["-y", "@mastra/mcp-docs-server@latest"]
    }
  }
}

      Windowsの場合：

      {
  "mcpServers": {
    "mastra": {
      "command": "cmd",
      "args": ["/c", "npx", "-y", "@mastra/mcp-docs-server@latest"]
    }
  }
}

  2. 設定後の手順:

    1. Clineを再起動します
    2. MCPサーバーが起動するまで少し時間がかかる場合があります（初回は特に）

  3. 利用可能なツール:

    • ドキュメント検索: Mastraの完全なドキュメントにアクセス
    • コード例の参照: プロジェクト構造、実装パターン、ベストプラクティス
    • ブログ記事の検索: 技術記事、更新情報、AI関連ニュース
    • パッケージ更新情報: バグ修正、新機能、破壊的変更の確認

  4. トラブルシューティング:

    • サーバーが起動しない場合：
      • npxがインストールされていることを確認
      • 設定ファイルの構文を確認
      • 他のMCPサーバーとの競合がないか確認
    • ツール呼び出しが失敗する場合：
      • MCPサーバーを再起動
      • Clineを最新バージョンに更新

これらの設定が完了すると、以下のような質問やタスクをClineに依頼できます：

  • "エージェントにevalsを追加してテストを書いて"
  • "このワークフローを作成して[タスク]"
  • "このサードパーティAPIにアクセスするツールを作成して"
  • "Mastraの最新のMCP関連ニュースを教えて"
  • "メモリ関連のバグや最近の修正について教えて"

トラブルシューティング

MCP Serverが起動しない場合

  1. npxが正しくインストールされているか確認

    • npx --versionで確認
    • 必要に応じてnpm install -g npxでインストール

  2. 競合するMCPサーバーがないか確認

    • IDEのMCP設定で他のサーバーを一時的に無効化

  3. 設定ファイルの構文を確認

    • JSONの構文エラーがないか確認

ツール呼び出しが失敗する場合

  1. MCPサーバーとIDEを再起動

    • IDEを完全に終了して再起動
    • MCP設定でサーバーを再起動

  2. IDEを最新バージョンに更新

    • CursorやWindsurfの最新バージョンを使用

  3. ネットワーク接続を確認

    • MCP serverがnpmからパッケージをダウンロードできるか確認

まとめ

いかがだったでしょうか。

MCP Docs Serverを連携すれば、AIがドキュメントを読んで作業してくれるので、開発効率が大幅に向上します。

Mastraの詳細なドキュメントは公式サイトで確認できます。

僕もMastraをこれから使うところなのですが、上記の設定をしたところClineがドキュメントを読み込めるようになったので、うまく進められそうです。

Mastraを使用して具体的なAIエージェントを作ってみたら、また記事にしようと思います。

質問があったら、いつでもどうぞ！

Discussion

ログインするとコメントできます