Skip to main content
Glama
Smart Agent Workflow MCP

Smart Agent Workflow MCP

by vjrivmon

Smart Agent Workflow MCP

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

❌

✅

Related MCP server: aico

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

Available Tools

20 tools
abort_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

    B3.4/5.0

    Scored across 20 tools

    Disambiguation3/5

    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.

    Naming Consistency4/5

    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.

    Tool Count3/5

    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.

    Completeness4/5

    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

    ActivityInactive
    ResponsivenessOutdated data

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables 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.
      1
      MIT