Skip to content
Draft
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
12 changes: 6 additions & 6 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -750,7 +750,7 @@ For negotiated supported protocol versions `2026-07-28` or newer, the consolidat
- **OAuth Challenge Scopes**: `repo`, `read:org`
- `method`: The type of data to fetch (string, required)
- `owner`: Repository owner (required for all methods) (string, required)
- `repo`: Repository name (required for labels, assignees, milestones, branches, issue fields, reviewers) (string, optional)
- `repo`: Repository name (required for labels, assignees, milestones, branches, issue fields, reviewers; optional for issue types) (string, optional)

</details>

Expand Down Expand Up @@ -1041,17 +1041,17 @@ For negotiated supported protocol versions `2026-07-28` or newer, the consolidat
- `state`: New state (string, optional)
- `state_reason`: Reason for the state change. Ignored unless state is changed. (string, optional)
- `title`: Issue title (string, optional)
- `type`: Type of this issue. For updates, pass null to remove the current type. Only use if issue types are enabled for this repository. Use list_issue_types to get valid type values for this repository or its owner organization. If the repository doesn't support issue types, omit this parameter. (string | null, optional)
- `type`: Type of this issue. For updates, pass null to remove the current type. Only use if issue types are enabled for this repository. Use list_issue_types to get valid type values for this repository or its owner. If the repository doesn't support issue types, omit this parameter. (string | null, optional)

- **list_issue_fields** - List issue fields
- **OAuth Challenge Scopes**: `repo`, `read:org`
- `owner`: The account owner of the repository or organization. The name is not case sensitive. (string, required)
- `repo`: The name of the repository. When provided, returns fields for this specific repository (inherited from its organization). When omitted, returns org-level fields directly. (string, optional)
- `owner`: The account owner of the repository (user or organization). The name is not case sensitive. (string, required)
- `repo`: The name of the repository. When provided, returns fields for this specific repository (inherited from its owner). When omitted, returns the owner's fields directly. (string, optional)

- **list_issue_types** - List available issue types
- **OAuth Challenge Scopes**: `repo`, `read:org`
- `owner`: The account owner of the repository or organization. (string, required)
- `repo`: The name of the repository. When provided, returns issue types for this specific repository. When omitted, returns org-level issue types directly. (string, optional)
- `owner`: The account owner of the repository (user or organization). (string, required)
- `repo`: The name of the repository. When provided, returns issue types for this specific repository. When omitted, returns the owner's issue types directly. (string, optional)

- **list_issues** - List issues
- **OAuth Challenge Scopes**: `repo`
Expand Down
4 changes: 2 additions & 2 deletions pkg/github/__toolsnaps__/issue_write.snap
Original file line number Diff line number Diff line change
Expand Up @@ -41,7 +41,7 @@
"type": "boolean"
},
"field_name": {
"description": "Issue field name (case-insensitive). Must match a field returned by list_issue_fields for this repository or its organization.",
"description": "Issue field name (case-insensitive). Must match a field returned by list_issue_fields for this repository or its owner.",
"type": "string"
},
"field_option_name": {
Expand Down Expand Up @@ -139,7 +139,7 @@
"type": "null"
}
],
"description": "Type of this issue. For updates, pass null to remove the current type. Only use if issue types are enabled for this repository. Use list_issue_types to get valid type values for this repository or its owner organization. If the repository doesn't support issue types, omit this parameter."
"description": "Type of this issue. For updates, pass null to remove the current type. Only use if issue types are enabled for this repository. Use list_issue_types to get valid type values for this repository or its owner. If the repository doesn't support issue types, omit this parameter."
}
},
"required": [
Expand Down
6 changes: 3 additions & 3 deletions pkg/github/__toolsnaps__/list_issue_fields.snap
Original file line number Diff line number Diff line change
Expand Up @@ -4,15 +4,15 @@
"readOnlyHint": true,
"title": "List issue fields"
},
"description": "List issue fields for a repository or organization. Returns field definitions including name, type (text, number, date, single_select), and for single_select fields the list of valid option names. When repo is omitted, returns org-level fields directly.",
"description": "List issue fields for a repository or its owner (user or organization). Returns field definitions including name, type (text, number, date, single_select), and for single_select fields the list of valid option names. When repo is omitted, returns the owner's fields directly, which works for organizations and the authenticated user.",
"inputSchema": {
"properties": {
"owner": {
"description": "The account owner of the repository or organization. The name is not case sensitive.",
"description": "The account owner of the repository (user or organization). The name is not case sensitive.",
"type": "string"
},
"repo": {
"description": "The name of the repository. When provided, returns fields for this specific repository (inherited from its organization). When omitted, returns org-level fields directly.",
"description": "The name of the repository. When provided, returns fields for this specific repository (inherited from its owner). When omitted, returns the owner's fields directly.",
"type": "string"
}
},
Expand Down
6 changes: 3 additions & 3 deletions pkg/github/__toolsnaps__/list_issue_types.snap
Original file line number Diff line number Diff line change
Expand Up @@ -4,15 +4,15 @@
"readOnlyHint": true,
"title": "List available issue types"
},
"description": "List supported issue types for a repository or its owner organization. When repo is omitted, returns org-level issue types directly.",
"description": "List supported issue types for a repository or its owner (user or organization). When repo is omitted, returns the owner's issue types directly, which works for organizations and the authenticated user.",
"inputSchema": {
"properties": {
"owner": {
"description": "The account owner of the repository or organization.",
"description": "The account owner of the repository (user or organization).",
"type": "string"
},
"repo": {
"description": "The name of the repository. When provided, returns issue types for this specific repository. When omitted, returns org-level issue types directly.",
"description": "The name of the repository. When provided, returns issue types for this specific repository. When omitted, returns the owner's issue types directly.",
"type": "string"
}
},
Expand Down
2 changes: 1 addition & 1 deletion pkg/github/__toolsnaps__/set_issue_fields.snap
Original file line number Diff line number Diff line change
Expand Up @@ -6,7 +6,7 @@
"readOnlyHint": false,
"title": "Set Issue Fields"
},
"description": "Set issue field values for an issue. Fields are organization-level custom fields (text, number, date, or single select). Use this to create or update field values on an issue.",
"description": "Set issue field values for an issue. Fields are custom fields (text, number, date, or single select) defined by the repository owner (user or organization). Use this to create or update field values on an issue.",
"icons": [
{
"mimeType": "image/png",
Expand Down
2 changes: 1 addition & 1 deletion pkg/github/__toolsnaps__/ui_get.snap
Original file line number Diff line number Diff line change
Expand Up @@ -32,7 +32,7 @@
"type": "string"
},
"repo": {
"description": "Repository name (required for labels, assignees, milestones, branches, issue fields, reviewers)",
"description": "Repository name (required for labels, assignees, milestones, branches, issue fields, reviewers; optional for issue types)",
"type": "string"
}
},
Expand Down
73 changes: 47 additions & 26 deletions pkg/github/issue_fields.go
Original file line number Diff line number Diff line change
Expand Up @@ -101,13 +101,22 @@ type issueFieldsOrgQuery struct {
} `graphql:"organization(login: $login)"`
}

// ListIssueFields creates a tool to list issue field definitions for a repository or organization.
// issueFieldsUserQuery is the GraphQL query for listing issue fields on a user account.
type issueFieldsUserQuery struct {
User struct {
IssueFields struct {
Nodes []issueFieldNode
} `graphql:"issueFields(first: 100)"`
} `graphql:"user(login: $login)"`
}

// ListIssueFields creates a tool to list issue field definitions for a repository or its owner.
func ListIssueFields(t translations.TranslationHelperFunc) inventory.ServerTool {
st := NewToolWithSchemaOptions[IssueMetadataInput, []IssueFieldOutput](
ToolsetMetadataIssues,
mcp.Tool{
Name: "list_issue_fields",
Description: t("TOOL_LIST_ISSUE_FIELDS_DESCRIPTION", "List issue fields for a repository or organization. Returns field definitions including name, type (text, number, date, single_select), and for single_select fields the list of valid option names. When repo is omitted, returns org-level fields directly."),
Description: t("TOOL_LIST_ISSUE_FIELDS_DESCRIPTION", "List issue fields for a repository or its owner (user or organization). Returns field definitions including name, type (text, number, date, single_select), and for single_select fields the list of valid option names. When repo is omitted, returns the owner's fields directly, which works for organizations and the authenticated user."),
Annotations: &mcp.ToolAnnotations{
Title: t("TOOL_LIST_ISSUE_FIELDS_USER_TITLE", "List issue fields"),
ReadOnlyHint: true,
Expand All @@ -117,11 +126,11 @@ func ListIssueFields(t translations.TranslationHelperFunc) inventory.ServerTool
Properties: map[string]*jsonschema.Schema{
"owner": {
Type: "string",
Description: "The account owner of the repository or organization. The name is not case sensitive.",
Description: "The account owner of the repository (user or organization). The name is not case sensitive.",
},
"repo": {
Type: "string",
Description: "The name of the repository. When provided, returns fields for this specific repository (inherited from its organization). When omitted, returns org-level fields directly.",
Description: "The name of the repository. When provided, returns fields for this specific repository (inherited from its owner). When omitted, returns the owner's fields directly.",
},
},
Required: []string{"owner"},
Expand All @@ -136,12 +145,21 @@ func ListIssueFields(t translations.TranslationHelperFunc) inventory.ServerTool
return utils.NewToolResultError("missing required parameter: owner"), nil, nil
}

client, err := deps.GetClient(ctx)
if err != nil {
return utils.NewToolResultErrorFromErr("failed to get GitHub client", err), nil, nil
}
scope, errResult := resolveIssueMetadataScope(ctx, client, owner, repo)
if errResult != nil {
return errResult, nil, nil
}

gqlClient, err := deps.GetGQLClient(ctx)
if err != nil {
return utils.NewToolResultErrorFromErr("failed to get GitHub GraphQL client", err), nil, nil
}

fields, err := fetchIssueFields(ctx, gqlClient, owner, repo)
fields, err := fetchIssueFields(ctx, gqlClient, scope)
if err != nil {
return ghErrors.NewGitHubGraphQLErrorResponse(ctx, "failed to list issue fields", err), nil, nil
}
Expand All @@ -152,44 +170,47 @@ func ListIssueFields(t translations.TranslationHelperFunc) inventory.ServerTool
}

result := utils.NewToolResultText(string(r))
// Issue field definitions are repo/org structural metadata
// Issue field definitions are repo/owner structural metadata
// (trusted). When scoped to a specific repo, confidentiality
// follows that repo's visibility; for an org-level lookup (no
// follows that repo's visibility; for an owner-level lookup (no
// repo) it is conservatively treated as private.
if repo == "" {
result = attachStaticIFCLabel(ctx, deps, result, ifc.LabelRepoMetadata(true))
} else {
if scope.Kind == issueMetadataRepo {
result = attachRepoVisibilityIFCLabelLazy(ctx, deps, owner, repo, result, ifc.LabelRepoMetadata)
} else {
result = attachStaticIFCLabel(ctx, deps, result, ifc.LabelRepoMetadata(true))
}
return result, issueFieldOutputs(fields), nil
}, normalizeIssueStrings([]string{"owner"}, []string{"repo"}))
return st
}

// fetchIssueFields returns the issue field definitions for the given owner.
// If repo is provided, fields are scoped to that repository (inherited from its
// organization); otherwise fields are returned directly from the organization.
func fetchIssueFields(ctx context.Context, gqlClient *githubv4.Client, owner, repo string) ([]IssueField, error) {
if repo != "" {
// fetchIssueFields returns the issue field definitions for scope. A repository
// returns the fields it inherits from its owner.
func fetchIssueFields(ctx context.Context, gqlClient *githubv4.Client, scope issueMetadataScope) ([]IssueField, error) {
switch scope.Kind {
case issueMetadataOrg:
var query issueFieldsOrgQuery
if err := gqlClient.Query(ctx, &query, map[string]any{"login": githubv4.String(scope.Owner)}); err != nil {
return nil, err
}
return issueFieldsFromNodes(query.Organization.IssueFields.Nodes), nil
case issueMetadataViewer:
var query issueFieldsUserQuery
if err := gqlClient.Query(ctx, &query, map[string]any{"login": githubv4.String(scope.Owner)}); err != nil {
return nil, err
}
return issueFieldsFromNodes(query.User.IssueFields.Nodes), nil
default:
var query issueFieldsRepoQuery
vars := map[string]any{
"owner": githubv4.String(owner),
"name": githubv4.String(repo),
"owner": githubv4.String(scope.Owner),
"name": githubv4.String(scope.Repo),
}
if err := gqlClient.Query(ctx, &query, vars); err != nil {
return nil, err
}
return issueFieldsFromNodes(query.Repository.IssueFields.Nodes), nil
}

var query issueFieldsOrgQuery
vars := map[string]any{
"login": githubv4.String(owner),
}
if err := gqlClient.Query(ctx, &query, vars); err != nil {
return nil, err
}
return issueFieldsFromNodes(query.Organization.IssueFields.Nodes), nil
}

// issueFieldsFromNodes converts GraphQL issue field union nodes into IssueField values.
Expand Down
67 changes: 65 additions & 2 deletions pkg/github/issue_fields_test.go
Original file line number Diff line number Diff line change
Expand Up @@ -3,11 +3,13 @@ package github
import (
"context"
"encoding/json"
"net/http"
"testing"

"github.com/github/github-mcp-server/v2/internal/githubv4mock"
"github.com/github/github-mcp-server/v2/internal/toolsnaps"
"github.com/github/github-mcp-server/v2/pkg/translations"
"github.com/google/go-github/v92/github"
"github.com/google/jsonschema-go/jsonschema"
"github.com/shurcooL/githubv4"
"github.com/stretchr/testify/assert"
Expand Down Expand Up @@ -39,16 +41,21 @@ func Test_ListIssueFields(t *testing.T) {
defaultOrgVars := map[string]any{
"login": githubv4.String("testowner"),
}
orgAccount := &github.User{Login: new("testowner"), Type: new("Organization")}
viewerAccount := &github.User{Login: new("testowner"), Type: new("User")}
otherUserAccount := &github.User{Login: new("hubot"), Type: new("User")}

tests := []struct {
name string
requestArgs map[string]any
restHandlers map[string]http.HandlerFunc
mockQueryStruct any
mockVars map[string]any
gqlResponse githubv4mock.GQLResponse
expectError bool
expectedFields []IssueField
expectedErrMsg string
notInErrMsg string
}{
{
name: "no fields returns empty list",
Expand Down Expand Up @@ -159,10 +166,13 @@ func Test_ListIssueFields(t *testing.T) {
expectedErrMsg: "missing required parameter: owner",
},
{
name: "no repo returns org-level fields",
name: "organization owner returns organization fields",
requestArgs: map[string]any{
"owner": "testowner",
},
restHandlers: map[string]http.HandlerFunc{
"GET /users/testowner": mockResponse(t, http.StatusOK, orgAccount),
},
mockQueryStruct: orgQueryStruct,
mockVars: defaultOrgVars,
gqlResponse: githubv4mock.DataResponse(map[string]any{
Expand All @@ -185,6 +195,53 @@ func Test_ListIssueFields(t *testing.T) {
{ID: "IFT_1", DatabaseID: 77, Name: "DRI", DataType: "TEXT", Visibility: "ORG_ONLY"},
},
},
{
name: "authenticated user owner returns their own fields",
requestArgs: map[string]any{
"owner": "testowner",
},
restHandlers: map[string]http.HandlerFunc{
"GET /users/testowner": mockResponse(t, http.StatusOK, viewerAccount),
"GET /user": mockResponse(t, http.StatusOK, viewerAccount),
},
mockQueryStruct: issueFieldsUserQuery{},
mockVars: defaultOrgVars,
gqlResponse: githubv4mock.DataResponse(map[string]any{
"user": map[string]any{
"issueFields": map[string]any{
"nodes": []any{
map[string]any{
"__typename": "IssueFieldDate",
"id": "IFD_9",
"fullDatabaseId": "909",
"name": "Due",
"dataType": "DATE",
"visibility": "ALL",
},
},
},
},
}),
expectedFields: []IssueField{
{ID: "IFD_9", DatabaseID: 909, Name: "Due", DataType: "DATE", Visibility: "ALL"},
},
},
{
name: "another user owner asks for repo",
requestArgs: map[string]any{
"owner": "hubot",
},
restHandlers: map[string]http.HandlerFunc{
"GET /users/hubot": mockResponse(t, http.StatusOK, otherUserAccount),
"GET /user": mockResponse(t, http.StatusOK, viewerAccount),
},
mockQueryStruct: issueFieldsUserQuery{},
mockVars: map[string]any{"login": githubv4.String("hubot")},
gqlResponse: githubv4mock.ErrorResponse("FORBIDDEN"),
expectError: true,
expectedErrMsg: "Pass repo to list them for one of the owner's repositories",
notInErrMsg: "hubot",
},
{
name: "number field returned",
requestArgs: map[string]any{
Expand Down Expand Up @@ -264,6 +321,9 @@ func Test_ListIssueFields(t *testing.T) {
)
gqlClient := githubv4.NewClient(mockedHTTPClient)
deps := BaseDeps{GQLClient: gqlClient}
if tc.restHandlers != nil {
deps.Client = mustNewGHClient(t, MockHTTPClientWithHandlers(tc.restHandlers))
}
handler := serverTool.Handler(deps)

request := createMCPRequest(tc.requestArgs)
Expand All @@ -278,6 +338,9 @@ func Test_ListIssueFields(t *testing.T) {
require.True(t, result.IsError)
errorContent := getErrorResult(t, result)
assert.Contains(t, errorContent.Text, tc.expectedErrMsg)
if tc.notInErrMsg != "" {
assert.NotContains(t, errorContent.Text, tc.notInErrMsg, "the error must not echo untrusted input")
}
return
}

Expand All @@ -289,7 +352,7 @@ func Test_ListIssueFields(t *testing.T) {
var returnedFields []IssueField
err = json.Unmarshal([]byte(textContent.Text), &returnedFields)
require.NoError(t, err)
require.Equal(t, len(tc.expectedFields), len(returnedFields))
require.Equal(t, len(tc.expectedFields), len(returnedFields), "field count in %s", textContent.Text)
for i, expected := range tc.expectedFields {
assert.Equal(t, expected.ID, returnedFields[i].ID)
assert.Equal(t, expected.DatabaseID, returnedFields[i].DatabaseID)
Expand Down
Loading
Loading