make JSON format default and CSVFormat flag, refactor data and metadata handling

Author: kerobbi

cmd/github-mcp-server/main.go

@@ -62,7 +62,7 @@ var (
 				LogFilePath:          viper.GetString("log-file"),
 				ContentWindowSize:    viper.GetInt("content-window-size"),
 				LockdownMode:         viper.GetBool("lockdown-mode"),
-				JSONFormat:           viper.GetBool("json-format"),
+				CSVFormat:            viper.GetBool("csv-format"),
 				TOONFormat:           viper.GetBool("toon-format"),
 			}
 			return ghmcp.RunStdioServer(stdioServerConfig)
@@ -86,7 +86,7 @@ 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("csv-format", false, "Enable CSV output format")
 	rootCmd.PersistentFlags().Bool("toon-format", false, "Enable TOON output format")
 
 	// Bind flag to viper
@@ -99,7 +99,7 @@ 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("csv-format", rootCmd.PersistentFlags().Lookup("csv-format"))
 	_ = viper.BindPFlag("toon-format", rootCmd.PersistentFlags().Lookup("toon-format"))
 
 	// Add subcommands

internal/ghmcp/server.go

@@ -55,8 +55,8 @@ type MCPServerConfig struct {
 	// LockdownMode indicates if we should enable lockdown mode
 	LockdownMode bool
 
-	// JSONFormat controls whether tools return a JSON response
-	JSONFormat bool
+	// CSVFormat controls whether tools return a CSV response
+	CSVFormat bool
 
 	// TOONFormat controls whether tools return a TOON response
 	TOONFormat bool
@@ -170,7 +170,7 @@ func NewMCPServer(cfg MCPServerConfig) (*server.MCPServer, error) {
 		getRawClient,
 		cfg.Translator,
 		cfg.ContentWindowSize,
-		github.FeatureFlags{LockdownMode: cfg.LockdownMode, JSONFormat: cfg.JSONFormat, TOONFormat: cfg.TOONFormat},
+		github.FeatureFlags{LockdownMode: cfg.LockdownMode, CSVFormat: cfg.CSVFormat, TOONFormat: cfg.TOONFormat},
 	)
 	err = tsg.EnableToolsets(enabledToolsets, nil)
 
@@ -226,8 +226,8 @@ type StdioServerConfig struct {
 	// LockdownMode indicates if we should enable lockdown mode
 	LockdownMode bool
 
-	// JSONFormat controls whether tools return a JSON response
-	JSONFormat bool
+	// CSVFormat controls whether tools return a CSV response
+	CSVFormat bool
 
 	// TOONFormat controls whether tools return a TOON response
 	TOONFormat bool
@@ -251,7 +251,7 @@ func RunStdioServer(cfg StdioServerConfig) error {
 		Translator:        t,
 		ContentWindowSize: cfg.ContentWindowSize,
 		LockdownMode:      cfg.LockdownMode,
-		JSONFormat:        cfg.JSONFormat,
+		CSVFormat:         cfg.CSVFormat,
 		TOONFormat:        cfg.TOONFormat,
 	})
 	if err != nil {

pkg/github/feature_flags.go

@@ -3,8 +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
+	// CSVFormat controls whether tools return a CSV response
+	CSVFormat bool
 	// TOONFormat controls whether tools return a TOON response
 	TOONFormat bool
 }

pkg/github/issues.go

@@ -131,14 +131,17 @@ type IssueQueryResult interface {
 	GetIssueFragment() IssueQueryFragment
 }
 
+// PageInfo contains pagination information
+type PageInfo struct {
+	HasNextPage     githubv4.Boolean `json:"hasNextPage"`
+	HasPreviousPage githubv4.Boolean `json:"hasPreviousPage"`
+	StartCursor     githubv4.String  `json:"startCursor"`
+	EndCursor       githubv4.String  `json:"endCursor"`
+}
+
 type IssueQueryFragment struct {
-	Nodes    []IssueFragment `graphql:"nodes"`
-	PageInfo struct {
-		HasNextPage     githubv4.Boolean
-		HasPreviousPage githubv4.Boolean
-		StartCursor     githubv4.String
-		EndCursor       githubv4.String
-	}
+	Nodes      []IssueFragment `graphql:"nodes"`
+	PageInfo   PageInfo
 	TotalCount int
 }
 
@@ -474,7 +477,7 @@ func GetIssueLabels(ctx context.Context, client *githubv4.Client, owner string,
 }
 
 // ListIssueTypes creates a tool to list defined issue types for an organization. This can be used to understand supported issue type values for creating or updating issues.
-func ListIssueTypes(getClient GetClientFn, t translations.TranslationHelperFunc) (tool mcp.Tool, handler server.ToolHandlerFunc) {
+func ListIssueTypes(getClient GetClientFn, t translations.TranslationHelperFunc, flags FeatureFlags) (tool mcp.Tool, handler server.ToolHandlerFunc) {
 
 	return mcp.NewTool("list_issue_types",
 			mcp.WithDescription(t("TOOL_LIST_ISSUE_TYPES_FOR_ORG", "List supported issue types for repository owner (organization).")),
@@ -511,12 +514,7 @@ func ListIssueTypes(getClient GetClientFn, t translations.TranslationHelperFunc)
 				return mcp.NewToolResultError(fmt.Sprintf("failed to list issue types: %s", string(body))), nil
 			}
 
-			r, err := json.Marshal(issueTypes)
-			if err != nil {
-				return nil, fmt.Errorf("failed to marshal issue types: %w", err)
-			}
-
-			return mcp.NewToolResultText(string(r)), nil
+			return FormatResponse(issueTypes, flags)
 		}
 }
 
@@ -807,7 +805,7 @@ func ReprioritizeSubIssue(ctx context.Context, client *github.Client, owner stri
 }
 
 // SearchIssues creates a tool to search for issues.
-func SearchIssues(getClient GetClientFn, t translations.TranslationHelperFunc) (tool mcp.Tool, handler server.ToolHandlerFunc) {
+func SearchIssues(getClient GetClientFn, t translations.TranslationHelperFunc, flags FeatureFlags) (tool mcp.Tool, handler server.ToolHandlerFunc) {
 	return mcp.NewTool("search_issues",
 			mcp.WithDescription(t("TOOL_SEARCH_ISSUES_DESCRIPTION", "Search for issues in GitHub repositories using issues search syntax already scoped to is:issue")),
 			mcp.WithToolAnnotation(mcp.ToolAnnotation{
@@ -847,7 +845,7 @@ func SearchIssues(getClient GetClientFn, t translations.TranslationHelperFunc) (
 			WithPagination(),
 		),
 		func(ctx context.Context, request mcp.CallToolRequest) (*mcp.CallToolResult, error) {
-			return searchHandler(ctx, getClient, request, "issue", "failed to search issues")
+			return searchHandler(ctx, getClient, request, "issue", "failed to search issues", flags)
 		}
 }
 
@@ -1367,38 +1365,33 @@ func ListIssues(getGQLClient GetGQLClientFn, t translations.TranslationHelperFun
 
 			// Extract and convert all issue nodes using the common interface
 			var issues []*github.Issue
-			var pageInfo struct {
-				HasNextPage     githubv4.Boolean
-				HasPreviousPage githubv4.Boolean
-				StartCursor     githubv4.String
-				EndCursor       githubv4.String
-			}
-			var totalCount int
+			var fragment IssueQueryFragment
 
 			if queryResult, ok := issueQuery.(IssueQueryResult); ok {
-				fragment := queryResult.GetIssueFragment()
+				fragment = queryResult.GetIssueFragment()
 				for _, issue := range fragment.Nodes {
 					issues = append(issues, fragmentToIssue(issue))
 				}
-				pageInfo = fragment.PageInfo
-				totalCount = fragment.TotalCount
 			}
 
-			// Create metadata for pagination
-			metadata := map[string]interface{}{
-				"pageInfo": map[string]interface{}{
-					"hasNextPage":     pageInfo.HasNextPage,
-					"hasPreviousPage": pageInfo.HasPreviousPage,
-					"startCursor":     string(pageInfo.StartCursor),
-					"endCursor":       string(pageInfo.EndCursor),
-				},
-				"totalCount": totalCount,
+			// Create response with issues
+			response := &IssuesListResponse{
+				Issues:     issues,
+				PageInfo:   fragment.PageInfo,
+				TotalCount: fragment.TotalCount,
 			}
 
-			return FormatResponse(issues, flags, "issues", metadata)
+			return FormatResponse(response, flags)
 		}
 }
 
+// IssuesListResponse represents the response from list_issues with pagination
+type IssuesListResponse struct {
+	Issues     []*github.Issue `json:"issues"`
+	PageInfo   PageInfo        `json:"pageInfo"`
+	TotalCount int             `json:"totalCount"`
+}
+
 // mvpDescription is an MVP idea for generating tool descriptions from structured data in a shared format.
 // It is not intended for widespread usage and is not a complete implementation.
 type mvpDescription struct {

pkg/github/issues_test.go

@@ -365,7 +365,7 @@ func Test_AddIssueComment(t *testing.T) {
 func Test_SearchIssues(t *testing.T) {
 	// Verify tool definition once
 	mockClient := github.NewClient(nil)
-	tool, _ := SearchIssues(stubGetClientFn(mockClient), translations.NullTranslationHelper)
+	tool, _ := SearchIssues(stubGetClientFn(mockClient), translations.NullTranslationHelper, stubFeatureFlags(nil))
 	require.NoError(t, toolsnaps.Test(tool.Name, tool))
 
 	assert.Equal(t, "search_issues", tool.Name)
@@ -654,7 +654,7 @@ func Test_SearchIssues(t *testing.T) {
 		t.Run(tc.name, func(t *testing.T) {
 			// Setup client with mock
 			client := github.NewClient(tc.mockedClient)
-			_, handler := SearchIssues(stubGetClientFn(client), translations.NullTranslationHelper)
+			_, handler := SearchIssues(stubGetClientFn(client), translations.NullTranslationHelper, stubFeatureFlags(nil))
 
 			// Create call request
 			request := createMCPRequest(tc.requestArgs)
@@ -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, FeatureFlags{JSONFormat: true})
+	tool, _ := ListIssues(stubGetGQLClientFn(mockClient), translations.NullTranslationHelper, stubFeatureFlags(nil))
 	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, FeatureFlags{JSONFormat: true})
+			_, handler := ListIssues(stubGetGQLClientFn(gqlClient), translations.NullTranslationHelper, stubFeatureFlags(nil))
 
 			req := createMCPRequest(tc.reqParams)
 			res, err := handler(context.Background(), req)
@@ -3380,7 +3380,7 @@ func Test_ReprioritizeSubIssue(t *testing.T) {
 func Test_ListIssueTypes(t *testing.T) {
 	// Verify tool definition once
 	mockClient := github.NewClient(nil)
-	tool, _ := ListIssueTypes(stubGetClientFn(mockClient), translations.NullTranslationHelper)
+	tool, _ := ListIssueTypes(stubGetClientFn(mockClient), translations.NullTranslationHelper, stubFeatureFlags(nil))
 	require.NoError(t, toolsnaps.Test(tool.Name, tool))
 
 	assert.Equal(t, "list_issue_types", tool.Name)
@@ -3467,7 +3467,7 @@ func Test_ListIssueTypes(t *testing.T) {
 		t.Run(tc.name, func(t *testing.T) {
 			// Setup client with mock
 			client := github.NewClient(tc.mockedClient)
-			_, handler := ListIssueTypes(stubGetClientFn(client), translations.NullTranslationHelper)
+			_, handler := ListIssueTypes(stubGetClientFn(client), translations.NullTranslationHelper, stubFeatureFlags(nil))
 
 			// Create call request
 			request := createMCPRequest(tc.requestArgs)

pkg/github/pullrequests.go

@@ -828,7 +828,7 @@ func ListPullRequests(getClient GetClientFn, t translations.TranslationHelperFun
 				}
 			}
 
-			return FormatResponse(prs, flags, "")
+			return FormatResponse(prs, flags)
 		}
 }
 
@@ -926,7 +926,7 @@ func MergePullRequest(getClient GetClientFn, t translations.TranslationHelperFun
 }
 
 // SearchPullRequests creates a tool to search for pull requests.
-func SearchPullRequests(getClient GetClientFn, t translations.TranslationHelperFunc) (tool mcp.Tool, handler server.ToolHandlerFunc) {
+func SearchPullRequests(getClient GetClientFn, t translations.TranslationHelperFunc, flags FeatureFlags) (tool mcp.Tool, handler server.ToolHandlerFunc) {
 	return mcp.NewTool("search_pull_requests",
 			mcp.WithDescription(t("TOOL_SEARCH_PULL_REQUESTS_DESCRIPTION", "Search for pull requests in GitHub repositories using issues search syntax already scoped to is:pr")),
 			mcp.WithToolAnnotation(mcp.ToolAnnotation{
@@ -966,7 +966,7 @@ func SearchPullRequests(getClient GetClientFn, t translations.TranslationHelperF
 			WithPagination(),
 		),
 		func(ctx context.Context, request mcp.CallToolRequest) (*mcp.CallToolResult, error) {
-			return searchHandler(ctx, getClient, request, "pr", "failed to search pull requests")
+			return searchHandler(ctx, getClient, request, "pr", "failed to search pull requests", 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, FeatureFlags{JSONFormat: true})
+	tool, _ := ListPullRequests(stubGetClientFn(mockClient), translations.NullTranslationHelper, stubFeatureFlags(nil))
 	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, FeatureFlags{JSONFormat: true})
+			_, handler := ListPullRequests(stubGetClientFn(client), translations.NullTranslationHelper, stubFeatureFlags(nil))
 
 			// Create call request
 			request := createMCPRequest(tc.requestArgs)
@@ -826,7 +826,7 @@ func Test_MergePullRequest(t *testing.T) {
 
 func Test_SearchPullRequests(t *testing.T) {
 	mockClient := github.NewClient(nil)
-	tool, _ := SearchPullRequests(stubGetClientFn(mockClient), translations.NullTranslationHelper)
+	tool, _ := SearchPullRequests(stubGetClientFn(mockClient), translations.NullTranslationHelper, stubFeatureFlags(nil))
 	require.NoError(t, toolsnaps.Test(tool.Name, tool))
 
 	assert.Equal(t, "search_pull_requests", tool.Name)
@@ -1091,7 +1091,7 @@ func Test_SearchPullRequests(t *testing.T) {
 		t.Run(tc.name, func(t *testing.T) {
 			// Setup client with mock
 			client := github.NewClient(tc.mockedClient)
-			_, handler := SearchPullRequests(stubGetClientFn(client), translations.NullTranslationHelper)
+			_, handler := SearchPullRequests(stubGetClientFn(client), translations.NullTranslationHelper, stubFeatureFlags(nil))
 
 			// Create call request
 			request := createMCPRequest(tc.requestArgs)

pkg/github/repositories.go

@@ -101,7 +101,7 @@ func GetCommit(getClient GetClientFn, t translations.TranslationHelperFunc, flag
 			}
 
 			return mcp.NewToolResultText(string(r)), nil
-			// return FormatResponse(minimalCommit, flags, "")
+			// return FormatResponse(minimalCommit, flags)
 		}
 }
 
@@ -192,12 +192,12 @@ func ListCommits(getClient GetClientFn, t translations.TranslationHelperFunc, fl
 				minimalCommits[i] = convertToMinimalCommit(commit, false)
 			}
 
-			return FormatResponse(minimalCommits, flags, "")
+			return FormatResponse(minimalCommits, flags)
 		}
 }
 
 // ListBranches creates a tool to list branches in a GitHub repository.
-func ListBranches(getClient GetClientFn, t translations.TranslationHelperFunc) (tool mcp.Tool, handler server.ToolHandlerFunc) {
+func ListBranches(getClient GetClientFn, t translations.TranslationHelperFunc, flags FeatureFlags) (tool mcp.Tool, handler server.ToolHandlerFunc) {
 	return mcp.NewTool("list_branches",
 			mcp.WithDescription(t("TOOL_LIST_BRANCHES_DESCRIPTION", "List branches in a GitHub repository")),
 			mcp.WithToolAnnotation(mcp.ToolAnnotation{
@@ -264,12 +264,7 @@ func ListBranches(getClient GetClientFn, t translations.TranslationHelperFunc) (
 				minimalBranches = append(minimalBranches, convertToMinimalBranch(branch))
 			}
 
-			r, err := json.Marshal(minimalBranches)
-			if err != nil {
-				return nil, fmt.Errorf("failed to marshal response: %w", err)
-			}
-
-			return mcp.NewToolResultText(string(r)), nil
+			return FormatResponse(minimalBranches, flags)
 		}
 }
 
@@ -1219,7 +1214,7 @@ func PushFiles(getClient GetClientFn, t translations.TranslationHelperFunc) (too
 }
 
 // ListTags creates a tool to list tags in a GitHub repository.
-func ListTags(getClient GetClientFn, t translations.TranslationHelperFunc) (tool mcp.Tool, handler server.ToolHandlerFunc) {
+func ListTags(getClient GetClientFn, t translations.TranslationHelperFunc, flags FeatureFlags) (tool mcp.Tool, handler server.ToolHandlerFunc) {
 	return mcp.NewTool("list_tags",
 			mcp.WithDescription(t("TOOL_LIST_TAGS_DESCRIPTION", "List git tags in a GitHub repository")),
 			mcp.WithToolAnnotation(mcp.ToolAnnotation{
@@ -1278,12 +1273,7 @@ func ListTags(getClient GetClientFn, t translations.TranslationHelperFunc) (tool
 				return mcp.NewToolResultError(fmt.Sprintf("failed to list tags: %s", string(body))), nil
 			}
 
-			r, err := json.Marshal(tags)
-			if err != nil {
-				return nil, fmt.Errorf("failed to marshal response: %w", err)
-			}
-
-			return mcp.NewToolResultText(string(r)), nil
+			return FormatResponse(tags, flags)
 		}
 }
 
@@ -1375,7 +1365,7 @@ func GetTag(getClient GetClientFn, t translations.TranslationHelperFunc) (tool m
 }
 
 // ListReleases creates a tool to list releases in a GitHub repository.
-func ListReleases(getClient GetClientFn, t translations.TranslationHelperFunc) (tool mcp.Tool, handler server.ToolHandlerFunc) {
+func ListReleases(getClient GetClientFn, t translations.TranslationHelperFunc, flags FeatureFlags) (tool mcp.Tool, handler server.ToolHandlerFunc) {
 	return mcp.NewTool("list_releases",
 			mcp.WithDescription(t("TOOL_LIST_RELEASES_DESCRIPTION", "List releases in a GitHub repository")),
 			mcp.WithToolAnnotation(mcp.ToolAnnotation{
@@ -1430,12 +1420,7 @@ func ListReleases(getClient GetClientFn, t translations.TranslationHelperFunc) (
 				return mcp.NewToolResultError(fmt.Sprintf("failed to list releases: %s", string(body))), nil
 			}
 
-			r, err := json.Marshal(releases)
-			if err != nil {
-				return nil, fmt.Errorf("failed to marshal response: %w", err)
-			}
-
-			return mcp.NewToolResultText(string(r)), nil
+			return FormatResponse(releases, flags)
 		}
 }