github-projects-mcp

Instructions

Args:
    owner: The GitHub organization or user name that owns the project
    project_number: The project number
    issue_owner: The owner of the repository containing the issue
    issue_repo: The repository name containing the issue
    issue_number: The issue number

Returns:
    A formatted string confirming the addition

Implementation Reference

• src/github_projects_mcp/server.py:307-340 (handler)

  MCP tool handler for 'add_issue_to_project'. Registers the tool via @mcp.tool(), defines input schema via type hints and docstring, executes by calling GitHubClient helper, and formats response.

  @mcp.tool()
  async def add_issue_to_project(
      owner: str,
      project_number: int,
      issue_owner: str,
      issue_repo: str,
      issue_number: int,
  ) -> str:
      """Add an existing GitHub issue to a Project V2.
  
      Args:
          owner: The GitHub organization or user name that owns the project
          project_number: The project number
          issue_owner: The owner of the repository containing the issue
          issue_repo: The repository name containing the issue
          issue_number: The issue number
  
      Returns:
          A formatted string confirming the addition
      """
      try:
          result = await github_client.add_issue_to_project(
              owner, project_number, issue_owner, issue_repo, issue_number
          )
          return (
              f"Successfully added issue {issue_owner}/{issue_repo}#{issue_number} to project #{project_number}!\n"
              f"Item ID: {result['id']}"
          )
      except GitHubClientError as e:
          logger.error(
              f"Error adding issue {issue_owner}/{issue_repo}#{issue_number} to project {owner}/{project_number}: {e}"
          )
          return f"Error: Could not add issue to project. Details: {e}"

• src/github_projects_mcp/github_client.py:825-928 (helper)

  Core implementation in GitHubClient: fetches project and issue node IDs, then executes GraphQL mutation 'addProjectV2ItemById' to add the issue to the project.

  async def add_issue_to_project(
      self,
      owner: str,
      project_number: int,
      issue_owner: str,
      issue_repo: str,
      issue_number: int,
  ) -> Dict[str, Any]:
      """Add an existing GitHub issue to a Project V2.
  
      Args:
          owner: The GitHub organization or user name that owns the project
          project_number: The project number
          issue_owner: The owner of the repository containing the issue
          issue_repo: The repository name containing the issue
          issue_number: The issue number
  
      Returns:
          The project item data
  
      Raises:
          GitHubClientError: If project or issue is not found, or adding fails.
      """
      # Get project ID
      try:
          project_id = await self.get_project_node_id(owner, project_number)
      except GitHubClientError as e:
          logger.error(f"Cannot add issue: {e}")
          raise
  
      # Get issue ID
      issue_query = """
      query GetIssueId($owner: String!, $repo: String!, $number: Int!) {
        repository(owner: $owner, name: $repo) {
          issue(number: $number) {
            id
          }
        }
      }
      """
  
      issue_variables = {
          "owner": issue_owner,
          "repo": issue_repo,
          "number": issue_number,
      }
  
      try:
          issue_result = await self.execute_query(issue_query, issue_variables)
          if not issue_result.get("repository") or not issue_result["repository"].get(
              "issue"
          ):
              raise GitHubClientError(
                  f"Issue {issue_number} not found in {issue_owner}/{issue_repo}"
              )
      except GitHubClientError as e:
          logger.error(
              f"Failed to get issue ID for {issue_owner}/{issue_repo}#{issue_number}: {e}"
          )
          raise
  
      issue_id = issue_result["repository"]["issue"]["id"]
  
      # Add issue to project
      add_query = """
      mutation AddItemToProject($projectId: ID!, $contentId: ID!) {
        addProjectV2ItemById(input: {
          projectId: $projectId,
          contentId: $contentId
        }) {
          item {
            id
            content {
              ... on Issue {
                title
                number
              }
              ... on PullRequest {
                title
                number
              }
            }
          }
        }
      }
      """
  
      variables = {"projectId": project_id, "contentId": issue_id}
  
      try:
          result = await self.execute_query(add_query, variables)
          if not result.get("addProjectV2ItemById") or not result[
              "addProjectV2ItemById"
          ].get("item"):
              raise GitHubClientError(
                  f"Failed to add issue {issue_number} to project {project_number}"
              )
          return result["addProjectV2ItemById"]["item"]
      except GitHubClientError as e:
          logger.error(
              f"Failed to add issue {issue_number} to project {project_number}: {e}"
          )
          raise