🎯 Structured Workflow Engine MCP Server

Context Engineering Framework with ready-to-use development workflows that bring structure to chaos.

🎯 What is this

Structured Workflow System - designed to help both high-tier and low-tier AI models follow consistent processes:

• 🧠 Context Engineering - workflows engineered for reliable AI execution across model tiers
• 🔧 9 Workflows - battle-tested processes that provide structure and guardrails
• ⚡ Smart Validation - automatically validates prerequisites and skips irrelevant steps
• 📋 12 Mini-Prompts - context-engineered prompts organized by development phases

🚀 Installation

# 1. Clone repository
git clone https://github.com/your-repo/agents-playbook
cd agents-playbook

# 2. Install dependencies
npm install

# 3. Add OpenAI API key to .env
OPENAI_API_KEY=your_key_here

# 4. Generate search index
npm run build:embeddings

# 5. Start server
npm run dev

MCP Server:

• Local Development: http://localhost:3000/api/mcp
• Production: https://agents-playbook.vercel.app/api/mcp

🧪 Testing

# MCP Inspector for testing
DANGEROUSLY_OMIT_AUTH=true npx @modelcontextprotocol/inspector@latest http://localhost:3000/api/mcp

# Run tests (90+ tests)
npm run test:integration

🛠️ Available Tools

get_available_workflows

Search workflows with AI semantic search.

Example:

• Input: "fix critical bug"
• Output: quick-fix workflow (🎯 89% match)

select_workflow

Get complete workflow with execution plan.

get_next_step

Step-by-step navigation with smart validation.

📁 Workflows (9 total)

🚀 Development (4)

• feature-development - Complete feature development lifecycle
• product-development - From idea to product launch
• quick-fix - Fast bug fixes and hotfixes
• code-refactoring - Code architecture improvements

🧪 Testing & QA (3)

• fix-tests - Systematic test failure diagnosis and repair with refactoring integration
• fix-circular-dependencies - Comprehensive circular dependency resolution with architectural refactoring
• unit-test-coverage - Comprehensive unit test coverage improvement

📋 Setup & Planning (2)

• project-initialization - New project setup
• trd-creation - Technical Requirements Document creation

🎯 Usage Examples

1. Search: "create new feature"
2. Result: feature-development workflow (🎯 92% match)  
3. Execute: 14 steps with TRD integration and smart skipping

1. Search: "improve test coverage"  
2. Result: unit-test-coverage workflow (🎯 94% match)
3. Execute: 7 steps of systematic coverage improvement

1. Search: "circular dependencies"  
2. Result: fix-circular-dependencies workflow (🎯 95% match)
3. Execute: 7 steps of dependency resolution with refactoring integration

1. Search: "technical documentation"  
2. Result: trd-creation workflow (🎯 94% match)
3. Execute: 7 steps of TRD creation with validation

🔌 MCP Integration

🤖 Claude Desktop

{
  "mcpServers": {
    "agents-playbook": {
      "url": "https://agents-playbook.vercel.app/api/mcp"
    }
  }
}

🎯 Cursor

Add to your Cursor settings or create a MCP configuration:

{
  "mcpServers": {
    "agents-playbook": {
      "url": "https://agents-playbook.vercel.app/api/mcp",
      "description": "AI Agent Workflow Engine with semantic search"
    }
  }
}

For Cursor users:

1. Open Cursor Settings
2. Navigate to "Extensions" or "Integrations"
3. Add MCP Server configuration
4. Restart Cursor

📁 Direct File Usage (Any IDE)

Copy playbook files directly to your project:

# Copy entire playbook to your project
cp -r public/playbook/ /path/to/your/project/

# For Cursor: create a .cursorrules file
echo "Use workflows from playbook/ directory for structured development" > .cursorrules

📚 Local Usage

# Copy entire playbook to your project
cp -r public/playbook/ /path/to/your/project/

# For Cursor: create a .cursorrules file
echo "Use workflows from playbook/ directory for structured development" > .cursorrules

Benefits:

• ✅ Works without MCP server
• ✅ Customize for your team
• ✅ Offline access
• ✅ Version control with project
• ✅ Cursor can reference workflows directly

🧠 How it works

• Context Engineering - workflows designed with clear context boundaries and validation
• Semantic Search - OpenAI embeddings understand task context for workflow selection
• YAML Workflows - structured processes with phases, steps, and guardrails
• Mini-Prompts - context-engineered reusable prompts that work across model tiers
• Smart Validation - prevents execution without required context, provides structure for low-tier models

🐛 Troubleshooting

"No workflows found"

• Use simple terms: "bug", "feature", "documentation"
• Check: npm run build:embeddings

"OpenAI API errors"

• Check OPENAI_API_KEY in .env
• System falls back to text search if OpenAI unavailable

"Can't connect to MCP server"

• Make sure server is running: npm run dev
• URL: http://localhost:3000/api/mcp

"Steps are being skipped"

• This is normal behavior! System skips steps without required context
• Check logs to understand skip reasons

---

🎯 Structured Workflow Engine - Context engineering framework that brings order to chaos in AI-driven development