> Discover all available pages from the documentation index: https://mastra.zisheng.pro/zh-TW/llms.txt

# 使用 AI 建置

如需搭配 Mastra Skill 與 CLI 進行日常 AI 輔助開發，請參閱[開發](https://mastra.zisheng.pro/zh-TW/docs/getting-started/develop)。本頁介紹讓 Coding Agent 存取 Mastra 文件的其他方式。

## 套件內嵌文件

Mastra 套件在 `dist/docs` 中包含內嵌文件。安裝 Mastra 套件後，AI Agent 可以直接從 `node_modules` 讀取這些檔案，以瞭解套件的 API 與模式。

每個 `dist/docs` 都包含：

- `SKILL.md`：遵循 skills 標準的 Skill 檔案
- `references/`：包含套件相關文件檔案的資料夾
- `assets/SOURCE_MAP.json`：將公開 export 連結至其 `node_modules` 位置的 source map 檔案

## Context 檔案

Mastra 提供根 [`llms.txt`](https://mastra.ai/llms.txt) 檔案，其中包含所有可用文件頁面的概覽。Mastra 不提供 `llms-full.txt`，因為將所有文件放在單一檔案中並無實際幫助。

每個文件頁面改為提供各自的 `llms.txt` 檔案。這些檔案是精簡的 markdown 檔案。每個文件頁面底部都有對應 `llms.txt` 檔案的連結。

在任何 Mastra 文件 URL 後加上 `/llms.txt` 即可存取。也可以在 URL 結尾加上 `.md` 副檔名來要求該檔案。

[簡介頁面](https://mastra.zisheng.pro/zh-TW/docs)範例：

- [`/docs/llms.txt`](https://mastra.ai/docs/llms.txt)
- [`/docs.md`](https://mastra.ai/docs.md)

## MCP 文件伺服器

> **警告:** 不建議在日常開發中使用 MCP 文件伺服器。請改用 [Mastra Skill](https://mastra.zisheng.pro/zh-TW/docs/getting-started/develop)，因為其內容更新、效能也更好。

`@mastra/mcp-docs-server` 套件可透過 [Model Context Protocol（MCP）](https://modelcontextprotocol.io/docs/getting-started/intro)，直接從本機存取完整 Mastra 文件。它可搭配 Cursor、Windsurf、Cline、Claude Code、VS Code、Codex，或任何支援 MCP 的工具使用。

這些 Tool 可協助 Agent 擷取精準且符合工作需求的資訊，無論是為 Agent 新增功能、建立新專案骨架，或探索功能的運作方式。

若無法使用本機 MCP 伺服器而需要連線至遠端伺服器，請使用此 URL：`https://mastra.mcp.kapa.ai`。基於速率限制用途，你必須使用 Google 帳戶驗證（只會傳送匿名 ID）。若條件允許，Mastra 建議使用本機 MCP 伺服器，以獲得更好的效能與可靠性。

### 安裝

[`create-mastra`](https://mastra.zisheng.pro/zh-TW/reference/cli/create-mastra) 指令不會設定 MCP 文件伺服器。需要 migration Tool 等 MCP 專屬 Tool 時，請手動新增伺服器。

如果你的工具未列於下方且沒有專屬操作說明，可以嘗試使用此通用 JSON 設定新增 MCP 伺服器。

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

#### Claude Code CLI

使用終端機指令安裝：

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

如果專案範圍的 `.mcp.json` 檔案尚不存在，此指令會建立該檔案。將 Claude Code 作為 [Visual Studio Code 擴充功能](https://code.claude.com/docs/en/vs-code#connect-to-external-tools-with-mcp)使用時，也可以使用相同指令。

[進一步瞭解如何在 Claude Code 使用 MCP 伺服器](https://docs.claude.com/en/docs/claude-code/mcp)

#### OpenAI Codex CLI

1. 從終端機註冊：

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

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

[進一步瞭解如何在 OpenAI Codex 使用 MCP 伺服器](https://developers.openai.com/codex/mcp)

#### Cursor

選取下方按鈕安裝：

[![安裝 MCP 伺服器](https://cursor.com/deeplink/mcp-install-light.svg)](cursor://anysphere.cursor-deeplink/mcp/install?name=mastra\&config=eyJjb21tYW5kIjoibnB4IC15IEBtYXN0cmEvbWNwLWRvY3Mtc2VydmVyIn0%3D)

若已依照自動安裝流程操作，開啟 Cursor 時，左下角會出現彈出式視窗，提示你啟用 Mastra Docs MCP Server。

![Cursor 中的彈出式視窗顯示：「New MCP server detected: mastra」。使用者可以選擇「Skip」或「Enable」。](/zh-TW/assets/images/enable-mastra-docs-cursor-cd5872abdc36c0e10951a59a47f25e12.png)

[進一步瞭解如何在 Cursor 使用 MCP 伺服器](https://cursor.com/de/docs/context/mcp)

#### Antigravity

Google Antigravity 是以 Agent 為優先的開發平台，支援透過 MCP 伺服器存取外部文件、API 與專案 context。

1. 開啟 Antigravity MCP 設定檔：

   - 按一下 **Agent session**，選取編輯器側邊面板頂端的 **「…」下拉式選單**，再選取 **MCP Servers** 以開啟 **MCP Store**。
   - 你可以透過 Antigravity 的 MCP Store 介面存取該功能

   ![Antigravity MCP Store。頂端有搜尋列，下方列出可用的 MCP 伺服器；右上角則有下拉式選單。](/zh-TW/assets/images/antigravity_mcp_server-689ea495d9c7139cc431f1f1b9827f9b.png)

2. 若要新增自訂 MCP 伺服器，請選取 MCP Store 頂端的 **Manage MCP Servers**，然後在主要分頁選取 **View raw config**。

   ![Antigravity MCP Store 顯示 Manage MCP Servers 選項與 View raw config 按鈕。](/zh-TW/assets/images/antigravity_managed_mcp-b661e8c04b3219000f8d842e5eb26a1a.png)

3. 新增 Mastra MCP 伺服器設定：

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

4. 儲存設定並重新啟動 Antigravity

   ![UI 顯示 MCP 伺服器已啟用，也可以個別切換 Tool。](/zh-TW/assets/images/antigravity_final_interface_mcp-7fa132dbe76cdee9f61136a26d6e6615.png)

完成設定後，Mastra MCP 伺服器會向 Antigravity Agent 公開下列內容：

- Mastra 已建立索引的文件與 API schema，讓程式碼生成期間可透過程式擷取相關 context
- 存放於 Mastra Docs 的程式碼片段範例與使用模式
- 用於錯誤處理與編輯器偵錯參考的結構化資料
- 目前 Mastra 專案模式的中繼資料，用於程式碼建議與自動完成

MCP 伺服器會顯示在 Antigravity 的 MCP Store 中，你可以在該處依需要管理連線狀態與驗證。

[進一步瞭解如何在 Antigravity 使用 MCP 伺服器](https://antigravity.google)

#### Visual Studio Code

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

2. 插入下列設定：

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

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

1. 開啟 VSCode 設定。

2. 前往 MCP 設定。

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

   ![VSCode 設定頁面中的項目。選項名稱為「Chat \> MCP: Enabled (Preview)」，說明文字為：「Enables integration with Model Context Protocol servers to provide additional tools and functionality.」](/zh-TW/assets/images/vscode-mcp-setting-8d1eb4f3df1e33606503f8c5e937e9e3.png)

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

![mcp.json 檔案的螢幕擷取畫面，顯示編輯器中的 start 按鈕](/zh-TW/assets/images/vscode-start-mcp-26480d86080c4907cb497a325de106a4.png)

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

![VSCode 的 Tool 頁面，可在此查看可用 Tool](/zh-TW/assets/images/vscode-mcp-running-d92d6ed234d1148093dc804b0ead3515.png)

[進一步瞭解如何在 Visual Studio Code 使用 MCP 伺服器](https://code.visualstudio.com/docs/copilot/customization/mcp-servers)

#### Windsurf

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

2. 插入下列設定：

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

3. 儲存設定並重新啟動 Windsurf

[進一步瞭解如何在 Windsurf 使用 MCP 伺服器](https://docs.windsurf.com/windsurf/cascade/mcp#mcp-config-json)

#### OpenCode

你可以在 [OpenCode 設定](https://opencode.ai/docs/config/)的 `mcp` 下定義 MCP 伺服器。在專案根目錄建立 `opencode.jsonc` 檔案，並加入下列內容：

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

[進一步瞭解如何在 OpenCode 使用 MCP 伺服器](https://opencode.ai/docs/mcp-servers)

#### Zed

1. 在編輯器中開啟 `~/.config/zed/settings.json`
2. 插入下列設定：

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

### 用法

設定完成後，即可詢問 AI Tool 有關 Mastra 的問題，或要求它執行操作。在這些步驟中，Tool 會從 Mastra MCP 伺服器取得最新資訊。

**新增功能：**

- 「為我的 Agent 新增 Evals 並撰寫測試」
- 「為我撰寫執行下列 `[task]` 的 Workflow」
- 「建立新的 Tool，讓我的 Agent 能存取 `[3rd party API]`」

**詢問整合方式：**

- 「Mastra 能與 AI SDK 搭配使用嗎？ 如何在我的 `[React/Svelte/etc]` 專案中使用？」
- 「Mastra 支援 `[provider]` 語音與 voice API 嗎？請在我的程式碼中提供使用範例。」

**偵錯或更新現有程式碼：**

- 「我的 Agent Memory 發生錯誤，最近是否有任何相關變更或錯誤修正？」
- 「Working Memory 在 Mastra 中如何運作？要如何用它執行 `[task]`？它的行為似乎不符合我的預期。」
- 「我看到有新的 Workflow 功能，請先說明，再更新 `[workflow]` 以使用這些功能。」

### 疑難排解

1. **伺服器未啟動**

   - 確認已安裝 [npx](https://docs.npmjs.com/cli/v11/commands/npx)，且可正常運作。
   - 檢查是否有衝突的 MCP 伺服器。
   - 確認設定檔語法正確。

2. **Tool 呼叫失敗**

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