Structured Workflow Engine

This Structured Workflow Engine MCP Server provides an integrated environment to manage AI development workflows with semantic search, validation guards, and reusable mini-prompts. You connect with an MCP client to search, select, and execute structured workflows that guide AI models from planning through delivery, with smart skipping of irrelevant steps when prerequisites are missing.

How to use

Connect to the MCP server using your MCP client by pointing it at the available endpoints. You can access the remote MCP server for development and testing at the production URL, or run a local instance to work entirely offline. You will search for workflows, choose a complete execution plan, and then run through the steps with automatic validation and step skipping when context is not available.

How to install

Prerequisites: ensure you have Node.js installed on your system (version 14+ is recommended). You also need a valid OpenAI API key for semantic search indexing and prompts.

# 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

Additional configuration and usage notes

MCP endpoints include a local development URL and a production URL you can use from your MCP client. The local development endpoint is http://localhost:3000/api/mcp and the production endpoint is https://agents-playbook.vercel.app/api/mcp. When you run the server locally, you can connect your client to the local URL to test workflows before deploying.

Troubleshooting

No workflows found: use simple terms like bug, feature, or documentation, and rebuild embeddings with npm run build:embeddings.

OpenAI API errors: verify OPENAI_API_KEY in your .env file. If OpenAI is unavailable, the system will fall back to semantic search.

Can't connect to MCP server: ensure the server is running and reachable at http://localhost:3000/api/mcp.

Steps are being skipped: this is expected when required context is not present. Check logs to understand why a step is skipped.

Security and local usage considerations

Keep your OpenAI API key secure. Do not expose the key in client-side code. If you are deploying publicly, use environment variables or secret management to protect keys.

Examples of typical workflows

Search: create new feature; Result: feature-development workflow; Execute: 14 steps with validation and skipping where appropriate.

Search: improve test coverage; Result: unit-test-coverage workflow; Execute: 7 steps to systematically improve coverage.

Available tools

get_available_workflows

Search workflows using AI semantic search to find the most relevant process for your task.

select_workflow

Retrieve the complete workflow along with its execution plan for structured execution.

get_next_step

Navigate through the workflow step-by-step with smart validation and guardrails.