{"id":52006244,"url":"https://github.com/samber/godig","last_synced_at":"2026-07-31T15:30:32.411Z","repository":{"id":366395965,"uuid":"1275933813","full_name":"samber/godig","owner":"samber","description":"🔌 CLI \u0026 MCP server for pkg.go.dev","archived":false,"fork":false,"pushed_at":"2026-07-01T11:29:46.000Z","size":100,"stargazers_count":12,"open_issues_count":2,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2026-07-01T13:17:41.745Z","etag":null,"topics":["agent","cli","client","dependencies","doc","go","golang","mcp","module","openapi","package","pkg","skills","symbol","version","vulnerability"],"latest_commit_sha":null,"homepage":"https://godig.samber.dev/mcp","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/samber.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":".github/FUNDING.yml","license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null},"funding":{"github":["samber"],"ko_fi":"samuelberthe"}},"created_at":"2026-06-21T10:27:49.000Z","updated_at":"2026-07-01T09:42:25.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/samber/godig","commit_stats":null,"previous_names":["samber/godig"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/samber/godig","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/samber%2Fgodig","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/samber%2Fgodig/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/samber%2Fgodig/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/samber%2Fgodig/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/samber","download_url":"https://codeload.github.com/samber/godig/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/samber%2Fgodig/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":36123529,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-07-20T02:08:10.276Z","status":"online","status_checked_at":"2026-07-31T02:00:06.731Z","response_time":112,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["agent","cli","client","dependencies","doc","go","golang","mcp","module","openapi","package","pkg","skills","symbol","version","vulnerability"],"created_at":"2026-07-31T15:30:29.941Z","updated_at":"2026-07-31T15:30:32.399Z","avatar_url":"https://github.com/samber.png","language":"Go","funding_links":["https://github.com/sponsors/samber","https://ko-fi.com/samuelberthe"],"categories":[],"sub_categories":[],"readme":"\n# godig - CLI \u0026 MCP server for pkg.go.dev\n\n[![tag](https://img.shields.io/github/tag/samber/godig.svg)](https://github.com/samber/godig/releases)\n![Go Version](https://img.shields.io/badge/Go-%3E%3D%201.25-%23007d9c)\n[![GoDoc](https://godoc.org/github.com/samber/godig?status.svg)](https://pkg.go.dev/github.com/samber/godig)\n![Build Status](https://github.com/samber/godig/actions/workflows/test.yml/badge.svg)\n[![Go report](https://goreportcard.com/badge/github.com/samber/godig)](https://goreportcard.com/report/github.com/samber/godig)\n[![Contributors](https://img.shields.io/github/contributors/samber/godig)](https://github.com/samber/godig/graphs/contributors)\n[![License](https://img.shields.io/github/license/samber/godig)](./LICENSE)\n\n`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.\n\nIts 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.\n\n\u003e [!TIP]\n\u003e 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`.\n\n\u003cimg width=\"3808\" height=\"1280\" alt=\"image\" src=\"https://github.com/user-attachments/assets/d7a76b36-d298-4b5c-a136-ef739e89816d\" /\u003e\n\n## 🚀 Install\n\n```sh\ngo install github.com/samber/godig/cmd/godig@latest\n\n# AI Agent Skill:\nnpx skills add https://github.com/samber/cc-skills-golang --skill golang-pkg-go-dev\n\n# Register the MCP server into Claude Code (stdio)\nclaude mcp add pkg-go-dev -- godig mcp\n```\n\nRequires Go \u003e= 1.25. See [Skill](#-skill) to also register the MCP server with your agent.\n\n## 💡 Quick start\n\n```sh\n# Overview — one compact call: metadata, latest + recent versions, licenses, vulns\ngodig overview github.com/samber/ro\n\n# Search\ngodig search \"result option monad\" --limit 5\n\n# Package facets\ngodig package info github.com/samber/ro\ngodig package imports github.com/samber/ro\ngodig package doc github.com/samber/ro --format md\ngodig package examples github.com/samber/ro\ngodig package examples github.com/samber/ro --symbol Map   # examples for one symbol only\ngodig package licenses github.com/samber/ro\n\n# Single symbol (token-efficient vs the full package doc/examples)\ngodig symbol doc github.com/samber/ro Map\ngodig symbol examples github.com/samber/mo Either.ForEach\n\n# Module facets\ngodig module info github.com/samber/ro            # incl. download size + min Go version\ngodig module readme github.com/samber/ro\ngodig module licenses github.com/samber/ro\ngodig dependencies github.com/samber/oops         # go.mod requires/replaces/excludes\n\n# Lists (auto-paginated; --limit to cap, -o md for a Markdown table)\ngodig versions github.com/samber/ro -o md\ngodig major-versions github.com/samber/do        # v1, v2, v3 ... (separate modules)\ngodig major-versions github.com/samber/do --exclude-pseudo   # drop majors whose latest is a pseudo-version\ngodig packages github.com/samber/ro\ngodig imported-by github.com/samber/ro --limit 20\ngodig symbols github.com/samber/ro\n\n# Filter (a Go boolean expression over item fields) and build context (goos/goarch)\ngodig versions github.com/samber/ro --filter 'hasPrefix(version, \"v0.3\")'\ngodig symbols github.com/samber/ro --goos linux --goarch amd64\n\n# Vulnerabilities\ngodig vulns github.com/samber/ro\n\n# Run as an MCP server (stdio; --transport http for HTTP)\ngodig mcp\n```\n\nGlobal flags: `-o, --output` (`table` default, `json`, `raw`, `md`), `--base-url`,\n`--vuln-base-url` (Go vulnerability database, default `https://vuln.go.dev`), `--timeout`,\n`--log-level` (`debug|info|warn|error|off`, default `error`; logs go to **stderr**).\nAll flags can also be set via `GODIG_`-prefixed environment variables.\n\nExit codes: `0` success, `1` runtime error (e.g. network, package not found), `2` usage error\n(missing/invalid arguments or flags, or a group invoked without a subcommand).\n\n## 🧠 Commands\n\n| Command                                   | Description                          |\n| ----------------------------------------- | ------------------------------------ |\n| `godig overview \u003cpath\u003e`                   | One-call compact summary (start here)|\n| `godig search \u003cquery\u003e [--symbol \u003cs\u003e]`     | Search packages and symbols          |\n| `godig package info \u003cpath\u003e`               | Package metadata                     |\n| `godig package imports \u003cpath\u003e`            | Packages that a package imports      |\n| `godig package doc \u003cpath\u003e --format \u003cfmt\u003e` | Package documentation (md/text/html) |\n| `godig package examples \u003cpath\u003e`           | Documentation with examples (`--symbol` to scope) |\n| `godig package licenses \u003cpath\u003e`           | Package licenses                     |\n| `godig symbol doc \u003cpath\u003e \u003csymbol\u003e`        | One symbol's signature + doc         |\n| `godig symbol examples \u003cpath\u003e \u003csymbol\u003e`   | One symbol's runnable examples       |\n| `godig module info \u003cpath\u003e`                | Module metadata (incl. size + min Go version) |\n| `godig module licenses \u003cpath\u003e`            | Module licenses                      |\n| `godig module readme \u003cpath\u003e`              | Module README                        |\n| `godig dependencies \u003cmodule\u003e`             | Module dependencies from its go.mod  |\n| `godig packages \u003cmodule\u003e`                 | List a module's packages             |\n| `godig versions \u003cmodule\u003e`                 | List module versions                 |\n| `godig major-versions \u003cmodule\u003e`           | List major versions (v1, v2, v3 ...) |\n| `godig imported-by \u003cpath\u003e`                | Packages that import a package       |\n| `godig symbols \u003cpath\u003e`                    | Exported symbols of a package        |\n| `godig vulns \u003cpath\u003e`                      | Known vulnerabilities                |\n| `godig mcp`                               | Run the MCP server (stdio or http)   |\n\nRun `godig \u003ccommand\u003e --help` (or `godig package --help`) for per-command flags. Each operation is\nalso exposed as an MCP tool (e.g. `overview`, `package-info`, `module-readme`). Utility commands:\n`godig version` and `godig completion \u003cshell\u003e` (bash/zsh/fish/powershell).\n\n**For AI agents (token-efficient):** start with `overview` — one call returns a compact summary\n(no large docs). Fetch `doc`, `examples`, `module readme` or `licenses` only when the full text is\nactually needed, and cap long lists (`versions`, `imported-by`) with `--limit`.\n\n## 🔎 Filters\n\nThe `--filter` flag (on `search`, `versions`, `packages`, `imported-by`, `symbols`,\n`major-versions`) takes a **Go boolean expression** evaluated server-side over each item. The\nidentifiers are the item's fields — which **differ per command**, so a field valid for one list is\nnot valid for another (e.g. `search` exposes `packagePath`, not `path`). Helper functions include\n`hasPrefix`, `hasSuffix` and `contains`.\n\n```sh\ngodig search \"result option\" --filter 'hasPrefix(packagePath, \"github.com/samber/\")'\ngodig versions github.com/samber/ro --filter 'hasPrefix(version, \"v0.3\")'\ngodig symbols github.com/samber/ro  --filter 'kind == \"Function\"'\ngodig imported-by github.com/samber/ro --filter 'contains(path, \"/internal/\")'\n```\n\nAvailable fields per command (string unless noted):\n\n| Command          | Filterable fields                                                                 |\n| ---------------- | --------------------------------------------------------------------------------- |\n| `search`         | `modulePath`, `packagePath`, `synopsis`, `version`                                 |\n| `versions`       | `version`, `modulePath`, `deprecated` (bool), `retracted` (bool), `hasGoMod` (bool), `commitTime` |\n| `packages`       | `path`, `name`, `synopsis`, `isRedistributable` (bool)                             |\n| `imported-by`    | `path` (the importing package path)                                                |\n| `symbols`        | `name`, `kind` (`Function`/`Method`/`Type`/`Variable`/`Constant`), `synopsis`, `parent` |\n| `major-versions` | `modulePath`, `major`, `version`, `isLatest` (bool)                                |\n\n\u003e [!NOTE]\n\u003e Identifiers follow the pkg.go.dev API's filter schema, using the lowercase JSON field name.\n\u003e `kind` values are capitalized (`Function`, not `func`). An unknown identifier is rejected\n\u003e by the API with `HTTP 400 undefined identifier: \u003cname\u003e`, which names the offending field.\n\n## 📫 MCP server\n\n`godig mcp` runs an MCP server exposing one read-only tool per operation, over either transport.\n\n**stdio** (default) — the client launches the binary on demand:\n\n```sh\nclaude mcp add pkg-go-dev -- godig mcp\n```\n\n```json\n{ \"mcpServers\": { \"pkg-go-dev\": { \"command\": \"godig\", \"args\": [\"mcp\"] } } }\n```\n\n**streamable HTTP** — a shared, long-running server at `/mcp` (`--addr`, default `:8080`):\n\n```sh\ngodig mcp --transport http --addr :8080\nclaude mcp add --transport http pkg-go-dev http://localhost:8080/mcp\n```\n\n```json\n{ \"mcpServers\": { \"pkg-go-dev\": { \"type\": \"http\", \"url\": \"http://localhost:8080/mcp\" } } }\n```\n\nA public instance is hosted on [Clever Cloud](https://www.clever.cloud) at **`https://godig.samber.dev/mcp`** — register it without running anything locally:\n\n```sh\nclaude mcp add --transport http pkg-go-dev https://godig.samber.dev/mcp\n```\n\n```json\n{ \"mcpServers\": { \"pkg-go-dev\": { \"type\": \"http\", \"url\": \"https://godig.samber.dev/mcp\" } } }\n```\n\n## 🥷 Skill\n\nA 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.\n\n```sh\nnpx skills add https://github.com/samber/cc-skills-golang --skill golang-pkg-go-dev\n```\n\n## 🔧 How it works\n\n- `internal/spec` is a hand-written catalog of the operations (name, flags, types).\n- 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.\n- `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`.\n\n## 🤝 Contributing\n\n```sh\n# Install dev dependencies\nmake tools\n\n# Run tests\nmake test\n\n# Lint\nmake lint\n\n# Build (with version ldflags)\nmake build\n```\n\n## 👤 Contributors\n\n![Contributors](https://contrib.rocks/image?repo=samber/godig)\n\n## 🙏 Acknowledgements\n\nThanks to [Clever Cloud](https://www.clever.cloud) for hosting the public `godig.samber.dev` MCP server.\n\n## 💫 Show your support\n\nGive a ⭐️ if this project helped you!\n\n[![GitHub Sponsors](https://img.shields.io/github/sponsors/samber?style=for-the-badge)](https://github.com/sponsors/samber)\n\n## 📝 License\n\nCopyright © 2026 [Samuel Berthe](https://github.com/samber).\n\nThis project is [MIT](./LICENSE) licensed.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsamber%2Fgodig","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsamber%2Fgodig","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsamber%2Fgodig/lists"}