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:

• --non-interactive: Read tokens from GITHUB_TOKEN and ASANA_TOKEN environment variables
• --force: Overwrite existing configuration files
• --skip-validation: Skip token validation

For detailed setup instructions, see Setup Guide.

Quick Start

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

Check Tools

Workflow Tools

Commands

Init Command

Initialize project configuration:

npx auto-fix-workflow init

Options:

• --non-interactive: Read tokens from environment variables
• --force: Overwrite existing files
• --skip-validation: Skip token validation

Triage Command

Analyze and prioritize issues for processing:

npx auto-fix-workflow triage --label auto-fix --limit 10

Options:

• --label: Filter by label
• --state: Filter by state (open/closed)
• --limit: Maximum issues to process
• --dry-run: Preview without making changes

Autofix Command

Execute automated fix workflow:

npx auto-fix-workflow autofix --issues 1,2,3

Options:

• --issues: Comma-separated issue numbers
• --group-by: Grouping strategy (component/file/none)
• --fail-fast: Stop on first failure
• --dry-run: Preview operations

Environment Variables

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.

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