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

# 使用 AI 建置

如要在日常開發中透過 Mastra Skill 及 CLI 使用 AI 輔助，請參閱[開發](https://mastra.zisheng.pro/zh-HK/docs/getting-started/develop)。本頁介紹讓編程助手存取 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`](https://mastra.ai/llms.txt) 檔案，概述所有可用的文檔頁面。由於把所有文檔放在單一檔案並不實用，因此不會提供 `llms-full.txt`。

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

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

[簡介頁面](https://mastra.zisheng.pro/zh-HK/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-HK/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 的工具。

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

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

### 安裝

[`create-mastra`](https://mastra.zisheng.pro/zh-HK/reference/cli/create-mastra) 指令不會配置 MCP 文檔伺服器。如需遷移 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-HK/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-HK/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-HK/assets/images/antigravity_managed_mcp-b661e8c04b3219000f8d842e5eb26a1a.png)

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

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

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

   ![介面顯示 MCP 伺服器已啟用，亦可個別切換 Tool。](/zh-HK/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-HK/assets/images/vscode-mcp-setting-8d1eb4f3df1e33606503f8c5e937e9e3.png)

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

![編輯器中的 mcp.json 檔案截圖，顯示 start 按鈕。](/zh-HK/assets/images/vscode-start-mcp-26480d86080c4907cb497a325de106a4.png)

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

![VSCode 的 Tool 頁面，顯示可用 Tool。](/zh-HK/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 工具詢問 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](https://docs.npmjs.com/cli/v11/commands/npx) 並可正常運作。
   - 檢查有否互相衝突的 MCP 伺服器。
   - 核實配置檔案語法。

2. **Tool 調用失敗**

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