diff --git a/.github/workflows/docs-check.yml b/.github/workflows/docs-check.yml new file mode 100644 index 000000000..c28c528b2 --- /dev/null +++ b/.github/workflows/docs-check.yml @@ -0,0 +1,47 @@ +name: Documentation Check + +on: + push: + branches: [ main ] + pull_request: + branches: [ main ] + +permissions: + contents: read + +jobs: + docs-check: + runs-on: ubuntu-latest + steps: + - name: Checkout code + uses: actions/checkout@v4 + + - name: Set up Go + uses: actions/setup-go@v5 + with: + go-version-file: 'go.mod' + + - name: Build docs generator + run: go build -o github-mcp-server ./cmd/github-mcp-server + + - name: Generate documentation + run: ./github-mcp-server generate-docs + + - name: Check for documentation changes + run: | + if ! git diff --exit-code README.md; then + echo "❌ Documentation is out of date!" + echo "" + echo "The generated documentation differs from what's committed." + echo "Please run the following command to update the documentation:" + echo "" + echo " go run ./cmd/github-mcp-server generate-docs" + echo "" + echo "Then commit the changes." + echo "" + echo "Changes detected:" + git diff README.md + exit 1 + else + echo "✅ Documentation is up to date!" + fi diff --git a/README.md b/README.md index f1f3bdaf0..4458b95ab 100644 --- a/README.md +++ b/README.md @@ -263,19 +263,21 @@ _Toolsets are not limited to Tools. Relevant MCP Resources and Prompts are also The following sets of tools are available (all are on by default): + | Toolset | Description | | ----------------------- | ------------------------------------------------------------- | -| `actions` | GitHub Actions workflows and CI/CD operations | | `context` | **Strongly recommended**: Tools that provide context about the current user and GitHub context you are operating in | -| `code_security` | Code scanning alerts and security features | -| `issues` | Issue-related tools (create, read, update, comment) | -| `notifications` | GitHub Notifications related tools | -| `pull_requests` | Pull request operations (create, merge, review) | -| `repos` | Repository-related tools (file operations, branches, commits) | -| `secret_protection` | Secret protection related tools, such as GitHub Secret Scanning | -| `users` | Anything relating to GitHub Users | -| `experiments` | Experimental features (not considered stable) | - +| `actions` | GitHub Actions workflows and CI/CD operations | +| `code_security` | Code security related tools, such as GitHub Code Scanning | +| `experiments` | Experimental features that are not considered stable yet | +| `issues` | GitHub Issues related tools | +| `notifications` | GitHub Notifications related tools | +| `orgs` | GitHub Organization related tools | +| `pull_requests` | GitHub Pull Request related tools | +| `repos` | GitHub Repository related tools | +| `secret_protection` | Secret protection related tools, such as GitHub Secret Scanning | +| `users` | GitHub User related tools | + #### Specifying Toolsets @@ -426,582 +428,510 @@ export GITHUB_MCP_TOOL_ADD_ISSUE_COMMENT_DESCRIPTION="an alternative description ## Tools -

- -

Context

- -- **get_me** - Get details of the authenticated user - - No parameters required - -

Issues

- -- **get_issue** - Gets the contents of an issue within a repository +

Actions

+- **cancel_workflow_run** - Cancel workflow run - `owner`: Repository owner (string, required) - `repo`: Repository name (string, required) - - `issue_number`: Issue number (number, required) - -- **get_issue_comments** - Get comments for a GitHub issue + - `run_id`: The unique identifier of the workflow run (number, required) +- **delete_workflow_run_logs** - Delete workflow logs - `owner`: Repository owner (string, required) - `repo`: Repository name (string, required) - - `issue_number`: Issue number (number, required) - -- **create_issue** - Create a new issue in a GitHub repository + - `run_id`: The unique identifier of the workflow run (number, required) +- **download_workflow_run_artifact** - Download workflow artifact + - `artifact_id`: The unique identifier of the artifact (number, required) - `owner`: Repository owner (string, required) - `repo`: Repository name (string, required) - - `title`: Issue title (string, required) - - `body`: Issue body content (string, optional) - - `assignees`: Usernames to assign to this issue (string[], optional) - - `labels`: Labels to apply to this issue (string[], optional) - -- **add_issue_comment** - Add a comment to an issue +- **get_job_logs** - Get job logs + - `failed_only`: When true, gets logs for all failed jobs in run_id (boolean, optional) + - `job_id`: The unique identifier of the workflow job (required for single job logs) (number, optional) - `owner`: Repository owner (string, required) - `repo`: Repository name (string, required) - - `issue_number`: Issue number (number, required) - - `body`: Comment text (string, required) - -- **list_issues** - List and filter repository issues + - `return_content`: Returns actual log content instead of URLs (boolean, optional) + - `run_id`: Workflow run ID (required when using failed_only) (number, optional) +- **get_workflow_run** - Get workflow run - `owner`: Repository owner (string, required) - `repo`: Repository name (string, required) - - `state`: Filter by state ('open', 'closed', 'all') (string, optional) - - `labels`: Labels to filter by (string[], optional) - - `sort`: Sort by ('created', 'updated', 'comments') (string, optional) - - `direction`: Sort direction ('asc', 'desc') (string, optional) - - `since`: Filter by date (ISO 8601 timestamp) (string, optional) - - `page`: Page number (number, optional) - - `perPage`: Results per page (number, optional) - -- **update_issue** - Update an existing issue in a GitHub repository + - `run_id`: The unique identifier of the workflow run (number, required) +- **get_workflow_run_logs** - Get workflow run logs - `owner`: Repository owner (string, required) - `repo`: Repository name (string, required) - - `issue_number`: Issue number to update (number, required) - - `title`: New title (string, optional) - - `body`: New description (string, optional) - - `state`: New state ('open' or 'closed') (string, optional) - - `labels`: New labels (string[], optional) - - `assignees`: New assignees (string[], optional) - - `milestone`: New milestone number (number, optional) - -- **search_issues** - Search for issues and pull requests - - `query`: Search query (string, required) - - `sort`: Sort field (string, optional) - - `order`: Sort order (string, optional) - - `page`: Page number (number, optional) - - `perPage`: Results per page (number, optional) - -- **assign_copilot_to_issue** - Assign Copilot to a specific issue in a GitHub repository + - `run_id`: The unique identifier of the workflow run (number, required) +- **get_workflow_run_usage** - Get workflow usage - `owner`: Repository owner (string, required) - `repo`: Repository name (string, required) - - `issueNumber`: Issue number (number, required) - - _Note_: This tool can help with creating a Pull Request with source code changes to resolve the issue. More information can be found at [GitHub Copilot documentation](https://docs.github.com/en/copilot/using-github-copilot/using-copilot-coding-agent-to-work-on-tasks/about-assigning-tasks-to-copilot) - -

- -

Pull Requests

- -- **get_pull_request** - Get details of a specific pull request + - `run_id`: The unique identifier of the workflow run (number, required) +- **list_workflow_jobs** - List workflow jobs + - `filter`: Filters jobs by their completed_at timestamp (string, optional) - `owner`: Repository owner (string, required) + - `page`: The page number of the results to fetch (number, optional) + - `per_page`: The number of results per page (max 100) (number, optional) - `repo`: Repository name (string, required) - - `pullNumber`: Pull request number (number, required) - -- **list_pull_requests** - List and filter repository pull requests + - `run_id`: The unique identifier of the workflow run (number, required) +- **list_workflow_run_artifacts** - List workflow artifacts - `owner`: Repository owner (string, required) + - `page`: The page number of the results to fetch (number, optional) + - `per_page`: The number of results per page (max 100) (number, optional) - `repo`: Repository name (string, required) - - `state`: PR state (string, optional) - - `sort`: Sort field (string, optional) - - `direction`: Sort direction (string, optional) - - `perPage`: Results per page (number, optional) - - `page`: Page number (number, optional) - -- **merge_pull_request** - Merge a pull request + - `run_id`: The unique identifier of the workflow run (number, required) +- **list_workflow_runs** - List workflow runs + - `actor`: Returns someone's workflow runs. Use the login for the user who created the workflow run. (string, optional) + - `branch`: Returns workflow runs associated with a branch. Use the name of the branch. (string, optional) + - `event`: Returns workflow runs for a specific event type (string, optional) - `owner`: Repository owner (string, required) + - `page`: The page number of the results to fetch (number, optional) + - `per_page`: The number of results per page (max 100) (number, optional) - `repo`: Repository name (string, required) - - `pullNumber`: Pull request number (number, required) - - `commit_title`: Title for the merge commit (string, optional) - - `commit_message`: Message for the merge commit (string, optional) - - `merge_method`: Merge method (string, optional) - -- **get_pull_request_files** - Get the list of files changed in a pull request + - `status`: Returns workflow runs with the check run status (string, optional) + - `workflow_id`: The workflow ID or workflow file name (string, required) +- **list_workflows** - List workflows - `owner`: Repository owner (string, required) + - `page`: The page number of the results to fetch (number, optional) + - `per_page`: The number of results per page (max 100) (number, optional) - `repo`: Repository name (string, required) - - `pullNumber`: Pull request number (number, required) - -- **get_pull_request_status** - Get the combined status of all status checks for a pull request +- **rerun_failed_jobs** - Rerun failed jobs - `owner`: Repository owner (string, required) - `repo`: Repository name (string, required) - - `pullNumber`: Pull request number (number, required) - -- **update_pull_request_branch** - Update a pull request branch with the latest changes from the base branch + - `run_id`: The unique identifier of the workflow run (number, required) +- **rerun_workflow_run** - Rerun workflow run - `owner`: Repository owner (string, required) - `repo`: Repository name (string, required) - - `pullNumber`: Pull request number (number, required) - - `expectedHeadSha`: The expected SHA of the pull request's HEAD ref (string, optional) - -- **get_pull_request_comments** - Get the review comments on a pull request + - `run_id`: The unique identifier of the workflow run (number, required) +- **run_workflow** - Run workflow + - `inputs`: Inputs the workflow accepts (object, optional) - `owner`: Repository owner (string, required) + - `ref`: The git reference for the workflow. The reference can be a branch or tag name. (string, required) - `repo`: Repository name (string, required) - - `pullNumber`: Pull request number (number, required) + - `workflow_id`: The workflow ID (numeric) or workflow file name (e.g., main.yml, ci.yaml) (string, required) -- **get_pull_request_reviews** - Get the reviews on a pull request +

- - `owner`: Repository owner (string, required) - - `repo`: Repository name (string, required) - - `pullNumber`: Pull request number (number, required) +

-- **get_pull_request_diff** - Get the diff of a pull request +

Code Security

- - `owner`: Repository owner (string, required) - - `repo`: Repository name (string, required) - - `pullNumber`: Pull request number (number, required) +- **get_code_scanning_alert** - Get code scanning alert + - `alertNumber`: The number of the alert. (number, required) + - `owner`: The owner of the repository. (string, required) + - `repo`: The name of the repository. (string, required) -- **create_pending_pull_request_review** - Create a pending review for a pull request that can be submitted later +- **list_code_scanning_alerts** - List code scanning alerts + - `owner`: The owner of the repository. (string, required) + - `ref`: The Git reference for the results you want to list. (string, optional) + - `repo`: The name of the repository. (string, required) + - `severity`: Filter code scanning alerts by severity (string, optional) + - `state`: Filter code scanning alerts by state. Defaults to open (string, optional) + - `tool_name`: The name of the tool used for code scanning. (string, optional) - - `owner`: Repository owner (string, required) - - `repo`: Repository name (string, required) - - `pullNumber`: Pull request number (number, required) - - `commitID`: SHA of commit to review (string, optional) +

-- **add_pull_request_review_comment_to_pending_review** - Add a comment to the requester's latest pending pull request review +

- - `owner`: Repository owner (string, required) - - `repo`: Repository name (string, required) - - `pullNumber`: Pull request number (number, required) - - `path`: The relative path to the file that necessitates a comment (string, required) - - `body`: The text of the review comment (string, required) - - `subjectType`: The level at which the comment is targeted (string, required) - - Enum: "FILE", "LINE" - - `line`: The line of the blob in the pull request diff that the comment applies to (number, optional) - - `side`: The side of the diff to comment on (string, optional) - - Enum: "LEFT", "RIGHT" - - `startLine`: For multi-line comments, the first line of the range (number, optional) - - `startSide`: For multi-line comments, the starting side of the diff (string, optional) - - Enum: "LEFT", "RIGHT" +

Context

-- **submit_pending_pull_request_review** - Submit the requester's latest pending pull request review +- **get_me** - Get my user profile + - `reason`: Optional: the reason for requesting the user information (string, optional) - - `owner`: Repository owner (string, required) - - `repo`: Repository name (string, required) - - `pullNumber`: Pull request number (number, required) - - `event`: The event to perform (string, required) - - Enum: "APPROVE", "REQUEST_CHANGES", "COMMENT" - - `body`: The text of the review comment (string, optional) +

-- **delete_pending_pull_request_review** - Delete the requester's latest pending pull request review +

+ +

Issues

+- **add_issue_comment** - Add comment to issue + - `body`: Comment content (string, required) + - `issue_number`: Issue number to comment on (number, required) - `owner`: Repository owner (string, required) - `repo`: Repository name (string, required) - - `pullNumber`: Pull request number (number, required) -- **create_and_submit_pull_request_review** - Create and submit a review for a pull request without review comments +- **assign_copilot_to_issue** - Assign Copilot to issue + - `issueNumber`: Issue number (number, required) + - `owner`: Repository owner (string, required) + - `repo`: Repository name (string, required) +- **create_issue** - Open new issue + - `assignees`: Usernames to assign to this issue (string[], optional) + - `body`: Issue body content (string, optional) + - `labels`: Labels to apply to this issue (string[], optional) + - `milestone`: Milestone number (number, optional) - `owner`: Repository owner (string, required) - `repo`: Repository name (string, required) - - `pullNumber`: Pull request number (number, required) - - `body`: Review comment text (string, required) - - `event`: Review action ('APPROVE', 'REQUEST_CHANGES', 'COMMENT') (string, required) - - `commitID`: SHA of commit to review (string, optional) + - `title`: Issue title (string, required) -- **create_pull_request** - Create a new pull request +- **get_issue** - Get issue details + - `issue_number`: The number of the issue (number, required) + - `owner`: The owner of the repository (string, required) + - `repo`: The name of the repository (string, required) +- **get_issue_comments** - Get issue comments + - `issue_number`: Issue number (number, required) - `owner`: Repository owner (string, required) + - `page`: Page number (number, optional) + - `per_page`: Number of records per page (number, optional) - `repo`: Repository name (string, required) - - `title`: PR title (string, required) - - `body`: PR description (string, optional) - - `head`: Branch containing changes (string, required) - - `base`: Branch to merge into (string, required) - - `draft`: Create as draft PR (boolean, optional) - - `maintainer_can_modify`: Allow maintainer edits (boolean, optional) -- **update_pull_request** - Update an existing pull request in a GitHub repository +- **list_issues** - List issues + - `direction`: Sort direction (string, optional) + - `labels`: Filter by labels (string[], optional) + - `owner`: Repository owner (string, required) + - `page`: Page number for pagination (min 1) (number, optional) + - `perPage`: Results per page for pagination (min 1, max 100) (number, optional) + - `repo`: Repository name (string, required) + - `since`: Filter by date (ISO 8601 timestamp) (string, optional) + - `sort`: Sort order (string, optional) + - `state`: Filter by state (string, optional) +- **search_issues** - Search issues + - `order`: Sort order (string, optional) + - `owner`: Optional repository owner. If provided with repo, only notifications for this repository are listed. (string, optional) + - `page`: Page number for pagination (min 1) (number, optional) + - `perPage`: Results per page for pagination (min 1, max 100) (number, optional) + - `query`: Search query using GitHub issues search syntax (string, required) + - `repo`: Optional repository name. If provided with owner, only notifications for this repository are listed. (string, optional) + - `sort`: Sort field by number of matches of categories, defaults to best match (string, optional) + +- **update_issue** - Edit issue + - `assignees`: New assignees (string[], optional) + - `body`: New description (string, optional) + - `issue_number`: Issue number to update (number, required) + - `labels`: New labels (string[], optional) + - `milestone`: New milestone number (number, optional) - `owner`: Repository owner (string, required) - `repo`: Repository name (string, required) - - `pullNumber`: Pull request number to update (number, required) + - `state`: New state (string, optional) - `title`: New title (string, optional) - - `body`: New description (string, optional) - - `state`: New state ('open' or 'closed') (string, optional) - - `base`: New base branch name (string, optional) - - `maintainer_can_modify`: Allow maintainer edits (boolean, optional) -- **request_copilot_review** - Request a GitHub Copilot review for a pull request (experimental; subject to GitHub API support) +

- - `owner`: Repository owner (string, required) - - `repo`: Repository name (string, required) - - `pullNumber`: Pull request number (number, required) - - _Note_: Currently, this tool will only work for github.com +

+ +

Notifications

+ +- **dismiss_notification** - Dismiss notification + - `state`: The new state of the notification (read/done) (string, optional) + - `threadID`: The ID of the notification thread (string, required) + +- **get_notification_details** - Get notification details + - `notificationID`: The ID of the notification (string, required) + +- **list_notifications** - List notifications + - `before`: Only show notifications updated before the given time (ISO 8601 format) (string, optional) + - `filter`: Filter notifications to, use default unless specified. Read notifications are ones that have already been acknowledged by the user. Participating notifications are those that the user is directly involved in, such as issues or pull requests they have commented on or created. (string, optional) + - `owner`: Optional repository owner. If provided with repo, only notifications for this repository are listed. (string, optional) + - `page`: Page number for pagination (min 1) (number, optional) + - `perPage`: Results per page for pagination (min 1, max 100) (number, optional) + - `repo`: Optional repository name. If provided with owner, only notifications for this repository are listed. (string, optional) + - `since`: Only show notifications updated after the given time (ISO 8601 format) (string, optional) + +- **manage_notification_subscription** - Manage notification subscription + - `action`: Action to perform: ignore, watch, or delete the notification subscription. (string, required) + - `notificationID`: The ID of the notification thread. (string, required) + +- **manage_repository_notification_subscription** - Manage repository notification subscription + - `action`: Action to perform: ignore, watch, or delete the repository notification subscription. (string, required) + - `owner`: The account owner of the repository. (string, required) + - `repo`: The name of the repository. (string, required) + +- **mark_all_notifications_read** - Mark all notifications as read + - `lastReadAt`: Describes the last point that notifications were checked (optional). Default: Now (string, optional) + - `owner`: Optional repository owner. If provided with repo, only notifications for this repository are marked as read. (string, optional) + - `repo`: Optional repository name. If provided with owner, only notifications for this repository are marked as read. (string, optional)

Repositories

Organizations

-- **create_or_update_file** - Create or update a single file in a repository - - `owner`: Repository owner (string, required) - - `repo`: Repository name (string, required) - - `path`: File path (string, required) - - `message`: Commit message (string, required) - - `content`: File content (string, required) - - `branch`: Branch name (string, optional) - - `sha`: File SHA if updating (string, optional) +- **search_orgs** - Search organizations + - `order`: Sort order (string, optional) + - `page`: Page number for pagination (min 1) (number, optional) + - `perPage`: Results per page for pagination (min 1, max 100) (number, optional) + - `query`: Search query using GitHub organizations search syntax scoped to type:org (string, required) + - `sort`: Sort field by category (string, optional) -- **delete_file** - Delete a file from a GitHub repository +

+ +

Pull Requests

+ +- **add_pull_request_review_comment_to_pending_review** - Add comment to the requester's latest pending pull request review + - `body`: The text of the review comment (string, required) + - `line`: The line of the blob in the pull request diff that the comment applies to. For multi-line comments, the last line of the range (number, optional) - `owner`: Repository owner (string, required) + - `path`: The relative path to the file that necessitates a comment (string, required) + - `pullNumber`: Pull request number (number, required) - `repo`: Repository name (string, required) - - `path`: Path to the file to delete (string, required) - - `message`: Commit message (string, required) - - `branch`: Branch to delete the file from (string, required) + - `side`: The side of the diff to comment on. LEFT indicates the previous state, RIGHT indicates the new state (string, optional) + - `startLine`: For multi-line comments, the first line of the range that the comment applies to (number, optional) + - `startSide`: For multi-line comments, the starting side of the diff that the comment applies to. LEFT indicates the previous state, RIGHT indicates the new state (string, optional) + - `subjectType`: The level at which the comment is targeted (string, required) -- **list_branches** - List branches in a GitHub repository +- **create_and_submit_pull_request_review** - Create and submit a pull request review without comments + - `body`: Review comment text (string, required) + - `commitID`: SHA of commit to review (string, optional) + - `event`: Review action to perform (string, required) - `owner`: Repository owner (string, required) + - `pullNumber`: Pull request number (number, required) - `repo`: Repository name (string, required) - - `page`: Page number (number, optional) - - `perPage`: Results per page (number, optional) -- **push_files** - Push multiple files in a single commit +- **create_pending_pull_request_review** - Create pending pull request review + - `commitID`: SHA of commit to review (string, optional) - `owner`: Repository owner (string, required) + - `pullNumber`: Pull request number (number, required) - `repo`: Repository name (string, required) - - `branch`: Branch to push to (string, required) - - `files`: Files to push, each with path and content (array, required) - - `message`: Commit message (string, required) - -- **search_repositories** - Search for GitHub repositories - - `query`: Search query (string, required) - - `sort`: Sort field (string, optional) - - `order`: Sort order (string, optional) - - `page`: Page number (number, optional) - - `perPage`: Results per page (number, optional) - -- **create_repository** - Create a new GitHub repository - - `name`: Repository name (string, required) - - `description`: Repository description (string, optional) - - `private`: Whether the repository is private (boolean, optional) - - `autoInit`: Auto-initialize with README (boolean, optional) -- **get_file_contents** - Get contents of a file or directory +- **create_pull_request** - Open new pull request + - `base`: Branch to merge into (string, required) + - `body`: PR description (string, optional) + - `draft`: Create as draft PR (boolean, optional) + - `head`: Branch containing changes (string, required) + - `maintainer_can_modify`: Allow maintainer edits (boolean, optional) - `owner`: Repository owner (string, required) - `repo`: Repository name (string, required) - - `path`: File path (string, required) - - `ref`: Git reference (string, optional) + - `title`: PR title (string, required) -- **fork_repository** - Fork a repository +- **delete_pending_pull_request_review** - Delete the requester's latest pending pull request review - `owner`: Repository owner (string, required) + - `pullNumber`: Pull request number (number, required) - `repo`: Repository name (string, required) - - `organization`: Target organization name (string, optional) -- **create_branch** - Create a new branch +- **get_pull_request** - Get pull request details - `owner`: Repository owner (string, required) + - `pullNumber`: Pull request number (number, required) - `repo`: Repository name (string, required) - - `branch`: New branch name (string, required) - - `sha`: SHA to create branch from (string, required) -- **list_commits** - Get a list of commits of a branch in a repository +- **get_pull_request_comments** - Get pull request comments - `owner`: Repository owner (string, required) + - `pullNumber`: Pull request number (number, required) - `repo`: Repository name (string, required) - - `sha`: Branch name, tag, or commit SHA (string, optional) - - `author`: Author username or email address (string, optional) - - `path`: Only commits containing this file path (string, optional) - - `page`: Page number (number, optional) - - `perPage`: Results per page (number, optional) -- **get_commit** - Get details for a commit from a repository +- **get_pull_request_diff** - Get pull request diff - `owner`: Repository owner (string, required) + - `pullNumber`: Pull request number (number, required) - `repo`: Repository name (string, required) - - `sha`: Commit SHA, branch name, or tag name (string, required) - - `page`: Page number, for files in the commit (number, optional) - - `perPage`: Results per page, for files in the commit (number, optional) -- **get_tag** - Get details about a specific git tag in a GitHub repository +- **get_pull_request_files** - Get pull request files - `owner`: Repository owner (string, required) + - `page`: Page number for pagination (min 1) (number, optional) + - `perPage`: Results per page for pagination (min 1, max 100) (number, optional) + - `pullNumber`: Pull request number (number, required) - `repo`: Repository name (string, required) - - `tag`: Tag name (string, required) -- **list_tags** - List git tags in a GitHub repository +- **get_pull_request_reviews** - Get pull request reviews - `owner`: Repository owner (string, required) + - `pullNumber`: Pull request number (number, required) - `repo`: Repository name (string, required) - - `page`: Page number (number, optional) - - `perPage`: Results per page (number, optional) - -- **search_code** - Search for code across GitHub repositories - - `query`: Search query (string, required) - - `sort`: Sort field (string, optional) - - `order`: Sort order (string, optional) - - `page`: Page number (number, optional) - - `perPage`: Results per page (number, optional) - -

- -

Users

- -- **search_users** - Search for GitHub users - - `q`: Search query (string, required) - - `sort`: Sort field (string, optional) - - `order`: Sort order (string, optional) - - `page`: Page number (number, optional) - - `perPage`: Results per page (number, optional) - -

- -

Actions

- -- **list_workflows** - List workflows in a repository +- **get_pull_request_status** - Get pull request status checks - `owner`: Repository owner (string, required) + - `pullNumber`: Pull request number (number, required) - `repo`: Repository name (string, required) - - `page`: Page number (number, optional) - - `perPage`: Results per page (number, optional) - -- **list_workflow_runs** - List workflow runs for a specific workflow +- **list_pull_requests** - List pull requests + - `base`: Filter by base branch (string, optional) + - `direction`: Sort direction (string, optional) + - `head`: Filter by head user/org and branch (string, optional) - `owner`: Repository owner (string, required) + - `page`: Page number for pagination (min 1) (number, optional) + - `perPage`: Results per page for pagination (min 1, max 100) (number, optional) - `repo`: Repository name (string, required) - - `workflow_id`: Workflow ID or filename (string, required) - - `branch`: Filter by branch name (string, optional) - - `event`: Filter by event type (string, optional) - - `status`: Filter by run status (string, optional) - - `page`: Page number (number, optional) - - `perPage`: Results per page (number, optional) - -- **run_workflow** - Trigger a workflow via workflow_dispatch event + - `sort`: Sort by (string, optional) + - `state`: Filter by state (string, optional) +- **merge_pull_request** - Merge pull request + - `commit_message`: Extra detail for merge commit (string, optional) + - `commit_title`: Title for merge commit (string, optional) + - `merge_method`: Merge method (string, optional) - `owner`: Repository owner (string, required) + - `pullNumber`: Pull request number (number, required) - `repo`: Repository name (string, required) - - `workflow_id`: Workflow ID or filename (string, required) - - `ref`: Git reference (branch, tag, or SHA) (string, required) - - `inputs`: Input parameters for the workflow (object, optional) - -- **get_workflow_run** - Get details of a specific workflow run +- **request_copilot_review** - Request Copilot review - `owner`: Repository owner (string, required) + - `pullNumber`: Pull request number (number, required) - `repo`: Repository name (string, required) - - `run_id`: Workflow run ID (number, required) -- **get_workflow_run_logs** - Download logs for a workflow run +- **search_pull_requests** - Search pull requests + - `order`: Sort order (string, optional) + - `owner`: Optional repository owner. If provided with repo, only notifications for this repository are listed. (string, optional) + - `page`: Page number for pagination (min 1) (number, optional) + - `perPage`: Results per page for pagination (min 1, max 100) (number, optional) + - `query`: Search query using GitHub pull request search syntax (string, required) + - `repo`: Optional repository name. If provided with owner, only notifications for this repository are listed. (string, optional) + - `sort`: Sort field by number of matches of categories, defaults to best match (string, optional) +- **submit_pending_pull_request_review** - Submit the requester's latest pending pull request review + - `body`: The text of the review comment (string, optional) + - `event`: The event to perform (string, required) - `owner`: Repository owner (string, required) + - `pullNumber`: Pull request number (number, required) - `repo`: Repository name (string, required) - - `run_id`: Workflow run ID (number, required) - -- **list_workflow_jobs** - List jobs for a workflow run +- **update_pull_request** - Edit pull request + - `base`: New base branch name (string, optional) + - `body`: New description (string, optional) + - `maintainer_can_modify`: Allow maintainer edits (boolean, optional) - `owner`: Repository owner (string, required) + - `pullNumber`: Pull request number to update (number, required) - `repo`: Repository name (string, required) - - `run_id`: Workflow run ID (number, required) - - `filter`: Filter by job status (string, optional) - - `page`: Page number (number, optional) - - `perPage`: Results per page (number, optional) - -- **get_job_logs** - Download logs for a specific workflow job or efficiently get all failed job logs for a workflow run + - `state`: New state (string, optional) + - `title`: New title (string, optional) +- **update_pull_request_branch** - Update pull request branch + - `expectedHeadSha`: The expected SHA of the pull request's HEAD ref (string, optional) - `owner`: Repository owner (string, required) + - `pullNumber`: Pull request number (number, required) - `repo`: Repository name (string, required) - - `job_id`: Job ID (number, required for single job logs) - - `run_id`: Workflow run ID (number, required when using failed_only) - - `failed_only`: When true, gets logs for all failed jobs in run_id (boolean, optional) - - `return_content`: Returns actual log content instead of URLs (boolean, optional) -- **rerun_workflow_run** - Re-run an entire workflow +

- - `owner`: Repository owner (string, required) - - `repo`: Repository name (string, required) - - `run_id`: Workflow run ID (number, required) - - `enable_debug_logging`: Enable debug logging for the re-run (boolean, optional) +

-- **rerun_failed_jobs** - Re-run only the failed jobs in a workflow run +

Repositories

+- **create_branch** - Create branch + - `branch`: Name for new branch (string, required) + - `from_branch`: Source branch (defaults to repo default) (string, optional) - `owner`: Repository owner (string, required) - `repo`: Repository name (string, required) - - `run_id`: Workflow run ID (number, required) - - `enable_debug_logging`: Enable debug logging for the re-run (boolean, optional) - -- **cancel_workflow_run** - Cancel a running workflow - - `owner`: Repository owner (string, required) +- **create_or_update_file** - Create or update file + - `branch`: Branch to create/update the file in (string, required) + - `content`: Content of the file (string, required) + - `message`: Commit message (string, required) + - `owner`: Repository owner (username or organization) (string, required) + - `path`: Path where to create/update the file (string, required) - `repo`: Repository name (string, required) - - `run_id`: Workflow run ID (number, required) + - `sha`: SHA of file being replaced (for updates) (string, optional) -- **list_workflow_run_artifacts** - List artifacts from a workflow run +- **create_repository** - Create repository + - `autoInit`: Initialize with README (boolean, optional) + - `description`: Repository description (string, optional) + - `name`: Repository name (string, required) + - `private`: Whether repo should be private (boolean, optional) - - `owner`: Repository owner (string, required) +- **delete_file** - Delete file + - `branch`: Branch to delete the file from (string, required) + - `message`: Commit message (string, required) + - `owner`: Repository owner (username or organization) (string, required) + - `path`: Path to the file to delete (string, required) - `repo`: Repository name (string, required) - - `run_id`: Workflow run ID (number, required) - - `page`: Page number (number, optional) - - `perPage`: Results per page (number, optional) - -- **download_workflow_run_artifact** - Get download URL for a specific artifact +- **fork_repository** - Fork repository + - `organization`: Organization to fork to (string, optional) - `owner`: Repository owner (string, required) - `repo`: Repository name (string, required) - - `artifact_id`: Artifact ID (number, required) - -- **delete_workflow_run_logs** - Delete logs for a workflow run +- **get_commit** - Get commit details - `owner`: Repository owner (string, required) + - `page`: Page number for pagination (min 1) (number, optional) + - `perPage`: Results per page for pagination (min 1, max 100) (number, optional) - `repo`: Repository name (string, required) - - `run_id`: Workflow run ID (number, required) + - `sha`: Commit SHA, branch name, or tag name (string, required) -- **get_workflow_run_usage** - Get usage metrics for a workflow run +- **get_file_contents** - Get file or directory contents + - `owner`: Repository owner (username or organization) (string, required) + - `path`: Path to file/directory (directories must end with a slash '/') (string, required) + - `ref`: Accepts optional git refs such as `refs/tags/{tag}`, `refs/heads/{branch}` or `refs/pull/{pr_number}/head` (string, optional) + - `repo`: Repository name (string, required) + - `sha`: Accepts optional git sha, if sha is specified it will be used instead of ref (string, optional) +- **get_tag** - Get tag details - `owner`: Repository owner (string, required) - `repo`: Repository name (string, required) - - `run_id`: Workflow run ID (number, required) - -

- -

Code Scanning

- -- **get_code_scanning_alert** - Get a code scanning alert + - `tag`: Tag name (string, required) +- **list_branches** - List branches - `owner`: Repository owner (string, required) + - `page`: Page number for pagination (min 1) (number, optional) + - `perPage`: Results per page for pagination (min 1, max 100) (number, optional) - `repo`: Repository name (string, required) - - `alertNumber`: Alert number (number, required) -- **list_code_scanning_alerts** - List code scanning alerts for a repository +- **list_commits** - List commits + - `author`: Author username or email address (string, optional) - `owner`: Repository owner (string, required) + - `page`: Page number for pagination (min 1) (number, optional) + - `perPage`: Results per page for pagination (min 1, max 100) (number, optional) - `repo`: Repository name (string, required) - - `ref`: Git reference (string, optional) - - `state`: Alert state (string, optional) - - `severity`: Alert severity (string, optional) - - `tool_name`: The name of the tool used for code scanning (string, optional) - -

- -

Secret Scanning

- -- **get_secret_scanning_alert** - Get a secret scanning alert + - `sha`: SHA or Branch name (string, optional) +- **list_tags** - List tags - `owner`: Repository owner (string, required) + - `page`: Page number for pagination (min 1) (number, optional) + - `perPage`: Results per page for pagination (min 1, max 100) (number, optional) - `repo`: Repository name (string, required) - - `alertNumber`: Alert number (number, required) -- **list_secret_scanning_alerts** - List secret scanning alerts for a repository +- **push_files** - Push files to repository + - `branch`: Branch to push to (string, required) + - `files`: Array of file objects to push, each object with path (string) and content (string) (object[], required) + - `message`: Commit message (string, required) - `owner`: Repository owner (string, required) - `repo`: Repository name (string, required) - - `state`: Alert state (string, optional) - - `secret_type`: The secret types to be filtered for in a comma-separated list (string, optional) - - `resolution`: The resolution status (string, optional) + +- **search_code** - Search code + - `order`: Sort order (string, optional) + - `page`: Page number for pagination (min 1) (number, optional) + - `perPage`: Results per page for pagination (min 1, max 100) (number, optional) + - `q`: Search query using GitHub code search syntax (string, required) + - `sort`: Sort field ('indexed' only) (string, optional) + +- **search_repositories** - Search repositories + - `page`: Page number for pagination (min 1) (number, optional) + - `perPage`: Results per page for pagination (min 1, max 100) (number, optional) + - `query`: Search query (string, required)

Notifications

- -- **list_notifications** – List notifications for a GitHub user - - `filter`: Filter to apply to the response (`default`, `include_read_notifications`, `only_participating`) - - `since`: Only show notifications updated after the given time (ISO 8601 format) - - `before`: Only show notifications updated before the given time (ISO 8601 format) - - `owner`: Optional repository owner (string) - - `repo`: Optional repository name (string) - - `page`: Page number (number, optional) - - `perPage`: Results per page (number, optional) - -- **get_notification_details** – Get detailed information for a specific GitHub notification - - `notificationID`: The ID of the notification (string, required) - -- **dismiss_notification** – Dismiss a notification by marking it as read or done - - `threadID`: The ID of the notification thread (string, required) - - `state`: The new state of the notification (`read` or `done`) +

Secret Protection

-- **mark_all_notifications_read** – Mark all notifications as read - - `lastReadAt`: Describes the last point that notifications were checked (optional, RFC3339/ISO8601 string, default: now) - - `owner`: Optional repository owner (string) - - `repo`: Optional repository name (string) +- **get_secret_scanning_alert** - Get secret scanning alert + - `alertNumber`: The number of the alert. (number, required) + - `owner`: The owner of the repository. (string, required) + - `repo`: The name of the repository. (string, required) -- **manage_notification_subscription** – Manage a notification subscription (ignore, watch, or delete) for a notification thread - - `notificationID`: The ID of the notification thread (string, required) - - `action`: Action to perform: `ignore`, `watch`, or `delete` (string, required) - -- **manage_repository_notification_subscription** – Manage a repository notification subscription (ignore, watch, or delete) - - `owner`: The account owner of the repository (string, required) - - `repo`: The name of the repository (string, required) - - `action`: Action to perform: `ignore`, `watch`, or `delete` (string, required) +- **list_secret_scanning_alerts** - List secret scanning alerts + - `owner`: The owner of the repository. (string, required) + - `repo`: The name of the repository. (string, required) + - `resolution`: Filter by resolution (string, optional) + - `secret_type`: A comma-separated list of secret types to return. All default secret patterns are returned. To return generic patterns, pass the token name(s) in the parameter. (string, optional) + - `state`: Filter by state (string, optional)

-## Resources -

Repository Content

- -- **Get Repository Content** - Retrieves the content of a repository at a specific path. - - - **Template**: `repo://{owner}/{repo}/contents{/path*}` - - **Parameters**: - - `owner`: Repository owner (string, required) - - `repo`: Repository name (string, required) - - `path`: File or directory path (string, optional) - -- **Get Repository Content for a Specific Branch** - Retrieves the content of a repository at a specific path for a given branch. - - - **Template**: `repo://{owner}/{repo}/refs/heads/{branch}/contents{/path*}` - - **Parameters**: - - `owner`: Repository owner (string, required) - - `repo`: Repository name (string, required) - - `branch`: Branch name (string, required) - - `path`: File or directory path (string, optional) - -- **Get Repository Content for a Specific Commit** - Retrieves the content of a repository at a specific path for a given commit. - - - **Template**: `repo://{owner}/{repo}/sha/{sha}/contents{/path*}` - - **Parameters**: - - `owner`: Repository owner (string, required) - - `repo`: Repository name (string, required) - - `sha`: Commit SHA (string, required) - - `path`: File or directory path (string, optional) - -- **Get Repository Content for a Specific Tag** - Retrieves the content of a repository at a specific path for a given tag. - - - **Template**: `repo://{owner}/{repo}/refs/tags/{tag}/contents{/path*}` - - **Parameters**: - - `owner`: Repository owner (string, required) - - `repo`: Repository name (string, required) - - `tag`: Tag name (string, required) - - `path`: File or directory path (string, optional) - -- **Get Repository Content for a Specific Pull Request** - Retrieves the content of a repository at a specific path for a given pull request. - - - **Template**: `repo://{owner}/{repo}/refs/pull/{prNumber}/head/contents{/path*}` - - **Parameters**: - - `owner`: Repository owner (string, required) - - `repo`: Repository name (string, required) - - `prNumber`: Pull request number (string, required) - - `path`: File or directory path (string, optional) +

Users

+ +- **search_users** - Search users + - `order`: Sort order (string, optional) + - `page`: Page number for pagination (min 1) (number, optional) + - `perPage`: Results per page for pagination (min 1, max 100) (number, optional) + - `query`: Search query using GitHub users search syntax scoped to type:user (string, required) + - `sort`: Sort field by category (string, optional)

+ ## Library Usage diff --git a/cmd/github-mcp-server/generate_docs.go b/cmd/github-mcp-server/generate_docs.go new file mode 100644 index 000000000..ff0342ec2 --- /dev/null +++ b/cmd/github-mcp-server/generate_docs.go @@ -0,0 +1,354 @@ +package main + +import ( + "context" + "fmt" + "net/url" + "os" + "regexp" + "sort" + "strings" + + "github.com/github/github-mcp-server/pkg/github" + "github.com/github/github-mcp-server/pkg/raw" + "github.com/github/github-mcp-server/pkg/toolsets" + "github.com/github/github-mcp-server/pkg/translations" + gogithub "github.com/google/go-github/v72/github" + "github.com/mark3labs/mcp-go/mcp" + "github.com/shurcooL/githubv4" + "github.com/spf13/cobra" +) + +var generateDocsCmd = &cobra.Command{ + Use: "generate-docs", + Short: "Generate documentation for tools and toolsets", + Long: `Generate the automated sections of README.md and docs/remote-server.md with current tool and toolset information.`, + RunE: func(cmd *cobra.Command, args []string) error { + return generateAllDocs() + }, +} + +func init() { + rootCmd.AddCommand(generateDocsCmd) +} + +// mockGetClient returns a mock GitHub client for documentation generation +func mockGetClient(ctx context.Context) (*gogithub.Client, error) { + return gogithub.NewClient(nil), nil +} + +// mockGetGQLClient returns a mock GraphQL client for documentation generation +func mockGetGQLClient(ctx context.Context) (*githubv4.Client, error) { + return githubv4.NewClient(nil), nil +} + +// mockGetRawClient returns a mock raw client for documentation generation +func mockGetRawClient(ctx context.Context) (*raw.Client, error) { + return nil, nil +} + +func generateAllDocs() error { + if err := generateReadmeDocs("README.md"); err != nil { + return fmt.Errorf("failed to generate README docs: %w", err) + } + + if err := generateRemoteServerDocs("docs/remote-server.md"); err != nil { + return fmt.Errorf("failed to generate remote-server docs: %w", err) + } + + return nil +} + +func generateReadmeDocs(readmePath string) error { + // Create translation helper + t, _ := translations.TranslationHelper() + + // Create toolset group with mock clients + tsg := github.DefaultToolsetGroup(false, mockGetClient, mockGetGQLClient, mockGetRawClient, t) + + // Generate toolsets documentation + toolsetsDoc := generateToolsetsDoc(tsg) + + // Generate tools documentation + toolsDoc := generateToolsDoc(tsg) + + // Read the current README.md + // #nosec G304 - readmePath is controlled by command line flag, not user input + content, err := os.ReadFile(readmePath) + if err != nil { + return fmt.Errorf("failed to read README.md: %w", err) + } + + // Replace toolsets section + updatedContent := replaceSection(string(content), "START AUTOMATED TOOLSETS", "END AUTOMATED TOOLSETS", toolsetsDoc) + + // Replace tools section + updatedContent = replaceSection(updatedContent, "START AUTOMATED TOOLS", "END AUTOMATED TOOLS", toolsDoc) + + // Write back to file + err = os.WriteFile(readmePath, []byte(updatedContent), 0600) + if err != nil { + return fmt.Errorf("failed to write README.md: %w", err) + } + + fmt.Println("Successfully updated README.md with automated documentation") + return nil +} + +func generateRemoteServerDocs(docsPath string) error { + content, err := os.ReadFile(docsPath) //#nosec G304 + if err != nil { + return fmt.Errorf("failed to read docs file: %w", err) + } + + toolsetsDoc := generateRemoteToolsetsDoc() + + // Replace content between markers + startMarker := "" + endMarker := "" + + contentStr := string(content) + startIndex := strings.Index(contentStr, startMarker) + endIndex := strings.Index(contentStr, endMarker) + + if startIndex == -1 || endIndex == -1 { + return fmt.Errorf("automation markers not found in %s", docsPath) + } + + newContent := contentStr[:startIndex] + startMarker + "\n" + toolsetsDoc + "\n" + endMarker + contentStr[endIndex+len(endMarker):] + + return os.WriteFile(docsPath, []byte(newContent), 0600) //#nosec G306 +} + +func generateToolsetsDoc(tsg *toolsets.ToolsetGroup) string { + var lines []string + + // Add table header and separator + lines = append(lines, "| Toolset | Description |") + lines = append(lines, "| ----------------------- | ------------------------------------------------------------- |") + + // Add the context toolset row (handled separately in README) + lines = append(lines, "| `context` | **Strongly recommended**: Tools that provide context about the current user and GitHub context you are operating in |") + + // Get all toolsets except context (which is handled separately above) + var toolsetNames []string + for name := range tsg.Toolsets { + if name != "context" && name != "dynamic" { // Skip context and dynamic toolsets as they're handled separately + toolsetNames = append(toolsetNames, name) + } + } + + // Sort toolset names for consistent output + sort.Strings(toolsetNames) + + for _, name := range toolsetNames { + toolset := tsg.Toolsets[name] + lines = append(lines, fmt.Sprintf("| `%s` | %s |", name, toolset.Description)) + } + + return strings.Join(lines, "\n") +} + +func generateToolsDoc(tsg *toolsets.ToolsetGroup) string { + var sections []string + + // Get all toolset names and sort them alphabetically for deterministic order + var toolsetNames []string + for name := range tsg.Toolsets { + if name != "dynamic" { // Skip dynamic toolset as it's handled separately + toolsetNames = append(toolsetNames, name) + } + } + sort.Strings(toolsetNames) + + for _, toolsetName := range toolsetNames { + toolset := tsg.Toolsets[toolsetName] + + tools := toolset.GetAvailableTools() + if len(tools) == 0 { + continue + } + + // Sort tools by name for deterministic order + sort.Slice(tools, func(i, j int) bool { + return tools[i].Tool.Name < tools[j].Tool.Name + }) + + // Generate section header - capitalize first letter and replace underscores + sectionName := formatToolsetName(toolsetName) + + var toolDocs []string + for _, serverTool := range tools { + toolDoc := generateToolDoc(serverTool.Tool) + toolDocs = append(toolDocs, toolDoc) + } + + if len(toolDocs) > 0 { + section := fmt.Sprintf("

\n\n

\n\n%s\n\n

", + sectionName, strings.Join(toolDocs, "\n\n")) + sections = append(sections, section) + } + } + + return strings.Join(sections, "\n\n") +} + +func formatToolsetName(name string) string { + switch name { + case "pull_requests": + return "Pull Requests" + case "repos": + return "Repositories" + case "code_security": + return "Code Security" + case "secret_protection": + return "Secret Protection" + case "orgs": + return "Organizations" + default: + // Fallback: capitalize first letter and replace underscores with spaces + parts := strings.Split(name, "_") + for i, part := range parts { + if len(part) > 0 { + parts[i] = strings.ToUpper(string(part[0])) + part[1:] + } + } + return strings.Join(parts, " ") + } +} + +func generateToolDoc(tool mcp.Tool) string { + var lines []string + + // Tool name only (using annotation name instead of verbose description) + lines = append(lines, fmt.Sprintf("- **%s** - %s", tool.Name, tool.Annotations.Title)) + + // Parameters + schema := tool.InputSchema + if len(schema.Properties) > 0 { + // Get parameter names and sort them for deterministic order + var paramNames []string + for propName := range schema.Properties { + paramNames = append(paramNames, propName) + } + sort.Strings(paramNames) + + for _, propName := range paramNames { + prop := schema.Properties[propName] + required := contains(schema.Required, propName) + requiredStr := "optional" + if required { + requiredStr = "required" + } + + // Get the type and description + typeStr := "unknown" + description := "" + + if propMap, ok := prop.(map[string]interface{}); ok { + if typeVal, ok := propMap["type"].(string); ok { + if typeVal == "array" { + if items, ok := propMap["items"].(map[string]interface{}); ok { + if itemType, ok := items["type"].(string); ok { + typeStr = itemType + "[]" + } + } else { + typeStr = "array" + } + } else { + typeStr = typeVal + } + } + + if desc, ok := propMap["description"].(string); ok { + description = desc + } + } + + paramLine := fmt.Sprintf(" - `%s`: %s (%s, %s)", propName, description, typeStr, requiredStr) + lines = append(lines, paramLine) + } + } else { + lines = append(lines, " - No parameters required") + } + + return strings.Join(lines, "\n") +} + +func contains(slice []string, item string) bool { + for _, s := range slice { + if s == item { + return true + } + } + return false +} + +func replaceSection(content, startMarker, endMarker, newContent string) string { + startPattern := fmt.Sprintf(``, regexp.QuoteMeta(startMarker)) + endPattern := fmt.Sprintf(``, regexp.QuoteMeta(endMarker)) + + re := regexp.MustCompile(fmt.Sprintf(`(?s)%s.*?%s`, startPattern, endPattern)) + + replacement := fmt.Sprintf("\n%s\n", startMarker, newContent, endMarker) + + return re.ReplaceAllString(content, replacement) +} + +func generateRemoteToolsetsDoc() string { + var buf strings.Builder + + // Create translation helper + t, _ := translations.TranslationHelper() + + // Create toolset group with mock clients + tsg := github.DefaultToolsetGroup(false, mockGetClient, mockGetGQLClient, mockGetRawClient, t) + + // Generate table header + buf.WriteString("| Name | Description | API URL | 1-Click Install (VS Code) | Read-only Link | 1-Click Read-only Install (VS Code) |\n") + buf.WriteString("|----------------|--------------------------------------------------|-------------------------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|\n") + + // Get all toolsets + toolsetNames := make([]string, 0, len(tsg.Toolsets)) + for name := range tsg.Toolsets { + if name != "context" && name != "dynamic" { // Skip context and dynamic toolsets as they're handled separately + toolsetNames = append(toolsetNames, name) + } + } + sort.Strings(toolsetNames) + + // Add "all" toolset first (special case) + buf.WriteString("| all | All available GitHub MCP tools | https://api.githubcopilot.com/mcp/ | [Install](https://insiders.vscode.dev/redirect/mcp/install?name=github&config=%7B%22type%22%3A%20%22http%22%2C%22url%22%3A%20%22https%3A%2F%2Fapi.githubcopilot.com%2Fmcp%2F%22%7D) | [read-only](https://api.githubcopilot.com/mcp/readonly) | [Install read-only](https://insiders.vscode.dev/redirect/mcp/install?name=github&config=%7B%22type%22%3A%20%22http%22%2C%22url%22%3A%20%22https%3A%2F%2Fapi.githubcopilot.com%2Fmcp%2Freadonly%22%7D) |\n") + + // Add individual toolsets + for _, name := range toolsetNames { + toolset := tsg.Toolsets[name] + + formattedName := formatToolsetName(name) + description := toolset.Description + apiURL := fmt.Sprintf("https://api.githubcopilot.com/mcp/x/%s", name) + readonlyURL := fmt.Sprintf("https://api.githubcopilot.com/mcp/x/%s/readonly", name) + + // Create install config JSON (URL encoded) + installConfig := url.QueryEscape(fmt.Sprintf(`{"type": "http","url": "%s"}`, apiURL)) + readonlyConfig := url.QueryEscape(fmt.Sprintf(`{"type": "http","url": "%s"}`, readonlyURL)) + + // Fix URL encoding to use %20 instead of + for spaces + installConfig = strings.ReplaceAll(installConfig, "+", "%20") + readonlyConfig = strings.ReplaceAll(readonlyConfig, "+", "%20") + + installLink := fmt.Sprintf("[Install](https://insiders.vscode.dev/redirect/mcp/install?name=gh-%s&config=%s)", name, installConfig) + readonlyInstallLink := fmt.Sprintf("[Install read-only](https://insiders.vscode.dev/redirect/mcp/install?name=gh-%s&config=%s)", name, readonlyConfig) + + buf.WriteString(fmt.Sprintf("| %-14s | %-48s | %-53s | %-218s | %-110s | %-288s |\n", + formattedName, + description, + apiURL, + installLink, + fmt.Sprintf("[read-only](%s)", readonlyURL), + readonlyInstallLink, + )) + } + + return buf.String() +} diff --git a/docs/remote-server.md b/docs/remote-server.md index 888caef43..50404ec85 100644 --- a/docs/remote-server.md +++ b/docs/remote-server.md @@ -14,17 +14,22 @@ The remote GitHub MCP server is built using this repository as a library, and bi Below is a table of available toolsets for the remote GitHub MCP Server. Each toolset is provided as a distinct URL so you can mix and match to create the perfect combination of tools for your use-case. Add `/readonly` to the end of any URL to restrict the tools in the toolset to only those that enable read access. We also provide the option to use [headers](#headers) instead. - + | Name | Description | API URL | 1-Click Install (VS Code) | Read-only Link | 1-Click Read-only Install (VS Code) | |----------------|--------------------------------------------------|-------------------------------------------------------|----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|---------------------------------------------------------------------------------------------------------------|-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| | all | All available GitHub MCP tools | https://api.githubcopilot.com/mcp/ | [Install](https://insiders.vscode.dev/redirect/mcp/install?name=github&config=%7B%22type%22%3A%20%22http%22%2C%22url%22%3A%20%22https%3A%2F%2Fapi.githubcopilot.com%2Fmcp%2F%22%7D) | [read-only](https://api.githubcopilot.com/mcp/readonly) | [Install read-only](https://insiders.vscode.dev/redirect/mcp/install?name=github&config=%7B%22type%22%3A%20%22http%22%2C%22url%22%3A%20%22https%3A%2F%2Fapi.githubcopilot.com%2Fmcp%2Freadonly%22%7D) | -| code_security | Code security related tools, such as Code Scanning| https://api.githubcopilot.com/mcp/x/code_security | [Install](https://insiders.vscode.dev/redirect/mcp/install?name=gh-code_security&config=%7B%22type%22%3A%20%22http%22%2C%22url%22%3A%20%22https%3A%2F%2Fapi.githubcopilot.com%2Fmcp%2Fx%2Fcode_security%22%7D) | [read-only](https://api.githubcopilot.com/mcp/x/code_security/readonly) | [Install read-only](https://insiders.vscode.dev/redirect/mcp/install?name=gh-code_security&config=%7B%22type%22%3A%20%22http%22%2C%22url%22%3A%20%22https%3A%2F%2Fapi.githubcopilot.com%2Fmcp%2Fx%2Fcode_security%2Freadonly%22%7D)| -| issues | GitHub Issues related tools | https://api.githubcopilot.com/mcp/x/issues | [Install](https://insiders.vscode.dev/redirect/mcp/install?name=gh-issues&config=%7B%22type%22%3A%20%22http%22%2C%22url%22%3A%20%22https%3A%2F%2Fapi.githubcopilot.com%2Fmcp%2Fx%2Fissues%22%7D) | [read-only](https://api.githubcopilot.com/mcp/x/issues/readonly) | [Install read-only](https://insiders.vscode.dev/redirect/mcp/install?name=gh-issues&config=%7B%22type%22%3A%20%22http%22%2C%22url%22%3A%20%22https%3A%2F%2Fapi.githubcopilot.com%2Fmcp%2Fx%2Fissues%2Freadonly%22%7D) | -| notifications | GitHub Notifications related tools | https://api.githubcopilot.com/mcp/x/notifications | [Install](https://insiders.vscode.dev/redirect/mcp/install?name=gh-notifications&config=%7B%22type%22%3A%20%22http%22%2C%22url%22%3A%20%22https%3A%2F%2Fapi.githubcopilot.com%2Fmcp%2Fx%2Fnotifications%22%7D) | [read-only](https://api.githubcopilot.com/mcp/x/notifications/readonly) | [Install read-only](https://insiders.vscode.dev/redirect/mcp/install?name=gh-notifications&config=%7B%22type%22%3A%20%22http%22%2C%22url%22%3A%20%22https%3A%2F%2Fapi.githubcopilot.com%2Fmcp%2Fx%2Fnotifications%2Freadonly%22%7D)| -| pull_requests | GitHub Pull Request related tools | https://api.githubcopilot.com/mcp/x/pull_requests | [Install](https://insiders.vscode.dev/redirect/mcp/install?name=gh-pull_requests&config=%7B%22type%22%3A%20%22http%22%2C%22url%22%3A%20%22https%3A%2F%2Fapi.githubcopilot.com%2Fmcp%2Fx%2Fpull_requests%22%7D) | [read-only](https://api.githubcopilot.com/mcp/x/pull_requests/readonly) | [Install read-only](https://insiders.vscode.dev/redirect/mcp/install?name=gh-pull_requests&config=%7B%22type%22%3A%20%22http%22%2C%22url%22%3A%20%22https%3A%2F%2Fapi.githubcopilot.com%2Fmcp%2Fx%2Fpull_requests%2Freadonly%22%7D)| -| repos | GitHub Repository related tools | https://api.githubcopilot.com/mcp/x/repos | [Install](https://insiders.vscode.dev/redirect/mcp/install?name=gh-repos&config=%7B%22type%22%3A%20%22http%22%2C%22url%22%3A%20%22https%3A%2F%2Fapi.githubcopilot.com%2Fmcp%2Fx%2Frepos%22%7D) | [read-only](https://api.githubcopilot.com/mcp/x/repos/readonly) | [Install read-only](https://insiders.vscode.dev/redirect/mcp/install?name=gh-repos&config=%7B%22type%22%3A%20%22http%22%2C%22url%22%3A%20%22https%3A%2F%2Fapi.githubcopilot.com%2Fmcp%2Fx%2Frepos%2Freadonly%22%7D) | -| secret_protection | Secret protection related tools, e.g. Secret Scanning | https://api.githubcopilot.com/mcp/x/secret_protection | [Install](https://insiders.vscode.dev/redirect/mcp/install?name=gh-secret_protection&config=%7B%22type%22%3A%20%22http%22%2C%22url%22%3A%20%22https%3A%2F%2Fapi.githubcopilot.com%2Fmcp%2Fx%2Fsecret_protection%22%7D) | [read-only](https://api.githubcopilot.com/mcp/x/secret_protection/readonly) | [Install read-only](https://insiders.vscode.dev/redirect/mcp/install?name=gh-secret_protection&config=%7B%22type%22%3A%20%22http%22%2C%22url%22%3A%20%22https%3A%2F%2Fapi.githubcopilot.com%2Fmcp%2Fx%2Fsecret_protection%2Freadonly%22%7D)| -| users | GitHub User related tools | https://api.githubcopilot.com/mcp/x/users | [Install](https://insiders.vscode.dev/redirect/mcp/install?name=gh-users&config=%7B%22type%22%3A%20%22http%22%2C%22url%22%3A%20%22https%3A%2F%2Fapi.githubcopilot.com%2Fmcp%2Fx%2Fusers%22%7D) | [read-only](https://api.githubcopilot.com/mcp/x/users/readonly) | [Install read-only](https://insiders.vscode.dev/redirect/mcp/install?name=gh-users&config=%7B%22type%22%3A%20%22http%22%2C%22url%22%3A%20%22https%3A%2F%2Fapi.githubcopilot.com%2Fmcp%2Fx%2Fusers%2Freadonly%22%7D) | +| Actions | GitHub Actions workflows and CI/CD operations | https://api.githubcopilot.com/mcp/x/actions | [Install](https://insiders.vscode.dev/redirect/mcp/install?name=gh-actions&config=%7B%22type%22%3A%20%22http%22%2C%22url%22%3A%20%22https%3A%2F%2Fapi.githubcopilot.com%2Fmcp%2Fx%2Factions%22%7D) | [read-only](https://api.githubcopilot.com/mcp/x/actions/readonly) | [Install read-only](https://insiders.vscode.dev/redirect/mcp/install?name=gh-actions&config=%7B%22type%22%3A%20%22http%22%2C%22url%22%3A%20%22https%3A%2F%2Fapi.githubcopilot.com%2Fmcp%2Fx%2Factions%2Freadonly%22%7D) | +| Code Security | Code security related tools, such as GitHub Code Scanning | https://api.githubcopilot.com/mcp/x/code_security | [Install](https://insiders.vscode.dev/redirect/mcp/install?name=gh-code_security&config=%7B%22type%22%3A%20%22http%22%2C%22url%22%3A%20%22https%3A%2F%2Fapi.githubcopilot.com%2Fmcp%2Fx%2Fcode_security%22%7D) | [read-only](https://api.githubcopilot.com/mcp/x/code_security/readonly) | [Install read-only](https://insiders.vscode.dev/redirect/mcp/install?name=gh-code_security&config=%7B%22type%22%3A%20%22http%22%2C%22url%22%3A%20%22https%3A%2F%2Fapi.githubcopilot.com%2Fmcp%2Fx%2Fcode_security%2Freadonly%22%7D) | +| Experiments | Experimental features that are not considered stable yet | https://api.githubcopilot.com/mcp/x/experiments | [Install](https://insiders.vscode.dev/redirect/mcp/install?name=gh-experiments&config=%7B%22type%22%3A%20%22http%22%2C%22url%22%3A%20%22https%3A%2F%2Fapi.githubcopilot.com%2Fmcp%2Fx%2Fexperiments%22%7D) | [read-only](https://api.githubcopilot.com/mcp/x/experiments/readonly) | [Install read-only](https://insiders.vscode.dev/redirect/mcp/install?name=gh-experiments&config=%7B%22type%22%3A%20%22http%22%2C%22url%22%3A%20%22https%3A%2F%2Fapi.githubcopilot.com%2Fmcp%2Fx%2Fexperiments%2Freadonly%22%7D) | +| Issues | GitHub Issues related tools | https://api.githubcopilot.com/mcp/x/issues | [Install](https://insiders.vscode.dev/redirect/mcp/install?name=gh-issues&config=%7B%22type%22%3A%20%22http%22%2C%22url%22%3A%20%22https%3A%2F%2Fapi.githubcopilot.com%2Fmcp%2Fx%2Fissues%22%7D) | [read-only](https://api.githubcopilot.com/mcp/x/issues/readonly) | [Install read-only](https://insiders.vscode.dev/redirect/mcp/install?name=gh-issues&config=%7B%22type%22%3A%20%22http%22%2C%22url%22%3A%20%22https%3A%2F%2Fapi.githubcopilot.com%2Fmcp%2Fx%2Fissues%2Freadonly%22%7D) | +| Notifications | GitHub Notifications related tools | https://api.githubcopilot.com/mcp/x/notifications | [Install](https://insiders.vscode.dev/redirect/mcp/install?name=gh-notifications&config=%7B%22type%22%3A%20%22http%22%2C%22url%22%3A%20%22https%3A%2F%2Fapi.githubcopilot.com%2Fmcp%2Fx%2Fnotifications%22%7D) | [read-only](https://api.githubcopilot.com/mcp/x/notifications/readonly) | [Install read-only](https://insiders.vscode.dev/redirect/mcp/install?name=gh-notifications&config=%7B%22type%22%3A%20%22http%22%2C%22url%22%3A%20%22https%3A%2F%2Fapi.githubcopilot.com%2Fmcp%2Fx%2Fnotifications%2Freadonly%22%7D) | +| Organizations | GitHub Organization related tools | https://api.githubcopilot.com/mcp/x/orgs | [Install](https://insiders.vscode.dev/redirect/mcp/install?name=gh-orgs&config=%7B%22type%22%3A%20%22http%22%2C%22url%22%3A%20%22https%3A%2F%2Fapi.githubcopilot.com%2Fmcp%2Fx%2Forgs%22%7D) | [read-only](https://api.githubcopilot.com/mcp/x/orgs/readonly) | [Install read-only](https://insiders.vscode.dev/redirect/mcp/install?name=gh-orgs&config=%7B%22type%22%3A%20%22http%22%2C%22url%22%3A%20%22https%3A%2F%2Fapi.githubcopilot.com%2Fmcp%2Fx%2Forgs%2Freadonly%22%7D) | +| Pull Requests | GitHub Pull Request related tools | https://api.githubcopilot.com/mcp/x/pull_requests | [Install](https://insiders.vscode.dev/redirect/mcp/install?name=gh-pull_requests&config=%7B%22type%22%3A%20%22http%22%2C%22url%22%3A%20%22https%3A%2F%2Fapi.githubcopilot.com%2Fmcp%2Fx%2Fpull_requests%22%7D) | [read-only](https://api.githubcopilot.com/mcp/x/pull_requests/readonly) | [Install read-only](https://insiders.vscode.dev/redirect/mcp/install?name=gh-pull_requests&config=%7B%22type%22%3A%20%22http%22%2C%22url%22%3A%20%22https%3A%2F%2Fapi.githubcopilot.com%2Fmcp%2Fx%2Fpull_requests%2Freadonly%22%7D) | +| Repositories | GitHub Repository related tools | https://api.githubcopilot.com/mcp/x/repos | [Install](https://insiders.vscode.dev/redirect/mcp/install?name=gh-repos&config=%7B%22type%22%3A%20%22http%22%2C%22url%22%3A%20%22https%3A%2F%2Fapi.githubcopilot.com%2Fmcp%2Fx%2Frepos%22%7D) | [read-only](https://api.githubcopilot.com/mcp/x/repos/readonly) | [Install read-only](https://insiders.vscode.dev/redirect/mcp/install?name=gh-repos&config=%7B%22type%22%3A%20%22http%22%2C%22url%22%3A%20%22https%3A%2F%2Fapi.githubcopilot.com%2Fmcp%2Fx%2Frepos%2Freadonly%22%7D) | +| Secret Protection | Secret protection related tools, such as GitHub Secret Scanning | https://api.githubcopilot.com/mcp/x/secret_protection | [Install](https://insiders.vscode.dev/redirect/mcp/install?name=gh-secret_protection&config=%7B%22type%22%3A%20%22http%22%2C%22url%22%3A%20%22https%3A%2F%2Fapi.githubcopilot.com%2Fmcp%2Fx%2Fsecret_protection%22%7D) | [read-only](https://api.githubcopilot.com/mcp/x/secret_protection/readonly) | [Install read-only](https://insiders.vscode.dev/redirect/mcp/install?name=gh-secret_protection&config=%7B%22type%22%3A%20%22http%22%2C%22url%22%3A%20%22https%3A%2F%2Fapi.githubcopilot.com%2Fmcp%2Fx%2Fsecret_protection%2Freadonly%22%7D) | +| Users | GitHub User related tools | https://api.githubcopilot.com/mcp/x/users | [Install](https://insiders.vscode.dev/redirect/mcp/install?name=gh-users&config=%7B%22type%22%3A%20%22http%22%2C%22url%22%3A%20%22https%3A%2F%2Fapi.githubcopilot.com%2Fmcp%2Fx%2Fusers%22%7D) | [read-only](https://api.githubcopilot.com/mcp/x/users/readonly) | [Install read-only](https://insiders.vscode.dev/redirect/mcp/install?name=gh-users&config=%7B%22type%22%3A%20%22http%22%2C%22url%22%3A%20%22https%3A%2F%2Fapi.githubcopilot.com%2Fmcp%2Fx%2Fusers%2Freadonly%22%7D) | + + ### Headers diff --git a/script/tag-release b/script/tag-release new file mode 100755 index 000000000..fd94167c3 --- /dev/null +++ b/script/tag-release @@ -0,0 +1,151 @@ +#!/bin/bash + +# Exit immediately if a command exits with a non-zero status. +set -e + +# Initialize variables +TAG="" +DRY_RUN=false + +# Parse arguments +for arg in "$@"; do + case $arg in + --dry-run) + DRY_RUN=true + ;; + *) + # The first non-flag argument is the tag + if [[ ! $arg == --* ]]; then + if [ -z "$TAG" ]; then + TAG=$arg + fi + fi + ;; + esac +done + +if [ "$DRY_RUN" = true ]; then + echo "DRY RUN: No changes will be pushed to the remote repository." + echo +fi + +# 1. Validate input +if [ -z "$TAG" ]; then + echo "Error: No tag specified." + echo "Usage: ./script/tag-release vX.Y.Z [--dry-run]" + exit 1 +fi + +# Regular expression for semantic versioning (vX.Y.Z or vX.Y.Z-suffix) +if [[ ! $TAG =~ ^v[0-9]+\.[0-9]+\.[0-9]+(-.*)?$ ]]; then + echo "Error: Tag must be in format vX.Y.Z or vX.Y.Z-suffix (e.g., v1.0.0 or v1.0.0-rc1)" + exit 1 +fi + +# 2. Check current branch +CURRENT_BRANCH=$(git rev-parse --abbrev-ref HEAD) +if [ "$CURRENT_BRANCH" != "main" ]; then + echo "Error: You must be on the 'main' branch to create a release." + echo "Current branch is '$CURRENT_BRANCH'." + exit 1 +fi + +# 3. Fetch latest from origin +echo "Fetching latest changes from origin..." +git fetch origin main + +# 4. Check if the working directory is clean +if ! git diff-index --quiet HEAD --; then + echo "Error: Working directory is not clean. Please commit or stash your changes." + exit 1 +fi + +# 5. Check if main is up-to-date with origin/main +LOCAL_SHA=$(git rev-parse @) +REMOTE_SHA=$(git rev-parse @{u}) + +if [ "$LOCAL_SHA" != "$REMOTE_SHA" ]; then + echo "Error: Your local 'main' branch is not up-to-date with 'origin/main'. Please pull the latest changes." + exit 1 +fi +echo "✅ Local 'main' branch is up-to-date with 'origin/main'." + +# 6. Check if tag already exists +if git tag -l | grep -q "^${TAG}$"; then + echo "Error: Tag ${TAG} already exists locally." + exit 1 +fi +if git ls-remote --tags origin | grep -q "refs/tags/${TAG}$"; then + echo "Error: Tag ${TAG} already exists on remote 'origin'." + exit 1 +fi + +# 7. Confirm release with user +echo +LATEST_TAG=$(git tag --sort=-version:refname | head -n 1) +if [ -n "$LATEST_TAG" ]; then + echo "Current latest release: $LATEST_TAG" +fi +echo "Proposed new release: $TAG" +echo +read -p "Do you want to proceed with the release? (y/n) " -n 1 -r +echo # Move to a new line +if [[ ! $REPLY =~ ^[Yy]$ ]]; then + echo "Release cancelled." + exit 1 +fi +echo + +# 8. Create the new release tag +if [ "$DRY_RUN" = true ]; then + echo "DRY RUN: Skipping creation of tag $TAG." +else + echo "Creating new release tag: $TAG" + git tag -a "$TAG" -m "Release $TAG" +fi + +# 9. Push the new tag to the remote repository +if [ "$DRY_RUN" = true ]; then + echo "DRY RUN: Skipping push of tag $TAG to origin." +else + echo "Pushing tag $TAG to origin..." + git push origin "$TAG" +fi + +# 10. Update and push the 'latest-release' tag +if [ "$DRY_RUN" = true ]; then + echo "DRY RUN: Skipping update and push of 'latest-release' tag." +else + echo "Updating 'latest-release' tag to point to $TAG..." + git tag -f latest-release "$TAG" + echo "Pushing 'latest-release' tag to origin..." + git push origin latest-release --force +fi + +if [ "$DRY_RUN" = true ]; then + echo "✅ DRY RUN complete. No tags were created or pushed." +else + echo "✅ Successfully tagged and pushed release $TAG." + echo "✅ 'latest-release' tag has been updated." +fi + +# 11. Post-release instructions +REPO_URL=$(git remote get-url origin) +REPO_SLUG=$(echo "$REPO_URL" | sed -e 's/.*github.com[:\/]//' -e 's/\.git$//') + +cat << EOF + +## 🎉 Release $TAG has been initiated! + +### Next steps: +1. 📋 Check https://github.com/$REPO_SLUG/releases and wait for the draft release to show up (after the goreleaser workflow completes) +2. ✏️ Edit the new release, delete the existing notes and click the auto-generate button GitHub provides +3. ✨ Add a section at the top calling out the main features +4. 🚀 Publish the release +5. 📢 Post message in #gh-mcp-releases channel in Slack and then share to the other mcp channels + +### Resources: +- 📦 Draft Release: https://github.com/$REPO_SLUG/releases/tag/$TAG + +The release process is now ready for your review and completion! +EOF pFad - Phonifier reborn

Note: This service is not intended for secure transactions such as banking, social media, email, or purchasing. Use at your own risk. We assume no liability whatsoever for broken pages.

Alternative Proxies:

Pfad - The Proxy pFad of © 2024 Garber Painting. All rights reserved.