Add raw client error annotation and annotate GetFileContents (#1570)

* Add raw client error annotation and annotate GetFileContents

* Track response.

* add raw errors to context

* add raw api error test

* Update pkg/errors/error.go

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

* Add blank line after Error() method for readability

* add NewGitHubRawAPIErrorResponse back

---------

Co-authored-by: Matt Holloway <mattdholloway@pm.me>
Co-authored-by: Matt Holloway <mattdholloway@github.com>
Co-authored-by: Copilot <175728472+Copilot@users.noreply.github.com>

Author: 3 people

pkg/errors/error.go

@@ -3,6 +3,7 @@ package errors
 import (
 	"context"
 	"fmt"
+	"net/http"
 
 	"github.com/github/github-mcp-server/pkg/utils"
 	"github.com/google/go-github/v79/github"
@@ -44,10 +45,29 @@ func (e *GitHubGraphQLError) Error() string {
 	return fmt.Errorf("%s: %w", e.Message, e.Err).Error()
 }
 
+type GitHubRawAPIError struct {
+	Message  string         `json:"message"`
+	Response *http.Response `json:"-"`
+	Err      error          `json:"-"`
+}
+
+func newGitHubRawAPIError(message string, resp *http.Response, err error) *GitHubRawAPIError {
+	return &GitHubRawAPIError{
+		Message:  message,
+		Response: resp,
+		Err:      err,
+	}
+}
+
+func (e *GitHubRawAPIError) Error() string {
+	return fmt.Errorf("%s: %w", e.Message, e.Err).Error()
+}
+
 type GitHubErrorKey struct{}
 type GitHubCtxErrors struct {
 	api     []*GitHubAPIError
 	graphQL []*GitHubGraphQLError
+	raw     []*GitHubRawAPIError
 }
 
 // ContextWithGitHubErrors updates or creates a context with a pointer to GitHub error information (to be used by middleware).
@@ -59,6 +79,7 @@ func ContextWithGitHubErrors(ctx context.Context) context.Context {
 		// If the context already has GitHubCtxErrors, we just empty the slices to start fresh
 		val.api = []*GitHubAPIError{}
 		val.graphQL = []*GitHubGraphQLError{}
+		val.raw = []*GitHubRawAPIError{}
 	} else {
 		// If not, we create a new GitHubCtxErrors and set it in the context
 		ctx = context.WithValue(ctx, GitHubErrorKey{}, &GitHubCtxErrors{})
@@ -83,6 +104,14 @@ func GetGitHubGraphQLErrors(ctx context.Context) ([]*GitHubGraphQLError, error)
 	return nil, fmt.Errorf("context does not contain GitHubCtxErrors")
 }
 
+// GetGitHubRawAPIErrors retrieves the slice of GitHubRawAPIErrors from the context.
+func GetGitHubRawAPIErrors(ctx context.Context) ([]*GitHubRawAPIError, error) {
+	if val, ok := ctx.Value(GitHubErrorKey{}).(*GitHubCtxErrors); ok {
+		return val.raw, nil // return the slice of raw API errors from the context
+	}
+	return nil, fmt.Errorf("context does not contain GitHubCtxErrors")
+}
+
 func NewGitHubAPIErrorToCtx(ctx context.Context, message string, resp *github.Response, err error) (context.Context, error) {
 	apiErr := newGitHubAPIError(message, resp, err)
 	if ctx != nil {
@@ -107,6 +136,15 @@ func addGitHubGraphQLErrorToContext(ctx context.Context, err *GitHubGraphQLError
 	return nil, fmt.Errorf("context does not contain GitHubCtxErrors")
 }
 
+func addRawAPIErrorToContext(ctx context.Context, err *GitHubRawAPIError) (context.Context, error) {
+	if val, ok := ctx.Value(GitHubErrorKey{}).(*GitHubCtxErrors); ok {
+		val.raw = append(val.raw, err)
+		return ctx, nil
+	}
+
+	return nil, fmt.Errorf("context does not contain GitHubCtxErrors")
+}
+
 // NewGitHubAPIErrorResponse returns an mcp.NewToolResultError and retains the error in the context for access via middleware
 func NewGitHubAPIErrorResponse(ctx context.Context, message string, resp *github.Response, err error) *mcp.CallToolResult {
 	apiErr := newGitHubAPIError(message, resp, err)
@@ -125,6 +163,15 @@ func NewGitHubGraphQLErrorResponse(ctx context.Context, message string, err erro
 	return utils.NewToolResultErrorFromErr(message, err)
 }
 
+// NewGitHubRawAPIErrorResponse returns an mcp.NewToolResultError and retains the error in the context for access via middleware
+func NewGitHubRawAPIErrorResponse(ctx context.Context, message string, resp *http.Response, err error) *mcp.CallToolResult {
+	rawErr := newGitHubRawAPIError(message, resp, err)
+	if ctx != nil {
+		_, _ = addRawAPIErrorToContext(ctx, rawErr) // Explicitly ignore error for graceful handling
+	}
+	return utils.NewToolResultErrorFromErr(message, err)
+}
+
 // NewGitHubAPIStatusErrorResponse handles cases where the API call succeeds (err == nil)
 // but returns an unexpected HTTP status code. It creates a synthetic error from the
 // status code and response body, then records it in context for observability tracking.

pkg/errors/error_test.go

@@ -63,6 +63,33 @@ func TestGitHubErrorContext(t *testing.T) {
 		assert.Equal(t, "failed to execute mutation: GraphQL query failed", gqlError.Error())
 	})
 
+	t.Run("Raw API errors can be added to context and retrieved", func(t *testing.T) {
+		// Given a context with GitHub error tracking enabled
+		ctx := ContextWithGitHubErrors(context.Background())
+
+		// Create a mock HTTP response
+		resp := &http.Response{
+			StatusCode: 404,
+			Status:     "404 Not Found",
+		}
+		originalErr := fmt.Errorf("raw content not found")
+
+		// When we add a raw API error to the context
+		rawAPIErr := newGitHubRawAPIError("failed to fetch raw content", resp, originalErr)
+		updatedCtx, err := addRawAPIErrorToContext(ctx, rawAPIErr)
+		require.NoError(t, err)
+
+		// Then we should be able to retrieve the error from the updated context
+		rawErrors, err := GetGitHubRawAPIErrors(updatedCtx)
+		require.NoError(t, err)
+		require.Len(t, rawErrors, 1)
+
+		rawError := rawErrors[0]
+		assert.Equal(t, "failed to fetch raw content", rawError.Message)
+		assert.Equal(t, resp, rawError.Response)
+		assert.Equal(t, originalErr, rawError.Err)
+	})
+
 	t.Run("multiple errors can be accumulated in context", func(t *testing.T) {
 		// Given a context with GitHub error tracking enabled
 		ctx := ContextWithGitHubErrors(context.Background())
@@ -82,6 +109,11 @@ func TestGitHubErrorContext(t *testing.T) {
 		ctx, err = addGitHubGraphQLErrorToContext(ctx, gqlErr)
 		require.NoError(t, err)
 
+		// And add a raw API error
+		rawErr := newGitHubRawAPIError("raw error", &http.Response{StatusCode: 404}, fmt.Errorf("not found"))
+		ctx, err = addRawAPIErrorToContext(ctx, rawErr)
+		require.NoError(t, err)
+
 		// Then we should be able to retrieve all errors
 		apiErrors, err := GetGitHubAPIErrors(ctx)
 		require.NoError(t, err)
@@ -91,10 +123,15 @@ func TestGitHubErrorContext(t *testing.T) {
 		require.NoError(t, err)
 		assert.Len(t, gqlErrors, 1)
 
+		rawErrors, err := GetGitHubRawAPIErrors(ctx)
+		require.NoError(t, err)
+		assert.Len(t, rawErrors, 1)
+
 		// Verify error details
 		assert.Equal(t, "first error", apiErrors[0].Message)
 		assert.Equal(t, "second error", apiErrors[1].Message)
 		assert.Equal(t, "graphql error", gqlErrors[0].Message)
+		assert.Equal(t, "raw error", rawErrors[0].Message)
 	})
 
 	t.Run("context pointer sharing allows middleware to inspect errors without context propagation", func(t *testing.T) {
@@ -160,6 +197,12 @@ func TestGitHubErrorContext(t *testing.T) {
 		assert.Error(t, err)
 		assert.Contains(t, err.Error(), "context does not contain GitHubCtxErrors")
 		assert.Nil(t, gqlErrors)
+
+		// Same for raw API errors
+		rawErrors, err := GetGitHubRawAPIErrors(ctx)
+		assert.Error(t, err)
+		assert.Contains(t, err.Error(), "context does not contain GitHubCtxErrors")
+		assert.Nil(t, rawErrors)
 	})
 
 	t.Run("ContextWithGitHubErrors resets existing errors", func(t *testing.T) {
@@ -169,18 +212,31 @@ func TestGitHubErrorContext(t *testing.T) {
 		ctx, err := NewGitHubAPIErrorToCtx(ctx, "existing error", resp, fmt.Errorf("error"))
 		require.NoError(t, err)
 
-		// Verify error exists
+		// Add a raw API error too
+		rawErr := newGitHubRawAPIError("existing raw error", &http.Response{StatusCode: 404}, fmt.Errorf("error"))
+		ctx, err = addRawAPIErrorToContext(ctx, rawErr)
+		require.NoError(t, err)
+
+		// Verify errors exist
 		apiErrors, err := GetGitHubAPIErrors(ctx)
 		require.NoError(t, err)
 		assert.Len(t, apiErrors, 1)
 
+		rawErrors, err := GetGitHubRawAPIErrors(ctx)
+		require.NoError(t, err)
+		assert.Len(t, rawErrors, 1)
+
 		// When we call ContextWithGitHubErrors again
 		resetCtx := ContextWithGitHubErrors(ctx)
 
-		// Then the errors should be cleared
+		// Then all errors should be cleared
 		apiErrors, err = GetGitHubAPIErrors(resetCtx)
 		require.NoError(t, err)
-		assert.Len(t, apiErrors, 0, "Errors should be reset")
+		assert.Len(t, apiErrors, 0, "API errors should be reset")
+
+		rawErrors, err = GetGitHubRawAPIErrors(resetCtx)
+		require.NoError(t, err)
+		assert.Len(t, rawErrors, 0, "Raw API errors should be reset")
 	})
 
 	t.Run("NewGitHubAPIErrorResponse creates MCP error result and stores context error", func(t *testing.T) {

pkg/github/repositories.go

@@ -724,7 +724,7 @@ func GetFileContents(t translations.TranslationHelperFunc) inventory.ServerTool
 					// If the raw content is found, return it directly
 					body, err := io.ReadAll(resp.Body)
 					if err != nil {
-						return utils.NewToolResultError("failed to read response body"), nil, nil
+						return ghErrors.NewGitHubRawAPIErrorResponse(ctx, "failed to get raw repository content", resp, err), nil, nil
 					}
 					contentType := resp.Header.Get("Content-Type")