package github

import (

"context"

"encoding/json"

"errors"

"fmt"

"io"

"net/http"

"strconv"

"time"

ghErrors "github.com/github/github-mcp-server/pkg/errors"

"github.com/github/github-mcp-server/pkg/ifc"

"github.com/github/github-mcp-server/pkg/inventory"

"github.com/github/github-mcp-server/pkg/scopes"

"github.com/github/github-mcp-server/pkg/translations"

"github.com/github/github-mcp-server/pkg/utils"

"github.com/google/go-github/v89/github"

"github.com/google/jsonschema-go/jsonschema"

"github.com/modelcontextprotocol/go-sdk/mcp"

"github.com/shurcooL/githubv4"

)

const (

ProjectUpdateFailedError = "failed to update a project item"

ProjectAddFailedError = "failed to add a project item"

ProjectDeleteFailedError = "failed to delete a project item"

ProjectListFailedError = "failed to list project items"

ProjectStatusUpdateListFailedError = "failed to list project status updates"

ProjectStatusUpdateGetFailedError = "failed to get project status update"

ProjectStatusUpdateCreateFailedError = "failed to create project status update"

ProjectResolveIDFailedError = "failed to resolve project ID"

MaxProjectsPerPage = 50

maxProjectItemsPerBatch = 50

)

// Method constants for consolidated project tools

const (

projectsMethodListProjects = "list_projects"

projectsMethodListProjectFields = "list_project_fields"

projectsMethodListProjectItems = "list_project_items"

projectsMethodGetProject = "get_project"

projectsMethodGetProjectField = "get_project_field"

projectsMethodGetProjectItem = "get_project_item"

projectsMethodAddProjectItem = "add_project_item"

projectsMethodUpdateProjectItem = "update_project_item"

projectsMethodUpdateProjectItems = "update_project_items"

projectsMethodDeleteProjectItem = "delete_project_item"

projectsMethodListProjectStatusUpdates = "list_project_status_updates"

projectsMethodGetProjectStatusUpdate = "get_project_status_update"

projectsMethodCreateProjectStatusUpdate = "create_project_status_update"

projectsMethodCreateProject = "create_project"

projectsMethodCreateIterationField = "create_iteration_field"

)

// GraphQL types for ProjectV2 status updates

type statusUpdateNode struct {

ID githubv4.ID

Body *githubv4.String

Status *githubv4.String

CreatedAt githubv4.DateTime

StartDate *githubv4.String

TargetDate *githubv4.String

Creator struct {

Login githubv4.String

}

}

type projectVisibility struct {

Public githubv4.Boolean

}

type statusUpdateNodeWithProject struct {

statusUpdateNode

Project projectVisibility

}

type statusUpdateConnection struct {

Nodes []statusUpdateNode

PageInfo PageInfoFragment

}

type statusUpdatesProject struct {

Public githubv4.Boolean

StatusUpdates statusUpdateConnection `graphql:"statusUpdates(first: $first, after: $after, orderBy: {field: CREATED_AT, direction: DESC})"`

}

// statusUpdatesUserQuery is the GraphQL query for listing status updates on a user-owned project.

type statusUpdatesUserQuery struct {

User struct {

ProjectV2 statusUpdatesProject `graphql:"projectV2(number: $projectNumber)"`

} `graphql:"user(login: $owner)"`

}

// statusUpdatesOrgQuery is the GraphQL query for listing status updates on an org-owned project.

type statusUpdatesOrgQuery struct {

Organization struct {

ProjectV2 statusUpdatesProject `graphql:"projectV2(number: $projectNumber)"`

} `graphql:"organization(login: $owner)"`

}

// statusUpdateNodeQuery is the GraphQL query for fetching a single status update by node ID.

type statusUpdateNodeQuery struct {

Node struct {

StatusUpdate statusUpdateNodeWithProject `graphql:"... on ProjectV2StatusUpdate"`

} `graphql:"node(id: $id)"`

}

// CreateProjectV2StatusUpdateInput is the input for the createProjectV2StatusUpdate mutation.

// Defined locally because the shurcooL/githubv4 library does not include this type.

type CreateProjectV2StatusUpdateInput struct {

ProjectID githubv4.ID `json:"projectId"`

Body *githubv4.String `json:"body,omitempty"`

Status *githubv4.String `json:"status,omitempty"`

StartDate *githubv4.String `json:"startDate,omitempty"`

TargetDate *githubv4.String `json:"targetDate,omitempty"`

ClientMutationID *githubv4.String `json:"clientMutationId,omitempty"`

}

// validProjectV2StatusUpdateStatuses is the set of valid status values for the createProjectV2StatusUpdate mutation.

var validProjectV2StatusUpdateStatuses = map[string]bool{

"INACTIVE": true,

"ON_TRACK": true,

"AT_RISK": true,

"OFF_TRACK": true,

"COMPLETE": true,

}

func convertToMinimalStatusUpdate(node statusUpdateNode) MinimalProjectStatusUpdate {

var creator *MinimalUser

if login := string(node.Creator.Login); login != "" {

creator = &MinimalUser{Login: login}

}

return MinimalProjectStatusUpdate{

ID: fmt.Sprintf("%v", node.ID),

Body: derefString(node.Body),

Status: derefString(node.Status),

CreatedAt: node.CreatedAt.Time.Format(time.RFC3339),

StartDate: derefString(node.StartDate),

TargetDate: derefString(node.TargetDate),

Creator: creator,

}

}

func derefString(s *githubv4.String) string {

if s == nil {

return ""

}

return string(*s)

}

// ProjectsList returns the tool and handler for listing GitHub Projects resources.

func ProjectsList(t translations.TranslationHelperFunc) inventory.ServerTool {

tool := NewTool(

ToolsetMetadataProjects,

mcp.Tool{

Name: "projects_list",

Description: t("TOOL_PROJECTS_LIST_DESCRIPTION",

`Tools for listing GitHub Projects resources.

Use this tool to list projects for a user or organization, or list project fields and items for a specific project.

`),

Annotations: &mcp.ToolAnnotations{

Title: t("TOOL_PROJECTS_LIST_USER_TITLE", "List GitHub Projects resources"),

ReadOnlyHint: true,

},

InputSchema: &jsonschema.Schema{

Type: "object",

Properties: map[string]*jsonschema.Schema{

"method": {

Type: "string",

Description: "The action to perform",

Enum: []any{

projectsMethodListProjects,

projectsMethodListProjectFields,

projectsMethodListProjectItems,

projectsMethodListProjectStatusUpdates,

},

},

"owner_type": {

Type: "string",

Description: "Owner type (user or org). If not provided, will automatically try both.",

Enum: []any{"user", "org"},

},

"owner": {

Type: "string",

Description: "The owner (user or organization login). The name is not case sensitive.",

},

"project_number": {

Type: "number",

Description: "The project's number. Required for 'list_project_fields', 'list_project_items', and 'list_project_status_updates' methods.",

},

"query": {

Type: "string",

Description: `Filter/query string. For list_projects: filter by title text and state (e.g. "roadmap is:open"). For list_project_items: advanced filtering using GitHub's project filtering syntax.`,

},

"fields": {

Type: "array",

Description: "Field IDs to include when listing project items (e.g. [\"102589\", \"985201\"]). CRITICAL: Always provide to get field values. Without this (and without 'field_names'), only titles returned. Mutually exclusive with 'field_names' — provide one, not both. Only used for 'list_project_items' method.",

Items: &jsonschema.Schema{

Type: "string",

},

},

"field_names": {

Type: "array",

Description: "Field names to include when listing project items (e.g. [\"Status\", \"Priority\"]). Resolved server-side to field IDs — pass this instead of 'fields' when you only know the human-readable names. Names that fail to resolve return a structured error. Mutually exclusive with 'fields' — provide one, not both. Only used for 'list_project_items' method.",

Items: &jsonschema.Schema{

Type: "string",

},

},

"per_page": {

Type: "number",

Description: fmt.Sprintf("Results per page (max %d)", MaxProjectsPerPage),

},

"after": {

Type: "string",

Description: "Forward pagination cursor from previous pageInfo.nextCursor.",

},

"before": {

Type: "string",

Description: "Backward pagination cursor from previous pageInfo.prevCursor (rare).",

},

},

Required: []string{"method", "owner"},

},

},

[]scopes.Scope{scopes.ReadProject},

func(ctx context.Context, deps ToolDependencies, _ *mcp.CallToolRequest, args map[string]any) (*mcp.CallToolResult, any, error) {

method, err := RequiredParam[string](args, "method")

if err != nil {

return utils.NewToolResultError(err.Error()), nil, nil

}

owner, err := RequiredParam[string](args, "owner")

if err != nil {

return utils.NewToolResultError(err.Error()), nil, nil

}

ownerType, err := OptionalParam[string](args, "owner_type")

if err != nil {

return utils.NewToolResultError(err.Error()), nil, nil

}

client, err := deps.GetClient(ctx)

if err != nil {

return utils.NewToolResultError(err.Error()), nil, nil

}

switch method {

case projectsMethodListProjects:

result, visibilities, payload, err := listProjects(ctx, client, args, owner, ownerType)

result = attachJoinedIFCLabel(ctx, deps, result, visibilities, ifc.LabelProjectList)

return result, payload, err

case projectsMethodListProjectFields, projectsMethodListProjectItems, projectsMethodListProjectStatusUpdates:

// All other methods require project_number and ownerType detection

projectNumber, err := RequiredInt(args, "project_number")

if err != nil {

return utils.NewToolResultError(err.Error()), nil, nil

}

if ownerType == "" {

ownerType, err = detectOwnerType(ctx, client, owner, projectNumber)

if err != nil {

return utils.NewToolResultError(err.Error()), nil, nil

}

}

switch method {

case projectsMethodListProjectFields:

result, payload, err := listProjectFields(ctx, client, args, owner, ownerType)

if shouldAttachIFCLabel(ctx, deps, result) {

isPrivate, visibilityErr := FetchProjectIsPrivate(ctx, client, owner, ownerType, projectNumber)

if visibilityErr == nil {

result = attachProjectVisibilityIFCLabel(ctx, deps, result, isPrivate, ifc.LabelProject)

}

}

return result, payload, err

case projectsMethodListProjectItems:

gqlClient, gqlErr := deps.GetGQLClient(ctx)

if gqlErr != nil {

return utils.NewToolResultError(gqlErr.Error()), nil, nil

}

result, payload, err := listProjectItems(ctx, client, gqlClient, args, owner, ownerType)

if shouldAttachIFCLabel(ctx, deps, result) {

isPrivate, visibilityErr := FetchProjectIsPrivate(ctx, client, owner, ownerType, projectNumber)

if visibilityErr == nil {

result = attachProjectVisibilityIFCLabel(ctx, deps, result, isPrivate, ifc.LabelProjectContent)

}

}

return result, payload, err

case projectsMethodListProjectStatusUpdates:

gqlClient, err := deps.GetGQLClient(ctx)

if err != nil {

return utils.NewToolResultError(err.Error()), nil, nil

}

result, isPrivate, payload, err := listProjectStatusUpdates(ctx, gqlClient, args, owner, ownerType)

result = attachStaticIFCLabel(ctx, deps, result, ifc.LabelProjectContent(isPrivate))

return result, payload, err

default:

return utils.NewToolResultError(fmt.Sprintf("unknown method: %s", method)), nil, nil

}

default:

return utils.NewToolResultError(fmt.Sprintf("unknown method: %s", method)), nil, nil

}

},

)

return tool

}

// ProjectsGet returns the tool and handler for getting GitHub Projects resources.

func ProjectsGet(t translations.TranslationHelperFunc) inventory.ServerTool {

tool := NewTool(

ToolsetMetadataProjects,

mcp.Tool{

Name: "projects_get",

Description: t("TOOL_PROJECTS_GET_DESCRIPTION", `Get details about specific GitHub Projects resources.

Use this tool to get details about individual projects, project fields, and project items by their unique IDs.

`),

Annotations: &mcp.ToolAnnotations{

Title: t("TOOL_PROJECTS_GET_USER_TITLE", "Get details of GitHub Projects resources"),

ReadOnlyHint: true,

},

InputSchema: &jsonschema.Schema{

Type: "object",

Properties: map[string]*jsonschema.Schema{

"method": {

Type: "string",

Description: "The method to execute",

Enum: []any{

projectsMethodGetProject,

projectsMethodGetProjectField,

projectsMethodGetProjectItem,

projectsMethodGetProjectStatusUpdate,

},

},

"owner_type": {

Type: "string",

Description: "Owner type (user or org). If not provided, will be automatically detected.",

Enum: []any{"user", "org"},

},

"owner": {

Type: "string",

Description: "The owner (user or organization login). The name is not case sensitive.",

},

"project_number": {

Type: "number",

Description: "The project's number.",

},

"field_id": {

Type: "number",

Description: "The field's ID. Required for 'get_project_field' method.",

},

"item_id": {

Type: "number",

Description: "The item's ID. Required for 'get_project_item' method.",

},

"fields": {

Type: "array",

Description: "Specific list of field IDs to include in the response when getting a project item (e.g. [\"102589\", \"985201\", \"169875\"]). If neither 'fields' nor 'field_names' is provided, only the title field is included. Mutually exclusive with 'field_names' — provide one, not both. Only used for 'get_project_item' method.",

Items: &jsonschema.Schema{

Type: "string",

},

},

"field_names": {

Type: "array",

Description: "Specific list of field names to include in the response when getting a project item (e.g. [\"Status\", \"Priority\"]). Resolved server-side to field IDs — pass this instead of 'fields' when you only know the human-readable names. Mutually exclusive with 'fields' — provide one, not both. Only used for 'get_project_item' method.",

Items: &jsonschema.Schema{

Type: "string",

},

},

"status_update_id": {

Type: "string",

Description: "The node ID of the project status update. Required for 'get_project_status_update' method.",

},

},

Required: []string{"method"},

},

},

[]scopes.Scope{scopes.ReadProject},

func(ctx context.Context, deps ToolDependencies, _ *mcp.CallToolRequest, args map[string]any) (*mcp.CallToolResult, any, error) {

method, err := RequiredParam[string](args, "method")

if err != nil {

return utils.NewToolResultError(err.Error()), nil, nil

}

// Handle get_project_status_update early — it only needs status_update_id

if method == projectsMethodGetProjectStatusUpdate {

statusUpdateID, err := RequiredParam[string](args, "status_update_id")

if err != nil {

return utils.NewToolResultError(err.Error()), nil, nil

}

gqlClient, err := deps.GetGQLClient(ctx)

if err != nil {

return utils.NewToolResultError(err.Error()), nil, nil

}

result, isPrivate, payload, err := getProjectStatusUpdate(ctx, gqlClient, statusUpdateID)

result = attachStaticIFCLabel(ctx, deps, result, ifc.LabelProjectContent(isPrivate))

return result, payload, err

}

owner, err := RequiredParam[string](args, "owner")

if err != nil {

return utils.NewToolResultError(err.Error()), nil, nil

}

ownerType, err := OptionalParam[string](args, "owner_type")

if err != nil {

return utils.NewToolResultError(err.Error()), nil, nil

}

projectNumber, err := RequiredInt(args, "project_number")

if err != nil {

return utils.NewToolResultError(err.Error()), nil, nil

}

client, err := deps.GetClient(ctx)

if err != nil {

return utils.NewToolResultError(err.Error()), nil, nil

}

// Detect owner type if not provided

if ownerType == "" {

ownerType, err = detectOwnerType(ctx, client, owner, projectNumber)

if err != nil {

return utils.NewToolResultError(err.Error()), nil, nil

}

}

switch method {

case projectsMethodGetProject:

result, isPrivate, payload, err := getProject(ctx, client, owner, ownerType, projectNumber)

result = attachStaticIFCLabel(ctx, deps, result, ifc.LabelProject(isPrivate))

return result, payload, err

case projectsMethodGetProjectField:

fieldID, err := RequiredBigInt(args, "field_id")

if err != nil {

return utils.NewToolResultError(err.Error()), nil, nil

}

result, payload, err := getProjectField(ctx, client, owner, ownerType, projectNumber, fieldID)

if shouldAttachIFCLabel(ctx, deps, result) {

isPrivate, visibilityErr := FetchProjectIsPrivate(ctx, client, owner, ownerType, projectNumber)

if visibilityErr == nil {

result = attachProjectVisibilityIFCLabel(ctx, deps, result, isPrivate, ifc.LabelProject)

}

}

return result, payload, err

case projectsMethodGetProjectItem:

itemID, err := RequiredBigInt(args, "item_id")

if err != nil {

return utils.NewToolResultError(err.Error()), nil, nil

}

fields, err := OptionalBigIntArrayParam(args, "fields")

if err != nil {

return utils.NewToolResultError(err.Error()), nil, nil

}

fieldNames, err := OptionalStringArrayParam(args, "field_names")

if err != nil {

return utils.NewToolResultError(err.Error()), nil, nil

}

if len(fields) > 0 && len(fieldNames) > 0 {

return utils.NewToolResultError("provide either 'fields' or 'field_names', not both"), nil, nil

}

if len(fieldNames) > 0 {

gqlClient, gqlErr := deps.GetGQLClient(ctx)

if gqlErr != nil {

return utils.NewToolResultError(gqlErr.Error()), nil, nil

}

resolvedIDs, resolveErr := resolveFieldNamesToIDs(ctx, gqlClient, owner, ownerType, projectNumber, fieldNames)

if resolveErr != nil {

var structured *ghErrors.StructuredResolutionError

if errors.As(resolveErr, &structured) {

return ghErrors.NewStructuredResolutionErrorResponse(structured), nil, nil

}

return utils.NewToolResultError(resolveErr.Error()), nil, nil

}

fields = append(fields, resolvedIDs...)

}

result, payload, err := getProjectItem(ctx, client, owner, ownerType, projectNumber, itemID, fields)

if shouldAttachIFCLabel(ctx, deps, result) {

isPrivate, visibilityErr := FetchProjectIsPrivate(ctx, client, owner, ownerType, projectNumber)

if visibilityErr == nil {

result = attachProjectVisibilityIFCLabel(ctx, deps, result, isPrivate, ifc.LabelProjectContent)

}

}

return result, payload, err

default:

return utils.NewToolResultError(fmt.Sprintf("unknown method: %s", method)), nil, nil

}

},

)

return tool

}

func updateProjectItemsItemSchema() *jsonschema.Schema {

variant := func(required []string, properties map[string]*jsonschema.Schema) *jsonschema.Schema {

return &jsonschema.Schema{

Type: "object",

AdditionalProperties: &jsonschema.Schema{Not: &jsonschema.Schema{}},

Properties: properties,

Required: required,

}

}

return &jsonschema.Schema{

Type: "object",

OneOf: []*jsonschema.Schema{

variant([]string{"node_id"}, map[string]*jsonschema.Schema{

"node_id": {

Type: "string",

Description: "The project item's GraphQL node ID, as returned by 'list_project_items' or 'add_project_item'.",

},

}),

variant([]string{"item_id"}, map[string]*jsonschema.Schema{

"item_id": {

Type: "integer",

Description: "The numeric project item ID.",

},

}),

variant([]string{"item_owner", "item_repo", "issue_number"}, map[string]*jsonschema.Schema{

"item_owner": {

Type: "string",

Description: "Owner of the repository containing the issue.",

},

"item_repo": {

Type: "string",

Description: "Repository containing the issue.",

},

"issue_number": {

Type: "integer",

Description: "Issue number used to resolve the project item.",

},

}),

},

}

}

func projectUpdatedFieldSchema() *jsonschema.Schema {

value := &jsonschema.Schema{

Description: "The value to apply. Any JSON value is accepted; use null to clear the field.",

}

variant := func(required []string, properties map[string]*jsonschema.Schema) *jsonschema.Schema {

properties["value"] = value

return &jsonschema.Schema{

Type: "object",

AdditionalProperties: &jsonschema.Schema{Not: &jsonschema.Schema{}},

Properties: properties,

Required: required,

}

}

return &jsonschema.Schema{

Type: "object",

Description: "The field/value to apply, using {\"id\": 123, \"value\": ...} or {\"name\": \"Status\", \"value\": ...}; null clears the field. Required for 'update_project_item' and 'update_project_items', where one top-level field/value applies to every item in a batch. For 'update_project_item' SINGLE_SELECT fields, the name form accepts option names; the ID form expects an option ID.",

OneOf: []*jsonschema.Schema{

variant([]string{"id", "value"}, map[string]*jsonschema.Schema{

"id": {

Type: "integer",

Description: "The numeric project field ID.",

},

}),

variant([]string{"name", "value"}, map[string]*jsonschema.Schema{

"name": {

Type: "string",

Description: "The project field name. Matching is case-insensitive.",

},

}),

},

}

}

// ProjectsWrite returns the tool and handler for modifying GitHub Projects resources.

func ProjectsWrite(t translations.TranslationHelperFunc) inventory.ServerTool {

tool := NewTool(

ToolsetMetadataProjects,

mcp.Tool{

Name: "projects_write",

Description: t("TOOL_PROJECTS_WRITE_DESCRIPTION", "Create and manage GitHub Projects: create projects, add/update/delete items, bulk-update many items at once, create status updates, and add iteration fields."),

Annotations: &mcp.ToolAnnotations{

Title: t("TOOL_PROJECTS_WRITE_USER_TITLE", "Manage GitHub Projects"),

ReadOnlyHint: false,

DestructiveHint: jsonschema.Ptr(true),

},

InputSchema: &jsonschema.Schema{

Type: "object",

Properties: map[string]*jsonschema.Schema{

"method": {

Type: "string",

Description: "The method to execute",

Enum: []any{

projectsMethodAddProjectItem,

projectsMethodUpdateProjectItem,

projectsMethodUpdateProjectItems,

projectsMethodDeleteProjectItem,

projectsMethodCreateProjectStatusUpdate,

projectsMethodCreateProject,

projectsMethodCreateIterationField,

},

},

"owner_type": {

Type: "string",

Description: "Owner type (user or org). Required for 'create_project' method. If not provided for other methods, will be automatically detected.",

Enum: []any{"user", "org"},

},

"owner": {

Type: "string",

Description: "The project owner (user or organization login). The name is not case sensitive.",

},

"project_number": {

Type: "number",

Description: "The project's number. Required for all methods except 'create_project'.",

},

"title": {

Type: "string",

Description: "The project title. Required for 'create_project' method.",

},

"item_id": {

Type: "number",

Description: "The project item ID. Required for 'delete_project_item'. For 'update_project_item', provide either item_id, or (item_owner + item_repo + issue_number) to resolve the item by issue.",

},

"item_type": {

Type: "string",

Description: "The item's type, either issue or pull_request. Required for 'add_project_item' method.",

Enum: []any{"issue", "pull_request"},

},

"item_owner": {

Type: "string",

Description: "The owner (user or organization) of the repository containing the issue or pull request. Required for 'add_project_item' method. Also accepted by 'update_project_item' when resolving the item by issue number.",

},

"item_repo": {

Type: "string",

Description: "The name of the repository containing the issue or pull request. Required for 'add_project_item' method. Also accepted by 'update_project_item' when resolving the item by issue number.",

},

"issue_number": {

Type: "number",

Description: "The issue number. Required for 'add_project_item' when item_type is 'issue'. Also accepted by 'update_project_item' to resolve the item by issue number (combine with item_owner and item_repo).",

},

"pull_request_number": {

Type: "number",

Description: "The pull request number (use when item_type is 'pull_request' for 'add_project_item' method). Provide either issue_number or pull_request_number.",

},

"updated_field": projectUpdatedFieldSchema(),

"items": {

Type: "array",

Description: "The items to update with the top-level 'updated_field'. Required for 'update_project_items'; prefer it over calling 'update_project_item' in a loop. Each entry must match exactly one reference variant: 'node_id', numeric 'item_id', or 'item_owner' + 'item_repo' + 'issue_number'. Limit: " + strconv.Itoa(maxProjectItemsPerBatch) + " items per call.",

Items: updateProjectItemsItemSchema(),

},

"body": {

Type: "string",

Description: "The body of the status update (markdown). Used for 'create_project_status_update' method.",

},

"status": {

Type: "string",

Description: "The status of the project. Used for 'create_project_status_update' method.",

Enum: []any{"INACTIVE", "ON_TRACK", "AT_RISK", "OFF_TRACK", "COMPLETE"},

},

"start_date": {

Type: "string",

Description: "Start date in YYYY-MM-DD format. Used for 'create_project_status_update' and 'create_iteration_field' methods.",

},

"target_date": {

Type: "string",

Description: "The target date of the status update in YYYY-MM-DD format. Used for 'create_project_status_update' method.",

},

"field_name": {

Type: "string",

Description: "The name of the iteration field (e.g. 'Sprint'). Required for 'create_iteration_field' method.",

},

"iteration_duration": {

Type: "number",

Description: "Duration in days for iterations of the field (e.g. 7 for weekly, 14 for bi-weekly). Required for 'create_iteration_field' method.",

},

"iterations": {

Type: "array",

Description: "Custom iterations for 'create_iteration_field' method. Only set this when you need iterations with varying durations, breaks between them, or specific titles. Otherwise omit it: GitHub auto-creates three iterations of 'iteration_duration' days starting on 'start_date', which is the right choice for most cases.",

Items: &jsonschema.Schema{

Type: "object",

AdditionalProperties: &jsonschema.Schema{Not: &jsonschema.Schema{}},

Properties: map[string]*jsonschema.Schema{

"title": {

Type: "string",

Description: "Iteration title (e.g. 'Sprint 1')",

},

"start_date": {

Type: "string",

Description: "Start date in YYYY-MM-DD format",

},

"duration": {

Type: "number",

Description: "Duration in days",

},

},

Required: []string{"title", "start_date", "duration"},

},

},

},

Required: []string{"method", "owner"},

},

},

[]scopes.Scope{scopes.Project},

func(ctx context.Context, deps ToolDependencies, _ *mcp.CallToolRequest, args map[string]any) (*mcp.CallToolResult, any, error) {

method, err := RequiredParam[string](args, "method")

if err != nil {

return utils.NewToolResultError(err.Error()), nil, nil

}

owner, err := RequiredParam[string](args, "owner")

if err != nil {

return utils.NewToolResultError(err.Error()), nil, nil

}

ownerType, err := OptionalParam[string](args, "owner_type")

if err != nil {

return utils.NewToolResultError(err.Error()), nil, nil

}

gqlClient, err := deps.GetGQLClient(ctx)

if err != nil {

return utils.NewToolResultError(err.Error()), nil, nil

}

// create_project does not require project_number or a REST client

if method == projectsMethodCreateProject {

return createProject(ctx, gqlClient, owner, ownerType, args)

}

projectNumber, err := RequiredInt(args, "project_number")

if err != nil {

return utils.NewToolResultError(err.Error()), nil, nil

}

client, err := deps.GetClient(ctx)

if err != nil {

return utils.NewToolResultError(err.Error()), nil, nil

}

// Detect owner type if not provided

if ownerType == "" {

ownerType, err = detectOwnerType(ctx, client, owner, projectNumber)

if err != nil {

return utils.NewToolResultError(err.Error()), nil, nil

}

}

switch method {

case projectsMethodAddProjectItem:

itemType, err := RequiredParam[string](args, "item_type")

if err != nil {

return utils.NewToolResultError(err.Error()), nil, nil

}

itemOwner, err := RequiredParam[string](args, "item_owner")

if err != nil {

return utils.NewToolResultError(err.Error()), nil, nil

}

itemRepo, err := RequiredParam[string](args, "item_repo")

if err != nil {

return utils.NewToolResultError(err.Error()), nil, nil

}

var itemNumber int

switch itemType {

case "issue":

itemNumber, err = RequiredInt(args, "issue_number")

if err != nil {

return utils.NewToolResultError("issue_number is required when item_type is 'issue'"), nil, nil

}

case "pull_request":

itemNumber, err = RequiredInt(args, "pull_request_number")

if err != nil {

return utils.NewToolResultError("pull_request_number is required when item_type is 'pull_request'"), nil, nil

}

default:

return utils.NewToolResultError("item_type must be either 'issue' or 'pull_request'"), nil, nil

}

return addProjectItem(ctx, gqlClient, owner, ownerType, projectNumber, itemOwner, itemRepo, itemNumber, itemType)

case projectsMethodUpdateProjectItem:

var itemID int64

if _, hasItemID := args["item_id"]; hasItemID {

id, err := RequiredBigInt(args, "item_id")

if err != nil {

return utils.NewToolResultError(err.Error()), nil, nil

}

itemID = id

} else {

// Resolve the item by (item_owner, item_repo, issue_number).

resolvedItemID, resolveErr := resolveItemIDFromIssueArgs(ctx, gqlClient, owner, ownerType, projectNumber, args)

if resolveErr != nil {

var structured *ghErrors.StructuredResolutionError

if errors.As(resolveErr, &structured) {

return ghErrors.NewStructuredResolutionErrorResponse(structured), nil, nil

}

return utils.NewToolResultError(resolveErr.Error()), nil, nil

}

itemID = resolvedItemID

}

rawUpdatedField, exists := args["updated_field"]

if !exists {

return utils.NewToolResultError("missing required parameter: updated_field"), nil, nil

}

fieldValue, ok := rawUpdatedField.(map[string]any)

if !ok || fieldValue == nil {

return utils.NewToolResultError("updated_field must be an object"), nil, nil

}

return updateProjectItem(ctx, client, gqlClient, owner, ownerType, projectNumber, itemID, fieldValue)

case projectsMethodUpdateProjectItems:

return updateProjectItemsBatch(ctx, client, gqlClient, owner, ownerType, projectNumber, args)

case projectsMethodDeleteProjectItem:

itemID, err := RequiredBigInt(args, "item_id")

if err != nil {

return utils.NewToolResultError(err.Error()), nil, nil

}

return deleteProjectItem(ctx, client, owner, ownerType, projectNumber, itemID)

case projectsMethodCreateProjectStatusUpdate:

body, err := OptionalParam[string](args, "body")

if err != nil {

return utils.NewToolResultError(err.Error()), nil, nil

}

status, err := OptionalParam[string](args, "status")

if err != nil {

return utils.NewToolResultError(err.Error()), nil, nil

}

startDate, err := OptionalParam[string](args, "start_date")

if err != nil {

return utils.NewToolResultError(err.Error()), nil, nil

}

targetDate, err := OptionalParam[string](args, "target_date")

if err != nil {

return utils.NewToolResultError(err.Error()), nil, nil

}

return createProjectStatusUpdate(ctx, gqlClient, owner, ownerType, projectNumber, body, status, startDate, targetDate)

case projectsMethodCreateIterationField:

return createIterationField(ctx, gqlClient, owner, ownerType, projectNumber, args)

default:

return utils.NewToolResultError(fmt.Sprintf("unknown method: %s", method)), nil, nil

}

},

)

return tool

}

// Helper functions for consolidated projects tools

func listProjects(ctx context.Context, client *github.Client, args map[string]any, owner, ownerType string) (*mcp.CallToolResult, []bool, any, error) {

queryStr, err := OptionalParam[string](args, "query")

if err != nil {

return utils.NewToolResultError(err.Error()), nil, nil, nil

}

pagination, err := extractPaginationOptionsFromArgs(args)

if err != nil {

return utils.NewToolResultError(err.Error()), nil, nil, nil

}

var resp *github.Response

var projects []*github.ProjectV2

minimalProjects := []MinimalProject{}

opts := &github.ListProjectsOptions{

ListProjectsPaginationOptions: pagination,

Query: queryStr,

}

// If owner_type not provided, fetch from both user and org

switch ownerType {

case "":

return listProjectsFromBothOwnerTypes(ctx, client, owner, opts)

case "org":

projects, resp, err = client.Projects.ListOrganizationProjects(ctx, owner, opts)

if err != nil {

return ghErrors.NewGitHubAPIErrorResponse(ctx,

"failed to list projects",

resp,

err,

), nil, nil, nil

}

default:

projects, resp, err = client.Projects.ListUserProjects(ctx, owner, opts)

if err != nil {

return ghErrors.NewGitHubAPIErrorResponse(ctx,

"failed to list projects",

resp,

err,

), nil, nil, nil

}

}

// For specified owner_type, process normally

if ownerType != "" {

defer func() { _ = resp.Body.Close() }()

for _, project := range projects {

mp := convertToMinimalProject(project)

mp.OwnerType = ownerType

minimalProjects = append(minimalProjects, *mp)

}

response := map[string]any{

"projects": minimalProjects,

"pageInfo": buildPageInfo(resp),

}

r, err := json.Marshal(response)

if err != nil {

return nil, nil, nil, fmt.Errorf("failed to marshal response: %w", err)

}

return utils.NewToolResultText(string(r)), projectVisibilities(minimalProjects), nil, nil

}

return nil, nil, nil, fmt.Errorf("unexpected state in listProjects")

}

// listProjectsFromBothOwnerTypes fetches projects from both user and org endpoints

// when owner_type is not specified, combining the results with owner_type labels.

func listProjectsFromBothOwnerTypes(ctx context.Context, client *github.Client, owner string, opts *github.ListProjectsOptions) (*mcp.CallToolResult, []bool, any, error) {

var minimalProjects []MinimalProject

var resp *github.Response

// Fetch user projects

userProjects, userResp, userErr := client.Projects.ListUserProjects(ctx, owner, opts)

if userErr == nil && userResp.StatusCode == http.StatusOK {

for _, project := range userProjects {

mp := convertToMinimalProject(project)

mp.OwnerType = "user"

minimalProjects = append(minimalProjects, *mp)

}

_ = userResp.Body.Close()

}

// Fetch org projects

orgProjects, orgResp, orgErr := client.Projects.ListOrganizationProjects(ctx, owner, opts)

if orgErr == nil && orgResp.StatusCode == http.StatusOK {

for _, project := range orgProjects {

mp := convertToMinimalProject(project)

mp.OwnerType = "org"

minimalProjects = append(minimalProjects, *mp)

}

resp = orgResp // Use org response for pagination info

} else if userResp != nil {

resp = userResp // Fallback to user response

}

// If both failed, return error

if (userErr != nil || userResp == nil || userResp.StatusCode != http.StatusOK) &&

(orgErr != nil || orgResp == nil || orgResp.StatusCode != http.StatusOK) {

return utils.NewToolResultError(fmt.Sprintf("failed to list projects for owner '%s': not found as user or organization", owner)), nil, nil, nil

}

response := map[string]any{

"projects": minimalProjects,

"note": "Results include both user and org projects. Each project includes 'owner_type' field. Pagination is limited when owner_type is not specified - specify 'owner_type' for full pagination support.",

}

if resp != nil {

response["pageInfo"] = buildPageInfo(resp)

defer func() { _ = resp.Body.Close() }()

}

r, err := json.Marshal(response)

if err != nil {

return nil, nil, nil, fmt.Errorf("failed to marshal response: %w", err)

}

return utils.NewToolResultText(string(r)), projectVisibilities(minimalProjects), nil, nil

}

func projectVisibilities(projects []MinimalProject) []bool {

visibilities := make([]bool, 0, len(projects))

for _, project := range projects {

isPrivate := true

if project.Public != nil {

isPrivate = !*project.Public

}

visibilities = append(visibilities, isPrivate)

}

return visibilities

}

func listProjectFields(ctx context.Context, client *github.Client, args map[string]any, owner, ownerType string) (*mcp.CallToolResult, any, error) {

projectNumber, err := RequiredInt(args, "project_number")

if err != nil {

return utils.NewToolResultError(err.Error()), nil, nil

}

pagination, err := extractPaginationOptionsFromArgs(args)

if err != nil {

return utils.NewToolResultError(err.Error()), nil, nil

}

var resp *github.Response

var projectFields []*github.ProjectV2Field

opts := &github.ListProjectsOptions{

ListProjectsPaginationOptions: pagination,

}

if ownerType == "org" {

projectFields, resp, err = client.Projects.ListOrganizationProjectFields(ctx, owner, projectNumber, opts)

} else {

projectFields, resp, err = client.Projects.ListUserProjectFields(ctx, owner, projectNumber, opts)