Smart Agent Workflow

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

npm version License: MIT

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