# Claude Desktop 看不到你的仓库。给它一个。

Canonical source: https://maguyva.ai/zh-hans/for-claude-desktop

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).

很多人会在 Claude Desktop 里询问自己此刻并没在编辑的代码：代码评审、新人入职、事故电话会。Maguyva 索引仓库并通过 MCP 提供，于是答案引用的是文件和行号，而不是记忆。

> 无需检出代码。直接问索引。

## 关于 Claude Desktop 需要知道的

四条 Claude Desktop 专属事实。

### claude_desktop_config.json

通过 Settings → Developer → Edit Config 打开。在 macOS 上位于 `~/Library/Application Support/Claude/`；在 Windows 上位于 `%APPDATA%\Claude\`。

### 本地桥接

这个文件用于启动本地进程，所以本指南通过 `npx` 运行 `@maguyva/mcp`。需要安装 Node.js。

### 一条 env 条目

桥接程序从同一文件中服务器的 `env` 块读取 `MAGUYVA_API_KEY`。

### 退出，再重新打开

Claude Desktop 在启动时读取这个文件。编辑后请彻底退出应用；服务器会在下次启动时运行。

## 项目指令定下基调，好好用它。

Claude 的项目功能可以保存指令和文件，项目里的每个对话一开始就会带上它们。适合放进去的有：

- 答案写给谁看：评审者、新同事、值班工程师。
- 解释和总结的内部风格。
- 几份你希望被引用的文档，比如架构概览。

上传的文件只是快照。你上传后的第二天，仓库就已经往前走了。

## 粘贴代码不够用的地方

缺了代码本身，关于代码的对话会出错的三种情况。

### // 粘贴的片段会过时

上周贴进对话的文件，描述的是上周的代码。Claude 会依据它拿到的那个版本，信心满满地作答。

### // 片段不是整个系统

单个文件很少能回答“这里失败了会发生什么？”处理函数、重试和告警通常分布在三个不同的包里。

### // 没有检出，就没有 grep

Claude Desktop 没有你仓库的工作副本。没有工具的话，关于结构的每个回答，都取决于你记得贴了什么。

## 作为 Claude Desktop 中 MCP 服务器的 Maguyva

一条 mcpServers 条目让 Claude 获得：

- **面向已索引仓库的 11 个工具**: 语义、结构（AST）、图和文本搜索，外加符号查找、依赖方和文件检索。
- **带文件路径和行号的答案**: 覆盖 285+ 种语言，每个说法你都能核实。
- **分支感知的结果**: 让 Claude 回答的是你指定的分支，而不是上个月某人上传的文件。

> 项目指令告诉 Claude *怎么回答*。
> Maguyva 给 Claude *作答所依据的代码*。

## 两种工作流

那些你原本得打开 IDE 才能回答的问题。

### 01. 在评审中解释一条代码路径

```text
claude> 支付 Webhook 的签名校验失败后会发生什么？

semantic_search("webhook signature verification failure")
  src/payments/webhooks.ts:64   verifySignature()
  src/payments/webhooks.ts:91   rejectAndAlert()

→ Claude 作答时引用了这两行。
[exit 0]
```

答案的每一步都指向一个你能打开的文件和行号。

### 02. 规划之前先估算改动规模

```text
claude> 有多少地方在读旧的 plan_code 字段？

text_pattern_search("plan_code")
  9 个文件中 14 处匹配
dependency_search("getPlanCode", dependents)
  6 个调用方

→ 估算从一个数字出发，而不是靠猜。
[exit 0]
```

在没人打开仓库的规划会议上很有用。

## 在 Claude Desktop 中配置

三个步骤。Free 层级：3 个代码仓库, 最多 5 万行索引代码，无需信用卡。

### 01. 在 maguyva.ai 索引一个代码仓库

挑一个你已经熟悉的，这样你能给答案打分。

### 02. 把 Maguyva 添加到 claude_desktop_config.json

`claude_desktop_config.json`

```json
{
  "mcpServers": {
    "maguyva": {
      "command": "npx",
      "args": [
        "-y",
        "@maguyva/mcp"
      ],
      "env": {
        "MAGUYVA_API_KEY": "mgv_xxxx"
      }
    }
  }
}
```

### 03. 替换占位符、重启，然后问一个问题

把 `mgv_xxxx` 换成你的 API 密钥，彻底退出 Claude Desktop 再重新打开。如果服务器没有出现，请查看 Claude 日志文件夹（macOS 上为 `~/Library/Logs/Claude`）中的 `mcp-server-maguyva.log`。

[MCP 本地服务器指南](https://modelcontextprotocol.io/docs/develop/connect-local-servers) 更详细地介绍了配置文件及其日志。

## 索引一个你已经熟悉的代码仓库。

通过 MCP 连接 Claude Desktop，然后问一个你能核实的问题。