Smart Agent Workflow MCP
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@Smart Agent Workflow MCP Create a new worktree for the dashboard redesign"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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 | ❌ | ✅ |
Related MCP server: aico
Quick Start
npx smart-agent-workflow-mcpInstallation
npm install -g smart-agent-workflow-mcpConfiguration
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 isolated feature environment with ephemeral worktree |
| List all active worktrees with metadata |
| Merge and cleanup (requires tests to pass!) |
| 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_statusComplete 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 |
| JSON with current status of all worktrees |
Philosophy
"No merge without green tests. Every feature builds collective knowledge."
The 3 Pillars:
🧪 Test-First: Quality gates that can't be bypassed
🧠 Memory: Context that grows with your project
📝 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_healthReturns 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 testContributing
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
Available Tools
20 toolsabort_worktreeA
Aborts worktree without merging. Use when feature is cancelled.
Inputs: worktree_path (required), reason.
checkpoint_contextA
Save the current workflow state and reset health score. Creates a checkpoint before context is lost to compaction. Use when health is critical or before long operations. Returns health before/after and entries saved.
Inputs: tags, force, message.
cleanup_worktreeA
Merges worktree to main and removes it. REQUIRES tests and build to pass first! Run run_e2e_tests and verify_build before calling this. Use force=true to bypass (NOT recommended).
Inputs: worktree_path (required), force, commit_message.
complete_featureA
Completes a feature: runs E2E tests, verifies build, merges to main, cleans up worktree. BLOCKS if tests or build fail. This is the safe way to merge - quality gates cannot be bypassed.
Inputs: worktree_path (required), skip_tests, commit_message.
create_worktreeB
Creates an ephemeral git worktree for isolated feature development
Inputs: task (required), base_branch.
generate_completion_reportA
Generates a detailed markdown report for a completed feature workflow. Includes test results, build status, timing, and git changes summary. Reports are saved to .smart-agent-workflow/reports/
Inputs: output_path, workflow_id, include_diff, include_tests, +1 more.
generate_test_templateA
Generates a Playwright E2E test template for a feature. Every feature MUST have tests before merge.
Inputs: type (required), feature_name (required), base_url, worktree_path.
get_context_healthA
Get current context health metrics: health score, operations count, estimated tokens, session duration, and whether checkpoint is recommended. Use this to monitor context usage and anticipate compaction.
Inputs: include_log.
get_memoryA
Query the knowledge graph for relevant memories. Search by content, filter by type (decision, learning, error, etc.), tags, workflow, or file path. Returns sorted by importance and recency.
Inputs: tags, type, limit, query, +3 more.
get_test_resultsA
Gets the latest test and build results from a worktree. Shows if the testing gate has been passed.
Inputs: worktree_path, include_output.
get_workflow_statusC
Gets the current status of all active workflows, including phase, steps, and progress.
Inputs: limit, include_history.
restore_contextA
Restore context from a previous workflow. Retrieves decisions, learnings, files modified, and related memories. Use this to resume work on a feature or learn from past implementations.
Inputs: limit, workflow_id, feature_name, include_related.
rollback_featureA
Rolls back a failed or unwanted feature: aborts worktree, cleans up branch, records reason. Use this when you need to abandon a feature without merging.
Inputs: reason (required), keep_branch, worktree_path.
run_e2e_testsA
Runs E2E tests with Playwright. Tests MUST pass before merge. Supports retries and custom test paths.
Inputs: headed, project, retries, test_path, +1 more.
save_contextA
Save the current workflow context to memory. Captures decisions, learnings, and file changes for future sessions. Use this to persist important context before completing or rolling back a feature.
Inputs: tags, notes, decisions, learnings, +1 more.
start_featureA
Starts a new feature with full workflow: creates worktree, sets up environment, initializes tracking. This is the recommended way to begin any development work.
Inputs: description (required), feature_name (required), type, base_branch.
sync_changelogA
Syncs CHANGELOG.md with workflow information. Follows Keep a Changelog format. Automatically detects version from package.json and categorizes changes based on feature type.
Inputs: entry, version, category, workflow_id, +1 more.
update_documentationA
Updates project documentation (CLAUDE.md, README.md) with information from the current workflow. Can auto-detect sections or target specific ones. Useful for keeping docs in sync with development.
Inputs: mode, content, section, doc_path, +1 more.
verify_buildA
Runs npm build and validates the output. Build MUST succeed before merge.
Inputs: script, timeout, worktree_path.
worktree_statusA
Lists all active worktrees with their metadata
Inputs: no named parameters.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 20 tools
Several tools overlap in scope: abort_worktree, rollback_feature, and cleanup_worktree all handle worktree termination at different levels, while create_worktree and start_feature both create worktrees. The descriptions help clarify the hierarchy, but an agent may struggle to choose between low-level and high-level equivalents.
Most tools follow a consistent verb_noun snake_case pattern (e.g., start_feature, verify_build, save_context). The exception is 'worktree_status', which is a noun phrase rather than a verb-led command, making it slightly inconsistent with the rest.
At 20 tools, the server is on the heavier side of the typical range. While each tool has a distinct role, some are redundant due to nested operations (e.g., abort_worktree vs. rollback_feature), suggesting the count could be trimmed without losing functionality.
The tool surface covers the full feature development lifecycle—start, test, build, merge, rollback, and cleanup—plus memory/context management and documentation. Minor gaps exist, such as no direct way to list completed features or delete specific memories, but these are easily worked around.
Maintenance
Related MCP Connectors
Live GitHub repo AST X-Ray, 42 coding-agent DoD gates, Git worktree guards & brownfield baselines.
716Live GitHub repo AST X-Ray, 42 coding-agent DoD gates, Git worktree guards & brownfield baselines.
AI-native git hosting — repos, PRs, issues, CI gates, and AI code review over MCP (60 tools).
Git collaboration for AI agents and people: tasks, hand-offs, reviews, teams, shared memory.
Related MCP Servers
- AlicenseNot gradedqualityCmaintenanceAutomatically captures project state on git commits, detects context drift, and delivers structured token-budgeted briefings to AI agents, ensuring project continuity without manual effort.85 npm2MIT
- FlicenseNot gradedqualityDmaintenanceEnables orchestrating multi-agent AI coding workflows with Git worktree isolation, parallel testing, and security scanning via the Model Context Protocol.-
- AlicenseAqualityCmaintenanceEnables MCP clients to delegate routine coding tasks to a local model in isolated git worktrees, using test results as a gate and the client as the reviewer before changes are merged.5MIT
- AlicenseNot gradedqualityBmaintenanceEnables any coding model or session to pick up where a previous one left off by keeping handoff state (START / SPEC / DECISIONS / TASKS / LOG) in the repository and projecting each harness's entry files from a single source. It also blocks commits until structural checks and the project's own executable acceptance tests actually pass, providing init, onboarding, session briefing/exit, verification, sync, and task-claim tools.1MIT