Claudette MCP Server

MCP server for Claudette IDE - providing Claude with 50+ comprehensive workspace management tools.

v2.0.0 - Major release with self-healing git operations, conflict recovery tools, smart retry mechanism, and improved test runner. Claude should NEVER need to run manual git commands.

What's New in v2.0.0

Self-Healing Git Operations

• sync_branch now auto-detects conflicts via file markers (not string matching)
• Auto-aborts failed operations to keep repo in clean state
• Returns detailed conflict info with suggested actions

New Conflict Recovery Tools

• get_conflict_status - Check if repo is mid-merge/rebase, list conflicted files
• abort_conflict - Abort merge/rebase/cherry-pick to recover
• stage_and_continue - Continue operation after resolving conflicts

Smart Retry Mechanism

• retry_workflow_step - Retry failed step without re-running entire workflow
• Preserves passed steps (types, lint, etc.) - more efficient than re-triggering

Improved Workflow Recommendations

• Detects conflict state (blocks workflow, suggests resolution)
• Detects failed workflow state (recommends retry over re-trigger)
• Detects behind-remote state (warns push will fail)

Test Runner Improvements

• Now reads test commands from package.json scripts
• Respects project's ESM configuration (--experimental-vm-modules)
• Clears stale test results (>5 min old) before running

Installation

npx @azerate/claudette-mcp

Or install globally:

npm install -g @azerate/claudette-mcp

Setup

Option 1: Add via Claude Code CLI

claude mcp add claudette -- npx @azerate/claudette-mcp

Option 2: Add to .mcp.json (project-level)

Create .mcp.json in your project root:

{
  "mcpServers": {
    "claudette": {
      "type": "stdio",
      "command": "npx",
      "args": ["@azerate/claudette-mcp"]
    }
  }
}

Option 3: Add to Claude Code settings

Add to ~/.claude.json:

"mcpServers": {
  "claudette": {
    "type": "stdio",
    "command": "npx",
    "args": ["@azerate/claudette-mcp"]
  }
}

Available Tools

Code Quality & Errors

| Tool | Description | |------|-------------| | get_errors | Get TypeScript compilation errors for the workspace | | run_tests | Run Jest tests and return results | | get_test_results | Get the latest test results | | run_benchmarks | Run performance benchmarks (tinybench/vitest) | | get_benchmark_results | Get the latest benchmark results |

Code Crawlers (Bug Detection)

| Tool | Description | |------|-------------| | crawl_quality | Scan for code quality issues: console.log, empty catches, TODO/FIXME, any types, debugger statements, magic numbers | | crawl_security | Scan for security issues: hardcoded secrets, SQL injection, XSS vulnerabilities, unsafe eval, CORS issues | | crawl_react | Scan for React issues: index as key, inline functions/objects, hook violations, missing dependencies | | crawl_typescript | Scan for TypeScript issues: any types, type assertions, non-null assertions, broad types |

Logger Setup

| Tool | Description | |------|-------------| | setup_logger | Create a pino-based logger utility with best practices (structured logging, pretty output in dev, JSON in prod) | | crawl_console_logs | Scan for console.log/warn/error statements and provide migration suggestions to use proper logging |

Git & Changes

| Tool | Description | |------|-------------| | get_changes | Get pending git changes (modified, added, deleted files) | | get_branch_info | Get current branch, behind/ahead status, sync state | | get_branch_pr_status | Check if current branch has an open/merged/closed PR | | create_branch | Create a new feature branch from main/master | | sync_branch | Self-healing - Rebase/merge with main, auto-aborts on conflict |

Git Conflict Recovery (NEW in v2.0.0)

| Tool | Description | |------|-------------| | get_conflict_status | Check if repo is in conflict state (mid-merge/rebase), list conflicted files | | abort_conflict | Abort current merge/rebase/cherry-pick to recover to clean state | | stage_and_continue | Stage resolved files and continue the operation |

Checkpoints (Git Stash Snapshots)

| Tool | Description | |------|-------------| | get_checkpoints | List saved checkpoints (git stash snapshots) | | create_checkpoint | Create a checkpoint before risky changes | | restore_checkpoint | Restore workspace to a previous checkpoint | | delete_checkpoint | Delete a checkpoint permanently |

Workflow Automation

| Tool | Description | |------|-------------| | get_workflow_status | Get current workflow pipeline status | | get_workflow_recommendation | Smart recommendation - analyzes branch, PR status, conflicts, and changes to suggest the best next action | | trigger_workflow | Start the workflow (lint, types, tests, coverage, benchmarks) | | retry_workflow_step | NEW - Retry a failed step without re-running passed steps | | generate_commit_message | Generate a commit message from changes | | approve_commit | Stage and commit with the provided message | | approve_push | Push committed changes to remote | | approve_write_tests | Mark the write tests step as complete | | create_pr | Create a pull request using gh CLI | | approve_code_review | Complete code review and merge the PR |

Project Memory

| Tool | Description | |------|-------------| | get_memory | Get project memory notes | | add_memory | Add a note to project memory | | clear_memory | Clear all project memory notes | | delete_memory | Delete specific notes by index | | replace_memory | Replace all memory with new notes (for consolidation) |

Scripts & Automation

| Tool | Description | |------|-------------| | list_scripts | List npm scripts and their status (running/stopped) | | run_script | Start an npm script (auto-launches Chrome for dev scripts) | | stop_script | Stop a running script | | get_console_output | Get console output from a running or recently run script | | check_quick_actions | Check for pending UI-triggered actions |

Refactoring

| Tool | Description | |------|-------------| | create_refactor_plan | Analyze workspace and create verified refactoring plan with test baseline | | get_refactor_plan | Get the current refactor plan | | get_next_refactor_step | Get the next uncompleted step | | verify_refactor | Run tests and compare to baseline to catch regressions | | complete_refactor_step | Mark a step as completed | | complete_refactor | Finish refactoring and delete plan |

Smart Workflow Recommendations

Before starting a workflow, always call get_workflow_recommendation to get intelligent guidance:

get_workflow_recommendation(workspace_path="/path/to/project")

The tool analyzes your current state and recommends the best action:

| Recommended Action | When | What to Do | |-------------------|------|------------| | resolve_conflicts | Repo is mid-merge/rebase | Use get_conflict_status, then abort_conflict or resolve manually | | retry_failed_step | Workflow stopped at failed step | Fix issue, then use retry_workflow_step (more efficient than re-trigger) | | sync_branch_first | Branch is behind remote | Use sync_branch before workflow to avoid push failures | | start_workflow | Normal flow, no blockers | Proceed with trigger_workflow | | create_feature_branch | On main with requireFeatureBranch enabled | Use create_branch first | | add_to_existing_pr | On feature branch with open PR | Your commits will update the existing PR | | switch_to_main | PR was merged, branch is stale | Switch to main, pull, create new branch | | create_new_branch | PR was closed (not merged) | Create a fresh branch or reopen PR | | no_changes | No uncommitted changes | Nothing to commit yet |

Each recommendation includes:

• reason: Why this action is recommended
• suggestion: What you should do (trust this!)
• consequences: What will happen if you proceed

Self-Healing Git Operations

How sync_branch Works (v2.0.0)

When you call sync_branch, it now:

1. Checks for existing conflicts - Blocks if repo is already mid-merge/rebase
2. Performs rebase/merge - Syncs with main branch
3. Auto-detects conflicts - Uses file markers, not error message parsing
4. Auto-aborts on conflict - Returns repo to clean state
5. Returns detailed info - Lists conflicted files, suggests next actions

Example output when conflicts occur:

❌ Sync failed: rebase conflict detected and auto-aborted. Repository is back to clean state.

📁 Conflicted files:
   • src/components/Header.tsx
   • src/utils/api.ts

✅ Auto-recovery: Repository returned to clean state.

💡 Suggested actions:
   • The rebase was aborted to preserve your work.
   • Review the conflicting files listed above.
   • Consider making smaller, incremental changes that won't conflict.
   • Try sync_branch again after resolving the underlying issue.

Workflow Pipeline

The workflow feature provides a 10-step guided development process with best-practice Git support.

Failure Handling (v2.0.0)

When any check fails, you now have two options:

1. Fix and Retry (Recommended):

   • Fix the failing code/tests
   • Use retry_workflow_step to re-run only the failed step
   • Previously passed steps are preserved

2. Full Re-trigger:

   • Use trigger_workflow to restart everything
   • All steps run again from the beginning

trigger_workflow()
       |
       v
[AUTOMATIC CHECKS]
  1. Type checking (tsc --noEmit)
  2. Lint/Format (eslint --fix)
  3. Run tests
  4. Coverage analysis (files needing tests)
  5. Benchmarks (optional)
       |
       v
[HUMAN GATES]
  6. Write Tests (if coverage found gaps)
  7. Commit (approve_commit)
  8. Push (approve_push)
  9. Create PR (skipped if on main)
  10. Code Review (approve_code_review)

Branch Management

Best practice: Work on feature branches, not directly on main.

# Check current branch status
get_branch_info(workspace_path="/path/to/project")

# Create a feature branch
create_branch(workspace_path="/path/to/project", branch_name="feature/my-feature")

# Sync with latest main (rebase) - self-healing!
sync_branch(workspace_path="/path/to/project", method="rebase")

The workflow enforces feature branch usage by default (requireFeatureBranch: true). Toggle this in the UI or set in .claudette/workflow-config.json.

Logger Setup Example

Set up professional logging in any project:

# 1. Scan for console.log statements
crawl_console_logs(workspace_path="/path/to/project")

# 2. Set up pino logger (installs pino & pino-pretty)
setup_logger(workspace_path="/path/to/project")

# 3. The logger is created at src/utils/logger.ts

Usage after setup:

import { logger } from './utils/logger'

// Structured logging
logger.info({ userId: 123 }, 'User logged in')
logger.error({ err }, 'Failed to process request')
logger.debug({ data }, 'Debug info')

Example Usage

# Check for errors
get_errors(workspace_path="/path/to/project")

# Scan for code quality issues
crawl_quality(workspace_path="/path/to/project")

# Get smart recommendation before workflow
get_workflow_recommendation(workspace_path="/path/to/project")

# Run full workflow
trigger_workflow(workspace_path="/path/to/project")

# Check workflow status
get_workflow_status(workspace_path="/path/to/project")

# If a step failed, fix and retry just that step
retry_workflow_step(workspace_path="/path/to/project")

# After checks pass, commit
generate_commit_message(workspace_path="/path/to/project")
approve_commit(workspace_path="/path/to/project", message="Add new feature")

# Push changes
approve_push(workspace_path="/path/to/project")

Requirements

• Node.js 18+
• Claudette IDE server running on port 52001 (for full functionality)

License

MIT