feat(registry): add GitHub MCP server authentication setup

[divideby0]

Summary

Adds authentication setup for GitHub MCP server to enable repository operations, issue management, pull request workflows, and comprehensive GitHub integration from Claude Code.

Implementation Plan

See docs/features/009-github-authentication.md for detailed implementation approach.

Key Components

1. Registry Updates:

   • Update registry/mcp-servers/github/index.ts
   • Add configure() lifecycle method
   • Implement personal access token prompt with validation

2. Authentication Flow:

   • Display comprehensive permission requirements during setup
   • Interactive prompt for GitHub fine-grained personal access token
   • Validate token format (starts with github_pat_)
   • Store in .env.mcp.secrets as GITHUB_PERSONAL_ACCESS_TOKEN
   • Update MCP config to use dotenv-cli

3. Documentation:

   • Update registry/mcp-servers/github/claude.md
   • Document token creation process step-by-step
   • List all required permissions with explanations
   • Add troubleshooting guide for common auth issues
   • Include example workflows

4. CLAUDE.md Integration:

   • Comprehensive GitHub MCP capabilities overview
   • Common use case examples
   • Security best practices
   • Permission troubleshooting

Technical Approach

export const githubServer: MCPServer = {
  name: "github",
  displayName: "GitHub",
  description: "Repository operations, issues, and pull requests",

  async configure(ctx: SetupContext): Promise<void> {
    ctx.info(`
GitHub MCP Server requires a fine-grained personal access token.

REQUIRED PERMISSIONS (read + write):
✅ contents - Repository files and commits
✅ issues - Create and manage issues
✅ pull_requests - Create and manage PRs
✅ actions - View workflow runs
✅ discussions - Participate in discussions
✅ workflows - Manage workflow files

REQUIRED PERMISSIONS (read):
✅ metadata - Repository metadata
✅ notifications - Access notifications (read + write for marking read)

Get your token at: https://github.com/settings/tokens?type=beta

Select your repositories and grant the permissions above.
    `);

    const token = await ctx.prompt({
      type: "input",
      name: "GITHUB_PERSONAL_ACCESS_TOKEN",
      message: "Enter your GitHub fine-grained personal access token:",
      validate: (value: string) => {
        if (!value.startsWith("github_pat_")) {
          return "GitHub fine-grained tokens should start with 'github_pat_'";
        }
        if (value.length < 30) {
          return "Token appears too short";
        }
        return true;
      }
    });

    await ctx.saveSecret("GITHUB_PERSONAL_ACCESS_TOKEN", token);
  },

  install(ctx: SetupContext): MCPConfig {
    return {
      type: "stdio",
      command: "npx",
      args: [
        "-y",
        "dotenv-cli",
        "-e",
        ".env.mcp.secrets",
        "--",
        "npx",
        "-y",
        "@modelcontextprotocol/server-github"
      ],
      env: {}
    };
  }
};

Testing Strategy

• ✅ Test with valid GitHub fine-grained token
• ✅ Test with invalid token format (classic token)
• ✅ Test with insufficient permissions
• ✅ Verify repository operations work (read/write files)
• ✅ Test issue creation and management
• ✅ Test pull request workflows
• ✅ Test with multiple repositories
• ✅ Verify CLAUDE.md instructions are clear

GitHub MCP Capabilities

Repository Operations

• Create, read, update repository files
• Branch management (create, list, delete)
• Commit operations and history
• Repository search and filtering

Issue Management

• Create and update issues
• Add comments and labels
• Assign users and milestones
• Search and filter issues
• Close and reopen issues

Pull Request Workflows

• Create pull requests
• Review and add comments
• Merge operations (merge, squash, rebase)
• Request reviewers
• View PR status checks

Advanced Features

• Workflow management and triggers
• Discussion participation
• Notification handling
• Deployment tracking (with optional permissions)

Required Permissions Breakdown

Minimum Required (read + write)

contents

• Purpose: Read/write repository files, commits, branches
• Use Cases: File operations, commit creation, branch management
• Why: Core functionality for code interactions

issues

• Purpose: Create, update, close issues, add comments
• Use Cases: Issue tracking, project management
• Why: Essential for issue workflow automation

pull_requests

• Purpose: Create, update, merge PRs, add reviews
• Use Cases: Code review workflows, automated PR creation
• Why: Core functionality for development workflows

actions

• Purpose: View and re-run workflow runs
• Use Cases: CI/CD integration, workflow monitoring
• Why: Understanding build and test status

discussions

• Purpose: Participate in repository discussions
• Use Cases: Community engagement, Q&A
• Why: Full repository interaction capability

workflows

• Purpose: View and update workflow files
• Use Cases: CI/CD configuration management
• Why: Workflow file automation

Minimum Required (read)

metadata

• Purpose: Repository metadata (always included)
• Use Cases: Basic repository information
• Why: Required by GitHub for all tokens

notifications

• Purpose: Access notifications (read + write for marking as read)
• Use Cases: Notification management and filtering
• Why: Stay informed about repository activity

Optional Enhanced Permissions

administration (read + write)

• Purpose: Repository settings management
• Use Cases: Advanced repository configuration
• When: Power users managing repository settings

security_events (read + write)

• Purpose: Code scanning and secret scanning
• Use Cases: Security automation and monitoring
• When: Security-focused workflows

vulnerability_alerts (read + write)

• Purpose: Dependabot alerts management
• Use Cases: Dependency vulnerability tracking
• When: Security and dependency management

deployments (read + write)

• Purpose: Deployment status tracking
• Use Cases: Deployment automation and monitoring
• When: Production deployment workflows

Areas Requesting Feedback

1. Token Testing

Question: Should we test the token during setup?

Pros:

• Immediate validation of credentials and permissions
• Better user experience with clear error messages
• Can detect insufficient permissions early

Cons:

• Requires network call during setup
• Slower setup process
• May fail due to temporary network issues

Recommendation: Optional validation with --skip-validation flag

2. Permission Error Handling

Question: How should we handle permission errors during usage?

Context:

• Operations may fail due to insufficient permissions
• GitHub API returns specific error codes
• Users may not realize they need additional permissions

Options:

• A) Document expected errors in CLAUDE.md
• B) Provide guidance in error messages (requires MCP changes)
• C) Pre-flight permission check during configure
• D) Runtime permission suggestions based on failed operations

Recommendation: Combination of A and C

3. Multi-Account Support

Question: Should we support multiple GitHub accounts/tokens?

Use Cases:

• Personal and work GitHub accounts
• Different permissions for different repositories
• Testing vs production repositories

Implementation:

• Could use server name suffixes (github-work, github-personal)
• Or repository-scoped tokens
• Or org-scoped tokens

Recommendation: Document multi-server pattern, defer implementation

4. Workflow Examples Priority

Question: Which GitHub workflows should we document first?

Options (vote with 👍):

• A) Issue creation and management
• B) Pull request workflows
• C) File operations and commits
• D) Repository search and exploration
• E) CI/CD integration (actions/workflows)
• F) All of the above equally

Recommendation: Option F with practical examples for each

Related Issues

Closes #9

Checklist

• Implementation plan documented
• Registry entry updated with configure method
• Token validation implemented
• Permission display during setup
• MCP config updated for dotenv-cli
• CLAUDE.md fragment updated
• Tests added
• Documentation complete
• Manually tested with real GitHub token

---

Status: 🚧 Draft - Implementation plan complete, awaiting feedback before coding

[divideby0]

Note that https://www.npmjs.com/package/@modelcontextprotocol/server-github is actually deprecated, so we should use https://github.com/github/github-mcp-server. We should review docs to make sure that the cli is still compatible with the example above.

[divideby0]

once we have the pat and have validated its structure, let's also validate it by test calls to the endpoints the mcp needs. if it's easier, we could do that by spawning the mcp process in our validation step and making the rpc calls directly.

if the scopes are insufficient, we should advise the user of additional scopes to add. we should also ensure that the scopes provide access to the current repository (if one of the git remotes is github).

[divideby0]

actually, it might make sense to abstract that functionality so each registry item has its own set of validation calls it can make to the mcp to ensure that it's working with the appropriate credentials, etc. we'll create that as a separate github issue for all existing mcps.