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

Asana Tools

Git Tools (Internal)

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

Workflow Tools (Internal)

These tools are used internally by the autofix pipeline:

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:

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:

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

Environment Variables

Required

Optional - GitHub

Optional - Asana

Optional - Worktree

Optional - Checks

Optional - Logging

API Token Scopes

GitHub Token

Create a Personal Access Token with the following scopes:

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:

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