Skip to main content

GitHub API

Manage GitHub repositories, issues, pull requests, branches, files, and comprehensive engineering metrics through the ConstellationAPI.

Base Path​

/github

Available MCP Tools​

The GitHub integration provides 27 tools accessible via the MCP protocol.

Tool Summary​

CategoryTools
Repositoryget_repositories, get_repository, list_repos_by_user, get_repository_users, get_contributors
Userget_user_by_email
Issuesget_issues, get_issue, create_issue, update_issue, get_issue_comments, add_issue_comment, add_issue_labels, remove_issue_labels
Pull Requestsget_pull_requests, get_stale_prs, create_pull_request, merge_pull_request
Branches & Filescreate_branch, create_or_update_file
Metricsget_dora_metrics, get_dora_metrics_by_repo, get_developer_metrics, get_actions_info, get_pr_developer_metrics, get_pr_merge_time_metrics, get_eng_metrics, get_eng_metrics_by_repo
User Workget_my_github_work

Repository Operations​

get_repositories​

List all GitHub repositories accessible to the user.

Input Schema:

{
  "type": "object",
  "properties": {
    "limit": {
      "type": "integer",
      "description": "Maximum number of results to return"
    },
    "offset": {
      "type": "integer",
      "description": "Number of results to skip"
    }
  },
  "required": []
}

Example Request:

curl -X POST http://localhost:3007/mcp/github/execute \
  -H "Content-Type: application/json" \
  -H "X-JWT-Token: <your-jwt-token>" \
  -d '{
    "tool": "get_repositories",
    "arguments": { "limit": 10 }
  }'

Example Response:

{
  "success": true,
  "data": {
    "repositories": [
      {
        "id": 123456789,
        "name": "constellation-api",
        "full_name": "acme-corp/constellation-api",
        "description": "Multi-tenant REST API for project management",
        "url": "https://github.com/acme-corp/constellation-api",
        "html_url": "https://github.com/acme-corp/constellation-api",
        "default_branch": "main",
        "private": true,
        "language": "Python",
        "stargazers_count": 42,
        "forks_count": 8,
        "open_issues_count": 15,
        "created_at": "2023-06-15T10:00:00Z",
        "updated_at": "2024-01-20T16:45:00Z"
      },
      {
        "id": 987654321,
        "name": "frontend-app",
        "full_name": "acme-corp/frontend-app",
        "description": "React frontend application",
        "url": "https://github.com/acme-corp/frontend-app",
        "default_branch": "main",
        "private": true,
        "language": "TypeScript",
        "stargazers_count": 28,
        "forks_count": 3
      }
    ],
    "count": 2
  }
}

get_repository​

Get details for a specific repository.

Input Schema:

{
  "type": "object",
  "properties": {
    "repo_id": {
      "type": "string",
      "description": "Repository identifier in owner/repo format (e.g., microsoft/vscode)"
    }
  },
  "required": ["repo_id"]
}

Example Response:

{
  "success": true,
  "data": {
    "id": 123456789,
    "name": "constellation-api",
    "full_name": "acme-corp/constellation-api",
    "description": "Multi-tenant REST API for project management",
    "owner": {
      "login": "acme-corp",
      "id": 12345,
      "type": "Organization"
    },
    "private": true,
    "default_branch": "main",
    "language": "Python",
    "topics": ["api", "python", "fastapi", "rest"],
    "license": {
      "key": "mit",
      "name": "MIT License"
    },
    "permissions": {
      "admin": true,
      "push": true,
      "pull": true
    }
  }
}

list_repos_by_user​

List repositories for a specific user.

Input Schema:

{
  "type": "object",
  "properties": {
    "username": {
      "type": "string",
      "description": "GitHub username"
    },
    "limit": {
      "type": "integer"
    }
  },
  "required": ["username"]
}

get_repository_users​

List collaborators with access to repositories.

Input Schema:

{
  "type": "object",
  "properties": {
    "repo_id": {
      "type": "string",
      "description": "Optional - if not provided, fetches from all accessible repositories in parallel"
    }
  },
  "required": []
}

Example Response:

{
  "success": true,
  "data": {
    "users": [
      {
        "login": "johndoe",
        "id": 12345,
        "avatar_url": "https://avatars.githubusercontent.com/u/12345",
        "type": "User",
        "permissions": {
          "admin": false,
          "push": true,
          "pull": true
        }
      },
      {
        "login": "janedoe",
        "id": 67890,
        "avatar_url": "https://avatars.githubusercontent.com/u/67890",
        "type": "User",
        "permissions": {
          "admin": true,
          "push": true,
          "pull": true
        }
      }
    ],
    "count": 2
  }
}

get_contributors​

List contributors who have committed code.

Input Schema:

{
  "type": "object",
  "properties": {
    "repo_id": {
      "type": "string",
      "description": "Optional - if not provided, aggregates from all accessible repositories"
    },
    "limit": {
      "type": "integer"
    }
  },
  "required": []
}

Example Response:

{
  "success": true,
  "data": {
    "contributors": [
      {
        "login": "johndoe",
        "id": 12345,
        "contributions": 256,
        "avatar_url": "https://avatars.githubusercontent.com/u/12345"
      },
      {
        "login": "janedoe",
        "id": 67890,
        "contributions": 189,
        "avatar_url": "https://avatars.githubusercontent.com/u/67890"
      }
    ],
    "total_contributions": 445,
    "contributors_count": 2
  }
}

User Operations​

get_user_by_email​

Look up a GitHub user by email address.

Input Schema:

{
  "type": "object",
  "properties": {
    "email": {
      "type": "string",
      "description": "User email address"
    }
  },
  "required": ["email"]
}

Example Request:

curl -X POST http://localhost:3007/mcp/github/execute \
  -H "Content-Type: application/json" \
  -H "X-JWT-Token: <your-jwt-token>" \
  -d '{
    "tool": "get_user_by_email",
    "arguments": { "email": "john.doe@example.com" }
  }'

Example Response:

{
  "success": true,
  "data": {
    "login": "johndoe",
    "id": 12345,
    "name": "John Doe",
    "email": "john.doe@example.com",
    "avatar_url": "https://avatars.githubusercontent.com/u/12345",
    "company": "Acme Corp",
    "location": "San Francisco, CA",
    "bio": "Full-stack developer"
  }
}

Issue Operations​

get_issues​

List GitHub issues with optional filters.

Input Schema:

{
  "type": "object",
  "properties": {
    "repo_id": {
      "type": "string",
      "description": "Optional - fetches from all accessible repositories if not provided"
    },
    "state": {
      "type": "string",
      "enum": ["open", "closed", "all"],
      "description": "Filter by issue state"
    },
    "labels": {
      "type": "array",
      "items": { "type": "string" },
      "description": "Filter by labels"
    },
    "limit": {
      "type": "integer"
    }
  },
  "required": []
}

Example Request:

curl -X POST http://localhost:3007/mcp/github/execute \
  -H "Content-Type: application/json" \
  -H "X-JWT-Token: <your-jwt-token>" \
  -d '{
    "tool": "get_issues",
    "arguments": {
      "repo_id": "acme-corp/api",
      "state": "open",
      "labels": ["bug"],
      "limit": 20
    }
  }'

Example Response:

{
  "success": true,
  "data": {
    "issues": [
      {
        "id": 789456123,
        "number": 42,
        "title": "Authentication fails with expired tokens",
        "body": "When a user's token expires, the error message is not helpful...",
        "state": "open",
        "labels": [
          { "id": 1, "name": "bug", "color": "d73a4a" },
          { "id": 2, "name": "priority-high", "color": "ff0000" }
        ],
        "assignees": [
          {
            "login": "johndoe",
            "id": 12345,
            "avatar_url": "https://avatars.githubusercontent.com/u/12345"
          }
        ],
        "user": {
          "login": "reporter123",
          "id": 99999
        },
        "comments": 5,
        "created_at": "2024-01-15T10:30:00Z",
        "updated_at": "2024-01-20T14:45:00Z"
      }
    ],
    "count": 1
  }
}

get_issue​

Get a specific issue by number.

Input Schema:

{
  "type": "object",
  "properties": {
    "repo_id": {
      "type": "string",
      "description": "Repository in owner/repo format"
    },
    "issue_number": {
      "type": "integer",
      "description": "Issue number"
    }
  },
  "required": ["repo_id", "issue_number"]
}

create_issue​

Create a new GitHub issue.

Input Schema:

{
  "type": "object",
  "properties": {
    "repo_id": {
      "type": "string",
      "description": "Repository in owner/repo format"
    },
    "title": {
      "type": "string",
      "description": "Issue title"
    },
    "body": {
      "type": "string",
      "description": "Issue description"
    },
    "labels": {
      "type": "array",
      "items": { "type": "string" },
      "description": "Labels to apply"
    },
    "assignees": {
      "type": "array",
      "items": { "type": "string" },
      "description": "Usernames to assign"
    }
  },
  "required": ["repo_id", "title"]
}

Example Request:

curl -X POST http://localhost:3007/mcp/github/execute \
  -H "Content-Type: application/json" \
  -H "X-JWT-Token: <your-jwt-token>" \
  -d '{
    "tool": "create_issue",
    "arguments": {
      "repo_id": "acme-corp/api",
      "title": "Add rate limiting to API endpoints",
      "body": "## Description\nWe need to implement rate limiting to prevent abuse.\n\n## Requirements\n- 100 requests per minute per user\n- Return 429 status when exceeded",
      "labels": ["enhancement", "api"],
      "assignees": ["johndoe"]
    }
  }'

Example Response:

{
  "success": true,
  "data": {
    "id": 789456124,
    "number": 43,
    "title": "Add rate limiting to API endpoints",
    "body": "## Description\nWe need to implement rate limiting...",
    "state": "open",
    "labels": [
      { "name": "enhancement", "color": "a2eeef" },
      { "name": "api", "color": "0075ca" }
    ],
    "assignees": [{ "login": "johndoe" }],
    "html_url": "https://github.com/acme-corp/api/issues/43",
    "created_at": "2024-01-25T10:00:00Z"
  }
}

update_issue​

Update an existing issue.

Input Schema:

{
  "type": "object",
  "properties": {
    "repo_id": { "type": "string" },
    "issue_number": { "type": "integer" },
    "title": { "type": "string" },
    "body": { "type": "string" },
    "state": { "type": "string", "enum": ["open", "closed"] },
    "labels": { "type": "array", "items": { "type": "string" } },
    "assignees": { "type": "array", "items": { "type": "string" } }
  },
  "required": ["repo_id", "issue_number"]
}

get_issue_comments​

List comments on an issue.

Input Schema:

{
  "type": "object",
  "properties": {
    "repo_id": { "type": "string" },
    "issue_number": { "type": "integer" }
  },
  "required": ["repo_id", "issue_number"]
}

Example Response:

{
  "success": true,
  "data": {
    "comments": [
      {
        "id": 111222333,
        "body": "I can reproduce this issue on the latest version.",
        "user": {
          "login": "janedoe",
          "id": 67890
        },
        "created_at": "2024-01-16T09:15:00Z",
        "updated_at": "2024-01-16T09:15:00Z"
      },
      {
        "id": 111222334,
        "body": "Fixed in PR #44",
        "user": {
          "login": "johndoe",
          "id": 12345
        },
        "created_at": "2024-01-18T14:30:00Z"
      }
    ],
    "count": 2
  }
}

add_issue_comment​

Add a comment to an issue.

Input Schema:

{
  "type": "object",
  "properties": {
    "repo_id": { "type": "string" },
    "issue_number": { "type": "integer" },
    "body": { "type": "string", "description": "Comment text" }
  },
  "required": ["repo_id", "issue_number", "body"]
}

add_issue_labels / remove_issue_labels​

Add or remove labels from an issue.

Input Schema:

{
  "type": "object",
  "properties": {
    "repo_id": { "type": "string" },
    "issue_number": { "type": "integer" },
    "labels": { "type": "array", "items": { "type": "string" } }
  },
  "required": ["repo_id", "issue_number", "labels"]
}

Pull Request Operations​

get_pull_requests​

List pull requests with optional filters.

Input Schema:

{
  "type": "object",
  "properties": {
    "repo_id": {
      "type": "string",
      "description": "Optional - fetches from all repos if not provided"
    },
    "state": {
      "type": "string",
      "enum": ["open", "closed", "all", "merged"]
    },
    "limit": { "type": "integer" }
  },
  "required": []
}

Example Response:

{
  "success": true,
  "data": {
    "pull_requests": [
      {
        "id": 987654321,
        "number": 15,
        "title": "Add OAuth2 authentication flow",
        "body": "This PR implements the OAuth2 authentication...",
        "state": "open",
        "draft": false,
        "user": {
          "login": "johndoe",
          "id": 12345
        },
        "head": {
          "ref": "feature/oauth2-auth",
          "sha": "abc123def456"
        },
        "base": {
          "ref": "main",
          "sha": "789xyz000"
        },
        "created_at": "2024-01-18T09:00:00Z",
        "updated_at": "2024-01-20T16:30:00Z",
        "additions": 450,
        "deletions": 120,
        "changed_files": 12,
        "mergeable": true,
        "reviews": [
          {
            "user": { "login": "janedoe" },
            "state": "APPROVED",
            "submitted_at": "2024-01-19T11:00:00Z"
          }
        ]
      }
    ],
    "count": 1
  }
}

get_stale_prs​

List pull requests with no recent activity.

Input Schema:

{
  "type": "object",
  "properties": {
    "repo_id": { "type": "string", "description": "Optional" },
    "days_threshold": {
      "type": "integer",
      "description": "Days of inactivity to consider stale (default: 7)"
    }
  },
  "required": []
}

Example Response:

{
  "success": true,
  "data": {
    "stale_prs": [
      {
        "number": 8,
        "title": "WIP: Refactor database layer",
        "user": { "login": "developer1" },
        "created_at": "2023-12-01T10:00:00Z",
        "updated_at": "2023-12-15T14:30:00Z",
        "days_stale": 36,
        "repo": "acme-corp/api"
      }
    ],
    "count": 1,
    "threshold_days": 7
  }
}

create_pull_request​

Create a new pull request.

Input Schema:

{
  "type": "object",
  "properties": {
    "repo_id": { "type": "string" },
    "title": { "type": "string" },
    "head": { "type": "string", "description": "Source branch" },
    "base": { "type": "string", "description": "Target branch (default: main)" },
    "body": { "type": "string" },
    "draft": { "type": "boolean" }
  },
  "required": ["repo_id", "title", "head"]
}

Example Request:

curl -X POST http://localhost:3007/mcp/github/execute \
  -H "Content-Type: application/json" \
  -H "X-JWT-Token: <your-jwt-token>" \
  -d '{
    "tool": "create_pull_request",
    "arguments": {
      "repo_id": "acme-corp/api",
      "title": "Add rate limiting middleware",
      "head": "feature/rate-limiting",
      "base": "main",
      "body": "## Changes\n- Added rate limiting middleware\n- Configurable limits per endpoint\n\n## Testing\n- Unit tests added\n- Manual testing completed",
      "draft": false
    }
  }'

merge_pull_request​

Merge a pull request.

Input Schema:

{
  "type": "object",
  "properties": {
    "repo_id": { "type": "string" },
    "pr_number": { "type": "integer" },
    "merge_method": {
      "type": "string",
      "enum": ["merge", "squash", "rebase"],
      "description": "Merge strategy"
    },
    "commit_message": { "type": "string" }
  },
  "required": ["repo_id", "pr_number"]
}

Branch & File Operations​

create_branch​

Create a new branch.

Input Schema:

{
  "type": "object",
  "properties": {
    "repo_id": { "type": "string" },
    "branch_name": { "type": "string" },
    "from_branch": { "type": "string", "description": "Source branch (default: main)" }
  },
  "required": ["repo_id", "branch_name"]
}

Example Response:

{
  "success": true,
  "data": {
    "ref": "refs/heads/feature/new-feature",
    "sha": "abc123def456789",
    "url": "https://api.github.com/repos/acme-corp/api/git/refs/heads/feature/new-feature"
  }
}

create_or_update_file​

Create or update a file in a repository.

Input Schema:

{
  "type": "object",
  "properties": {
    "repo_id": { "type": "string" },
    "path": { "type": "string", "description": "File path in repository" },
    "content": { "type": "string", "description": "File content" },
    "message": { "type": "string", "description": "Commit message" },
    "branch": { "type": "string", "description": "Target branch" }
  },
  "required": ["repo_id", "path", "content", "message"]
}

Metrics Operations​

get_dora_metrics​

Get DORA (DevOps Research and Assessment) metrics.

Input Schema:

{
  "type": "object",
  "properties": {
    "repo_ids": {
      "type": "string",
      "description": "Comma-separated repository IDs (optional - aggregates all if not provided)"
    },
    "time_period_days": {
      "type": "integer",
      "description": "Time period for calculation (default: 30)"
    }
  },
  "required": []
}

Example Response:

{
  "success": true,
  "data": {
    "deployment_frequency": {
      "value": 4.5,
      "unit": "deploys_per_week",
      "category": "High",
      "description": "Average successful workflow runs per week",
      "benchmark": {
        "elite": ">7 per week",
        "high": "1-7 per week",
        "medium": "1 per month to 1 per week",
        "low": "<1 per month"
      }
    },
    "lead_time_for_changes": {
      "value": 2.3,
      "unit": "hours",
      "category": "Elite",
      "description": "Average time from workflow start to completion",
      "p50": 1.8,
      "p90": 4.2
    },
    "change_failure_rate": {
      "value": 8.5,
      "unit": "percent",
      "category": "High",
      "description": "Percentage of failed workflows",
      "total_workflows": 200,
      "failed_workflows": 17
    },
    "mean_time_to_recovery": {
      "value": 1.2,
      "unit": "hours",
      "category": "Elite",
      "description": "Average time from failure to recovery",
      "incidents_count": 5
    },
    "metadata": {
      "time_period_days": 30,
      "repositories_analyzed": 5,
      "start_date": "2023-12-25",
      "end_date": "2024-01-25"
    }
  }
}

get_developer_metrics​

Get developer activity metrics.

Input Schema:

{
  "type": "object",
  "properties": {
    "repo_id": { "type": "string", "description": "Optional" },
    "time_period_days": { "type": "integer" },
    "limit": { "type": "integer" }
  },
  "required": []
}

Example Response:

{
  "success": true,
  "data": {
    "developers": [
      {
        "username": "johndoe",
        "avatar_url": "https://avatars.githubusercontent.com/u/12345",
        "commits": {
          "total": 45,
          "additions": 3500,
          "deletions": 1200
        },
        "pull_requests": {
          "opened": 12,
          "merged": 10,
          "closed": 1,
          "avg_size": 285
        },
        "reviews": {
          "given": 28,
          "approved": 22,
          "changes_requested": 6
        },
        "avg_pr_cycle_time_hours": 18.5
      },
      {
        "username": "janedoe",
        "commits": {
          "total": 38,
          "additions": 2800,
          "deletions": 900
        },
        "pull_requests": {
          "opened": 8,
          "merged": 7,
          "closed": 1
        },
        "reviews": {
          "given": 35,
          "approved": 30
        }
      }
    ],
    "period_days": 30,
    "total_developers": 2
  }
}

get_eng_metrics​

Get comprehensive engineering leadership metrics (DORA + SPACE framework).

Example Response:

{
  "success": true,
  "data": {
    "cycle_time": {
      "average_hours": 24.5,
      "p50_hours": 18.2,
      "p90_hours": 48.0,
      "trend": "improving"
    },
    "review_rate": {
      "average_hours_to_first_review": 4.2,
      "prs_reviewed_same_day_percent": 78.5
    },
    "throughput": {
      "prs_merged_per_week": 12.3,
      "avg_pr_size": 245
    },
    "work_in_progress": {
      "open_prs": 8,
      "avg_age_hours": 36.5
    },
    "quality": {
      "change_failure_rate_percent": 8.5,
      "revert_rate_percent": 2.1
    }
  }
}

get_my_github_work​

Get all open GitHub work for a user.

Input Schema:

{
  "type": "object",
  "properties": {
    "username": {
      "type": "string",
      "description": "GitHub username OR email address"
    }
  },
  "required": ["username"]
}

Example Response:

{
  "success": true,
  "data": {
    "user": "johndoe",
    "open_prs": [
      {
        "repo": "acme-corp/api",
        "number": 42,
        "title": "Add rate limiting",
        "created_at": "2024-01-20T10:00:00Z",
        "updated_at": "2024-01-22T15:30:00Z",
        "additions": 350,
        "deletions": 45,
        "review_status": "APPROVED"
      }
    ],
    "review_requests": [
      {
        "repo": "acme-corp/frontend",
        "number": 38,
        "title": "Update dashboard components",
        "author": "janedoe",
        "created_at": "2024-01-21T09:00:00Z"
      }
    ],
    "assigned_issues": [
      {
        "repo": "acme-corp/api",
        "number": 15,
        "title": "Fix authentication timeout",
        "state": "open",
        "labels": ["bug", "priority-high"]
      }
    ],
    "summary": {
      "open_prs": 1,
      "reviews_pending": 1,
      "assigned_issues": 1,
      "total_work_items": 3
    }
  }
}

Error Handling​

Common Errors​

Repository Not Found:

{
  "success": false,
  "error": "Repository 'invalid/repo' not found or not accessible"
}

Rate Limit Exceeded:

{
  "success": false,
  "error": "GitHub API rate limit exceeded. Resets at 2024-01-25T12:00:00Z"
}

Authentication Error:

{
  "success": false,
  "error": "Invalid GitHub token or insufficient permissions"
}

Best Practices​

  1. Use Parallel Fetching: Omit repo_id to fetch from all repositories in parallel
  2. Leverage Metrics: Use DORA and engineering metrics for team insights
  3. Check Stale PRs: Regularly review get_stale_prs to maintain code review velocity
  4. User Lookup: Use get_user_by_email when you have email addresses from other systems
  5. Atomic Operations: Use create_or_update_file for simple file changes without full Git workflow