# 安装指南

Canonical source: https://maguyva.ai/zh-hans/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-hans/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 文档
- 工作原理: 了解上下文优化机制
- 故障排查: 解决配置和连接问题