godoccli

godoccli is a Go library and command-line tool designed to fetch, parse, and display Go documentation and source code for any package. It can retrieve information from your local Go environment or fetch specific versions of packages from a Go module proxy, making it a powerful tool for developers and documentation systems.

It can be used directly as a command-line tool or integrated into your Go projects as a library.

Command-Line Tool (godocmcp)

The godocmcp application runs an MCP server that exposes the core features of godoccli as callable tools. This is the quickest way to use godoccli's functionality from the terminal or other scripts.

Installation

To install the godocmcp command-line tool, run the following command:

go install github.com/samuelncui/godoccli/cmd/godocmcp@latest

This will download the source, compile it, and place the godocmcp executable in your Go bin directory ($GOPATH/bin).

Usage

You can run the server directly from your terminal. It accepts the following flags:

• -proxy <URL>: Sets the Go proxy URL to use. Defaults to https://proxy.golang.org.
• -verbose: Enables detailed logging for debugging purposes.

Example:

# Run the server with verbose logging
godocmcp -verbose

Exposed Tools

The server makes the following tools available for interaction:

1. show

   • Description: Retrieves and formats the documentation for a Go package or a specific symbol within it (like a function or type). It supports fetching specific versions, e.g., "github.com/gorilla/[email protected]" for third-party packages or "[email protected]" for the standard library.
   • Arguments:
     • path (string, required): The import path of the package.
     • symbol (string): The symbol to document. If omitted, it returns documentation for the whole package.
     • show_unexported (boolean): If true, includes documentation for unexported symbols.

2. read_src

   • Description: Fetches and formats the source code of a specific file within a Go package. Supports versioning and line-based slicing of the file content.
   • Arguments:
     • path (string, required): The full path to the source file, including package and version.
     • show_line_number (boolean): If true, adds line numbers to the output. Defaults to false.
     • limit (number): The maximum number of lines to return. Defaults to 50.
     • offset (number): The 0-indexed line number to start reading from. Defaults to 0.

3. list_src

   • Description: Lists all source files and directories within a given Go package.
   • Arguments:
     • path (string, required): The import path of the package or directory to list.

As a Library

You can also use godoccli directly in your Go applications to programmatically fetch documentation and source code.

Installation

To use godoccli as a library, add it to your project using go get:

go get github.com/samuelncui/godoccli

Usage

Here is a basic example of how to use the client to fetch documentation and source code.

package main

import (
	"fmt"
	"log"

	"github.com/samuelncui/godoccli"
)

func main() {
	// Initialize a new client.
	// You can customize it with options, such as forcing it to only use the remote proxy.
	client, err := godoccli.NewCli(godoccli.WithGoProxyURL("https://proxy.golang.org"), godoccli.WithRemoteOnly(true))
	if err != nil {
		log.Fatalf("Failed to create Cli client: %v", err)
	}
	defer client.Close() // Clean up the cache directory on exit

	// --- Example 1: Show documentation for a specific function ---
	fmt.Println("--- Doc for 'http.ListenAndServe' ---")
	showFuncResp, err := client.Show(&godoccli.ShowReq{Path: "net/http", Symbol: "ListenAndServe"})
	if err != nil {
		log.Printf("Show function 'http.ListenAndServe' failed: %v\n", err)
	} else {
		fmt.Println(showFuncResp.Doc)
	}
	fmt.Println("\n--------------------------------------------------\n")

	// --- Example 2: Show source code for a specific file version ---
	fmt.Println("--- Src for 'net/[email protected]/server.go' (lines 150-160) ---")
	srcReq := &godoccli.ReadSrcReq{
		Path:           "net/[email protected]/server.go",
		ShowLineNumber: true,
		Limit:          10,
		Offset:         149, // Line numbers are 1-based, offset is 0-based
	}
	srcResp, err := client.ReadSrc(srcReq)
	if err != nil {
		log.Printf("Src for 'net/http/server.go' failed: %v\n", err)
	} else {
		fmt.Println(srcResp.Source)
	}
}

API Overview

The godoccli client exposes three primary methods:

• Show(*ShowReq) (*ShowResp, error): Retrieves documentation for a package or a specific symbol.
• ReadSrc(*ReadSrcReq) (*ReadSrcResp, error): Retrieves the source code of a file.
• ListSrc(*ListSrcReq) (*ListSrcResp, error): Lists the contents of a package directory.

License

This project is licensed under the MIT License. See the LICENSE file for details.