# Godig

> 🔌 CLI & MCP server for pkg.go.dev

- **Type:** MCP server
- **Install:** `agentstack add mcp-samber-godig`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [samber](https://agentstack.voostack.com/s/samber)
- **Installs:** 0
- **Category:** [Security](https://agentstack.voostack.com/c/security)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [samber](https://github.com/samber)
- **Source:** https://github.com/samber/godig
- **Website:** https://godig.samber.dev/mcp

## Install

```sh
agentstack add mcp-samber-godig
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

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

## Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [samber](https://github.com/samber)
- **Source:** [samber/godig](https://github.com/samber/godig)
- **License:** MIT
- **Homepage:** https://godig.samber.dev/mcp

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/mcp-samber-godig
- Seller: https://agentstack.voostack.com/s/samber
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.