add response formatter and feature flags for easy testing

Author: kerobbi

cmd/github-mcp-server/main.go

@@ -62,6 +62,8 @@ var (
 				LogFilePath:          viper.GetString("log-file"),
 				ContentWindowSize:    viper.GetInt("content-window-size"),
 				LockdownMode:         viper.GetBool("lockdown-mode"),
+				JSONFormat:           viper.GetBool("json-format"),
+				TOONFormat:           viper.GetBool("toon-format"),
 			}
 			return ghmcp.RunStdioServer(stdioServerConfig)
 		},
@@ -84,6 +86,8 @@ func init() {
 	rootCmd.PersistentFlags().String("gh-host", "", "Specify the GitHub hostname (for GitHub Enterprise etc.)")
 	rootCmd.PersistentFlags().Int("content-window-size", 5000, "Specify the content window size")
 	rootCmd.PersistentFlags().Bool("lockdown-mode", false, "Enable lockdown mode")
+	rootCmd.PersistentFlags().Bool("json-format", false, "Use JSON output format instead of default CSV")
+	rootCmd.PersistentFlags().Bool("toon-format", false, "Enable TOON output format")
 
 	// Bind flag to viper
 	_ = viper.BindPFlag("toolsets", rootCmd.PersistentFlags().Lookup("toolsets"))
@@ -95,6 +99,8 @@ func init() {
 	_ = viper.BindPFlag("host", rootCmd.PersistentFlags().Lookup("gh-host"))
 	_ = viper.BindPFlag("content-window-size", rootCmd.PersistentFlags().Lookup("content-window-size"))
 	_ = viper.BindPFlag("lockdown-mode", rootCmd.PersistentFlags().Lookup("lockdown-mode"))
+	_ = viper.BindPFlag("json-format", rootCmd.PersistentFlags().Lookup("json-format"))
+	_ = viper.BindPFlag("toon-format", rootCmd.PersistentFlags().Lookup("toon-format"))
 
 	// Add subcommands
 	rootCmd.AddCommand(stdioCmd)

go.mod

@@ -3,6 +3,7 @@ module github.com/github/github-mcp-server
 go 1.24.0
 
 require (
+	github.com/alpkeskin/gotoon v0.1.1
 	github.com/google/go-github/v77 v77.0.0
 	github.com/josephburnett/jd v1.9.2
 	github.com/mark3labs/mcp-go v0.36.0

go.sum

@@ -1,3 +1,5 @@
+github.com/alpkeskin/gotoon v0.1.1 h1:GQOVwMfWKINnfEA6slrXHJaJYDwnUFmrPlXOtnuja1w=
+github.com/alpkeskin/gotoon v0.1.1/go.mod h1:XRTz8RM4tz8M2nB37MNRN8rHF4YgeYd8nIXmoU0B0+M=
 github.com/aymerick/douceur v0.2.0 h1:Mv+mAeH1Q+n9Fr+oyamOlAkUNPWPlA8PPGR0QAaYuPk=
 github.com/aymerick/douceur v0.2.0/go.mod h1:wlT5vV2O3h55X9m7iVYN0TBM0NH/MmbLnd30/FjWUq4=
 github.com/bahlo/generic-list-go v0.2.0 h1:5sz/EEAK+ls5wF+NeqDpk5+iNdMDXrh3z3nPnH1Wvgk=

internal/ghmcp/server.go

@@ -54,6 +54,12 @@ type MCPServerConfig struct {
 
 	// LockdownMode indicates if we should enable lockdown mode
 	LockdownMode bool
+
+	// JSONFormat controls whether tools return a JSON response
+	JSONFormat bool
+
+	// TOONFormat controls whether tools return a TOON response
+	TOONFormat bool
 }
 
 const stdioServerLogPrefix = "stdioserver"
@@ -164,7 +170,7 @@ func NewMCPServer(cfg MCPServerConfig) (*server.MCPServer, error) {
 		getRawClient,
 		cfg.Translator,
 		cfg.ContentWindowSize,
-		github.FeatureFlags{LockdownMode: cfg.LockdownMode},
+		github.FeatureFlags{LockdownMode: cfg.LockdownMode, JSONFormat: cfg.JSONFormat, TOONFormat: cfg.TOONFormat},
 	)
 	err = tsg.EnableToolsets(enabledToolsets, nil)
 
@@ -219,6 +225,12 @@ type StdioServerConfig struct {
 
 	// LockdownMode indicates if we should enable lockdown mode
 	LockdownMode bool
+
+	// JSONFormat controls whether tools return a JSON response
+	JSONFormat bool
+
+	// TOONFormat controls whether tools return a TOON response
+	TOONFormat bool
 }
 
 // RunStdioServer is not concurrent safe.
@@ -239,6 +251,8 @@ func RunStdioServer(cfg StdioServerConfig) error {
 		Translator:        t,
 		ContentWindowSize: cfg.ContentWindowSize,
 		LockdownMode:      cfg.LockdownMode,
+		JSONFormat:        cfg.JSONFormat,
+		TOONFormat:        cfg.TOONFormat,
 	})
 	if err != nil {
 		return fmt.Errorf("failed to create MCP server: %w", err)

pkg/github/feature_flags.go

@@ -3,4 +3,8 @@ package github
 // FeatureFlags defines runtime feature toggles that adjust tool behavior.
 type FeatureFlags struct {
 	LockdownMode bool
+	// JSONFormat controls whether tools return a JSON response
+	JSONFormat bool
+	// TOONFormat controls whether tools return a TOON response
+	TOONFormat bool
 }

pkg/github/issues.go

@@ -1192,7 +1192,7 @@ func UpdateIssue(ctx context.Context, client *github.Client, gqlClient *githubv4
 }
 
 // ListIssues creates a tool to list and filter repository issues
-func ListIssues(getGQLClient GetGQLClientFn, t translations.TranslationHelperFunc) (tool mcp.Tool, handler server.ToolHandlerFunc) {
+func ListIssues(getGQLClient GetGQLClientFn, t translations.TranslationHelperFunc, flags FeatureFlags) (tool mcp.Tool, handler server.ToolHandlerFunc) {
 	return mcp.NewTool("list_issues",
 			mcp.WithDescription(t("TOOL_LIST_ISSUES_DESCRIPTION", "List issues in a GitHub repository. For pagination, use the 'endCursor' from the previous response's 'pageInfo' in the 'after' parameter.")),
 			mcp.WithToolAnnotation(mcp.ToolAnnotation{
@@ -1384,9 +1384,8 @@ func ListIssues(getGQLClient GetGQLClientFn, t translations.TranslationHelperFun
 				totalCount = fragment.TotalCount
 			}
 
-			// Create response with issues
-			response := map[string]interface{}{
-				"issues": issues,
+			// Create metadata for pagination
+			metadata := map[string]interface{}{
 				"pageInfo": map[string]interface{}{
 					"hasNextPage":     pageInfo.HasNextPage,
 					"hasPreviousPage": pageInfo.HasPreviousPage,
@@ -1395,11 +1394,8 @@ func ListIssues(getGQLClient GetGQLClientFn, t translations.TranslationHelperFun
 				},
 				"totalCount": totalCount,
 			}
-			out, err := json.Marshal(response)
-			if err != nil {
-				return nil, fmt.Errorf("failed to marshal issues: %w", err)
-			}
-			return mcp.NewToolResultText(string(out)), nil
+
+			return FormatResponse(issues, flags, "issues", metadata)
 		}
 }
 

pkg/github/issues_test.go

@@ -857,7 +857,7 @@ func Test_CreateIssue(t *testing.T) {
 func Test_ListIssues(t *testing.T) {
 	// Verify tool definition
 	mockClient := githubv4.NewClient(nil)
-	tool, _ := ListIssues(stubGetGQLClientFn(mockClient), translations.NullTranslationHelper)
+	tool, _ := ListIssues(stubGetGQLClientFn(mockClient), translations.NullTranslationHelper, FeatureFlags{JSONFormat: true})
 	require.NoError(t, toolsnaps.Test(tool.Name, tool))
 
 	assert.Equal(t, "list_issues", tool.Name)
@@ -1118,7 +1118,7 @@ func Test_ListIssues(t *testing.T) {
 			}
 
 			gqlClient := githubv4.NewClient(httpClient)
-			_, handler := ListIssues(stubGetGQLClientFn(gqlClient), translations.NullTranslationHelper)
+			_, handler := ListIssues(stubGetGQLClientFn(gqlClient), translations.NullTranslationHelper, FeatureFlags{JSONFormat: true})
 
 			req := createMCPRequest(tc.reqParams)
 			res, err := handler(context.Background(), req)

pkg/github/pullrequests.go

@@ -713,7 +713,7 @@ func UpdatePullRequest(getClient GetClientFn, getGQLClient GetGQLClientFn, t tra
 }
 
 // ListPullRequests creates a tool to list and filter repository pull requests.
-func ListPullRequests(getClient GetClientFn, t translations.TranslationHelperFunc) (mcp.Tool, server.ToolHandlerFunc) {
+func ListPullRequests(getClient GetClientFn, t translations.TranslationHelperFunc, flags FeatureFlags) (mcp.Tool, server.ToolHandlerFunc) {
 	return mcp.NewTool("list_pull_requests",
 			mcp.WithDescription(t("TOOL_LIST_PULL_REQUESTS_DESCRIPTION", "List pull requests in a GitHub repository. If the user specifies an author, then DO NOT use this tool and use the search_pull_requests tool instead.")),
 			mcp.WithToolAnnotation(mcp.ToolAnnotation{
@@ -828,12 +828,7 @@ func ListPullRequests(getClient GetClientFn, t translations.TranslationHelperFun
 				}
 			}
 
-			r, err := json.Marshal(prs)
-			if err != nil {
-				return nil, fmt.Errorf("failed to marshal response: %w", err)
-			}
-
-			return mcp.NewToolResultText(string(r)), nil
+			return FormatResponse(prs, flags, "")
 		}
 }
 

pkg/github/pullrequests_test.go

@@ -578,7 +578,7 @@ func Test_UpdatePullRequest_Draft(t *testing.T) {
 func Test_ListPullRequests(t *testing.T) {
 	// Verify tool definition once
 	mockClient := github.NewClient(nil)
-	tool, _ := ListPullRequests(stubGetClientFn(mockClient), translations.NullTranslationHelper)
+	tool, _ := ListPullRequests(stubGetClientFn(mockClient), translations.NullTranslationHelper, FeatureFlags{JSONFormat: true})
 	require.NoError(t, toolsnaps.Test(tool.Name, tool))
 
 	assert.Equal(t, "list_pull_requests", tool.Name)
@@ -671,7 +671,7 @@ func Test_ListPullRequests(t *testing.T) {
 		t.Run(tc.name, func(t *testing.T) {
 			// Setup client with mock
 			client := github.NewClient(tc.mockedClient)
-			_, handler := ListPullRequests(stubGetClientFn(client), translations.NullTranslationHelper)
+			_, handler := ListPullRequests(stubGetClientFn(client), translations.NullTranslationHelper, FeatureFlags{JSONFormat: true})
 
 			// Create call request
 			request := createMCPRequest(tc.requestArgs)

pkg/github/repositories.go

@@ -18,7 +18,7 @@ import (
 	"github.com/mark3labs/mcp-go/server"
 )
 
-func GetCommit(getClient GetClientFn, t translations.TranslationHelperFunc) (tool mcp.Tool, handler server.ToolHandlerFunc) {
+func GetCommit(getClient GetClientFn, t translations.TranslationHelperFunc, flags FeatureFlags) (tool mcp.Tool, handler server.ToolHandlerFunc) {
 	return mcp.NewTool("get_commit",
 			mcp.WithDescription(t("TOOL_GET_COMMITS_DESCRIPTION", "Get details for a commit from a GitHub repository")),
 			mcp.WithToolAnnotation(mcp.ToolAnnotation{
@@ -101,11 +101,12 @@ func GetCommit(getClient GetClientFn, t translations.TranslationHelperFunc) (too
 			}
 
 			return mcp.NewToolResultText(string(r)), nil
+			// return FormatResponse(minimalCommit, flags, "")
 		}
 }
 
 // ListCommits creates a tool to get commits of a branch in a repository.
-func ListCommits(getClient GetClientFn, t translations.TranslationHelperFunc) (tool mcp.Tool, handler server.ToolHandlerFunc) {
+func ListCommits(getClient GetClientFn, t translations.TranslationHelperFunc, flags FeatureFlags) (tool mcp.Tool, handler server.ToolHandlerFunc) {
 	return mcp.NewTool("list_commits",
 			mcp.WithDescription(t("TOOL_LIST_COMMITS_DESCRIPTION", "Get list of commits of a branch in a GitHub repository. Returns at least 30 results per page by default, but can return more if specified using the perPage parameter (up to 100).")),
 			mcp.WithToolAnnotation(mcp.ToolAnnotation{
@@ -191,12 +192,7 @@ func ListCommits(getClient GetClientFn, t translations.TranslationHelperFunc) (t
 				minimalCommits[i] = convertToMinimalCommit(commit, false)
 			}
 
-			r, err := json.Marshal(minimalCommits)
-			if err != nil {
-				return nil, fmt.Errorf("failed to marshal response: %w", err)
-			}
-
-			return mcp.NewToolResultText(string(r)), nil
+			return FormatResponse(minimalCommits, flags, "")
 		}
 }