使用 AI 建置

如要在日常開發中透過 Mastra Skill 及 CLI 使用 AI 輔助，請參閱開發。本頁介紹讓編程助手存取 Mastra 文檔的其他方法。

內嵌套件文檔

Mastra 套件在 dist/docs 內附有文檔。安裝 Mastra 套件後，AI Agent 可直接從 node_modules 讀取這些檔案，以了解套件的 API 及模式。

每個 dist/docs 包括：

• SKILL.md：遵循 Skill 標準的 Skill 檔案
• references/：載有套件相關文檔檔案的資料夾
• assets/SOURCE_MAP.json：把公開匯出項目連結至其 node_modules 位置的來源對應檔案

Context 檔案

Mastra 提供根目錄 llms.txt 檔案，概述所有可用的文檔頁面。由於把所有文檔放在單一檔案並不實用，因此不會提供 llms-full.txt。

相反，每個文檔頁面都有自己的 llms.txt 檔案。這些是經過精簡的 Markdown 檔案。每個文檔頁面末端都會提供相應 llms.txt 檔案的連結。

在任何 Mastra 文檔 URL 後加上 /llms.txt 即可存取。你亦可在 URL 末端加入 .md 副檔名來取得檔案。

簡介頁面的例子：

• /docs/llms.txt
• /docs.md

MCP 文檔伺服器

注意

不建議在日常開發中使用 MCP 文檔伺服器。請改用 Mastra Skill，因為其內容更新，效能亦較佳。

@mastra/mcp-docs-server 套件可透過 Model Context Protocol (MCP)，直接在本機存取完整的 Mastra 文檔。它支援 Cursor、Windsurf、Cline、Claude Code、VS Code、Codex，以及任何支援 MCP 的工具。

這些工具可協助 Agent 擷取準確且切合任務的資料，無論你要為 Agent 加入功能、建立新項目框架，還是了解某項功能的運作方式都適用。

如果無法使用本機 MCP 伺服器而需要連接遙距伺服器，請使用此 URL：https://mastra.mcp.kapa.ai。你需要使用 Google 帳戶驗證（只會傳送匿名 ID），以便實施速率限制。如情況許可，Mastra 建議使用本機 MCP 伺服器，以獲得更佳效能及可靠性。

安裝

create-mastra 指令不會配置 MCP 文檔伺服器。如需遷移 Tool 等 MCP 專用 Tool，請手動加入伺服器。

如果下方沒有適用於你所用工具的特定指示，可嘗試使用以下通用 JSON 配置加入 MCP 伺服器。

mcp.json

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

Claude Code CLI

在終端機執行以下指令安裝：

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

如果項目尚未有 .mcp.json，此指令會建立一個項目範圍的檔案。以 Claude Code 作為 Visual Studio Code 擴充功能時，亦可使用相同指令。

進一步了解如何在 Claude Code 使用 MCP 伺服器

OpenAI Codex CLI

1. 在終端機註冊：

   codex mcp add mastra-docs -- npx -y @mastra/mcp-docs-server@latest

2. 執行 codex mcp list，確認伺服器顯示為 enabled。

進一步了解如何在 OpenAI Codex 使用 MCP 伺服器

Cursor

選取下方按鈕安裝：

如果使用自動安裝，開啟 Cursor 時左下角會顯示彈出視窗，提示你啟用 Mastra Docs MCP Server。

進一步了解如何在 Cursor 使用 MCP 伺服器

Antigravity

Google Antigravity 是以 Agent 為先的開發平台，支援 MCP 伺服器存取外部文檔、API 及項目 Context。

1. 開啟 Antigravity MCP 配置檔案：

   • 按一下 Agent session，在編輯器側邊面板頂部選取 「…」下拉選單，再選取 MCP Servers 以開啟 MCP Store。
   • 你亦可透過 Antigravity 的 MCP Store 介面存取。

   

2. 如要加入自訂 MCP 伺服器，請在 MCP Store 頂部選取 Manage MCP Servers，再於主分頁選取 View raw config。

   

3. 加入 Mastra MCP 伺服器配置：

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

4. 儲存配置並重新啟動 Antigravity。

   

配置完成後，Mastra MCP 伺服器會向 Antigravity Agent 提供：

• Mastra 的索引文檔及 API schema，讓程式碼生成期間可透過程式擷取相關 Context
• Mastra Docs 所載的程式碼範例及使用模式
• 編輯器內用於錯誤處理及除錯參考的結構化資料
• 關於目前 Mastra 項目模式的中繼資料，用於程式碼建議及補全

MCP 伺服器會顯示於 Antigravity 的 MCP Store，你可在當中管理連線狀態及驗證（如需要）。

進一步了解如何在 Antigravity 使用 MCP 伺服器

Visual Studio Code

1. 在 Workspace 建立 .vscode/mcp.json 檔案。

2. 加入以下配置：

   .vscode/mcp.json

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

安裝 MCP 伺服器後，可按以下方式使用：

1. 開啟 VSCode 設定。

2. 前往 MCP 設定。

3. 在 Chat > MCP 選項按一下「enable」。

   

MCP 只可在 VSCode 的 Agent 模式運作。進入 Agent 模式後，開啟 mcp.json 並選取「start」按鈕。請注意，只有在包含 mcp.json 的 .vscode 資料夾位於 Workspace 根目錄，或編輯器內檔案總管的最高層時，才會顯示「start」按鈕。

啟動 MCP 伺服器後，在 Copilot 窗格選取 Tool 按鈕，即可查看可用的 Tool。

進一步了解如何在 Visual Studio Code 使用 MCP 伺服器

Windsurf

1. 在編輯器開啟 ~/.codeium/windsurf/mcp_config.json。

2. 加入以下配置：

   ~/.codeium/windsurf/mcp_config.json

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

3. 儲存配置並重新啟動 Windsurf。

進一步了解如何在 Windsurf 使用 MCP 伺服器

OpenCode

你可在 OpenCode 配置的 mcp 下定義 MCP 伺服器。在項目根目錄建立 opencode.jsonc，內容如下：

opencode.jsonc

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "mastra": {
      "type": "local",
      "command": ["npx", "-y", "@mastra/mcp-docs-server@latest"],
      "enabled": true
    }
  }
}

進一步了解如何在 OpenCode 使用 MCP 伺服器

Zed

1. 在編輯器開啟 ~/.config/zed/settings.json。
2. 加入以下配置：

~/.config/zed/settings.json

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

使用方法

配置完成後，你可以向 AI 工具詢問 Mastra 相關問題，或指示它執行操作。在這些步驟中，它會從 Mastra MCP 伺服器取得最新資料。

加入功能：

• 「為我的 Agent 加入 Evals 並編寫測試」
• 「編寫一個執行以下 [task] 的 Workflow」
• 「建立一個新 Tool，讓我的 Agent 可存取 [3rd party API]」

查詢整合方式：

• 「Mastra 可否配合 AI SDK 使用？ 如何在我的 [React/Svelte/etc] 項目中使用？」
• 「Mastra 支援 [provider] 語音 API 嗎？請在我的程式碼中提供使用範例。」

除錯或更新現有程式碼：

• 「我的 Agent memory 出現問題，最近有相關變更或錯誤修正嗎？」
• 「Mastra 的 working memory 如何運作？如何用它完成 [task]？它的表現似乎與我的預期不同。」
• 「我看到有新的 Workflow 功能，請先解釋，再更新 [workflow] 以使用這些功能。」

疑難排解

1. 伺服器無法啟動

   • 確保已安裝 npx 並可正常運作。
   • 檢查有否互相衝突的 MCP 伺服器。
   • 核實配置檔案語法。

2. Tool 調用失敗

   • 重新啟動 MCP 伺服器及／或 IDE。
   • 把 IDE 更新至最新版本。