samber/godig

# godig - 用于 pkg.go.dev 的 CLI 和 MCP 服务器 [](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` 是一个命令行界面（CLI）**和** MCP 服务器，用于通过 [pkg.go.dev](https://pkg.go.dev) API 探索 Go 包和模块：支持搜索、文档、符号、版本、导入者和漏洞——所有这些都可以从你的 shell 或 AI 代理中执行。 它的命令和 MCP 工具建立在小型手写的目录（[`internal/spec`](internal/spec)）之上，并调用强类型的 [`go-pkggodev-client`](https://github.com/samber/go-pkggodev-client)。所有操作均为只读，且无需身份验证。 ## 🚀 安装 ``` 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 # 将 MCP server 注册到 Claude Code (stdio) claude mcp add pkg-go-dev -- godig mcp ``` 需要 Go >= 1.25。请参阅 [Skill](#-skill) 以便同时向你的代理注册 MCP 服务器。 ## 💡 快速开始 ``` # 概述 — 一次紧凑的调用：metadata、最新 + 近期 versions、licenses、vulns godig overview github.com/samber/ro # 搜索 godig search "result option monad" --limit 5 # Package facets godig package info 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 # 单个 symbol 的 signature + doc（与完整 package doc 相比，token 效率更高） godig symbol github.com/samber/ro Map godig symbol github.com/samber/mo Either.ForEach --examples # Module facets godig module info github.com/samber/ro godig module readme github.com/samber/ro godig module licenses github.com/samber/ro # 列表（自动分页；--limit 设置上限，-o md 输出 Markdown table） godig versions github.com/samber/ro -o md godig major-versions github.com/samber/do # v1, v2, v3 ... (separate modules) godig packages github.com/samber/ro godig imported-by github.com/samber/ro --limit 20 godig symbols github.com/samber/ro # Filter（针对 item fields 的 Go 布尔表达式）与构建上下文（goos/goarch） godig versions github.com/samber/ro --filter 'hasPrefix(version, "v0.3")' godig symbols github.com/samber/ro --goos linux --goarch amd64 # 漏洞 godig vulns github.com/samber/ro # 作为 MCP server 运行（stdio；--transport http 用于 HTTP） godig mcp ``` 全局 flag：`-o, --output`（默认为 `table`，可选 `json`、`raw`、`md`），`--base-url`，`--timeout`， `--log-level`（`debug|info|warn|error|off`，默认为 `error`；日志输出到 **stderr**）。 所有 flag 也可以通过以 `GODIG_` 为前缀的环境变量来设置。 ## 🧠 命令 | 命令 | 描述 | | ----------------------------------------- | ------------------------------------ | | `godig overview ` | 一键获取精简摘要（从此处开始） | | `godig search [--symbol ]` | 搜索包和符号 | | `godig package info ` | 包元数据 | | `godig package doc --format ` | 包文档 (md/text/html) | | `godig package examples ` | 带有示例的文档 (`--symbol` 用于指定范围) | | `godig package licenses ` | 包许可证 | | `godig symbol ` | 单个符号的签名和文档 | | `godig module info ` | 模块元数据 | | `godig module licenses ` | 模块许可证 | | `godig module readme ` | 模块 README | | `godig packages ` | 列出模块的包 | | `godig versions ` | 列出模块版本 | | `godig major-versions ` | 列出主要版本 (v1, v2, v3 ...) | | `godig imported-by ` | 导入该包的包 | | `godig symbols ` | 包的导出符号 | | `godig vulns ` | 已知的漏洞 | | `godig mcp` | 运行 MCP 服务器 (stdio 或 http) | 运行 `godig --help`（或 `godig package --help`）以查看特定命令的 flag。每个操作也 作为一个 MCP 工具暴露（例如 `overview`、`package-info`、`module-readme`）。 **对于 AI 代理（高效利用 token）：**从 `overview` 开始——一次调用即可返回精简摘要 （不包含大量文档）。仅在实际需要全文时才获取 `doc`、`examples`、`module readme` 或 `licenses`，并使用 `--limit` 截断过长的列表（如 `versions`、`imported-by`）。 ## 📫 MCP 服务器 `godig mcp` 运行一个 MCP 服务器，通过任一传输方式为每个操作暴露一个只读工具。 **stdio**（默认）—— 客户端按需启动二进制文件： ``` claude mcp add pkg-go-dev -- godig mcp ``` ``` { "mcpServers": { "pkg-go-dev": { "command": "godig", "args": ["mcp"] } } } ``` **流式 HTTP** —— 位于 `/mcp` 的共享、长期运行服务器（`--addr`，默认 `:8080`）： ``` godig mcp --transport http --addr :8080 claude mcp add --transport http pkg-go-dev http://localhost:8080/mcp ``` ``` { "mcpServers": { "pkg-go-dev": { "type": "http", "url": "http://localhost:8080/mcp" } } } ``` 公共实例托管在 [Clever Cloud](https://www.clever.cloud) 上，地址为 **`https://godig.samber.dev/mcp`** —— 无需在本地运行任何内容即可注册： ``` claude mcp add --transport http pkg-go-dev https://godig.samber.dev/mcp ``` ``` { "mcpServers": { "pkg-go-dev": { "type": "http", "url": "https://godig.samber.dev/mcp" } } } ``` ## 🥷 Skill 一个配套的 AI 代理 Skill，**`golang-pkg-go-dev`**，位于 [samber/cc-skills-golang](https://github.com/samber/cc-skills-golang)。它涵盖了设置（注册 MCP 服务器）和使用工作流（意图 -> 命令/工具），并在探索 Go 包时触发：文档、版本、导入者、漏洞。 ``` npx skills add https://github.com/samber/cc-skills-golang --skill golang-pkg-go-dev ``` ## 🔧 工作原理 - `internal/spec` 是一个手写的操作目录（名称、flag、类型）。 - CLI (`cmd/godig`) 和 MCP 服务器 (`internal/mcpserver`) 都通过遍历该目录来构建其功能表面 —— 每个操作对应一个 Cobra 命令和一个 MCP 工具。 - `internal/dispatch` 是共享的核心：它将每个操作名称映射到匹配的、强类型的 [`go-pkggodev-client`](https://github.com/samber/go-pkggodev-client) 调用；结果呈现为 `table`、`json` 或 `raw`。 ## 📝 许可证 Copyright © 2026 [Samuel Berthe](https://github.com/samber)。 本项目基于 [MIT](./LICENSE) 许可证。