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):

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.

As MCP Server

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

.mcp.json (MCP server configuration - can be committed):

{
  "mcpServers": {
    "auto-fix-workflow": {
      "command": "npx",
      "args": ["auto-fix-workflow"],
      "env": {}
    }
  }
}

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

# 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

GitHub Tools

| 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 |

Asana Tools

| 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 |

Git Tools (Internal)

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) |

Workflow Tools (Internal)

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

Init Command

Initialize project configuration:

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

Triage Command

Analyze Asana tasks and create GitHub issues:

# 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 <mode> | -m | enum | interactive | Mode: interactive, batch, single | | --dry-run | -d | boolean | false | Preview without making changes | | --project <gid> | -p | string | - | Asana project GID | | --section <gid> | -s | string | - | Asana section GID | | --priority <level> | -P | enum | - | Filter: critical, high, medium, low | | --limit <n> | -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.

Autofix Command

Execute automated fix workflow:

# 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 <nums> | string | - | Comma-separated issue numbers | | --group-by <strategy> | enum | component | Grouping: component, file, label, type, priority | | --max-parallel <n> | number | 3 | Maximum parallel worktrees (1-10) | | --dry-run | boolean | false | Preview without making changes | | --max-retries <n> | number | 3 | Maximum retry attempts per group (1-10) | | --labels <labels> | string | - | Filter issues by labels (comma-separated) | | --exclude-labels <labels> | string | - | Exclude issues with these labels | | --base-branch <name> | string | autofixing | Base branch for PRs | | --verbose | boolean | false | Enable verbose output | | --config <path> | string | - | Path to config file |

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

Environment Variables

Required

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

Optional - GitHub

| 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 |

Optional - Asana

| 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 |

Optional - Worktree

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

Optional - Checks

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

Optional - Logging

| 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

GitHub Token

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

Asana Token

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

Example 1: Triage Asana Tasks

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

Example 2: Auto-Fix Issues

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.

Example 3: Fix Specific Issues

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

Example 4: Dry Run Mode

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

# Install dependencies
npm install

# Build
npm run build

# Run tests
npm test

# Type check
npm run type-check

# Lint
npm run lint

Spec-Driven Development

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

# 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.

Branch Strategy

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