package github

import (

"context"

"encoding/json"

"errors"

"fmt"

"io"

"net/http"

"strconv"

"strings"

"time"

ghcontext "github.com/github/github-mcp-server/pkg/context"

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"

ProjectViewListFailedError = "failed to list project views"

ProjectViewGetFailedError = "failed to get project view"

ProjectViewCreateFailedError = "failed to create project view"

ProjectViewUpdateFailedError = "failed to update project view"

ProjectViewDeleteFailedError = "failed to delete project view"

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"

projectsMethodListProjectViews = "list_project_views"

projectsMethodGetProjectView = "get_project_view"

projectsMethodCreateProjectView = "create_project_view"

projectsMethodUpdateProjectView = "update_project_view"

projectsMethodDeleteProjectView = "delete_project_view"

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)"`

}

type projectViewNode struct {

ID githubv4.ID

Number githubv4.Int

Name githubv4.String

Layout githubv4.ProjectV2ViewLayout

Filter *githubv4.String

Configuration projectViewConfiguration

}

type projectViewConfiguration struct {

VisibleFields projectViewVisibleFieldsConnection `graphql:"visibleFields(first: 100)"`

}

type projectViewVisibleFieldsConnection struct {

Nodes []projectViewVisibleFieldNode

}

type projectViewVisibleFieldNode struct {

ProjectV2Field struct {

DatabaseID githubv4.Int `graphql:"databaseId"`

} `graphql:"... on ProjectV2Field"`

ProjectV2IterationField struct {

DatabaseID githubv4.Int `graphql:"databaseId"`

} `graphql:"... on ProjectV2IterationField"`

ProjectV2MultiSelectField struct {

DatabaseID githubv4.Int `graphql:"databaseId"`

} `graphql:"... on ProjectV2MultiSelectField"`

ProjectV2SingleSelectField struct {

DatabaseID githubv4.Int `graphql:"databaseId"`

} `graphql:"... on ProjectV2SingleSelectField"`

}

type projectViewNodeWithProject struct {

projectViewNode

Project projectVisibility

}

type projectViewConnection struct {

Nodes []projectViewNode

PageInfo PageInfoFragment

}

type projectViewsProject struct {

ID githubv4.ID

Public githubv4.Boolean

Views projectViewConnection `graphql:"views(first: $first, after: $after, last: $last, before: $before)"`

}

type projectViewsUserQuery struct {

User struct {

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

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

}

type projectViewsOrgQuery struct {

Organization struct {

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

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

}

type projectViewNodeQuery struct {

Node struct {

ProjectView projectViewNodeWithProject `graphql:"... on ProjectV2View"`

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

}

type projectViewParentQuery struct {

Node struct {

ProjectView struct {

ID githubv4.ID

Layout githubv4.ProjectV2ViewLayout

Project struct {

ID githubv4.ID

}

} `graphql:"... on ProjectV2View"`

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

}

// ProjectV2ViewConfigurationInput is the GraphQL view configuration input.

type ProjectV2ViewConfigurationInput struct {

VisibleFieldIDs []githubv4.ID `json:"visibleFieldIds"`

}

// CreateProjectV2ViewInput is the GraphQL input for creating a project view.

type CreateProjectV2ViewInput struct {

ProjectID githubv4.ID `json:"projectId"`

Name githubv4.String `json:"name"`

Layout githubv4.ProjectV2ViewLayout `json:"layout"`

Configuration *ProjectV2ViewConfigurationInput `json:"configuration,omitempty"`

}

// UpdateProjectV2ViewInput is the GraphQL input for updating a project view.

type UpdateProjectV2ViewInput struct {

ViewID githubv4.ID `json:"viewId"`

Name *githubv4.String `json:"name,omitempty"`

Layout *githubv4.ProjectV2ViewLayout `json:"layout,omitempty"`

Filter *githubv4.String `json:"filter,omitempty"`

Configuration *ProjectV2ViewConfigurationInput `json:"configuration,omitempty"`

}

type createProjectV2ViewMutation struct {

CreateProjectV2View struct {

ProjectV2View projectViewNode `graphql:"projectV2View"`

} `graphql:"createProjectV2View(input: $input)"`

}

type updateProjectV2ViewMutation struct {

UpdateProjectV2View struct {

ProjectV2View projectViewNode `graphql:"projectV2View"`

} `graphql:"updateProjectV2View(input: $input)"`

}

// DeleteProjectV2ViewInput is the GraphQL input for deleting a project view.

type DeleteProjectV2ViewInput struct {

ViewID githubv4.ID `json:"viewId"`

}

// 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, items, views, and status updates 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,

projectsMethodListProjectViews,

},

},

"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', 'list_project_views', 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, projectsMethodListProjectViews:

// 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

case projectsMethodListProjectViews:

gqlClient, err := deps.GetGQLClient(ctx)

if err != nil {

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

}

result, isPrivate, payload, err := listProjectViews(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, project items, and project views 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,

projectsMethodGetProjectView,

},

},

"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.",

},

"view_id": {

Type: "string",

Description: "The node ID of the project view. Required for 'get_project_view' 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 node-ID-only methods before requiring owner and project_number.

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

}

if method == projectsMethodGetProjectView {

viewID, err := RequiredParam[string](args, "view_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 := getProjectView(ctx, gqlClient, viewID)

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, "fields")

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, manage views, 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,

projectsMethodCreateProjectView,

projectsMethodUpdateProjectView,

projectsMethodDeleteProjectView,

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.",

},

"view_id": {

Type: "string",

Description: "Project view node ID for update or delete; must belong to owner/project_number.",

},

"name": {

Type: "string",

Description: "View name; required when creating a view.",

},

"layout": {

Type: "string",

Description: "View layout; required when creating a view.",

Enum: []any{"table", "board", "roadmap"},

},

"filter": {

AnyOf: []*jsonschema.Schema{

{Type: "string"},

{Type: "null"},

},

Description: "Saved view filter; omit on update to preserve it, or pass null to clear it.",

},

"visible_fields": {

Type: "array",

Description: "Ordered project field database IDs to show on create or replace on update; omit on update to preserve, or pass [] to reset. Mutually exclusive with visible_field_names. Roadmap accepts only [].",

Items: &jsonschema.Schema{

Type: "string",

},

},

"visible_field_names": {

Type: "array",

Description: "Ordered project field names to show on create or replace on update; omit on update to preserve, or pass [] to reset. Mutually exclusive with visible_fields. Roadmap accepts only [].",

Items: &jsonschema.Schema{

Type: "string",

},

},

"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

}

// create_project does not require project_number or a REST client

if method == projectsMethodCreateProject {

gqlClient, gqlErr := deps.GetGQLClient(ctx)

if gqlErr != nil {

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

}

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

}

}

gqlClient, err := deps.GetGQLClient(ctx)

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 {