# 安裝指南

Canonical source: https://maguyva.ai/zh-hant/docs/installation

License: text under [CC BY 4.0](https://creativecommons.org/licenses/by/4.0/); code samples under [MIT-0](https://opensource.org/license/mit-0); the Maguyva name, logos, brand assets and other code are not covered. Details: [maguyva.ai/license](https://maguyva.ai/license).

5 分鐘內完成設定並上手。本指南涵蓋 23 個 MCP 用戶端的設定，包括 Claude Code, Claude Desktop, Cursor, VS Code, Devin Desktop, Codex CLI, GitHub Copilot CLI, Gemini CLI, Cline, Goose, Continue, LM Studio, Kiro CLI, JetBrains, Zed, Trae, OpenCode, BoltAI, LibreChat, Antigravity, Claude Cowork, ChatGPT、和 Warp 等。

**先決條件**：你需要來自 [app.maguyva.ai](https://app.maguyva.ai) 的 API 金鑰，以及一個已連接的 GitHub 儲存庫。

## 環境設定

首先，將 API 金鑰設為環境變數。當你的 MCP 用戶端提供此次請求的預設值，或該金鑰僅能存取單一儲存庫時，省略 `repository`；否則請明確傳入。

### macOS/Linux (Bash/Zsh)

```bash
export MAGUYVA_API_KEY="mgv_xxxx"
```

### Windows (PowerShell)

```powershell
'$Env:MAGUYVA_API_KEY="mgv_xxxx"' | Out-File -Append $PROFILE
. $PROFILE
```

將 `mgv_xxxx` 替換為你在 [app.maguyva.ai](https://app.maguyva.ai) 取得的實際 API 金鑰。

## 用戶端設定

在下方選擇你的 MCP 用戶端，以取得對應的設定說明。

```json
{
  "mcpServers": {
    "maguyva": {
      "url": "https://maguyva.tools/mcp",
      "headers": {
        "Authorization": "Bearer ${env:MAGUYVA_API_KEY}"
      }
    }
  }
}
```

Maguyva 使用標準 MCP。任何支援此協定的用戶端都能連接——即使上方沒有官方指南。目前已提供 23 個用戶端的設定文件，並持續新增中。

## 驗證你的設定

連接後，試著向你的代理提出幾個問題：

- 「我連接了哪些儲存庫？」 — 驗證連線是否正常
- 「這個程式碼庫是如何處理身份驗證的？」 — 測試語意搜尋
- 「找出所有呼叫資料庫的函式」 — 測試依賴關係搜尋
- 「UserService 類別依賴什麼？」 — 測試符號查找

你應該會看到來自已連接儲存庫、附帶檔案路徑與行號的結果。若沒有，請查看下方的 [troubleshooting](https://maguyva.ai/zh-hant/docs/troubleshooting)。

## 儲存庫格式

指定儲存庫時：

- 含分支: `"owner/repo:branch"` (e.g. `"owner/repository:develop"`)
- 預設分支: `"owner/repo"`

**提示**：使用 `repository_context(action="info", repository="...")` 檢查儲存庫解析。覆寫儲存庫設定只對目前呼叫生效。

## 疑難排解

### API 金鑰問題

- 確認你的金鑰以 mgv_ 開頭
- 檢查金鑰是否已正確設定於你的環境中
- 確認金鑰尚未過期

### 找不到儲存庫

- 確認該儲存庫已在 app.maguyva.ai 中連接
- 檢查 owner/repo 格式是否正確
- 確認你有該儲存庫的存取權限

### MCP 連線問題

- 若用戶端使用 @maguyva/mcp 橋接程式，請確認 PATH 中可找到 npx
- 檢查你的 API 權杖是否有效且尚未過期
- 測試與 https://maguyva.tools/mcp 的連線
- 檢查你用戶端的 MCP 設定語法

## 後續步驟

- MCP API 參考: 完整的 API 文件
- 運作原理: 了解情境最佳化
- 疑難排解: 解決設定與連線問題