{
  "markdown": "# mcp-digger\n\n> **Code context for AI coding agents.** Progressive, on-demand access to your internal .NET / NuGet package source — agents browse, search, and read private C# libraries autonomously, with zero workspace pollution.\n\n> ⚠ **Scope: .NET / C# only.** mcp-digger indexes NuGet-style repos containing `.csproj` packages and `.cs` source files. It is not a general-purpose source indexer — other languages (TypeScript, Python, Java, Go, etc.) are out of scope.\n\n---\n\n## ✨ Why\n\nPublic NuGet packages have documentation ecosystems — API references, tutorials, community Q&A. Tools like `context7` serve that well.\n\nInternal .NET packages often have source code as their primary documentation. mcp-digger turns that source into structured, searchable, token-efficient context that any MCP-compatible agent can consume — bridging the documentation gap in private C# library ecosystems.\n\n**Without it:**\n\n- 🐢 **Slow context gathering** — `git clone` + `find` + `grep` + `cat` chains burn tokens on infrastructure before useful context is retrieved.\n- 🔍 **No semantic search** — file system tools find text, not API surfaces. \"Every type implementing this interface\" means writing extraction scripts on demand.\n- 💸 **Token waste** — agents read whole files when a single method signature would do.\n- 🖱 **Permission click fatigue** — dozens of shell-command approvals per session.\n- 🧹 **Workspace noise** — referenced repos pollute file search, git status, and the agent's context window.\n\n**With it:**\n\n- ✅ **Correct code on the first try** — real signatures, generic constraints, interface contracts, base class patterns.\n- ⚡ **Self-service context** — point the agent at your NuGet repos once; it browses, searches, and reads autonomously.\n- 🪙 **Progressive disclosure** — 200-token overview before 5,000 tokens of source. Most questions resolve at L1 or L2.\n- 🧼 **Zero workspace pollution** — managed clones live outside your project tree.\n- 🌐 **Any Git host** — GitHub, GitLab, Azure DevOps, Bitbucket, self-hosted — HTTPS or SSH.\n\n---\n\n## 🛠 How it works\n\nTen purpose-built tools, escalating from broad to deep. The agent picks the cheapest tool that answers its question.\n\n```\n                                                           ┌─→ 📦 dig_package_overview ─┐\n                                                           │   (docs, key types)        │\n   🩺 dig_status  →  📋 dig_list  →  📖 dig_repo_overview  ┤                            ├─→  🔎 dig_lookup     →  📄 dig_file\n   (health)          (discover)      (README + summaries)  │                            │   (symbol → file)       (full source)\n                                                           ├─→ 📁 dig_package_files ────┤\n                                                           │   (file listing)           │\n                                                           └────────────────────────────┴─→  📝 dig_signatures\n                                                                                            (stripped API)\n\n   Operational:  🔄 dig_refresh   (force cache invalidation, on demand)\n   Bootstrap:    🌱 dig_init      (only when no config exists)\n```\n\n---\n\n## 🧰 Tools (10)\n\n| Tier | Tool | What it does |\n|------|------|-------------|\n| **Health** | 🩺 `dig_status` | Config summary, connectivity check per repo, index health stats |\n| **Discovery** | 📋 `dig_list` | Lists configured repos + their packages with one-line `.csproj` summaries |\n| **L1 Overview** | 📖 `dig_repo_overview` | Repo `README.md` (filtered to architecture sections) + package count |\n| **L1 Overview** | 📦 `dig_package_overview` | Package docs, key interfaces, abstract classes, file count |\n| **L1 Overview** | 📁 `dig_package_files` | `.cs` file listing for a package, with directory summary header |\n| **L2 Search** | 🔎 `dig_lookup` | Indexed symbol search — `symbol`, `implements`, or `references` mode. Cross-package supported. |\n| **L2 Search** | 📝 `dig_signatures` | Stripped C# public API surface filtered by keyword (no method bodies) |\n| **L3 Source** | 📄 `dig_file` | Full source of a single file (capped at 1 MB) |\n| **Operational** | 🔄 `dig_refresh` | Force-rebuild caches for one or all repos |\n| **Bootstrap** | 🌱 `dig_init` | Creates starter `.digger/config.json` (registered only when no config is found) |\n\n**Search modes for `dig_lookup`:**\n\n| Mode | Finds |\n|------|-------|\n| `symbol` (default) | Type/method declarations matching a name substring |\n| `implements` | Classes/structs implementing an interface or extending a base class |\n| `references` | Files referencing a given type name (word-boundary, case-sensitive) |\n\n---\n\n## 🚀 Quick start\n\n### Install\n\n```bash\nnpm install -g mcp-digger\n# or run directly\nnpx mcp-digger\n```\n\nRequires Node.js 20+, `git` on `PATH`, and a .NET / C# source repo (NuGet packages with `.csproj` + `.cs` sources).\n\n### Minimal config\n\nCreate `.digger/config.json` in your workspace root:\n\n```jsonc\n{\n  \"repos\": [\n    {\n      \"name\": \"my-libraries\",\n      \"url\": \"https://github.com/org/shared-libs.git\",\n      \"packageFilter\": \"MyCompany.*\",\n      \"auth\": {\n        \"strategy\": \"pat\",\n        \"PAT-EnvVarName\": \"GIT_PAT\"\n      }\n    }\n  ]\n}\n```\n\nDon't have a config yet? Start the server, then call `dig_init` to scaffold one.\n\n### Agent setup\n\n<details>\n<summary><strong>Claude Code</strong></summary>\n\nAdd to `.claude/settings.json` or project settings:\n\n```json\n{\n  \"mcpServers\": {\n    \"digger\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"mcp-digger\"]\n    }\n  }\n}\n```\n</details>\n\n<details>\n<summary><strong>Codex CLI</strong></summary>\n\nAdd to `~/.codex/config.toml` (or `.codex/config.toml` for project-scoped):\n\n```toml\n[mcp_servers.mcp-digger]\ncommand = \"npx\"\nargs = [\"-y\", \"mcp-digger\"]\n```\n</details>\n\n<details>\n<summary><strong>Claude Desktop</strong></summary>\n\nAdd to `claude_desktop_config.json`:\n\n- Windows: `%APPDATA%\\Claude\\claude_desktop_config.json`\n- macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`\n\n```json\n{\n  \"mcpServers\": {\n    \"digger\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"mcp-digger\"]\n    }\n  }\n}\n```\n</details>\n\n<details>\n<summary><strong>VS Code</strong></summary>\n\nAdd to `.vscode/mcp.json` (workspace) or your user `mcp.json`:\n\n```json\n{\n  \"servers\": {\n    \"digger\": {\n      \"type\": \"stdio\",\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"mcp-digger\"]\n    }\n  }\n}\n```\n</details>\n\n<details>\n<summary><strong>Cursor</strong></summary>\n\nAdd to `.cursor/mcp.json` (project) or `~/.cursor/mcp.json` (global):\n\n```json\n{\n  \"mcpServers\": {\n    \"digger\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"mcp-digger\"]\n    }\n  }\n}\n```\n</details>\n\n### Verify\n\nOnce connected, ask your agent to call `dig_status` — it reports config validation, per-repo connectivity, and index health.\n\n---\n\n## ⚙ Configuration\n\n### Repos & packages\n\nA `repos[]` entry has three ways to declare packages:\n\n| Option | Behavior |\n|--------|----------|\n| `\"packages\": [\"A\", \"B\"]` | Explicit list — these packages plus any local sibling project they pull in via `<ProjectReference>` (transitive, sibling-only). |\n| `\"packageFilter\": \"MyCompany.*\"` | Wildcard — narrows to packages matching the prefix, found via `.sln`/`.slnx`/`Directory.Packages.props` workspace scan. Follows transitive `ProjectReference` links automatically. |\n| *(omit both)* | Auto-discover all non-test `.csproj` directories under `sourceRoot` (recursive — nested layouts supported). |\n\n`sourceRoot` defaults to `\"src\"` — set it to whichever directory holds your package folders. The walk is recursive, so nested layouts like `src/Group/Foo/Foo.csproj` are picked up.\n\n<details>\n<summary><strong>Branch tracking</strong></summary>\n\nBy default, managed clones use the repo's default branch. Pin to a specific one:\n\n```jsonc\n{\n  \"repos\": [\n    {\n      \"name\": \"my-libraries\",\n      \"url\": \"https://github.com/org/shared-libs.git\",\n      \"branch\": \"develop\"\n    }\n  ]\n}\n```\n\nThe branch is used for both initial clone and subsequent fetches. Only applies to managed clones — for local repos, you control the checked-out branch yourself.\n</details>\n\n<details>\n<summary><strong>Local repos (Mode B)</strong></summary>\n\nSkip managed cloning when the repo is already on disk. The local path is read-only — mcp-digger never fetches or modifies it.\n\n```jsonc\n{\n  \"localRepos\": {\n    \"my-libraries\": \"C:/repos/shared-libs\"\n  },\n  \"repos\": [\n    {\n      \"name\": \"my-libraries\",\n      \"sourceRoot\": \"src\"\n    }\n  ]\n}\n```\n</details>\n\n<details>\n<summary><strong>Auth strategies</strong></summary>\n\n| Strategy | Behavior |\n|----------|----------|\n| `auto` *(default)* | Try unauthenticated, fall back to PAT if set |\n| `pat` | Always use PAT (fatal if not set) |\n| `none` | Never authenticate |\n\nPATs can be inline (`\"PAT\": \"...\"`) or via environment variable indirection (`\"PAT-EnvVarName\": \"MY_TOKEN\"`). The `.env` file in your workspace root is loaded automatically — values containing ` #` should be quoted.\n</details>\n\n<details>\n<summary><strong>Environment variables</strong></summary>\n\n| Variable | Default | Purpose |\n|----------|---------|---------|\n| `DIGGER_CONFIG` | `.digger/config.json` | Override config file path |\n| `MANAGED_SOURCE_DIR` | `.digger/source` | Override managed clone directory |\n| `CACHE_DIR` | `.digger/cache` | Override cache directory |\n\nSecrets (PAT values) belong in `.env` or the real environment — never as env vars in this table.\n</details>\n\n---\n\n## 🩺 Diagnostics & recovery\n\n| Symptom | First call | Then |\n|---------|-----------|------|\n| Connection / auth issues | `dig_status` | Reports auth attempts, exact error, actionable hints |\n| \"No matches\" but you expect some | `dig_refresh <repo>` | Force-rebuilds index, picks up new extraction logic |\n| Server starts but no tools visible | `dig_status` | If unconfigured, only `dig_status` + `dig_init` are registered |\n| Need a config from scratch | `dig_init` | Scaffolds `.digger/config.json` (atomic — won't overwrite existing) |\n\n### Debug log\n\nEnable debug logging in your config:\n\n```jsonc\n{ \"debug\": true, \"repos\": [...] }\n```\n\nLogs go to `.digger/debug.log` (capped at 5 MB, auto-truncated). Critical errors and crash output land in `.digger/error.log`.\n\n---\n\n## 💬 Feedback\n\nTried mcp-digger on your codebase? Share what worked, what broke, what's missing in [GitHub Discussions](https://github.com/janeksm/mcp-digger/discussions). Bug reports go in [Issues](https://github.com/janeksm/mcp-digger/issues).\n\n---\n\n## 📜 License\n\nMIT License — see [LICENSE](LICENSE).\n",
  "bytes": 10512,
  "sha": "3e7b1a557823c7d0e0ab26906fddf1011fb9ca2b08d37f7003bde4887aac1e5a",
  "repo_slug": "janeksm/mcp-digger",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_janeksm_mcp_digger_75d129f5/readme"
}