atxtechbro / atxtechbro/dotfiles
Refine read/write tool classification based on usage experience
- Dominant language
- Shell
- Stars
- 27
- Forks
- 2
- PR merge metrics
- No merged PRs in 30d
Description
## Problem
The initial read/write separation of MCP tools was overly conservative, resulting in safe read-only operations being incorrectly classified as "write" tools. This creates unnecessary permission friction during normal usage.
**Example**: `get_issue` is currently in `github-write` but is clearly a safe read-only operation that should be in `github-read`.
## Evidence of Over-Classification
From actual usage, Claude is prompting for permission on clearly safe operations:
```
Tool use: github-write:get_issue(owner: "atxtechbro", repo: "dotfiles", issue_number: 647)
Get details of a specific issue in a GitHub repository.
Do you want to proceed?
```
This indicates our classification was too aggressive in quarantining safe operations.
## Proposed Review Process
### 1. Survey All GitHub Tools
Review every tool in both `github-read` and `github-write` to ensure proper classification:
**Clearly Read-Only (should be in github-read):**
- All `get_*` operations (get_issue, get_pull_request, get_commit, etc.)
- All `list_*` operations (list_issues, list_pull_requests, etc.)
- All `search_*` operations (search_code, search_issues, etc.)
- `download_*` operations (download_workflow_run_artifact, etc.)
- Notification read operations (get_notification_details, etc.)
**Borderline Cases to Evaluate:**
- `dismiss_notification` - Modifies notification state but harmless
- `mark_all_notifications_read` - Changes read status but non-destructive
- `manage_notification_subscription` - Changes subscription but non-destructive
**Clearly Write/Destructive (stay in github-write):**
- All `create_*` operations
- All `update_*` operations
- All `delete_*` operations
- `merge_pull_request`, `push_files`
- Workflow control (`run_workflow`, `cancel_workflow_run`, etc.)
### 2. Survey All Git Tools
Apply the same review to git tools:
**Likely Misclassified (should be git-read):**
- `git_fetch` - Fetches remote changes but doesn't modify working directory
- `git_remote` with list action - Just shows remote info
- `git_branch_delete` with remote=false - Deletes local branches only
**Borderline Cases:**
- `git_stash` - Saves current work but doesn't lose data
- Operations that modify .git but not working directory
### 3. Updated Classification Principles
**Read-Only Criteria:**
- Does NOT modify repository content
- Does NOT modify working directory
- Does NOT push changes to remote
- Does NOT delete or destroy data
- May modify local git metadata (.git directory) if non-destructive
**Write/Destructive Criteria:**
- Modifies repository content or working directory
- Pushes changes to remote repositories
- Deletes or destroys data
- Could cause data loss if misused
- Creates or modifies files outside the repository
## Implementation Plan
1. **Audit Phase**: Systematically review all tools in both servers
2. **Reclassification**: Move misclassified tools to appropriate servers
3. **Testing**: Verify the changes don't break existing workflows
4. **Documentation**: Update any docs that reference specific tool locations
## Success Criteria
- Safe read operations don't require permission prompts
- Genuinely destructive operations still require explicit permission
- Classification follows consistent, logical principles
- Reduced friction for common read-heavy workflows
This follows the **versioning mindset** principle - iterating on our initial implementation based on real usage experience rather than theoretical classification.
Labels: enhancement, security, mcp
Contributor guide
No contributing guide indexed for this repository
Research direction
Start by locating the github-read, github-write, and git tool definitions, then survey each operation against the read-only and write criteria in the issue. Reclassify the agreed tools, check related documentation, and verify that safe operations no longer prompt while destructive operations still do.
Written by the indexing model from the issue text.
Assessment
- Tech stack
- git, github, shell
- Domain
- security, tooling
- Issue type
- Feature
- Difficulty
- 4/5
- Estimated time
- 3-5 days
- Activity status
- Stale
- Clarity
- Mostly clear
- Newbie friendliness
- 35/100