https://github.com/samber/godig
🔌 CLI & MCP server for pkg.go.dev
https://github.com/samber/godig
agent cli client dependencies doc go golang mcp module openapi package pkg skills symbol version vulnerability
Last synced: 9 days ago
JSON representation
🔌 CLI & MCP server for pkg.go.dev
- Host: GitHub
- URL: https://github.com/samber/godig
- Owner: samber
- License: mit
- Created: 2026-06-21T10:27:49.000Z (about 2 months ago)
- Default Branch: main
- Last Pushed: 2026-07-01T11:29:46.000Z (about 1 month ago)
- Last Synced: 2026-07-01T13:17:41.745Z (about 1 month ago)
- Topics: agent, cli, client, dependencies, doc, go, golang, mcp, module, openapi, package, pkg, skills, symbol, version, vulnerability
- Language: Go
- Homepage: https://godig.samber.dev/mcp
- Size: 97.7 KB
- Stars: 12
- Watchers: 0
- Forks: 0
- Open Issues: 2
-
Metadata Files:
- Readme: README.md
- Funding: .github/FUNDING.yml
- License: LICENSE
Awesome Lists containing this project
README
# godig - CLI & MCP server for pkg.go.dev
[](https://github.com/samber/godig/releases)
[](https://pkg.go.dev/github.com/samber/godig)
[](https://goreportcard.com/report/github.com/samber/godig)
[](https://github.com/samber/godig/graphs/contributors)
[](./LICENSE)
`godig` is a CLI **and** an MCP server for exploring Go packages and modules via the [pkg.go.dev](https://pkg.go.dev) API: search, documentation, symbols, versions, importers and vulnerabilities — from your shell or from an AI agent.
Its commands and MCP tools are built from a small hand-written catalog ([`internal/spec`](internal/spec)) and call the typed [`go-pkggodev-client`](https://github.com/samber/go-pkggodev-client). All operations are read-only and need no authentication.
> [!TIP]
> Looking for a **Go library** instead of a CLI? Use [`samber/go-pkggodev-client`](https://github.com/samber/go-pkggodev-client) — the typed pkg.go.dev client that powers `godig`.
## 🚀 Install
```sh
go install github.com/samber/godig/cmd/godig@latest
# AI Agent Skill:
npx skills add https://github.com/samber/cc-skills-golang --skill golang-pkg-go-dev
# Register the MCP server into Claude Code (stdio)
claude mcp add pkg-go-dev -- godig mcp
```
Requires Go >= 1.25. See [Skill](#-skill) to also register the MCP server with your agent.
## 💡 Quick start
```sh
# Overview — one compact call: metadata, latest + recent versions, licenses, vulns
godig overview github.com/samber/ro
# Search
godig search "result option monad" --limit 5
# Package facets
godig package info github.com/samber/ro
godig package imports github.com/samber/ro
godig package doc github.com/samber/ro --format md
godig package examples github.com/samber/ro
godig package examples github.com/samber/ro --symbol Map # examples for one symbol only
godig package licenses github.com/samber/ro
# Single symbol (token-efficient vs the full package doc/examples)
godig symbol doc github.com/samber/ro Map
godig symbol examples github.com/samber/mo Either.ForEach
# Module facets
godig module info github.com/samber/ro # incl. download size + min Go version
godig module readme github.com/samber/ro
godig module licenses github.com/samber/ro
godig dependencies github.com/samber/oops # go.mod requires/replaces/excludes
# Lists (auto-paginated; --limit to cap, -o md for a Markdown table)
godig versions github.com/samber/ro -o md
godig major-versions github.com/samber/do # v1, v2, v3 ... (separate modules)
godig major-versions github.com/samber/do --exclude-pseudo # drop majors whose latest is a pseudo-version
godig packages github.com/samber/ro
godig imported-by github.com/samber/ro --limit 20
godig symbols github.com/samber/ro
# Filter (a Go boolean expression over item fields) and build context (goos/goarch)
godig versions github.com/samber/ro --filter 'hasPrefix(version, "v0.3")'
godig symbols github.com/samber/ro --goos linux --goarch amd64
# Vulnerabilities
godig vulns github.com/samber/ro
# Run as an MCP server (stdio; --transport http for HTTP)
godig mcp
```
Global flags: `-o, --output` (`table` default, `json`, `raw`, `md`), `--base-url`,
`--vuln-base-url` (Go vulnerability database, default `https://vuln.go.dev`), `--timeout`,
`--log-level` (`debug|info|warn|error|off`, default `error`; logs go to **stderr**).
All flags can also be set via `GODIG_`-prefixed environment variables.
Exit codes: `0` success, `1` runtime error (e.g. network, package not found), `2` usage error
(missing/invalid arguments or flags, or a group invoked without a subcommand).
## 🧠 Commands
| Command | Description |
| ----------------------------------------- | ------------------------------------ |
| `godig overview ` | One-call compact summary (start here)|
| `godig search [--symbol ]` | Search packages and symbols |
| `godig package info ` | Package metadata |
| `godig package imports ` | Packages that a package imports |
| `godig package doc --format ` | Package documentation (md/text/html) |
| `godig package examples ` | Documentation with examples (`--symbol` to scope) |
| `godig package licenses ` | Package licenses |
| `godig symbol doc ` | One symbol's signature + doc |
| `godig symbol examples ` | One symbol's runnable examples |
| `godig module info ` | Module metadata (incl. size + min Go version) |
| `godig module licenses ` | Module licenses |
| `godig module readme ` | Module README |
| `godig dependencies ` | Module dependencies from its go.mod |
| `godig packages ` | List a module's packages |
| `godig versions ` | List module versions |
| `godig major-versions ` | List major versions (v1, v2, v3 ...) |
| `godig imported-by ` | Packages that import a package |
| `godig symbols ` | Exported symbols of a package |
| `godig vulns ` | Known vulnerabilities |
| `godig mcp` | Run the MCP server (stdio or http) |
Run `godig --help` (or `godig package --help`) for per-command flags. Each operation is
also exposed as an MCP tool (e.g. `overview`, `package-info`, `module-readme`). Utility commands:
`godig version` and `godig completion ` (bash/zsh/fish/powershell).
**For AI agents (token-efficient):** start with `overview` — one call returns a compact summary
(no large docs). Fetch `doc`, `examples`, `module readme` or `licenses` only when the full text is
actually needed, and cap long lists (`versions`, `imported-by`) with `--limit`.
## 🔎 Filters
The `--filter` flag (on `search`, `versions`, `packages`, `imported-by`, `symbols`,
`major-versions`) takes a **Go boolean expression** evaluated server-side over each item. The
identifiers are the item's fields — which **differ per command**, so a field valid for one list is
not valid for another (e.g. `search` exposes `packagePath`, not `path`). Helper functions include
`hasPrefix`, `hasSuffix` and `contains`.
```sh
godig search "result option" --filter 'hasPrefix(packagePath, "github.com/samber/")'
godig versions github.com/samber/ro --filter 'hasPrefix(version, "v0.3")'
godig symbols github.com/samber/ro --filter 'kind == "Function"'
godig imported-by github.com/samber/ro --filter 'contains(path, "/internal/")'
```
Available fields per command (string unless noted):
| Command | Filterable fields |
| ---------------- | --------------------------------------------------------------------------------- |
| `search` | `modulePath`, `packagePath`, `synopsis`, `version` |
| `versions` | `version`, `modulePath`, `deprecated` (bool), `retracted` (bool), `hasGoMod` (bool), `commitTime` |
| `packages` | `path`, `name`, `synopsis`, `isRedistributable` (bool) |
| `imported-by` | `path` (the importing package path) |
| `symbols` | `name`, `kind` (`Function`/`Method`/`Type`/`Variable`/`Constant`), `synopsis`, `parent` |
| `major-versions` | `modulePath`, `major`, `version`, `isLatest` (bool) |
> [!NOTE]
> Identifiers follow the pkg.go.dev API's filter schema, using the lowercase JSON field name.
> `kind` values are capitalized (`Function`, not `func`). An unknown identifier is rejected
> by the API with `HTTP 400 undefined identifier: `, which names the offending field.
## 📫 MCP server
`godig mcp` runs an MCP server exposing one read-only tool per operation, over either transport.
**stdio** (default) — the client launches the binary on demand:
```sh
claude mcp add pkg-go-dev -- godig mcp
```
```json
{ "mcpServers": { "pkg-go-dev": { "command": "godig", "args": ["mcp"] } } }
```
**streamable HTTP** — a shared, long-running server at `/mcp` (`--addr`, default `:8080`):
```sh
godig mcp --transport http --addr :8080
claude mcp add --transport http pkg-go-dev http://localhost:8080/mcp
```
```json
{ "mcpServers": { "pkg-go-dev": { "type": "http", "url": "http://localhost:8080/mcp" } } }
```
A public instance is hosted on [Clever Cloud](https://www.clever.cloud) at **`https://godig.samber.dev/mcp`** — register it without running anything locally:
```sh
claude mcp add --transport http pkg-go-dev https://godig.samber.dev/mcp
```
```json
{ "mcpServers": { "pkg-go-dev": { "type": "http", "url": "https://godig.samber.dev/mcp" } } }
```
## 🥷 Skill
A companion AI-agent skill, **`golang-pkg-go-dev`**, lives in [samber/cc-skills-golang](https://github.com/samber/cc-skills-golang). It covers both setup (registering the MCP server) and usage workflows (intent → command/tool), and triggers when exploring Go packages: docs, versions, importers, vulnerabilities.
```sh
npx skills add https://github.com/samber/cc-skills-golang --skill golang-pkg-go-dev
```
## 🔧 How it works
- `internal/spec` is a hand-written catalog of the operations (name, flags, types).
- The CLI (`cmd/godig`) and the MCP server (`internal/mcpserver`) both build their surface by looping over that catalog — one Cobra command and one MCP tool per operation.
- `internal/dispatch` is the shared core: it maps each operation name to the matching typed [`go-pkggodev-client`](https://github.com/samber/go-pkggodev-client) call; results render as `table`, `json` or `raw`.
## 🤝 Contributing
```sh
# Install dev dependencies
make tools
# Run tests
make test
# Lint
make lint
# Build (with version ldflags)
make build
```
## 👤 Contributors
## 🙏 Acknowledgements
Thanks to [Clever Cloud](https://www.clever.cloud) for hosting the public `godig.samber.dev` MCP server.
## 💫 Show your support
Give a ⭐️ if this project helped you!
[](https://github.com/sponsors/samber)
## 📝 License
Copyright © 2026 [Samuel Berthe](https://github.com/samber).
This project is [MIT](./LICENSE) licensed.