From 43d2d2b0564cb60380cb5bd138eec1711f744826 Mon Sep 17 00:00:00 2001 From: Cursor Agent Date: Fri, 5 Jun 2026 00:07:38 +0000 Subject: [PATCH] docs(github): remove stale PAT/notifications references from GitHub MCP server docs The GitHub MCP server no longer ships notification tools (GetNotificationSummary, ListNotifications), which were the only tools that required a classic Personal Access Token. Remove the now-stale PAT and notifications content from both the generated toolkit docs (github.json documentation chunks) and the hand-authored GitHub auth provider page: - Drop the 'Special: Notifications' permissions block and the GITHUB_CLASSIC_PERSONAL_ACCESS_TOKEN secret row/callout. - Remove the Notifications rows from the permissions and troubleshooting tables and the notifications FAQ entry; rename the trailing permissions tab to 'Act on Behalf of User'. - Fix the ListIssues 'since' parameter description that wrongly referenced notifications. - Clarify that GITHUB_SERVER_URL is the only (optional) secret, since the PAT was the only required one. --- .../references/auth-providers/github/page.mdx | 24 ++----------------- .../data/toolkits/github.json | 8 +++---- 2 files changed, 6 insertions(+), 26 deletions(-) diff --git a/app/en/references/auth-providers/github/page.mdx b/app/en/references/auth-providers/github/page.mdx index a5353090d..80bd00740 100644 --- a/app/en/references/auth-providers/github/page.mdx +++ b/app/en/references/auth-providers/github/page.mdx @@ -822,11 +822,10 @@ This section lists the GitHub App permissions required by tools in the Arcade Gi | **Repositories** | Contents (Read/Write for file ops), Metadata (Read), Members (Read for org repos) | | **Reviews** | Contents (Read), Pull requests (Read/Write), Metadata (Read) | | **User Context** | Read user profile, Members (Read for orgs) | -| **Notifications** | ⚠️ Classic PAT with `notifications` scope (GitHub Apps limitation) | ### Detailed Permissions by Category - + **Issues Tools** (7 tools): @@ -914,18 +913,7 @@ This section lists the GitHub App permissions required by tools in the Arcade Gi -**⚠️ Notifications Tools** - -GitHub Apps **cannot** access the notifications API. This is a [platform limitation by design](https://docs.github.com/en/rest/activity/notifications). - -**Workaround:** - -- Tools: `get_notification_summary`, `list_notifications` -- **Required**: Classic Personal Access Token with `notifications` scope -- **Create at**: [github.com/settings/tokens](https://github.com/settings/tokens) -- **Why**: Notifications are personal user data, not accessible to apps by GitHub's design - -**User-on-Behalf-of Actions:** +**Act on Behalf of User** The "Act on behalf of user" permission is only needed for specific user-attributed actions: @@ -1029,7 +1017,6 @@ After initial installation, you can add more repositories: | **"Installation not found"** | Wrong Installation ID | Check Installation ID in URL | | **"403 Forbidden"** | Missing permissions, not installed, or rate limited | Review permissions, check installation | | **"404 Not Found" on existing repo** | Permissions not approved by admin | Check app settings → verify permissions approved | -| **Notifications not working** | GitHub Apps can't access notifications | Use classic PAT with `notifications` scope | | **Can't star repositories** | Missing "Act on behalf of user" permission | Enable in User permissions settings | ### Debugging Steps @@ -1110,13 +1097,6 @@ A: Starring repositories requires the "Act on behalf of user" permission: - The app can still read and perform other actions without this permission - [Why this permission exists](https://docs.github.com/en/apps/creating-github-apps/authenticating-with-a-github-app/authenticating-with-a-github-app-on-behalf-of-a-user) -**Q: Why can't I access notifications?** -A: Notifications require a classic PAT (GitHub Apps cannot access notifications API by design): - -- This is a platform limitation, not an Arcade limitation -- Create a classic PAT at [github.com/settings/tokens](https://github.com/settings/tokens) with `notifications` scope -- [Why GitHub Apps can't access notifications](https://docs.github.com/en/rest/activity/notifications) - ### Security **Q: What if my credentials are compromised?** diff --git a/toolkit-docs-generator/data/toolkits/github.json b/toolkit-docs-generator/data/toolkits/github.json index bc37fa703..7dc2756d8 100644 --- a/toolkit-docs-generator/data/toolkits/github.json +++ b/toolkit-docs-generator/data/toolkits/github.json @@ -2096,7 +2096,7 @@ "name": "since", "type": "string", "required": false, - "description": "Only show notifications updated after the given time. This is a timestamp in ISO 8601 format: YYYY-MM-DDTHH:MM:SSZ.", + "description": "Only show issues updated after the given time. This is a timestamp in ISO 8601 format: YYYY-MM-DDTHH:MM:SSZ.", "enum": null, "inferrable": true }, @@ -5829,7 +5829,7 @@ "type": "info", "location": "description", "position": "after", - "content": "\n **Configuration Required**: All tools require secrets to be configured in Arcade Dashboard. See [Secrets Setup](#secrets-setup) below.\n" + "content": "\n **Configuration**: On Arcade Cloud, these tools work out of the box. Self-hosted and GitHub Enterprise Server users can set the `GITHUB_SERVER_URL` secret in Arcade Dashboard. See [Secrets Setup](#secrets-setup) below.\n" }, { "type": "info", @@ -5842,14 +5842,14 @@ "type": "section", "location": "before_available_tools", "position": "after", - "content": "## GitHub App Permissions Summary\n\nWhen creating your GitHub App, you'll need to grant specific permissions. Here's a quick reference of which tools require which permissions:\n\n### Repository Permissions\n\n| Permission | Level | Required For |\n|------------|-------|--------------|\n| **Contents** | Read | All repository and pull request tools, getting file contents |\n| **Contents** | Write | Creating/updating files, creating branches, merging PRs |\n| **Issues** | Read & Write | Issue management, PR assignments, managing labels (Issues) |\n| **Pull requests** | Read & Write | Pull request management, reviews, managing labels (PRs) |\n| **Metadata** | Read | All tools (automatically granted) |\n| **Statuses** | Read | `CheckPullRequestMergeStatus` |\n\n### Organization Permissions\n\n| Permission | Level | Required For |\n|------------|-------|--------------|\n| **Members** | Read | Projects, collaborators, org repos, user search |\n| **Projects** | Read & Write | All Projects V2 tools |\n\n### User Permissions\n\n| Permission | Level | Required For |\n|------------|-------|--------------|\n| **Read user profile** | Read | User context tools, review workload |\n| **Act on behalf of user** | Enabled | `SetStarred` (starring repositories) |\n\n### Tools by Permission Requirements\n\n
\nBasic Repository Access (Contents Read + Metadata)\n\n- `GetRepository`\n- `CountStargazers`\n- `ListStargazers`\n- `ListRepositoryActivities`\n- `GetFileContents`\n\n
\n\n
\nRepository Write (Contents Write + Metadata)\n\n- `CreateBranch`\n- `CreateOrUpdateFile`\n- `UpdateFileLines`\n\n
\n\n
\nIssue Management (Contents Read + Issues + Metadata)\n\n- `CreateIssue`\n- `UpdateIssue`\n- `GetIssue`\n- `ListIssues`\n- `CreateIssueComment`\n- `ListRepositoryLabels`\n- `ManageLabels` (for issues)\n\n
\n\n
\nPull Request Read (Contents + Pull requests Read + Metadata)\n\n- `ListPullRequests`\n- `GetPullRequest`\n- `ListPullRequestCommits`\n- `ListReviewCommentsOnPullRequest`\n- `CheckPullRequestMergeStatus` (+ Statuses)\n\n
\n\n
\nPull Request Write (Contents Read + Pull requests Write + Metadata)\n\n- `UpdatePullRequest`\n- `CreatePullRequest`\n- `SubmitPullRequestReview`\n- `ManagePullRequest`\n- `ManagePullRequestReviewers`\n- `CreateReviewComment`\n- `CreateReplyForReviewComment`\n- `ResolveReviewThread`\n- `ManageLabels` (for pull requests)\n- `MergePullRequest` (+ Contents Write)\n\n
\n\n
\nOrganization Tools (Contents + Metadata + Members)\n\n- `ListOrgRepositories`\n- `SearchMyRepos`\n- `ListRepositoryCollaborators`\n- `AssignPullRequestUser` (+ Issues Write)\n\n
\n\n
\nProjects V2 (Contents + Metadata + Projects + Members)\n\n- `ListProjects`\n- `ListProjectItems`\n- `SearchProjectItem`\n- `ListProjectFields`\n- `UpdateProjectItem` (Projects Write)\n\n
\n\n
\nUser Context (Contents + Metadata + Read user profile)\n\n- `WhoAmI` (+ Members)\n- `GetUserRecentActivity`\n- `GetUserOpenItems`\n- `GetReviewWorkload` (+ Pull requests Read)\n\n
\n\n
\n⚠️ Special: Notifications (Requires Classic PAT)\n\n- `GetNotificationSummary`\n- `ListNotifications`\n\n**Note**: GitHub Apps cannot access notifications API. Requires classic Personal Access Token with `notifications` scope.\n\n
\n\n---", + "content": "## GitHub App Permissions Summary\n\nWhen creating your GitHub App, you'll need to grant specific permissions. Here's a quick reference of which tools require which permissions:\n\n### Repository Permissions\n\n| Permission | Level | Required For |\n|------------|-------|--------------|\n| **Contents** | Read | All repository and pull request tools, getting file contents |\n| **Contents** | Write | Creating/updating files, creating branches, merging PRs |\n| **Issues** | Read & Write | Issue management, PR assignments, managing labels (Issues) |\n| **Pull requests** | Read & Write | Pull request management, reviews, managing labels (PRs) |\n| **Metadata** | Read | All tools (automatically granted) |\n| **Statuses** | Read | `CheckPullRequestMergeStatus` |\n\n### Organization Permissions\n\n| Permission | Level | Required For |\n|------------|-------|--------------|\n| **Members** | Read | Projects, collaborators, org repos, user search |\n| **Projects** | Read & Write | All Projects V2 tools |\n\n### User Permissions\n\n| Permission | Level | Required For |\n|------------|-------|--------------|\n| **Read user profile** | Read | User context tools, review workload |\n| **Act on behalf of user** | Enabled | `SetStarred` (starring repositories) |\n\n### Tools by Permission Requirements\n\n
\nBasic Repository Access (Contents Read + Metadata)\n\n- `GetRepository`\n- `CountStargazers`\n- `ListStargazers`\n- `ListRepositoryActivities`\n- `GetFileContents`\n\n
\n\n
\nRepository Write (Contents Write + Metadata)\n\n- `CreateBranch`\n- `CreateOrUpdateFile`\n- `UpdateFileLines`\n\n
\n\n
\nIssue Management (Contents Read + Issues + Metadata)\n\n- `CreateIssue`\n- `UpdateIssue`\n- `GetIssue`\n- `ListIssues`\n- `CreateIssueComment`\n- `ListRepositoryLabels`\n- `ManageLabels` (for issues)\n\n
\n\n
\nPull Request Read (Contents + Pull requests Read + Metadata)\n\n- `ListPullRequests`\n- `GetPullRequest`\n- `ListPullRequestCommits`\n- `ListReviewCommentsOnPullRequest`\n- `CheckPullRequestMergeStatus` (+ Statuses)\n\n
\n\n
\nPull Request Write (Contents Read + Pull requests Write + Metadata)\n\n- `UpdatePullRequest`\n- `CreatePullRequest`\n- `SubmitPullRequestReview`\n- `ManagePullRequest`\n- `ManagePullRequestReviewers`\n- `CreateReviewComment`\n- `CreateReplyForReviewComment`\n- `ResolveReviewThread`\n- `ManageLabels` (for pull requests)\n- `MergePullRequest` (+ Contents Write)\n\n
\n\n
\nOrganization Tools (Contents + Metadata + Members)\n\n- `ListOrgRepositories`\n- `SearchMyRepos`\n- `ListRepositoryCollaborators`\n- `AssignPullRequestUser` (+ Issues Write)\n\n
\n\n
\nProjects V2 (Contents + Metadata + Projects + Members)\n\n- `ListProjects`\n- `ListProjectItems`\n- `SearchProjectItem`\n- `ListProjectFields`\n- `UpdateProjectItem` (Projects Write)\n\n
\n\n
\nUser Context (Contents + Metadata + Read user profile)\n\n- `WhoAmI` (+ Members)\n- `GetUserRecentActivity`\n- `GetUserOpenItems`\n- `GetReviewWorkload` (+ Pull requests Read)\n\n
\n\n---", "header": "## GitHub App Permissions Summary" }, { "type": "warning", "location": "custom_section", "position": "after", - "content": "## Configuration & Setup\n\n### Authentication\n\n\n **Critical**: This MCP Server uses **GitHub Apps** authentication, not OAuth Apps.\n \n You **must** create a GitHub App to use this server. OAuth Apps are not supported.\n\n\nThe Arcade GitHub MCP Server uses the [GitHub auth provider](/references/auth-providers/github) to connect to users' GitHub accounts.\n\n**For Arcade Cloud:**\n- No configuration needed\n- Your users will see `Arcade` as the requesting application\n- All tools work out of the box\n\n**For Self-Hosted:**\n- You must [create your own GitHub App](/references/auth-providers/github#creating-a-github-app)\n- [Configure the GitHub auth provider](/references/auth-providers/github#configuring-github-auth-in-arcade) with your app credentials\n- Your users will see your application name\n\n\n **New to GitHub Apps?** Read [Why Arcade Uses GitHub Apps](/references/auth-providers/github#why-arcade-uses-github-apps-not-oauth-apps) \n to understand the security and compliance benefits.\n\n\n### Secrets Setup\n\nAll tools require secrets to be configured in Arcade Dashboard.\n\n**Steps:**\n\n1. Go to [Arcade Dashboard](https://api.arcade.dev/dashboard)\n2. Navigate to **Secrets** in the left sidebar\n3. Click **Add Secret**\n4. Add the following secrets:\n\n| Secret Name | Value | Required For |\n|-------------|-------|--------------|\n| `GITHUB_SERVER_URL` | `https://api.github.com` (default for GitHub.com) | All tools |\n| `GITHUB_CLASSIC_PERSONAL_ACCESS_TOKEN` | Classic PAT with `notifications` scope | Notifications tools only |\n\n\n **Default**: If `GITHUB_SERVER_URL` is not configured, it defaults to `https://api.github.com` (GitHub.com)\n \n **GitHub Enterprise Users**: Set `GITHUB_SERVER_URL` to your Enterprise server's API endpoint (e.g., `https://github.yourcompany.com/api/v3`). Note that Enterprise uses `/api/v3` path. See [GitHub Enterprise Support](#github-enterprise-support) for details.\n\n\n\n **For Notifications Tools**: Create a classic Personal Access Token at [github.com/settings/tokens](https://github.com/settings/tokens) with only the `notifications` scope checked. GitHub Apps cannot access the notifications API.\n\n\n---", + "content": "## Configuration & Setup\n\n### Authentication\n\n\n **Critical**: This MCP Server uses **GitHub Apps** authentication, not OAuth Apps.\n \n You **must** create a GitHub App to use this server. OAuth Apps are not supported.\n\n\nThe Arcade GitHub MCP Server uses the [GitHub auth provider](/references/auth-providers/github) to connect to users' GitHub accounts.\n\n**For Arcade Cloud:**\n- No configuration needed\n- Your users will see `Arcade` as the requesting application\n- All tools work out of the box\n\n**For Self-Hosted:**\n- You must [create your own GitHub App](/references/auth-providers/github#creating-a-github-app)\n- [Configure the GitHub auth provider](/references/auth-providers/github#configuring-github-auth-in-arcade) with your app credentials\n- Your users will see your application name\n\n\n **New to GitHub Apps?** Read [Why Arcade Uses GitHub Apps](/references/auth-providers/github#why-arcade-uses-github-apps-not-oauth-apps) \n to understand the security and compliance benefits.\n\n\n### Secrets Setup\n\nGitHub tools read an optional `GITHUB_SERVER_URL` secret from the Arcade Dashboard. It defaults to `https://api.github.com`, so you only need to set it for GitHub Enterprise Server.\n\n**Steps:**\n\n1. Go to [Arcade Dashboard](https://api.arcade.dev/dashboard)\n2. Navigate to **Secrets** in the left sidebar\n3. Click **Add Secret**\n4. Add the following secrets:\n\n| Secret Name | Value | Required For |\n|-------------|-------|--------------|\n| `GITHUB_SERVER_URL` | `https://api.github.com` (default for GitHub.com) | All tools |\n\n\n **Default**: If `GITHUB_SERVER_URL` is not configured, it defaults to `https://api.github.com` (GitHub.com)\n \n **GitHub Enterprise Users**: Set `GITHUB_SERVER_URL` to your Enterprise server's API endpoint (e.g., `https://github.yourcompany.com/api/v3`). Note that Enterprise uses `/api/v3` path. See [GitHub Enterprise Support](#github-enterprise-support) for details.\n\n\n---", "header": "## Configuration & Setup" } ],