Smart Agent Workflow MCP

The only MCP that enforces tests before merge. Full-cycle development automation with testing gates and knowledge graph memory.

Why This MCP?

5+ git worktree MCPs exist. None require tests. This one does.

| Feature | Others | Smart Agent Workflow | |---------|--------|---------------------| | Worktree management | ✅ | ✅ | | Mandatory E2E tests | ❌ | ✅ | | Build verification | ❌ | ✅ | | Auto-rollback | ❌ | ✅ | | Memory persistence | ❌ | ✅ 🧠 | | Full-cycle workflow | ❌ | ✅ |

Quick Start

npx smart-agent-workflow-mcp

Installation

npm install -g smart-agent-workflow-mcp

Configuration

Claude Desktop

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "smart-agent-workflow": {
      "command": "npx",
      "args": ["smart-agent-workflow-mcp"]
    }
  }
}

Claude Code

Add to your MCP settings:

{
  "mcpServers": {
    "smart-agent-workflow": {
      "command": "npx",
      "args": ["smart-agent-workflow-mcp"]
    }
  }
}

Tools

Worktree Management

| Tool | Description | |------|-------------| | create_worktree | Create isolated feature environment with ephemeral worktree | | worktree_status | List all active worktrees with metadata | | cleanup_worktree | Merge and cleanup (requires tests to pass!) | | abort_worktree | Cancel without merge |

Usage Examples

Create a new worktree

Use create_worktree with task="Add user authentication" and base_branch="main"

List active worktrees

Use worktree_status

Complete and merge a feature

Use cleanup_worktree with worktree_path="/path/to/worktree"

Cancel a feature

Use abort_worktree with worktree_path="/path/to/worktree" and reason="Requirements changed"

Resources

| Resource | Description | |----------|-------------| | worktree://status | JSON with current status of all worktrees |

Philosophy

"No merge without green tests. Every feature builds collective knowledge."

The 3 Pillars:

1. 🧪 Test-First: Quality gates that can't be bypassed
2. 🧠 Memory: Context that grows with your project
3. 📝 Auto-Docs: Documentation enriched by history

Roadmap

| Version | Features | |---------|----------| | ✅ v0.1.0 | Worktree management | | ✅ v0.2.0 | Testing integration (Playwright, build verification) | | ✅ v0.3.0 | Full workflow (start_feature, complete_feature, rollback) | | ✅ v0.4.0 | Documentation (auto-update CLAUDE.md, reports) | | ✅ v0.5.0 | Memory (knowledge graph, context persistence) | | ✅ v0.6.0 | Context Health (statusline, auto-checkpoint) (current) | | 🔜 v1.0.0 | Production ready |

Context Health (v0.6.0)

Smart Agent Workflow now tracks context health to anticipate compaction:

Get Health Status

Use get_context_health

Returns health score (0-100), status (good/warning/critical), and recommendations.

Manual Checkpoint

Use checkpoint_context with message="Before major refactor"

Saves current workflow state and resets health to 100%.

Statusline Integration

Add to your Claude Code settings:

claude config set -g statusLine '{"type":"command","command":"npx smart-agent-workflow-mcp --statusline"}'

Shows: Phase: testing | Feature: auth | Progress: 4/8 | Health: 75%

Development

# Clone the repo
git clone https://github.com/vjrivmon/smart-agent-workflow-mcp.git
cd smart-agent-workflow-mcp

# Install dependencies
npm install

# Run in development mode
npm run dev

# Build
npm run build

# Test
npm test

Contributing

Contributions are welcome! Please read our Contributing Guide first.

License

MIT © Vicente Rivas Monferrer

Made with ❤️ by Vicente Rivas Monferrer

Recent Changes

Test entry from validation