# 🎯 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

```bash
# 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

```bash
# 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
```json
{
  "mcpServers": {
    "agents-playbook": {
      "url": "https://agents-playbook.vercel.app/api/mcp"
    }
  }
}
```

### 🎯 Cursor
Add to your Cursor settings or create a MCP configuration:

```json
{
  "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:

```bash
# 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

```bash
# 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