fix(main): only trust build version when major matches module path

debug.ReadBuildInfo() can report a version whose major version does
not match the module path's major version suffix (e.g. a v2 tag on a
module without a /v2 path), which is unreliable per Go's module
versioning rules. Extract the decision into resolveVersion() and only
accept the build version when its major matches the module path's
implied major version, otherwise fall back to the dev version.

Fixes #231.

Co-Authored-By: Codet <codet@commitgo.dev> (GPT-5-Codex)

README.md

@@ -20,14 +20,6 @@ make install
 
 Pass the Gitea host and access token as command-line flags or environment variables, flags take precedence. Run `gitea-mcp --help` for the full list of flags and environment variables. Logs are written to `$HOME/.gitea-mcp/gitea-mcp.log`, add `-d` for debug logging.
 
-Set `GITEA_EXTRA_HEADERS` to a JSON object of header name/value pairs to send with every outbound request to Gitea, for example when Gitea sits behind Cloudflare Access:
-
-```bash
-export GITEA_EXTRA_HEADERS='{"CF-Access-Client-Id":"id","CF-Access-Client-Secret":"secret"}'
-```
-
-These headers never override `Authorization`, `Content-Type`, or `Accept` set by `gitea-mcp` itself.
-
 ### MCP protocol and HTTP transport
 
 The server supports MCP up to `2026-07-28` and negotiates down to the client's version, advertising only the `tools` capability. Tool and Gitea failures return a `tools/call` result with `result.isError: true`, while malformed requests and server faults stay JSON-RPC errors.

cmd/cmd.go

@@ -2,11 +2,9 @@ package cmd
 
 import (
 	"context"
-	"encoding/json"
 	"flag"
 	"fmt"
 	"io"
-	"net/http"
 	"os"
 	"strconv"
 	"strings"
@@ -88,7 +86,6 @@ func initFlagSet(fs *flag.FlagSet, args []string, getenv func(string) string, re
 		fmt.Fprintf(w, "  GITEA_ACCESS_TOKEN\tProvide access token\n")
 		fmt.Fprintf(w, "  GITEA_ACCESS_TOKEN_FILE\tPath to a file containing the access token (e.g. a Docker secret)\n")
 		fmt.Fprintf(w, "  GITEA_DEBUG\tSet to 'true' for debug mode\n")
-		fmt.Fprintf(w, "  GITEA_EXTRA_HEADERS\tJSON object of extra HTTP headers to send with Gitea API requests\n")
 		fmt.Fprintf(w, "  GITEA_HOST\tOverride Gitea host URL\n")
 		fmt.Fprintf(w, "  GITEA_INSECURE\tSet to 'true' to ignore TLS errors\n")
 		fmt.Fprintf(w, "  GITEA_MAX_INLINE_ATTACHMENT_BYTES\tOverride inline image attachment size limit in bytes\n")
@@ -167,18 +164,6 @@ func initFlagSet(fs *flag.FlagSet, args []string, getenv func(string) string, re
 			flagPkg.MaxInlineAttachmentBytes = parsed
 		}
 	}
-	if val := getenv("GITEA_EXTRA_HEADERS"); val != "" {
-		var headers map[string]string
-		if err := json.Unmarshal([]byte(val), &headers); err != nil {
-			fmt.Fprintf(stderr, "invalid GITEA_EXTRA_HEADERS: %v\n", err)
-			osExit(1)
-		}
-		extraHeaders := make(http.Header, len(headers))
-		for name, value := range headers {
-			extraHeaders.Set(name, value)
-		}
-		flagPkg.ExtraHeaders = extraHeaders
-	}
 }
 
 // normalizeScope trims whitespace, lowercases, and converts internal spaces

cmd/cmd_test.go

@@ -5,7 +5,6 @@ import (
 	"flag"
 	"maps"
 	"slices"
-	"strings"
 	"testing"
 
 	flagPkg "gitea.com/gitea/gitea-mcp/pkg/flag"
@@ -96,54 +95,3 @@ func TestInitFlagSetScopes(t *testing.T) {
 		})
 	}
 }
-
-func TestInitFlagSetExtraHeaders(t *testing.T) {
-	t.Cleanup(func() { flagPkg.ExtraHeaders = nil })
-
-	getenv := func(key string) string {
-		if key == "GITEA_EXTRA_HEADERS" {
-			return `{"CF-Access-Client-Id":"id","CF-Access-Client-Secret":"secret"}`
-		}
-		return ""
-	}
-	readFile := func(string) ([]byte, error) { return nil, nil }
-	fs := flag.NewFlagSet("test", flag.ContinueOnError)
-	var stderr bytes.Buffer
-
-	initFlagSet(fs, []string{}, getenv, readFile, &stderr)
-
-	if got := flagPkg.ExtraHeaders.Get("CF-Access-Client-Id"); got != "id" {
-		t.Errorf("ExtraHeaders[CF-Access-Client-Id] = %q, want %q", got, "id")
-	}
-	if got := flagPkg.ExtraHeaders.Get("CF-Access-Client-Secret"); got != "secret" {
-		t.Errorf("ExtraHeaders[CF-Access-Client-Secret] = %q, want %q", got, "secret")
-	}
-}
-
-func TestInitFlagSetExtraHeadersInvalidJSON(t *testing.T) {
-	t.Cleanup(func() { flagPkg.ExtraHeaders = nil })
-
-	origOsExit := osExit
-	var exitCode int
-	osExit = func(code int) { exitCode = code }
-	t.Cleanup(func() { osExit = origOsExit })
-
-	getenv := func(key string) string {
-		if key == "GITEA_EXTRA_HEADERS" {
-			return `not-json`
-		}
-		return ""
-	}
-	readFile := func(string) ([]byte, error) { return nil, nil }
-	fs := flag.NewFlagSet("test", flag.ContinueOnError)
-	var stderr bytes.Buffer
-
-	initFlagSet(fs, []string{}, getenv, readFile, &stderr)
-
-	if exitCode != 1 {
-		t.Errorf("exitCode = %d, want 1", exitCode)
-	}
-	if !strings.Contains(stderr.String(), "GITEA_EXTRA_HEADERS") {
-		t.Errorf("stderr = %q, want mention of GITEA_EXTRA_HEADERS", stderr.String())
-	}
-}

main.go

@@ -1,7 +1,10 @@
 package main
 
 import (
+	"path"
 	"runtime/debug"
+	"strconv"
+	"strings"
 
 	"gitea.com/gitea/gitea-mcp/cmd"
 	"gitea.com/gitea/gitea-mcp/pkg/flag"
@@ -11,13 +14,65 @@ var Version = "dev"
 
 func init() {
 	if Version == "dev" {
-		if info, ok := debug.ReadBuildInfo(); ok && info.Main.Version != "" && info.Main.Version != "(devel)" {
-			Version = info.Main.Version
+		if info, ok := debug.ReadBuildInfo(); ok {
+			Version = resolveVersion(Version, info)
 		}
 	}
 	flag.Version = Version
 }
 
+// resolveVersion returns the version reported by debug.ReadBuildInfo when its
+// major version matches the major version encoded in the module path (e.g.
+// "/v2" suffix). Otherwise it falls back to devVersion, since Go's module
+// versioning rules make a mismatched major version untrustworthy (see #231).
+func resolveVersion(devVersion string, info *debug.BuildInfo) string {
+	if info == nil {
+		return devVersion
+	}
+	buildVersion := info.Main.Version
+	if buildVersion == "" || buildVersion == "(devel)" {
+		return devVersion
+	}
+
+	buildMajor := majorVersionOf(buildVersion)
+	pathMajor := majorVersionFromModulePath(info.Main.Path)
+	if buildMajor != pathMajor {
+		return devVersion
+	}
+
+	return buildVersion
+}
+
+// majorVersionOf extracts the numeric major version from a semver-like
+// string such as "v1.2.3", returning 0 if it cannot be parsed.
+func majorVersionOf(version string) int {
+	version = strings.TrimPrefix(version, "v")
+	dot := strings.IndexByte(version, '.')
+	if dot >= 0 {
+		version = version[:dot]
+	}
+	major, err := strconv.Atoi(version)
+	if err != nil {
+		return 0
+	}
+	return major
+}
+
+// majorVersionFromModulePath returns the major version encoded in a module
+// path's "/vN" suffix, or 1 if the module path has no such suffix (as is the
+// case for v0 and v1 modules).
+func majorVersionFromModulePath(modulePath string) int {
+	suffix := path.Base(modulePath)
+	if len(suffix) < 2 || suffix[0] != 'v' {
+		return 1
+	}
+	major, err := strconv.Atoi(suffix[1:])
+	if err != nil {
+		return 1
+	}
+	return major
+}
+
 func main() {
 	cmd.Execute()
 }

main_test.go

@@ -0,0 +1,61 @@
+package main
+
+import (
+	"runtime/debug"
+	"testing"
+)
+
+func TestResolveVersion(t *testing.T) {
+	cases := []struct {
+		name string
+		dev  string
+		info *debug.BuildInfo
+		want string
+	}{
+		{
+			name: "nil build info falls back to dev version",
+			dev:  "dev",
+			info: nil,
+			want: "dev",
+		},
+		{
+			name: "devel version falls back to dev version",
+			dev:  "dev",
+			info: &debug.BuildInfo{Main: debug.Module{Path: "gitea.com/gitea/gitea-mcp", Version: "(devel)"}},
+			want: "dev",
+		},
+		{
+			name: "empty version falls back to dev version",
+			dev:  "dev",
+			info: &debug.BuildInfo{Main: debug.Module{Path: "gitea.com/gitea/gitea-mcp", Version: ""}},
+			want: "dev",
+		},
+		{
+			name: "v1 version accepted for module path without major suffix",
+			dev:  "dev",
+			info: &debug.BuildInfo{Main: debug.Module{Path: "gitea.com/gitea/gitea-mcp", Version: "v1.2.3"}},
+			want: "v1.2.3",
+		},
+		{
+			name: "v2 version rejected when module path has no /v2 suffix",
+			dev:  "dev",
+			info: &debug.BuildInfo{Main: debug.Module{Path: "gitea.com/gitea/gitea-mcp", Version: "v2.0.0"}},
+			want: "dev",
+		},
+		{
+			name: "v2 version accepted when module path has /v2 suffix",
+			dev:  "dev",
+			info: &debug.BuildInfo{Main: debug.Module{Path: "gitea.com/gitea/gitea-mcp/v2", Version: "v2.0.0"}},
+			want: "v2.0.0",
+		},
+	}
+
+	for _, tc := range cases {
+		t.Run(tc.name, func(t *testing.T) {
+			got := resolveVersion(tc.dev, tc.info)
+			if got != tc.want {
+				t.Errorf("resolveVersion(%q, %+v) = %q, want %q", tc.dev, tc.info, got, tc.want)
+			}
+		})
+	}
+}

pkg/flag/flag.go

@@ -1,7 +1,5 @@
 package flag
 
-import "net/http"
-
 var (
 	Host    string
 	Bind    string
@@ -17,5 +15,4 @@ var (
 	Debug         bool
 	AllowedTools  map[string]struct{}
 	AllowedScopes map[string]struct{}
-	ExtraHeaders  http.Header
 )

pkg/gitea/gitea.go

@@ -30,32 +30,6 @@ func sharedTransport() *http.Transport {
 	return sharedTrans
 }
 
-// extraHeaderTransport injects flag.ExtraHeaders into every request, without
-// overriding headers the caller already set (e.g. Authorization, Content-Type,
-// Accept). It reads flag.ExtraHeaders on each round trip rather than caching
-// it, so tests can change it between requests.
-type extraHeaderTransport struct {
-	base http.RoundTripper
-}
-
-func (t *extraHeaderTransport) RoundTrip(req *http.Request) (*http.Response, error) {
-	headers := flag.ExtraHeaders
-	if len(headers) == 0 {
-		return t.base.RoundTrip(req)
-	}
-	cloned := req.Clone(req.Context())
-	for name, values := range headers {
-		if cloned.Header.Get(name) == "" {
-			cloned.Header[name] = values
-		}
-	}
-	return t.base.RoundTrip(cloned)
-}
-
-func giteaTransport() http.RoundTripper {
-	return &extraHeaderTransport{base: sharedTransport()}
-}
-
 // NewClient returns a cached *gitea.Client keyed by host+token. The SDK's per-client
 // version cache and the shared transport let us reuse keep-alive connections
 // and avoid the SDK's /api/v1/version preflight on every tool call.
@@ -66,7 +40,7 @@ func NewClient(token string) (*gitea.Client, error) {
 	}
 
 	httpClient := &http.Client{
-		Transport:     giteaTransport(),
+		Transport:     sharedTransport(),
 		CheckRedirect: checkRedirect,
 	}
 	opts := []gitea.ClientOption{

pkg/gitea/gitea_test.go

@@ -1,49 +0,0 @@
-package gitea
-
-import (
-	"context"
-	"net/http"
-	"net/http/httptest"
-	"testing"
-
-	"gitea.com/gitea/gitea-mcp/pkg/flag"
-)
-
-func TestNewClient_SendsExtraHeaders(t *testing.T) {
-	var gotClientID, gotAuthorization string
-	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
-		gotClientID = r.Header.Get("CF-Access-Client-Id")
-		gotAuthorization = r.Header.Get("Authorization")
-		w.Header().Set("Content-Type", "application/json")
-		w.WriteHeader(http.StatusOK)
-		_, _ = w.Write([]byte(`{"login":"octocat"}`))
-	}))
-	defer srv.Close()
-
-	origHost := flag.Host
-	origExtraHeaders := flag.ExtraHeaders
-	defer func() {
-		flag.Host = origHost
-		flag.ExtraHeaders = origExtraHeaders
-	}()
-	flag.Host = srv.URL
-	flag.ExtraHeaders = http.Header{
-		"Cf-Access-Client-Id": []string{"client-id"},
-		"Authorization":       []string{"should-not-override"},
-	}
-
-	client, err := NewClient("the-token")
-	if err != nil {
-		t.Fatalf("NewClient returned error: %v", err)
-	}
-	if _, _, err := client.Users.GetMyUserInfo(context.Background()); err != nil {
-		t.Fatalf("GetMyUserInfo returned error: %v", err)
-	}
-
-	if gotClientID != "client-id" {
-		t.Fatalf("CF-Access-Client-Id header = %q, want %q", gotClientID, "client-id")
-	}
-	if gotAuthorization != "token the-token" {
-		t.Fatalf("Authorization header = %q, want %q", gotAuthorization, "token the-token")
-	}
-}

pkg/gitea/rest.go

@@ -59,7 +59,7 @@ var (
 func restHTTPClient() *http.Client {
 	restClientOnce.Do(func() {
 		restClient = &http.Client{
-			Transport:     giteaTransport(),
+			Transport:     sharedTransport(),
 			Timeout:       httpClientTimeout,
 			CheckRedirect: checkRedirect,
 		}
@@ -180,7 +180,7 @@ func DoJSON(ctx context.Context, method, path string, query url.Values, body, re
 
 func attachmentHTTPClient(origin *url.URL) *http.Client {
 	return &http.Client{
-		Transport: giteaTransport(),
+		Transport: sharedTransport(),
 		CheckRedirect: func(req *http.Request, via []*http.Request) error {
 			if err := checkRedirect(req, via); err != nil {
 				return err

pkg/gitea/rest_test.go

@@ -62,44 +62,3 @@ func TestDoJSON_LimitsErrorResponseBody(t *testing.T) {
 		t.Fatalf("expected body length %d, got %d", errBodySnippetSize, len(httpErr.Body))
 	}
 }
-
-func TestDoJSON_SendsExtraHeaders(t *testing.T) {
-	var gotClientID, gotAuthorization string
-	srv := httptest.NewServer(http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
-		gotClientID = r.Header.Get("CF-Access-Client-Id")
-		gotAuthorization = r.Header.Get("Authorization")
-		w.WriteHeader(http.StatusOK)
-		_, _ = io.WriteString(w, "{}")
-	}))
-	defer srv.Close()
-
-	origHost := flag.Host
-	origToken := flag.Token
-	origExtraHeaders := flag.ExtraHeaders
-	defer func() {
-		flag.Host = origHost
-		flag.Token = origToken
-		flag.ExtraHeaders = origExtraHeaders
-	}()
-	flag.Host = srv.URL
-	flag.Token = "the-token"
-	flag.ExtraHeaders = http.Header{
-		"Cf-Access-Client-Id": []string{"client-id"},
-		"Authorization":       []string{"should-not-override"},
-	}
-
-	var out map[string]any
-	status, err := DoJSON(context.Background(), http.MethodGet, "repos/owner/repo", nil, nil, &out)
-	if err != nil {
-		t.Fatalf("DoJSON returned error: %v", err)
-	}
-	if status != http.StatusOK {
-		t.Fatalf("expected status %d, got %d", http.StatusOK, status)
-	}
-	if gotClientID != "client-id" {
-		t.Fatalf("CF-Access-Client-Id header = %q, want %q", gotClientID, "client-id")
-	}
-	if gotAuthorization != "token the-token" {
-		t.Fatalf("Authorization header = %q, want %q", gotAuthorization, "token the-token")
-	}
-}