auto-fix-workflow


English | 한국어

MCP (Model Context Protocol) server for automated GitHub issue management and code fixing workflows.

Features

- GitHub Integration: Manage issues, pull requests, and labels
- Asana Integration: Sync tasks and analyze for auto-fix suitability
- Git Worktree Management: Isolated development environments for parallel fixes
- Code Quality Checks: Run typecheck, lint, and tests with configurable order
- Workflow Orchestration: Group issues, plan fix strategies, create PRs
- AI-Powered Analysis: Claude CLI integration for automated code analysis and fix generation with budget tracking, intelligent model fallback (opus → sonnet → haiku), retry logic with exponential backoff, structured JSON schema validation, and tool-based security (read-only for analysis, edit-only for fixes)

Quick Start

Run the init command to configure your project (no installation required):

``bash
npx auto-fix-workflow init
`

This will:
- Create .mcp.json with MCP server configuration
- Create .auto-fix.yaml with workflow settings and tokens
- Add .auto-fix.yaml to .gitignore for security
- Create .github/ISSUE_TEMPLATE/auto-fix-issue.yml for standardized issue creation
- Create .github/PULL_REQUEST_TEMPLATE.md for PR standardization
- Create autofixing branch and push to origin

Options:
- -n, --non-interactive: Read tokens from GITHUB_TOKEN and ASANA_TOKEN environment variables
- -f, --force: Overwrite existing configuration files
- -s, --skip-validation: Skip token validation steps

For detailed setup instructions, see Setup Guide.

$3

After running npx auto-fix-workflow init, the following files are created:

.mcp.json (MCP server configuration - can be committed):
`json
{
"mcpServers": {
"auto-fix-workflow": {
"command": "npx",
"args": ["auto-fix-workflow"],
"env": {}
}
}
}
`

.auto-fix.yaml (workflow settings + tokens - gitignored):
`yaml


Tokens (this file is added to .gitignore)

tokens:
github: "your-github-token"
asana: "your-asana-token"

github:
owner: your-org
repo: your-repo
baseBranch: main

asana:
projectId: "1234567890"
workspaceId: "0987654321"

checks:
order:
- typecheck
- lint
- test
timeout: 300000
failFast: true

worktree:
baseDir: .worktrees
cleanupOnSuccess: true

ai:
budgetPerIssue: 1.0 # Maximum USD per issue
budgetPerSession: 100.0 # Maximum USD per session
preferredModel: opus # Primary model (opus|sonnet|haiku)
fallbackModel: sonnet # Fallback when budget tight
minConfidence: 0.5 # Minimum confidence to proceed
`

Available Tools

$3

| Tool | Description |
|------|-------------|
| get_github_issue | Fetch issue details by number |
| list_issues | List and filter repository issues |
| github_create_issue | Create new issues with labels |
| update_github_issue | Update issue state and content |
| github_create_pr | Create pull requests |
| add_issue_progress_comment | Add progress comment to an issue |

$3

| Tool | Description |
|------|-------------|
| asana_get_task | Fetch task details |
| asana_list_tasks | List project tasks |
| asana_update_task | Update task status |
| asana_analyze_task | Analyze task for auto-fix suitability |

$3

These tools are used internally by the autofix pipeline and are not directly exposed via MCP:

| Tool | Description |
|------|-------------|
| git_worktree | Unified worktree management (create/remove/list via action parameter) |

$3

These tools are used internally by the autofix pipeline:

| Tool | Description |
|------|-------------|
| group_issues | Group related issues by component/file/label |
| run_checks | Execute typecheck, lint, test in worktree |

> Note: triage and autofix are CLI commands, not MCP tools. See Commands for usage.

Commands

$3

Initialize project configuration:

`bash
npx auto-fix-workflow init
`

Options:
- -n, --non-interactive: Read tokens from GITHUB_TOKEN and ASANA_TOKEN environment variables
- -f, --force: Overwrite existing configuration files
- -s, --skip-validation: Skip token validation steps

$3

Analyze Asana tasks and create GitHub issues:

`bash


Interactive mode (select tasks from UI)

npx auto-fix-workflow triage

Batch mode (process all tasks automatically)

npx auto-fix-workflow triage --mode batch

Single task by GID

npx auto-fix-workflow triage 1234567890

Dry run with project filter

npx auto-fix-workflow triage --dry-run --project 1234567890
`

Options:
| Flag | Short | Type | Default | Description |
|------|-------|------|---------|-------------|
| --mode | -m | enum | interactive | Mode: interactive, batch, single |
| --dry-run | -d | boolean | false | Preview without making changes |
| --project | -p | string | - | Asana project GID |
| --section | -s | string | - | Asana section GID |
| --priority | -P | enum | - | Filter: critical, high, medium, low |
| --limit | -l | number | - | Maximum tasks to process |
| --yes | -y | boolean | false | Skip confirmation prompts |
| --verbose | -v | boolean | false | Enable verbose output |

Positional argument: Task GID (numeric) for single-task processing.

$3

Execute automated fix workflow:

`bash


Process all auto-fix labeled issues

npx auto-fix-workflow autofix --all

Fix specific issues

npx auto-fix-workflow autofix --issues 123,456

Dry run (preview only)

npx auto-fix-workflow autofix --all --dry-run

Custom grouping and parallelism

npx auto-fix-workflow autofix --all --group-by file --max-parallel 5
`

Options:
| Flag | Type | Default | Description |
|------|------|---------|-------------|
| --all | boolean | false | Process all auto-fix labeled issues |
| --issues | string | - | Comma-separated issue numbers |
| --group-by | enum | component | Grouping: component, file, label, type, priority |
| --max-parallel | number | 3 | Maximum parallel worktrees (1-10) |
| --dry-run | boolean | false | Preview without making changes |
| --max-retries | number | 3 | Maximum retry attempts per group (1-10) |
| --labels | string | - | Filter issues by labels (comma-separated) |
| --exclude-labels | string | - | Exclude issues with these labels |
| --base-branch | string | autofixing | Base branch for PRs |
| --verbose | boolean | false | Enable verbose output |
| --config | string | - | Path to config file |

> Note: --all and --issues are mutually exclusive.

Environment Variables

$3

| Variable | Description |
|----------|-------------|
| GITHUB_TOKEN | GitHub Personal Access Token |

$3

| Variable | Default | Description |
|----------|---------|-------------|
| GITHUB_OWNER | - | Repository owner (can also set in .auto-fix.yaml) |
| GITHUB_REPO | - | Repository name |
| GITHUB_API_URL | - | Custom GitHub API URL (for Enterprise) |
| GITHUB_DEFAULT_BRANCH | main | Default branch name |
| AUTOFIX_LABEL | auto-fix | Label for auto-fix target issues |
| AUTOFIX_SKIP_LABEL | auto-fix-skip | Label to exclude issues |

$3

| Variable | Description |
|----------|-------------|
| ASANA_TOKEN | Asana Personal Access Token (required for triage) |
| ASANA_DEFAULT_PROJECT_GID | Default Asana project GID |
| ASANA_TRIAGE_SECTION | Section name to scan for triage |
| ASANA_PROCESSED_SECTION | Section name for processed tasks |
| ASANA_SYNCED_TAG | Tag name for synced tasks |
| TRIAGE_MAX_BATCH_SIZE | Maximum batch size for triage |

$3

| Variable | Default | Description |
|----------|---------|-------------|
| WORKTREE_BASE_DIR | .worktrees | Base directory for worktrees |
| WORKTREE_MAX_CONCURRENT | 3 | Maximum concurrent worktrees |
| WORKTREE_PREFIX | autofix- | Branch name prefix |

$3

| Variable | Description |
|----------|-------------|
| TEST_COMMAND | Custom test command (auto-detected from package.json) |
| TYPECHECK_COMMAND | Custom typecheck command |
| LINT_COMMAND | Custom lint command |

$3

| Variable | Default | Description |
|----------|---------|-------------|
| AUTO_FIX_CONFIG | .auto-fix.yaml | Custom config file path |
| LOG_LEVEL | info | Log level: trace, debug, info, warn, error, fatal |
| LOG_PRETTY | true (dev) | Enable pretty log formatting |
| LOG_REDACT | true | Redact sensitive data in logs |
| NO_COLOR | - | Disable colored output |

API Token Scopes

$3

Create a Personal Access Token with the following scopes:

| Scope | Required | Description |
|-------|----------|-------------|
| repo | Yes | Full control of private repositories |
| public_repo | Yes (for public repos) | Access public repositories |
| read:org | Optional | Read org membership (for org repos) |

For fine-grained tokens (recommended):
- Repository access: Select specific repositories
- Permissions:
- Issues: Read and write
- Pull requests: Read and write
- Contents: Read and write
- Metadata: Read-only

$3

Create a Personal Access Token in Asana Developer Console:

| Permission | Description |
|------------|-------------|
| Read tasks | View task details and list tasks |
| Write tasks | Update task status, add comments |
| Read projects | Access project information |

Workflow Examples

$3

Analyze Asana tasks and convert them to GitHub Issues:

`
User: /triage

Claude: 🔍 Scanning Asana tasks in "To Triage" section...

📋 Found 3 tasks to analyze:

Task #12345: "Save button error"
├── ✅ Reproduction steps: Clear
├── ✅ Error message: TypeError - id property access error
├── ✅ Related file: src/components/Editor.tsx (handleSave function)
├── ✅ Root cause: document object accessed before initialization
└── 🎫 GitHub Issue #45 created

Task #12346: "App is slow"
├── ❌ Reproduction steps: Unclear
├── ❌ Specific symptoms: Unclear
└── 📝 Added "needs-more-info" tag to Asana

Task #12347: "Export PDF fails"
├── ✅ Reproduction steps: Clear
├── ✅ Error message: Found
└── 🎫 GitHub Issue #46 created

📊 Results:
- ✅ Converted: 2 tasks
- ⏳ Needs more info: 1 task
`

$3

Automatically fix GitHub issues with the auto-fix label:

`
User: /autofix

Claude: 🔍 Fetching issues with auto-fix label...

📋 Pending Issues (5):

Group 1: canvas-core (3 issues)
- #123: TypeError in handleSave
- #124: Null reference in renderPage
- #125: Missing validation in exportPDF

Group 2: ui (1 issue)
- #130: Button disabled state not working

Group 3: editor (1 issue)
- #132: Keyboard shortcut conflict

Select issues to process:
1. All issues (5 issues, 3 worktrees)
2. Select specific groups
3. Select specific issues

User: 1

Claude:
🚀 Starting auto-fix...

[Worktree 1/3] fix/issue-123-124-125 (canvas-core)
├── 📁 Worktree created
├── 🔍 Analyzing issues...
├── ✏️ Applying fixes...
├── 🧪 Running checks...
│ ├── ✅ typecheck (passed)
│ ├── ✅ lint (passed)
│ └── ✅ test (passed)
├── 📤 PR #201 created
└── 🧹 Worktree cleaned up

[Worktree 2/3] fix/issue-130 (ui)
├── 📁 Worktree created
├── 🔍 Analyzing issue...
├── ✏️ Applying fix...
├── 🧪 Running checks...
│ ├── ✅ typecheck (passed)
│ ├── ✅ lint (passed)
│ └── ✅ test (passed)
├── 📤 PR #202 created
└── 🧹 Worktree cleaned up

[Worktree 3/3] fix/issue-132 (editor)
├── 📁 Worktree created
├── 🔍 Analyzing issue...
├── ✏️ Applying fix...
├── 🧪 Running checks...
│ ├── ✅ typecheck (passed)
│ ├── ❌ test (failed - shortcut conflict with existing binding)
│ └── 🔄 Retry 1/3...
├── ✏️ Adjusting fix...
├── 🧪 Running checks...
│ ├── ✅ typecheck (passed)
│ ├── ✅ lint (passed)
│ └── ✅ test (passed)
├── 📤 PR #203 created
└── 🧹 Worktree cleaned up

📊 Results:
- ✅ Success: 5 issues (PR #201, #202, #203)
- ❌ Failed: 0 issues

All PRs target the 'autofixing' branch for manual review.
`

$3

Fix only specific issues:

`
User: /autofix --issues 123,124

Claude:
🚀 Processing issues #123, #124...

[Worktree] fix/issue-123-124
├── 📁 Worktree created
├── 🔍 Analyzing 2 issues...
├── ✏️ Applying fixes...
├── 🧪 Running checks... ✅ All passed
├── 📤 PR #204 created (Closes #123, #124)
└── 🧹 Worktree cleaned up

📊 Results:
- ✅ Success: 2 issues
- PR: https://github.com/your-org/your-repo/pull/204
`

$3

Preview what would happen without making changes:

`
User: /autofix --dry-run

Claude:
🔍 [DRY RUN] Analyzing auto-fix issues...

📋 Would process 3 issues:

Group: canvas-core
├── #123: TypeError in handleSave
│ └── Fix: Add null check for document object
├── #124: Null reference in renderPage
│ └── Fix: Initialize page state before render
└── #125: Missing validation in exportPDF
└── Fix: Add input validation for PDF options

Planned actions:
1. Create worktree: fix/issue-123-124-125
2. Apply 3 fixes
3. Run checks: typecheck, lint, test
4. Create PR targeting 'autofixing' branch
5. Clean up worktree

No changes made (dry run mode).
`

Development

`bash


Install dependencies

npm install

Build

npm run build

Run tests

npm test

Type check

npm run type-check

Lint

npm run lint
`

$3

This project was developed using sdd-tool for spec management.

`bash


Validate all specs

npx sdd-tool validate

List specs

npx sdd-tool list
`

Specs are located in .sdd/specs/ directory.

Autofix Pipeline

The autofix command processes issues through a 9-stage pipeline:

`
Stage 1: Worktree Create → Create isolated Git worktree
Stage 2: AI Analysis → Analyze issues with Claude CLI
Stage 3: AI Fix → Generate code fixes with Claude CLI
Stage 4: Install Deps → Install dependencies (npm install)
Stage 5: Quality Checks → Run typecheck → lint → test
Stage 6: Commit & Push → Commit changes and push branch
Stage 7: Create PR → Create pull request → autofixing branch
Stage 8: Update Issues → Add PR link comment to issues
Stage 9: Cleanup → Remove worktree
`

Issues are grouped by strategy (component, file, label, etc.) and processed in parallel using Git worktrees. Failed checks trigger automatic retry with AI-adjusted fixes.

$3

`
main ◀─────────────── (manual merge)
└── autofixing ◀─── (PR target)
├── fix/issue-123
├── fix/issue-124-125 (grouped)
└── fix/issue-126
`

Architecture

`
src/
├── common/ # Shared types, utilities, logging
├── github/ # GitHub API integration
├── asana/ # Asana API integration
├── git/ # Git worktree management
├── checks/ # Code quality checks
├── analyzer/ # Task analysis and code location
├── workflow/ # Issue grouping and fix strategies
├── commands/ # CLI commands (triage, autofix)
└── index.ts # MCP server entry point
``

Documentation

- Setup Guide - Initial setup for GitHub, Asana, and Sentry integration

License

MIT