mcp-digger

mcp-digger

为 AI 编码 Agent 提供代码上下文。 按需渐进式访问内部 .NET / NuGet 包源码——Agent 可自主浏览、搜索和读取私有 C# 库，且不会污染工作区。

⚠ 范围：仅限 .NET / C#。 mcp-digger 为包含 .csproj 包和 .cs 源文件的 NuGet 风格仓库建立索引。它不是通用源代码索引工具——其他语言（TypeScript、Python、Java、Go 等）不在支持范围内。

✨ 为什么使用

公共 NuGet 包拥有完善的文档生态——API 参考、教程和社区问答。context7 等工具很适合处理这类内容。

内部 .NET 包通常以源代码作为主要文档。mcp-digger 将这些源代码转换为结构化、可搜索且节省 token 的上下文，供任何兼容 MCP 的 Agent 使用，从而弥补私有 C# 库生态中的文档缺口。

没有它：

• 🐢 收集上下文速度慢 — git clone + find + grep + cat 的命令链会在获取有用上下文之前，就把 token 消耗在基础设施操作上。
• 🔍 无法语义搜索 — 文件系统工具只能查找文本，无法查找 API 接口。“实现这个接口的所有类型”意味着要临时编写提取脚本。
• 💸 浪费 token — 只需一个方法签名，Agent 却要读取整个文件。
• 🖱 频繁点击授权 — 每个会话都要批准数十条 Shell 命令。
• 🧹 工作区杂乱 — 引用的仓库会污染文件搜索、Git 状态和 Agent 的上下文窗口。

使用它：

• ✅ 首次尝试就获得正确代码 — 真实签名、泛型约束、接口契约和基类模式。
• ⚡ 自主获取上下文 — 只需让 Agent 指向 NuGet 仓库一次；它便可自主浏览、搜索和读取。
• 🪙 渐进式披露 — 先查看 200 个 token 的概述，再深入阅读 5,000 个 token 的源码。大多数问题在 L1 或 L2 就能解决。
• 🧼 工作区零污染 — 托管克隆位于项目树之外。
• 🌐 支持任何 Git 托管平台 — GitHub、GitLab、Azure DevOps、Bitbucket、自托管平台——支持 HTTPS 或 SSH。

🛠 工作原理

十个专用工具，按由浅入深的顺序排列。Agent 会选择能回答问题且成本最低的工具。

                                                           ┌─→ 📦 dig_package_overview ─┐
                                                           │   (docs, key types)        │
   🩺 dig_status  →  📋 dig_list  →  📖 dig_repo_overview  ┤                            ├─→  🔎 dig_lookup     →  📄 dig_file
   (health)          (discover)      (README + summaries)  │                            │   (symbol → file)       (full source)
                                                           ├─→ 📁 dig_package_files ────┤
                                                           │   (file listing)           │
                                                           └────────────────────────────┴─→  📝 dig_signatures
                                                                                            (stripped API)

   Operational:  🔄 dig_refresh   (force cache invalidation, on demand)
   Bootstrap:    🌱 dig_init      (only when no config exists)

🧰 工具（10 个）

dig_lookup 的搜索模式：

🚀 快速开始

安装

npm install -g mcp-digger
# or run directly
npx mcp-digger

需要 Node.js 20+、PATH 中可用的 git，以及 .NET / C# 源码仓库（包含 .csproj 和 .cs 源文件的 NuGet 包）。

最简配置

在工作区根目录创建 .digger/config.json：

{
  "repos": [
    {
      "name": "my-libraries",
      "url": "https://github.com/org/shared-libs.git",
      "packageFilter": "MyCompany.*",
      "auth": {
        "strategy": "pat",
        "PAT-EnvVarName": "GIT_PAT"
      }
    }
  ]
}

还没有配置文件？启动服务，然后调用 dig_init 来生成初始配置。

Agent 设置

{
  "mcpServers": {
    "digger": {
      "command": "npx",
      "args": ["-y", "mcp-digger"]
    }
  }
}

[mcp_servers.mcp-digger]
command = "npx"
args = ["-y", "mcp-digger"]

{
  "mcpServers": {
    "digger": {
      "command": "npx",
      "args": ["-y", "mcp-digger"]
    }
  }
}

{
  "servers": {
    "digger": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "mcp-digger"]
    }
  }
}

{
  "mcpServers": {
    "digger": {
      "command": "npx",
      "args": ["-y", "mcp-digger"]
    }
  }
}

验证

连接后，让你的 Agent 调用 dig_status——它会报告配置验证结果、各仓库的连接状态和索引健康状况。

⚙ 配置

仓库和包

repos[] 条目有三种声明包的方式：

sourceRoot 默认为 "src"——将其设为存放包目录的目录。扫描会递归进行，因此也会找到 src/Group/Foo/Foo.csproj 这样的嵌套布局。

{
  "repos": [
    {
      "name": "my-libraries",
      "url": "https://github.com/org/shared-libs.git",
      "branch": "develop"
    }
  ]
}

{
  "localRepos": {
    "my-libraries": "C:/repos/shared-libs"
  },
  "repos": [
    {
      "name": "my-libraries",
      "sourceRoot": "src"
    }
  ]
}

🩺 诊断与恢复

调试日志

在配置中启用调试日志：

{ "debug": true, "repos": [...] }

日志写入 .digger/debug.log（上限为 5 MB，并会自动截断）。严重错误和崩溃输出会写入 .digger/error.log。

💬 反馈

在你的代码库上试用了 mcp-digger？欢迎在 GitHub Discussions 分享哪些功能有效、哪些出了问题，以及还缺少什么。错误报告请提交至 Issues。

📜 许可证

MIT 许可证 — 详见 LICENSE。