@northbridge-security/secureai 0.1.13

package/docs/guides/github-mcp.md

@@ -0,0 +1,1075 @@
+# GitHub MCP Integration Guide
+
+This guide explains how to integrate GitHub MCP server with AI development tools for repository management, issue tracking, and pull request workflows.
+
+<details>
+  <summary>Table of Contents</summary>
+
+- [GitHub MCP Integration Guide](#github-mcp-integration-guide)
+  - [Overview](#overview)
+  - [What the Installer Does](#what-the-installer-does)
+    - [1. Token Validation](#1-token-validation)
+    - [2. MCP Server Configuration](#2-mcp-server-configuration)
+    - [3. Environment Setup](#3-environment-setup)
+  - [Prerequisites](#prerequisites)
+    - [System Requirements](#system-requirements)
+    - [GitHub Account Setup](#github-account-setup)
+  - [Fine-Grained Token Creation](#fine-grained-token-creation)
+    - [Security Considerations](#security-considerations)
+    - [Create Token](#create-token)
+  - [Manual Setup](#manual-setup)
+    - [Configure MCP Server](#configure-mcp-server)
+    - [Store Token in 1Password](#store-token-in-1password)
+    - [Update MCP Configuration](#update-mcp-configuration)
+    - [Verify Installation](#verify-installation)
+  - [Token Management](#token-management)
+    - [Token Rotation](#token-rotation)
+    - [Token Expiration](#token-expiration)
+    - [Emergency Revocation](#emergency-revocation)
+  - [Security Model](#security-model)
+    - [Read-Only Contents Permission](#read-only-contents-permission)
+    - [PR-Based Workflow](#pr-based-workflow)
+    - [What You Can Do](#what-you-can-do)
+    - [What You Cannot Do](#what-you-cannot-do)
+    - [Defense in Depth](#defense-in-depth)
+  - [Common Operations](#common-operations)
+    - [Repository Information](#repository-information)
+    - [Issue Management](#issue-management)
+    - [Pull Request Workflow](#pull-request-workflow)
+    - [CI/CD Monitoring](#cicd-monitoring)
+  - [Troubleshooting](#troubleshooting)
+    - [Token Validation Fails](#token-validation-fails)
+    - [MCP Server Not Found](#mcp-server-not-found)
+    - [Permission Denied](#permission-denied)
+    - [Rate Limit Exceeded](#rate-limit-exceeded)
+  - [External Resources](#external-resources)
+    - [Official Documentation](#official-documentation)
+    - [Security Best Practices](#security-best-practices)
+    - [Community Support](#community-support)
+
+</details>
+
+## Overview
+
+GitHub MCP server enables AI assistants to interact with GitHub repositories without requiring direct code push permissions. Using fine-grained Personal Access Tokens (PATs) with read-only repository access and PR creation rights, you maintain security while enabling powerful automation.
+
+**Key Features:**
+
+- Read repository contents and metadata
+- Create and manage issues
+- Create pull requests (code changes go through review)
+- Monitor CI/CD workflows and security alerts
+- Query repository statistics and contributor activity
+
+**Security Benefits:**
+
+- No direct code push capability (prevents unauthorized changes)
+- Token compromise cannot modify code without review
+- All changes tracked through pull request audit trail
+- Follows principle of least privilege
+
+## What the Installer Does
+
+Running `ai-toolkit install` with GitHub MCP selected automates the following:
+
+<details>
+  <summary>1. Token Validation</summary>
+
+### 1. Token Validation
+
+Validates GitHub token permissions:
+
+- Checks token format (fine-grained: `github_pat_*`, classic: `ghp_*`)
+- Verifies token is valid via GitHub API
+- For classic tokens: Checks OAuth scopes
+- For fine-grained tokens: Validates authentication (permissions not exposed via API)
+
+**Validation process:**
+
+```typescript
+// src/installers/github-mcp.ts:validateGitHubToken()
+const response = await fetch("https://api.github.com/user", {
+  headers: {
+    Authorization: `Bearer ${token}`,
+    "X-GitHub-Api-Version": "2022-11-28",
+  },
+});
+
+// HTTP 200: Token valid
+// HTTP 401: Invalid or expired
+// HTTP 403: Insufficient permissions or rate limited
+```
+
+</details>
+
+<details>
+  <summary>2. MCP Server Configuration</summary>
+
+### 2. MCP Server Configuration
+
+Configures Claude Code or other AI tools to use GitHub MCP:
+
+**Command executed:**
+
+```bash
+claude mcp add --scope user github-mcp \
+  --env GITHUB_PERSONAL_ACCESS_TOKEN=<token> \
+  -- npx -y @github/github-mcp-server
+```
+
+**Configuration created** (`~/.claude/config.json`):
+
+```json
+{
+  "mcpServers": {
+    "github-mcp": {
+      "command": "npx",
+      "args": ["-y", "@github/github-mcp-server"],
+      "env": {
+        "GITHUB_PERSONAL_ACCESS_TOKEN": "github_pat_..."
+      }
+    }
+  }
+}
+```
+
+</details>
+
+<details>
+  <summary>3. Environment Setup</summary>
+
+### 3. Environment Setup
+
+For project-level usage, creates environment template:
+
+**.env.example:**
+
+```bash
+# GitHub MCP Integration
+# Fine-grained token with read-only contents + PR write permissions
+GITHUB_PERSONAL_ACCESS_TOKEN=op://Private/GitHub/API Token (Read-Only)/token
+```
+
+</details>
+
+## Prerequisites
+
+<details>
+  <summary>System Requirements</summary>
+
+### System Requirements
+
+**Required:**
+
+- Node.js 18+ or Bun 1.0+
+- Claude Code, Cursor, or Codex CLI installed
+- Git 2.30+ configured
+- Internet connection for GitHub API access
+
+**Optional:**
+
+- 1Password CLI for secure token storage
+- 1Password Desktop app (version 8.0+)
+
+</details>
+
+<details>
+  <summary>GitHub Account Setup</summary>
+
+### GitHub Account Setup
+
+**Account requirements:**
+
+- Active GitHub account (free or paid)
+- Access to repositories you want to manage
+- Two-factor authentication (2FA) enabled (required for fine-grained tokens)
+
+**Enable 2FA if not already active:**
+
+1. GitHub → Settings → Password and authentication
+2. Two-factor authentication → Enable
+3. Use authenticator app or SMS
+
+</details>
+
+## Fine-Grained Token Creation
+
+<details>
+  <summary>Security Considerations</summary>
+
+### Security Considerations
+
+Fine-grained tokens provide granular control over permissions and repository access. This configuration follows the principle of least privilege:
+
+**Read-Only Contents:**
+
+- Token cannot push code directly to branches
+- Token cannot force push or delete branches
+- Token cannot modify repository settings
+- All code changes must go through pull request review
+
+**PR Write Access:**
+
+- Token can create pull requests
+- Token can comment on issues and PRs
+- Token cannot approve or merge pull requests (requires separate permission)
+- PR creation provides audit trail for all code changes
+
+**Security Benefits:**
+
+- Token compromise cannot directly modify codebase
+- All changes visible in PR review process
+- No workflow manipulation (read-only Actions permission)
+- Cannot disable security features (read-only security permissions)
+
+</details>
+
+<details>
+  <summary>Create Token</summary>
+
+### Create Token
+
+Navigate to GitHub → Settings → Developer settings → Personal access tokens → Fine-grained tokens → Generate new token
+
+**Token configuration:**
+
+| Setting           | Value                                   |
+| ----------------- | --------------------------------------- |
+| Token name        | `AI Assistant (Read-Only)`              |
+| Expiration        | 90 days (recommended) or custom         |
+| Resource owner    | Your username or organization           |
+| Repository access | All repositories OR select repositories |
+
+**Repository permissions:**
+
+| Permission      | Access Level | Purpose                           |
+| --------------- | ------------ | --------------------------------- |
+| Actions         | Read-only    | View workflow runs                |
+| Contents        | Read-only    | Read repository files             |
+| Issues          | Read & write | Create/update issues              |
+| Pull requests   | Read & write | Create/update PRs                 |
+| Security events | Read-only    | View security alerts              |
+| Workflows       | Read-only    | View workflow definitions         |
+| Metadata        | Read-only    | Access repository metadata (auto) |
+
+**Optional permissions** (add if needed):
+
+| Permission           | Access Level | Purpose                         |
+| -------------------- | ------------ | ------------------------------- |
+| Code scanning alerts | Read-only    | View code scanning results      |
+| Commit statuses      | Read-only    | Check CI/CD status              |
+| Dependabot alerts    | Read-only    | View dependency vulnerabilities |
+| Deployments          | Read-only    | Monitor deployment status       |
+| Discussions          | Read & write | Participate in discussions      |
+
+**After token creation:**
+
+1. Copy token immediately (shown only once)
+2. Store in 1Password or secure password manager
+3. Never commit token to version control
+4. Set calendar reminder 2 weeks before expiration
+
+</details>
+
+## Manual Setup
+
+If the installer cannot run or you prefer manual configuration:
+
+<details>
+  <summary>Configure MCP Server</summary>
+
+### Configure MCP Server
+
+**For Claude Code:**
+
+Edit `~/.claude/config.json`:
+
+```json
+{
+  "mcpServers": {
+    "github-mcp": {
+      "command": "npx",
+      "args": ["-y", "@github/github-mcp-server"],
+      "env": {
+        "GITHUB_PERSONAL_ACCESS_TOKEN": "github_pat_..."
+      }
+    }
+  }
+}
+```
+
+**For Cursor:**
+
+Add MCP server in Cursor settings:
+
+1. Open Settings → Features → MCP Servers
+2. Add new server:
+   - Name: `github-mcp`
+   - Command: `npx`
+   - Args: `-y @github/github-mcp-server`
+   - Environment: `GITHUB_PERSONAL_ACCESS_TOKEN=github_pat_...`
+
+**For Codex CLI:**
+
+Edit `~/.codex/config.toml`:
+
+```toml
+[[mcp_servers]]
+name = "github-mcp"
+command = "npx"
+args = ["-y", "@github/github-mcp-server"]
+
+[mcp_servers.env]
+GITHUB_PERSONAL_ACCESS_TOKEN = "github_pat_..."
+```
+
+</details>
+
+<details>
+  <summary>Store Token in 1Password</summary>
+
+### Store Token in 1Password
+
+**Create 1Password item:**
+
+1. Open 1Password
+2. Create new item → API Credential
+3. Configure fields:
+   - Title: `GitHub API Token (Read-Only)`
+   - Vault: `Private` (or your preferred vault)
+   - Field name: `token`
+   - Field value: Your GitHub fine-grained token
+
+**Add metadata** (recommended):
+
+- Username: Your GitHub username
+- Website: `https://github.com/settings/tokens`
+- Notes: Document token permissions and expiration date
+
+**Example 1Password structure:**
+
+```text
+Private/
+└── GitHub/
+    ├── API Token (Read-Only)
+    │   ├── token: github_pat_...
+    │   ├── username: your-github-username
+    │   ├── expires: 2024-03-15
+    │   └── permissions: contents:read, issues:write, pull_requests:write
+    └── SSH Key (for direct pushes)
+```
+
+</details>
+
+<details>
+  <summary>Update MCP Configuration</summary>
+
+### Update MCP Configuration
+
+Replace token with 1Password reference:
+
+**Claude Code** (`~/.claude/config.json`):
+
+```json
+{
+  "mcpServers": {
+    "github-mcp": {
+      "command": "npx",
+      "args": ["-y", "@github/github-mcp-server"],
+      "env": {
+        "GITHUB_PERSONAL_ACCESS_TOKEN": "op://Private/GitHub/API Token (Read-Only)/token"
+      }
+    }
+  }
+}
+```
+
+**Benefits of 1Password references:**
+
+- Token never stored in plain text
+- Automatic rotation without config changes
+- Biometric authentication required for access
+- Audit trail of token usage
+
+</details>
+
+<details>
+  <summary>Verify Installation</summary>
+
+### Verify Installation
+
+**Test MCP server connection:**
+
+```bash
+# For Claude Code
+claude mcp list
+# Should show: github-mcp
+
+claude mcp get github-mcp
+# Should show configuration details
+```
+
+**Test GitHub API access:**
+
+```bash
+# Direct token test
+curl -H "Authorization: Bearer github_pat_..." \
+  https://api.github.com/user
+```
+
+**Test in AI assistant:**
+
+Ask your AI assistant to perform a GitHub operation:
+
+```text
+"List my GitHub repositories"
+"Show recent issues in repository X"
+"Create a test issue in repository Y"
+```
+
+</details>
+
+## Token Management
+
+<details>
+  <summary>Token Rotation</summary>
+
+### Token Rotation
+
+Rotate tokens every 90 days or when:
+
+- Team member leaves with token access
+- Token may have been exposed in logs
+- Security policy requires rotation
+- Token permissions need to change
+
+**Rotation process:**
+
+1. **Create new token** with same permissions
+2. **Store in 1Password** (update existing item or create new)
+3. **Test new token** with curl or AI assistant
+4. **Update MCP configuration** if using direct token (1Password refs auto-update)
+5. **Revoke old token** in GitHub settings
+6. **Verify functionality** after rotation
+
+**Automated rotation with 1Password:**
+
+When using `op://` references, update the token in 1Password:
+
+1. Edit 1Password item
+2. Replace token field value
+3. Save item
+4. No configuration changes needed (reference remains same)
+5. Next MCP server start uses new token automatically
+
+</details>
+
+<details>
+  <summary>Token Expiration</summary>
+
+### Token Expiration
+
+**Before expiration:**
+
+- Set calendar reminder 2 weeks before expiration date
+- Create new token with same permissions
+- Test new token before old token expires
+- Update 1Password item or MCP configuration
+- Document new expiration date
+
+**After expiration:**
+
+GitHub MCP operations will fail with 401 Unauthorized:
+
+```text
+Error: GitHub API returned 401: Invalid or expired token.
+Please create a new GitHub token.
+```
+
+**Recovery steps:**
+
+1. Create new fine-grained token (see [Fine-Grained Token Creation](#fine-grained-token-creation))
+2. Update token in 1Password or MCP configuration
+3. Restart AI assistant to reload configuration
+4. Verify functionality with test operation
+
+</details>
+
+<details>
+  <summary>Emergency Revocation</summary>
+
+### Emergency Revocation
+
+Revoke token immediately if:
+
+- Token committed to public repository
+- Token found in logs or error messages
+- Suspicious activity on GitHub account
+- Token compromised in security incident
+
+**Revocation steps:**
+
+1. **Revoke in GitHub:**
+   - GitHub → Settings → Developer settings
+   - Personal access tokens → Fine-grained tokens
+   - Find token → Revoke
+
+2. **Create replacement token** (if needed for continued operation)
+
+3. **Update configuration:**
+   - Update 1Password item with new token
+   - Or update MCP configuration directly
+   - Restart AI assistant
+
+4. **Audit recent activity:**
+   - Check GitHub audit log for unauthorized actions
+   - Review recent PRs and issues created by token
+   - Verify no malicious changes were merged
+
+**GitHub audit log:**
+
+- Organization → Settings → Logs → Audit log
+- Filter by token name or time range
+- Look for unexpected API calls or repository changes
+
+</details>
+
+## Security Model
+
+<details>
+  <summary>Read-Only Contents Permission</summary>
+
+### Read-Only Contents Permission
+
+**What read-only Contents permission allows:**
+
+- Read file contents from all branches
+- Clone repositories (read-only)
+- View commit history
+- Access repository metadata
+- Read branch and tag information
+
+**What read-only Contents permission prevents:**
+
+- Push commits to any branch
+- Create or delete branches
+- Create or delete tags
+- Force push or rewrite history
+- Modify repository files directly
+
+**Example: Attempting direct push fails:**
+
+```bash
+$ git push origin feature-branch
+remote: Permission denied to github-actions[bot].
+fatal: unable to access 'https://github.com/user/repo.git/':
+       The requested URL returned error: 403
+```
+
+This protection ensures all code changes go through pull request review.
+
+</details>
+
+<details>
+  <summary>PR-Based Workflow</summary>
+
+### PR-Based Workflow
+
+**How PR creation works with limited permissions:**
+
+1. **AI reads repository** (Contents: read-only)
+2. **AI generates code changes** locally
+3. **AI creates pull request** (Pull requests: write)
+4. **Human reviews PR** in GitHub UI
+5. **Human approves and merges** (requires separate permission)
+
+**Why this is secure:**
+
+- Token cannot push code directly (no Contents write permission)
+- Token cannot merge PRs (no Pull requests admin permission)
+- Human review required for all code changes
+- Git history shows PR-based changes, not direct commits
+- Code review process enforced by permissions, not policy
+
+**Example workflow:**
+
+```text
+1. Claude: "I'll create a PR to fix the authentication bug"
+   → Creates branch locally (if allowed) OR
+   → Creates PR from fork
+
+2. Claude: "PR #123 created for review"
+   → You review PR in GitHub
+
+3. You: Approve and merge PR
+   → Changes merged to main branch
+   → Token could not perform this action
+```
+
+</details>
+
+<details>
+  <summary>What You Can Do</summary>
+
+### What You Can Do
+
+**Repository Operations:**
+
+- Read all repository files and history
+- Clone repositories (read-only)
+- Search code across repositories
+- View branch and tag information
+- Check repository statistics
+
+**Issue Management:**
+
+- Create new issues
+- Add labels, assignees, and milestones
+- Comment on existing issues
+- Close issues (if you created them)
+- Search and filter issues
+
+**Pull Requests:**
+
+- Create pull requests
+- Comment on PRs
+- Request reviews
+- Add labels and assignees
+- View PR status checks
+
+**CI/CD Monitoring:**
+
+- View workflow run status
+- Read workflow logs
+- Check deployment status
+- View commit status checks
+
+**Security Monitoring:**
+
+- Read code scanning alerts
+- View Dependabot alerts
+- Check secret scanning results
+- Read security advisories
+
+</details>
+
+<details>
+  <summary>What You Cannot Do</summary>
+
+### What You Cannot Do
+
+**Repository Modification:**
+
+- Push commits directly to branches
+- Create or delete branches
+- Force push or rewrite history
+- Modify repository settings
+- Delete repositories
+
+**Workflow Control:**
+
+- Trigger workflow runs manually
+- Cancel running workflows
+- Approve workflow runs requiring approval
+- Modify workflow files (read-only)
+
+**PR Administration:**
+
+- Approve pull requests (requires separate permission)
+- Merge pull requests
+- Close PRs you didn't create
+- Override branch protection rules
+
+**Security Configuration:**
+
+- Modify security settings
+- Disable security features
+- Change alert settings
+- Configure code scanning
+
+</details>
+
+<details>
+  <summary>Defense in Depth</summary>
+
+### Defense in Depth
+
+**Multiple security layers:**
+
+1. **Token permissions** - Read-only contents prevents direct pushes
+2. **Branch protection** - Requires PR reviews even if permissions allowed direct push
+3. **Required reviews** - Humans must approve code changes
+4. **Status checks** - CI/CD must pass before merge
+5. **CODEOWNERS** - Specific reviewers required for sensitive files
+
+**What happens if token is compromised:**
+
+| Attack Scenario     | With Read-Only Token               | With Write Token               |
+| ------------------- | ---------------------------------- | ------------------------------ |
+| Push malicious code | ❌ Blocked (no push permission)    | ✅ Succeeds, bypasses review   |
+| Create malicious PR | ⚠️ Creates PR, requires review     | ⚠️ Creates PR, requires review |
+| Trigger workflows   | ❌ Blocked (read-only Actions)     | ✅ Can trigger workflows       |
+| Disable security    | ❌ Blocked (read-only security)    | ✅ Can disable alerts          |
+| Modify secrets      | ❌ Blocked (no secrets permission) | ⚠️ Depends on permissions      |
+
+**Additional protections:**
+
+- Audit log tracks all API calls
+- Rate limiting prevents abuse
+- IP allowlists restrict token usage
+- Expiration dates limit exposure window
+
+</details>
+
+## Common Operations
+
+<details>
+  <summary>Repository Information</summary>
+
+### Repository Information
+
+**List repositories:**
+
+```text
+AI: "List all my GitHub repositories"
+→ Shows repositories you own or have access to
+```
+
+**Get repository details:**
+
+```text
+AI: "Show details for repository northbridge-security/ai-toolkit"
+→ Returns: name, description, stars, forks, language, last updated
+```
+
+**View recent commits:**
+
+```text
+AI: "Show the 10 most recent commits in ai-toolkit"
+→ Lists commits with author, message, SHA, date
+```
+
+**Read file contents:**
+
+```text
+AI: "Show me the contents of package.json in ai-toolkit"
+→ Returns file contents from main branch
+```
+
+</details>
+
+<details>
+  <summary>Issue Management</summary>
+
+### Issue Management
+
+**List issues:**
+
+```text
+AI: "Show open issues in ai-toolkit"
+→ Lists issues with title, number, labels, assignee
+```
+
+**Create issue:**
+
+```text
+AI: "Create an issue titled 'Bug: Login fails on Safari' with description..."
+→ Creates issue, returns issue number and URL
+```
+
+**Add labels and assignees:**
+
+```text
+AI: "Add label 'bug' and assign issue #42 to @username"
+→ Updates issue with label and assignee
+```
+
+**Close issue:**
+
+```text
+AI: "Close issue #42 with comment 'Fixed in PR #45'"
+→ Closes issue and adds comment
+```
+
+</details>
+
+<details>
+  <summary>Pull Request Workflow</summary>
+
+### Pull Request Workflow
+
+**Create pull request:**
+
+```text
+AI: "Create a PR to add GitHub Actions workflow"
+→ Creates PR with generated changes
+→ Returns PR number and URL for review
+```
+
+**List pull requests:**
+
+```text
+AI: "Show all open PRs in ai-toolkit"
+→ Lists PRs with title, number, author, status
+```
+
+**Check PR status:**
+
+```text
+AI: "What's the status of PR #123?"
+→ Shows: review status, CI checks, merge conflicts
+```
+
+**Add PR comment:**
+
+```text
+AI: "Comment on PR #123: 'Please add unit tests for the new function'"
+→ Adds comment to PR
+```
+
+</details>
+
+<details>
+  <summary>CI/CD Monitoring</summary>
+
+### CI/CD Monitoring
+
+**View workflow runs:**
+
+```text
+AI: "Show recent workflow runs for ai-toolkit"
+→ Lists workflow runs with status, duration, conclusion
+```
+
+**Check workflow status:**
+
+```text
+AI: "Did the latest CI workflow pass?"
+→ Shows: success/failure, failed jobs, error messages
+```
+
+**View deployment status:**
+
+```text
+AI: "What's the current deployment status?"
+→ Shows active deployments and their state
+```
+
+</details>
+
+## Troubleshooting
+
+<details>
+  <summary>Token Validation Fails</summary>
+
+### Token Validation Fails
+
+**Error:** `Invalid or expired token. Please create a new GitHub token.`
+
+**Possible causes:**
+
+1. Token expired (check expiration date in GitHub settings)
+2. Token revoked (check GitHub token list)
+3. Token copied incorrectly (missing characters or extra whitespace)
+4. 2FA required but not enabled on account
+
+**Solutions:**
+
+```bash
+# Verify token format
+echo $GITHUB_PERSONAL_ACCESS_TOKEN | wc -c
+# Fine-grained: ~255 characters (github_pat_...)
+# Classic: ~40 characters (ghp_...)
+
+# Test token directly
+curl -H "Authorization: Bearer ${GITHUB_PERSONAL_ACCESS_TOKEN}" \
+  https://api.github.com/user
+
+# Expected: JSON with user information
+# If 401: Token invalid or expired
+# If 403: Rate limited or insufficient permissions
+```
+
+**Create new token** if validation continues to fail (see [Fine-Grained Token Creation](#fine-grained-token-creation))
+
+</details>
+
+<details>
+  <summary>MCP Server Not Found</summary>
+
+### MCP Server Not Found
+
+**Error:** `MCP server "github-mcp" not found`
+
+**Check MCP configuration:**
+
+```bash
+# For Claude Code
+claude mcp list
+# Should show github-mcp in output
+
+# View configuration
+claude mcp get github-mcp
+```
+
+**If not listed:**
+
+```bash
+# Add GitHub MCP server
+claude mcp add --scope user github-mcp \
+  --env GITHUB_PERSONAL_ACCESS_TOKEN="your_token" \
+  -- npx -y @github/github-mcp-server
+
+# Verify installation
+claude mcp list
+```
+
+**Check configuration file:**
+
+```bash
+# macOS/Linux
+cat ~/.claude/config.json | jq '.mcpServers["github-mcp"]'
+
+# Should show command, args, and env configuration
+```
+
+**If configuration exists but server not loading:**
+
+1. Restart AI assistant
+2. Check Claude Code logs for errors
+3. Verify Node.js/npx is installed: `npx --version`
+4. Test manual server start: `npx @github/github-mcp-server`
+
+</details>
+
+<details>
+  <summary>Permission Denied</summary>
+
+### Permission Denied
+
+**Error:** `Permission denied` or `403 Forbidden` when performing GitHub operations
+
+**Check token permissions:**
+
+1. GitHub → Settings → Developer settings → Personal access tokens
+2. Click on your token
+3. Review "Repository permissions" section
+4. Verify required permissions are granted:
+   - Contents: Read-only (minimum)
+   - Issues: Read & write (for issue operations)
+   - Pull requests: Read & write (for PR operations)
+
+**If permissions are correct but errors continue:**
+
+```bash
+# Test specific permission
+curl -H "Authorization: Bearer ${GITHUB_PERSONAL_ACCESS_TOKEN}" \
+  https://api.github.com/repos/OWNER/REPO/contents/README.md
+
+# Expected: File contents
+# If 404: Repository not found or token lacks access
+# If 403: Token doesn't have Contents permission
+```
+
+**Solutions:**
+
+- Update token permissions in GitHub settings
+- Create new token with correct permissions
+- Verify repository access (token may not have access to private repos)
+- Check organization settings (org may restrict fine-grained tokens)
+
+</details>
+
+<details>
+  <summary>Rate Limit Exceeded</summary>
+
+### Rate Limit Exceeded
+
+**Error:** `API rate limit exceeded`
+
+**GitHub rate limits:**
+
+- Authenticated requests: 5,000 per hour
+- Search API: 30 requests per minute
+- GraphQL API: 5,000 points per hour
+
+**Check current rate limit:**
+
+```bash
+curl -H "Authorization: Bearer ${GITHUB_PERSONAL_ACCESS_TOKEN}" \
+  https://api.github.com/rate_limit
+```
+
+**Response:**
+
+```json
+{
+  "resources": {
+    "core": {
+      "limit": 5000,
+      "remaining": 4999,
+      "reset": 1234567890
+    }
+  }
+}
+```
+
+**If rate limited:**
+
+1. **Wait for reset** - `reset` field shows Unix timestamp for limit reset
+2. **Reduce request frequency** - Batch operations when possible
+3. **Use conditional requests** - Include `If-None-Match` headers for caching
+4. **Optimize queries** - Request only needed data
+
+**For persistent rate limit issues:**
+
+- Consider GitHub Enterprise (higher limits)
+- Use multiple tokens with different scopes
+- Implement caching for frequently accessed data
+- Switch to GraphQL API (more efficient than REST)
+
+</details>
+
+## External Resources
+
+<details>
+  <summary>Official Documentation</summary>
+
+### Official Documentation
+
+- **GitHub MCP Server**: https://github.com/github/github-mcp-server
+- **Fine-Grained PATs**: https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens#creating-a-fine-grained-personal-access-token
+- **GitHub API Reference**: https://docs.github.com/en/rest
+- **Token Permissions**: https://docs.github.com/en/rest/overview/permissions-required-for-fine-grained-personal-access-tokens
+
+</details>
+
+<details>
+  <summary>Security Best Practices</summary>
+
+### Security Best Practices
+
+- **Token Security**: https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/token-expiration-and-revocation
+- **GitHub Security**: https://docs.github.com/en/code-security
+- **Audit Logs**: https://docs.github.com/en/organizations/keeping-your-organization-secure/managing-security-settings-for-your-organization/reviewing-the-audit-log-for-your-organization
+- **Branch Protection**: https://docs.github.com/en/repositories/configuring-branches-and-merges-in-your-repository/managing-protected-branches/about-protected-branches
+
+</details>
+
+<details>
+  <summary>Community Support</summary>
+
+### Community Support
+
+- **GitHub MCP Issues**: https://github.com/github/github-mcp-server/issues
+- **MCP Specification**: https://modelcontextprotocol.io/
+- **AI Toolkit Issues**: https://github.com/northbridge-security/ai-toolkit/issues
+- **GitHub Community**: https://github.com/community
+
+</details>
+
+---
+
+For 1Password integration patterns, see [1Password Integration Guide](./1password.md)
+
+For MCP configuration details, see [MCP Integration Guide](./mcp-integration.md)