errors: improve rate limit error messages for AI agents

When the GitHub API returns a rate limit error, replace the raw Go HTTP
error string with a clean, actionable message so agents know exactly
how long to wait before retrying.

Before:
  search code: GET https://api.github.com/search/code: 403 API rate
  limit exceeded for user ID 12345. [rate reset in 2m59s]

After:
  search code: GitHub API rate limit exceeded. Retry after 2m59s.
  create issue: GitHub secondary rate limit exceeded. Retry after 47s.
  create issue: GitHub secondary rate limit exceeded. Wait before retrying.

Edge cases: expired/zero reset time, nil RetryAfter, and errors
wrapped with errors.As all produce "Wait before retrying." rather
than a negative or confusing duration.

The original error is stored in context via addGitHubAPIErrorToContext
before the rate-limit check, so middleware is unaffected.

Fixes #2385.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>

Author: danmoseley

pkg/errors/error.go

@@ -2,8 +2,10 @@ package errors
 
 import (
 	"context"
+	stderrors "errors"
 	"fmt"
 	"net/http"
+	"time"
 
 	"github.com/github/github-mcp-server/pkg/utils"
 	"github.com/google/go-github/v82/github"
@@ -159,6 +161,30 @@ func NewGitHubAPIErrorResponse(ctx context.Context, message string, resp *github
 	if ctx != nil {
 		_, _ = addGitHubAPIErrorToContext(ctx, apiErr) // Explicitly ignore error for graceful handling
 	}
+
+	var rateLimitErr *github.RateLimitError
+	if stderrors.As(err, &rateLimitErr) {
+		resetTime := rateLimitErr.Rate.Reset.Time
+		if !resetTime.IsZero() && resetTime.After(time.Now()) {
+			retryIn := time.Until(resetTime).Round(time.Second)
+			return utils.NewToolResultError(fmt.Sprintf(
+				"%s: GitHub API rate limit exceeded. Retry after %v.", message, retryIn))
+		}
+		return utils.NewToolResultError(fmt.Sprintf(
+			"%s: GitHub API rate limit exceeded. Wait before retrying.", message))
+	}
+
+	var abuseErr *github.AbuseRateLimitError
+	if stderrors.As(err, &abuseErr) {
+		if abuseErr.RetryAfter != nil && *abuseErr.RetryAfter > 0 {
+			return utils.NewToolResultError(fmt.Sprintf(
+				"%s: GitHub secondary rate limit exceeded. Retry after %v.",
+				message, abuseErr.RetryAfter.Round(time.Second)))
+		}
+		return utils.NewToolResultError(fmt.Sprintf(
+			"%s: GitHub secondary rate limit exceeded. Wait before retrying.", message))
+	}
+
 	return utils.NewToolResultErrorFromErr(message, err)
 }