feat(mcp): Add GitHub MCP Server Authentication Setup Instructions

## Overview

Add comprehensive instructions for obtaining and configuring a GitHub fine-grained personal access token for the `@modelcontextprotocol/server-github` MCP server.

## Current State

- GitHub MCP server uses `@modelcontextprotocol/server-github` package
- Configuration uses `dotenv-cli` to inject secrets from `.env.mcp.secrets`
- No guidance on creating tokens or required permissions

## Research Summary

Based on deep research of the official GitHub MCP server repository and GitHub's API documentation:

- **Official Repository**: https://github.com/github/github-mcp-server
- **NPM Package**: `@modelcontextprotocol/server-github` (deprecated, use GitHub source)
- **Authentication**: Requires GitHub fine-grained personal access token
- **Token Location**: Settings → Developer settings → Personal access tokens → Fine-grained tokens

## Requirements

### Fine-Grained Personal Access Token Permissions

The GitHub MCP server performs comprehensive operations across GitHub's REST API. The following permissions are required:

#### Repository Permissions (Minimum Required)

**Read + Write Access**:
- ✅ `contents` - File and branch operations
- ✅ `issues` - Issue creation and updates
- ✅ `pull_requests` - PR workflows and reviews
- ✅ `actions` - Workflow run management
- ✅ `discussions` - Discussions and comments
- ✅ `workflows` - Dispatch workflow events

**Read Access Only**:
- ✅ `metadata` - Repository and collaborator listings

**Optional (for enhanced features)**:
- `administration` (write) - Repository creation and settings
- `security_events` (read/write) - Code scanning alerts
- `vulnerability_alerts` (read/write) - Dependabot alerts
- `dependabot_secrets` (read/write) - Dependabot secrets management
- `secret_scanning_alerts` (read/write) - Secret scanning
- `labels` (read/write) - Label management
- `repository_hooks` (read/write) - Webhook management
- `repository_advisories` (read/write) - Security advisories
- `statuses` (read/write) - Commit status updates

#### Account Permissions

- `notifications` (read/write) - Personal notifications management

### Read-Only vs Read-Write

**Read-Only Configuration** (for viewing only):
- Set all permissions to `read` level
- Enables: listing, fetching, searching
- Limitations: Cannot create, update, or delete resources

**Full Functionality** (default recommendation):
- Set relevant permissions to `write` level
- Write permissions include read access
- Enables: All MCP server operations

### Token Creation Process

1. **Verify Email**: Ensure GitHub email is verified
2. **Navigate to Settings**:
   - Click profile photo (upper-right)
   - Select **Settings**
3. **Access Token Management**:
   - Left sidebar: **Developer settings**
   - Select: **Personal access tokens** → **Fine-grained tokens**
4. **Generate Token**:
   - Click **Generate new token**
   - Enter **Token name** (e.g., "MCP Server - Project Name")
   - Choose **Expiration** (recommend 90 days with renewal)
   - Add **Description**: "MCP server for Claude Code integration"
5. **Configure Access**:
   - **Resource owner**: Your user account (or organization if applicable)
   - **Repository access**: Select specific repositories or all
6. **Set Permissions**:
   - Grant minimum required permissions listed above
   - Start with read-only, add write as needed
7. **Generate and Copy**:
   - Click **Generate token**
   - Copy token immediately (shown only once)
   - Store securely in password manager

[TODO: USER INPUT NEEDED - Verify if there are any organization-specific approval requirements users should be aware of]

## Implementation

### Documentation Updates

**`registry/mcp-servers/github/index.ts`** (new file):
```typescript
/**
 * GitHub MCP Server
 */

import { join } from "@std/path";
import { BaseMCPServer } from "../../../src/lib/base-server.ts";
import { createNpxConfigWithSecrets } from "../../../src/lib/utils/dotenv.ts";
import type { DependencyRequirement, SecretRequirement } from "../../../src/lib/base-server.ts";
import type { ServerMetadata } from "../../../src/types/lifecycle.ts";

export class GitHubServer extends BaseMCPServer {
  override metadata: ServerMetadata = {
    id: "github",
    name: "GitHub",
    description: "Comprehensive GitHub integration for repositories, issues, PRs, and workflows",
    category: "optional",
    version: "0.4.0",
    repository: "https://github.com/github/github-mcp-server",
  };

  protected override getDependencies(): DependencyRequirement[] {
    return [
      {
        command: "node",
        name: "Node.js",
        minVersion: "18.0.0",
      },
    ];
  }

  override getSecrets(): SecretRequirement[] {
    return [
      {
        key: "GITHUB_PERSONAL_ACCESS_TOKEN",
        prompt: "Enter your GitHub fine-grained personal access token:",
        optional: false,
        validate: (value: string) => {
          if (!value || value.trim().length === 0) {
            return "GitHub token is required";
          }
          // GitHub fine-grained tokens start with 'github_pat_'
          if (!value.startsWith("github_pat_")) {
            return "Token should be a fine-grained personal access token (starts with 'github_pat_')";
          }
          return true;
        }
      },
    ];
  }

  protected override generateMcpConfig(_secrets: Record<string, string>) {
    // Use npx with dotenv wrapper to inject GITHUB_PERSONAL_ACCESS_TOKEN
    return createNpxConfigWithSecrets("@modelcontextprotocol/server-github");
  }

  override getClaudeMdContent(): string {
    const modulePath = new URL(".", import.meta.url).pathname;
    const claudeMdPath = join(modulePath, "claude.md");

    try {
      return Deno.readTextFileSync(claudeMdPath);
    } catch (_error) {
      return `### ${this.metadata.name}\n\n${this.metadata.description}`;
    }
  }
}

export default new GitHubServer();
```

**`registry/mcp-servers/github/claude.md`** (new file):
```markdown
### GitHub

**Purpose**: Comprehensive GitHub API integration for repository management, issues, pull requests, workflows, and security.

**When to Use**:
- Create, read, update files and branches
- Manage issues and pull requests
- Work with GitHub Actions workflows
- Access code security and Dependabot alerts
- Search repositories, code, and users
- Manage discussions and projects

**Available Operations**:

**Repository Management**:
- Create repositories and branches
- Read, create, update, delete file contents
- List commits, branches, tags, releases
- Manage collaborators and metadata

**Issues & Pull Requests**:
- Create, read, update issues and PRs
- Add comments and manage assignees
- Manage labels and review workflows
- Merge and close pull requests

**GitHub Actions**:
- List workflows and workflow runs
- Rerun, cancel workflow runs
- Get logs and artifacts
- Approve workflow jobs

**Code Security**:
- Code scanning alerts
- Dependabot alerts and secrets
- Secret scanning alerts
- Repository advisories

**Search & Discovery**:
- Search repositories, code, issues, PRs
- Search users and organizations
- List stargazers and watchers

**Projects & Discussions**:
- Manage organization and repository projects
- Create and list discussions
- Add discussion comments

**Examples**:
```
Create a new issue in owner/repo titled "Bug: Login fails"

Search for TypeScript files containing "authentication" in this repository

List all open pull requests for review

Get the latest workflow run status for the main branch

Create a new branch called "feature/new-api" from main
```

**Authentication**: Requires GitHub fine-grained personal access token with appropriate permissions.

**Permission Requirements**:

Minimum (read-only):
- contents: read
- issues: read
- pull_requests: read
- metadata: read

Recommended (full functionality):
- contents: read + write
- issues: read + write
- pull_requests: read + write
- actions: read + write
- discussions: read + write
- workflows: write

See Issue #9 for complete permission details.
```

### Interactive Configuration

During `ftk init`, when GitHub is selected:

```
ℹ️  GitHub Personal Access Token Required
   
   The GitHub MCP server requires a fine-grained personal access token.
   
   To create one:
   1. Go to: Settings → Developer settings → Personal access tokens → Fine-grained tokens
   2. Click "Generate new token"
   3. Grant required permissions (see documentation)
   
   Minimum permissions needed:
   • Repository: contents (read+write), issues, pull_requests, metadata
   • Account: notifications
   
   Token format: github_pat_XXXXXXXXXXXXXXXXXXXXX
   
   Create token at: https://github.com/settings/tokens?type=beta
```

### Help Text Update

```typescript
async configure(ctx: ConfigContext): Promise<ServerConfig> {
  ctx.info("GitHub MCP Server Setup");
  ctx.info("");
  ctx.info("You need a fine-grained personal access token with these permissions:");
  ctx.info("  • contents (read+write) - File operations");
  ctx.info("  • issues (read+write) - Issue management");
  ctx.info("  • pull_requests (read+write) - PR workflows");
  ctx.info("  • metadata (read) - Repository listings");
  ctx.info("");
  ctx.info("Create token at: https://github.com/settings/tokens?type=beta");
  ctx.info("");

  const token = await Input.prompt({
    message: "Enter your GitHub fine-grained personal access token:",
    validate: (value) => {
      if (!value || value.trim().length === 0) {
        return "GitHub token is required";
      }
      if (!value.startsWith("github_pat_")) {
        return "Must be a fine-grained token (starts with 'github_pat_')";
      }
      return true;
    }
  });

  return {
    command: "npx",
    args: [
      "-y",
      "dotenv-cli",
      "-e",
      ".env.mcp.secrets",
      "--",
      "npx",
      "-y",
      "@modelcontextprotocol/server-github"
    ],
    env: {}
  };
}
```

### `.env.mcp.secrets` Format

```bash
# GitHub MCP Server
GITHUB_PERSONAL_ACCESS_TOKEN=github_pat_XXXXXXXXXXXXXXXXXXXXX

# Exa MCP Server
EXA_API_KEY=your-exa-key-here

# Context7 MCP Server (optional)
CONTEXT7_API_KEY=your-context7-key-here
```

## Testing

- [ ] Verify token creation flow on GitHub
- [ ] Test read-only token configuration
- [ ] Test full write permissions
- [ ] Validate token format detection
- [ ] Test common operations (create issue, PR, etc.)
- [ ] Verify organization approval workflow if applicable

## Security Considerations

### Token Storage
- Store in `.env.mcp.secrets` (gitignored)
- Never commit tokens to version control
- Use password manager for backup

### Token Expiration
- Recommend 90-day expiration with renewal reminders
- Document renewal process in `CLAUDE.md`

### Token Scope
- Use repository-specific tokens when possible
- Avoid granting organization-wide access unnecessarily
- Regularly audit and rotate tokens

### Organization Restrictions
- Some organizations require approval for fine-grained tokens
- Document approval process for enterprise users
- Provide fallback to classic tokens if needed

## Related Issues

- Related to Exa authentication setup (#7)
- Related to Context7 authentication setup (#8)
- Depends on version pinning (#6)
- Related to `.env.mcp.secrets` management

## References

- **Official Repository**: https://github.com/github/github-mcp-server
- **NPM Package**: https://www.npmjs.com/package/@modelcontextprotocol/server-github
- **Token Creation**: https://github.com/settings/tokens?type=beta
- **Permission Docs**: https://docs.github.com/en/rest/authentication/permissions-required-for-fine-grained-personal-access-tokens
- **Token Management**: https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/managing-your-personal-access-tokens

Navigation Menu

Uh oh!

feat(mcp): Add GitHub MCP Server Authentication Setup Instructions #9

Overview

Current State

Research Summary

Requirements

Fine-Grained Personal Access Token Permissions

Repository Permissions (Minimum Required)

Account Permissions

Read-Only vs Read-Write

Token Creation Process

Implementation

Documentation Updates

Interactive Configuration

Help Text Update

`.env.mcp.secrets` Format

Testing

Security Considerations

Token Storage

Token Expiration

Token Scope

Organization Restrictions

Related Issues

References

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Uh oh!

feat(mcp): Add GitHub MCP Server Authentication Setup Instructions #9

Description

Overview

Current State

Research Summary

Requirements

Fine-Grained Personal Access Token Permissions

Repository Permissions (Minimum Required)

Account Permissions

Read-Only vs Read-Write

Token Creation Process

Implementation

Documentation Updates

Interactive Configuration

Help Text Update

.env.mcp.secrets Format

Testing

Security Considerations

Token Storage

Token Expiration

Token Scope

Organization Restrictions

Related Issues

References

Metadata

Metadata

Assignees

Labels

Type

Projects

Milestone

Relationships

Development

Issue actions

`.env.mcp.secrets` Format