GitHub Dev Assistant Plugin - Enhancement Proposal

## Summary
Enhance the `github-dev-assistant` plugin to support more advanced GitHub operations and improve overall functionality.

## Current State
The plugin provides **14 tools** covering:
- ✅ Auth (1): `github_check_auth`
- ✅ Repos (2): `github_list_repos`, `github_create_repo`
- ✅ Files (3): `github_get_file`, `github_update_file`, `github_create_branch`
- ✅ PRs (3): `github_create_pr`, `github_list_prs`, `github_merge_pr`
- ✅ Issues (4): `github_create_issue`, `github_list_issues`, `github_comment_issue`, `github_close_issue`
- ✅ Actions (1): `github_trigger_workflow`

## Proposed Enhancements

### 1. **File Operations** 🔧

#### 1.1 `github_delete_file`
**Description:** Delete a file from a GitHub repository.

**Parameters:**
```typescript
{
  owner: string,        // Repository owner
  repo: string,         // Repository name
  path: string,         // Path to file
  message: string,      // Commit message
  sha: string,          // File SHA (required)
  branch?: string       // Branch to delete from
}
```

**Use Cases:**
- Remove unwanted files
- Clean up repository
- Delete temporary files

#### 1.2 `github_list_directory`
**Description:** List contents of a directory in a GitHub repository.

**Parameters:**
```typescript
{
  owner: string,        // Repository owner
  repo: string,         // Repository name
  path?: string,        // Directory path (default: root)
  ref?: string          // Branch/tag/commit
}
```

**Use Cases:**
- Browse repository structure
- Find files in subdirectories
- Understand project organization

#### 1.3 `github_search_code`
**Description:** Search for code patterns in a repository.

**Parameters:**
```typescript
{
  owner: string,        // Repository owner
  repo: string,         // Repository name
  query: string,        // Search query (e.g., "function test" or "class User")
  ref?: string          // Branch/tag/commit to search
}
```

**Use Cases:**
- Find specific functions
- Locate code patterns
- Understand codebase structure

#### 1.4 `github_download_file`
**Description:** Download a file from GitHub and return content.

**Parameters:**
```typescript
{
  owner: string,        // Repository owner
  repo: string,         // Repository name
  path: string,         // File path
  ref?: string,         // Branch/tag/commit
  save_to_file?: string // Optional local file path
}
```

**Use Cases:**
- Download code files
- Export configuration files
- Save documentation

### 2. **Issue/PR Operations** 📝

#### 2.1 `github_list_comments`
**Description:** List comments on an issue or PR.

**Parameters:**
```typescript
{
  owner: string,        // Repository owner
  repo: string,         // Repository name
  issue_number?: number, // Issue number (if on issue)
  pr_number?: number     // PR number (if on PR)
}
```

**Use Cases:**
- Review discussions
- Track feedback
- Respond to comments

#### 2.2 `github_update_issue`
**Description:** Update an existing issue.

**Parameters:**
```typescript
{
  owner: string,        // Repository owner
  repo: string,         // Repository name
  issue_number: number, // Issue number
  title?: string,       // New title
  body?: string,        // New body
  state?: "open" | "closed", // New state
  labels?: string[]     // New labels
}
```

**Use Cases:**
- Update issue titles
- Change issue status
- Update issue body

#### 2.3 `github_reopen_issue`
**Description:** Reopen a closed issue.

**Parameters:**
```typescript
{
  owner: string,        // Repository owner
  repo: string,         // Repository name
  issue_number: number  // Issue number
}
```

**Use Cases:**
- Bring back closed issues
- Continue discussions
- Track reopened bugs

#### 2.4 `github_assign_issue`
**Description:** Assign an issue to a user or team.

**Parameters:**
```typescript
{
  owner: string,        // Repository owner
  repo: string,         // Repository name
  issue_number: number, // Issue number
  assignees?: string[]  // Users to assign
}
```

**Use Cases:**
- Delegate issues
- Assign to team members
- Track ownership

### 3. **Commit Operations** 📊

#### 3.1 `github_list_commits`
**Description:** List commits in a repository.

**Parameters:**
```typescript
{
  owner: string,        // Repository owner
  repo: string,         // Repository name
  branch?: string,      // Branch name (default: repo default)
  per_page?: number,    // Results per page (1-100)
  page?: number         // Page number
}
```

**Use Cases:**
- View commit history
- Analyze changes
- Understand development flow

#### 3.2 `github_get_commit`
**Description:** Get detailed information about a specific commit.

**Parameters:**
```typescript
{
  owner: string,        // Repository owner
  repo: string,         // Repository name
  commit_sha: string    // Commit SHA
}
```

**Use Cases:**
- Review specific changes
- Check commit details
- Investigate issues

#### 3.3 `github_list_pull_requests_reviews`
**Description:** List reviews on a PR.

**Parameters:**
```typescript
{
  owner: string,        // Repository owner
  repo: string,         // Repository name
  pr_number: number     // PR number
}
```

**Use Cases:**
- Review review status
- Track feedback
- Monitor approval

### 4. **Repository Operations** 📦

#### 4.1 `github_list_languages`
**Description:** List programming languages used in a repository.

**Parameters:**
```typescript
{
  owner: string,        // Repository owner
  repo: string         // Repository name
}
```

**Use Cases:**
- Analyze tech stack
- Understand project structure
- Identify dependencies

#### 4.2 `github_list_teams`
**Description:** List teams in an organization.

**Parameters:**
```typescript
{
  owner: string,        // Organization name
  per_page?: number,    // Results per page
  page?: number         // Page number
}
```

**Use Cases:**
- Understand team structure
- Find team members
- Check team permissions

#### 4.3 `github_list_collaborators`
**Description:** List collaborators on a repository.

**Parameters:**
```typescript
{
  owner: string,        // Repository owner
  repo: string         // Repository name,
  permission?: string   // Filter by permission level
}
```

**Use Cases:**
- Check access control
- Review permissions
- Find collaborators

### 5. **Workflow Operations** ⚙️

#### 5.1 `github_list_workflows`
**Description:** List GitHub Actions workflows in a repository.

**Parameters:**
```typescript
{
  owner: string,        // Repository owner
  repo: string         // Repository name
}
```

**Use Cases:**
- Check CI/CD pipelines
- Monitor workflow status
- Understand automation

#### 5.2 `github_list_workflow_runs`
**Description:** List runs of a specific workflow.

**Parameters:**
```typescript
{
  owner: string,        // Repository owner
  repo: string,         // Repository name
  workflow_id?: number  // Workflow ID (optional)
  per_page?: number,    // Results per page
  page?: number         // Page number
}
```

**Use Cases:**
- Check workflow execution
- Monitor CI/CD status
- Analyze failures

#### 5.3 `github_cancel_workflow_run`
**Description:** Cancel a running workflow run.

**Parameters:**
```typescript
{
  owner: string,        // Repository owner
  repo: string,         // Repository name
  run_id: number        // Workflow run ID
}
```

**Use Cases:**
- Stop failed workflows
- Save compute resources
- Control deployment

### 6. **Label/Tag Operations** 🏷️

#### 6.1 `github_list_labels`
**Description:** List labels in a repository.

**Parameters:**
```typescript
{
  owner: string,        // Repository owner
  repo: string         // Repository name
}
```

**Use Cases:**
- Check issue labels
- Understand categorization
- Find label themes

#### 6.2 `github_create_label`
**Description:** Create a new label.

**Parameters:**
```typescript
{
  owner: string,        // Repository owner
  repo: string,         // Repository name
  name: string,         // Label name
  color: string,        // Hex color (e.g., "FF5733")
  description?: string  // Label description
}
```

**Use Cases:**
- Create custom labels
- Organize issues
- Improve project management

#### 6.3 `github_delete_label`
**Description:** Delete a label from a repository.

**Parameters:**
```typescript
{
  owner: string,        // Repository owner
  repo: string,         // Repository name
  name: string          // Label name
}
```

**Use Cases:**
- Remove unused labels
- Clean up organization
- Simplify categorization

### 7. **Security Operations** 🔒

#### 7.1 `github_list_secrets`
**Description:** List repository secrets.

**Parameters:**
```typescript
{
  owner: string,        // Repository owner
  repo: string         // Repository name
}
```

**Use Cases:**
- Check secrets
- Audit security
- Manage credentials

#### 7.2 `github_add_secret`
**Description:** Add a new repository secret.

**Parameters:**
```typescript
{
  owner: string,        // Repository owner
  repo: string,         // Repository name
  name: string,         // Secret name
  value: string         // Secret value
}
```

**Use Cases:**
- Add API keys
- Configure environments
- Manage secrets

#### 7.3 `github_remove_secret`
**Description:** Remove a repository secret.

**Parameters:**
```typescript
{
  owner: string,        // Repository owner
  repo: string,         // Repository name
  name: string          // Secret name
}
```

**Use Cases:**
- Remove old secrets
- Clean up credentials
- Security cleanup

## Benefits

### 1. **Improved Developer Experience**
- More comprehensive toolset
- Easier to automate workflows
- Better integration with development practices

### 2. **Enhanced Automation**
- Full codebase management
- Issue tracking improvements
- CI/CD monitoring

### 3. **Better Security**
- Secrets management
- Access control review
- Audit capabilities

### 4. **Scalability**
- Handle large repositories
- Efficient pagination
- Organized tool categories

## Implementation Priority

### **High Priority** 🔴
1. `github_delete_file`
2. `github_list_directory`
3. `github_search_code`
4. `github_list_commits`

### **Medium Priority** 🟡
1. `github_list_comments`
2. `github_update_issue`
3. `github_list_labels`
4. `github_list_languages`

### **Low Priority** 🟢
1. `github_list_teams`
2. `github_list_collaborators`
3. `github_cancel_workflow_run`

## Testing Strategy

For each new tool:
1. Unit tests for input validation
2. Integration tests with GitHub API
3. Error handling tests
4. Edge case tests
5. Documentation updates

## Documentation Needs

1. Tool descriptions
2. Parameter documentation
3. Usage examples
4. Best practices guide
5. Security guidelines

## Security Considerations

1. **Secret Management:**
   - Never log secret values
   - Validate permissions before access
   - Audit secret operations

2. **Authorization:**
   - Respect repository permissions
   - Validate user roles
   - Handle permission errors gracefully

3. **Rate Limiting:**
   - Implement pagination
   - Respect GitHub API limits
   - Add retry logic for rate limits

## Dependencies

The plugin uses:
- `httpx` or `node-fetch` for API calls
- `dotenv` for configuration
- `mcp/types` for SDK integration

## Backward Compatibility

- All new tools are additive
- No breaking changes to existing tools
- New tools can be optionally enabled

## Conclusion

This enhancement will make the `github-dev-assistant` plugin a **complete GitHub automation solution**, covering all major operations. This will significantly improve developer productivity and enable powerful automation workflows.

---

**Created by:** GitHub Dev Assistant
**Status:** Enhancement Proposal
**Version:** 1.0
**Date:** 2026-03-24

GitHub Dev Assistant Plugin - Enhancement Proposal #35

Description

Summary

Current State

Proposed Enhancements

1. File Operations 🔧

1.1 github_delete_file

1.2 github_list_directory

1.3 github_search_code

1.4 github_download_file

2. Issue/PR Operations 📝

2.1 github_list_comments

2.2 github_update_issue

2.3 github_reopen_issue

2.4 github_assign_issue

3. Commit Operations 📊

3.1 github_list_commits

3.2 github_get_commit

3.3 github_list_pull_requests_reviews

4. Repository Operations 📦

4.1 github_list_languages

4.2 github_list_teams

4.3 github_list_collaborators

5. Workflow Operations ⚙️

5.1 github_list_workflows

5.2 github_list_workflow_runs

5.3 github_cancel_workflow_run

6. Label/Tag Operations 🏷️

6.1 github_list_labels

6.2 github_create_label

6.3 github_delete_label

7. Security Operations 🔒

7.1 github_list_secrets

7.2 github_add_secret

7.3 github_remove_secret

Benefits

1. Improved Developer Experience

2. Enhanced Automation

3. Better Security

4. Scalability

Implementation Priority

High Priority 🔴

Medium Priority 🟡

Low Priority 🟢

Testing Strategy

Documentation Needs

Security Considerations

Dependencies

Backward Compatibility

Conclusion

Metadata

Metadata

Assignees

Labels

Projects

Milestone

Relationships

Development

Issue actions

1.1 `github_delete_file`

1.2 `github_list_directory`

1.3 `github_search_code`

1.4 `github_download_file`

2.1 `github_list_comments`

2.2 `github_update_issue`

2.3 `github_reopen_issue`

2.4 `github_assign_issue`

3.1 `github_list_commits`

3.2 `github_get_commit`

3.3 `github_list_pull_requests_reviews`

4.1 `github_list_languages`

4.2 `github_list_teams`

4.3 `github_list_collaborators`

5.1 `github_list_workflows`

5.2 `github_list_workflow_runs`

5.3 `github_cancel_workflow_run`

6.1 `github_list_labels`

6.2 `github_create_label`

6.3 `github_delete_label`

7.1 `github_list_secrets`

7.2 `github_add_secret`

7.3 `github_remove_secret`