npm package: @qualequest/orchestration-mcp
Description: Model Context Protocol server for autonomous AI agent orchestration with 30+ coordination tools
Author: QualeQuest Intelligence
Latest version: 1.0.0

# QualeQuest Orchestration MCP Server

**Model Context Protocol server for autonomous AI agent coordination**

Coordinate AI agents across Claude Desktop, Claude Code, and custom platforms with 30+ built-in tools for task management, validation, context synchronization, and inter-agent communication.

## Installation

```bash
npm install @qualequest/orchestration-mcp
```

## Quick Start

Add to your Claude Desktop configuration (`claude_desktop_config.json`):

```json
{
  "mcpServers": {
    "qualequest-orchestration": {
      "command": "npx",
      "args": ["-y", "@qualequest/orchestration-mcp"],
      "env": {
        "QUALEQUEST_API_KEY": "your-api-key"
      }
    }
  }
}
```

Get your API key at [intelligence.qualequest.com](https://intelligence.qualequest.com)

## Features

- **⭐ V5.1 Intelligence Layer** - NEW flagship feature with 85% token reduction
- **38 Coordination Tools** - Complete agent orchestration toolkit (updated from 37)
- **Task Management** - Create, assign, track, and validate tasks
- **Evidence System** - File-verified validation evidence
- **Context Sync** - Save and retrieve agent context snapshots
- **Inter-Agent Messaging** - Priority-based communication with threading
- **ML Predictions** - Task duration, agent matching, success probability (PRO)
- **Pattern Learning** - Learn from disasters and optimize workflows (PRO)

## ⭐ V5.1 Intelligence Layer

**New in V5.1:** Intelligent session initialization that replaces 3 manual calls with 1 smart call.

### intelligent_session_init

The flagship feature of V5.1 delivers **85% token reduction** (5,500 → 800 tokens) with role-aware, actionable context.

**What it does:**
- Automatically retrieves relevant context from your last sessions
- Filters and prioritizes messages by importance
- Detects pending work and suggests next actions
- Identifies anomalies (stuck tasks, urgent messages)
- Optimizes output based on your role (PM, Engineer, Designer)

**Before (3 calls, ~5,500 tokens):**
```javascript
retrieve_context(agent_id, query_type, target_agent_id)  // ~2,500 tokens
get_agent_messages(to_agent_id, unread_only)             // ~2,000 tokens
acknowledge_onboarding(agent_id, ...)                     // ~1,000 tokens
```

**After (1 call, ~800 tokens):**
```javascript
intelligent_session_init(
  agent_id="OPUS-001",
  session_purpose="Review V5.1 launch status"
)
```

**Benefits:**
- 📉 **85% fewer tokens** - Massive cost savings on every session start
- ⚡ **40ms average latency** - Faster than sequential calls
- 🎯 **Role-optimized** - Output tailored to PM, Engineer, or Designer
- 🔍 **Proactive insights** - Detects stuck tasks and urgent issues automatically
- 🚀 **Better UX** - One call instead of three

**Performance:**
- Average latency: 40ms (tested: OPUS-001, BE-001, DESIGN-001)
- Target budget: <200ms
- 100% test pass rate across all agent types

See [docs/INTELLIGENT-SESSION-GUIDE.md](docs/INTELLIGENT-SESSION-GUIDE.md) for usage guide and best practices.

## Available Tools

### Core Coordination
- `deploy_agent` - Deploy agents with context packages
- `update_agent_status` - Update agent status (PENDING, ACTIVE, PAUSED, BLOCKED, COMPLETE)
- `send_agent_message` - Send messages between agents
- `get_agent_messages` - Retrieve messages for an agent

### Task Management
- `create_task` - Create new tasks (required before starting work)
- `start_task` - Start working on a task
- `query_tasks` - Query tasks with filters (status, agent, priority)
- `claim_task_completion` - Request to mark task complete

### Validation & Evidence
- `submit_validation_evidence` - Submit evidence with file verification
- `check_validation_status` - Check if task meets validation requirements

### Context Management
- `save_context_snapshot` - Save agent context for future retrieval
- `retrieve_context` - Retrieve previous context snapshots
- `acknowledge_onboarding` - Required protocol acknowledgment before work

### Decision Intelligence (PRO)
- `submit_decision_for_validation` - Submit major decisions for AI validation
- `query_decision_history` - Query past decisions to learn from history
- `get_strategic_recommendations` - Get AI-powered strategic suggestions

### ML Predictions (PRO)
- `predict_task_duration` - Predict task completion time
- `suggest_optimal_agent` - Recommend best agent for a task
- `predict_success_probability` - Predict task success likelihood

### Advanced Messaging
- `send_priority_message` - Send message with priority level
- `broadcast_to_agents` - Send message to multiple agents

### Learning & Optimization (PRO)
- `learn_from_disaster` - Log disasters for pattern learning
- `analyze_patterns` - Discover patterns in coordination events
- `generate_recommendations` - Generate actionable recommendations

## Pricing

| Tier | Price | Features |
|------|-------|----------|
| **FREE** | $0 | Basic coordination, 5 tools, local storage |
| **PRO** | $29/mo | All 30+ tools, ML predictions, cloud sync |
| **ENTERPRISE** | Custom | Dedicated instance, unlimited agents, SLA |

## Requirements

- Node.js >= 18.0.0
- Claude Desktop, Claude Code, or MCP-compatible client
- QualeQuest API key (get at intelligence.qualequest.com)

## Development

### Local Development Setup

```bash
# Clone repository
git clone https://github.com/qualequest/orchestration-mcp.git
cd orchestration-mcp

# Install dependencies
npm install

# Run in development mode (with auto-reload)
npm run dev

# Run tests
npm test
```

### Testing the Server Locally

#### Option 1: Test via Claude Desktop

Add to your `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "qualequest-local": {
      "command": "node",
      "args": ["C:/path/to/qualequest-mcp-server/server.js"],
      "env": {
        "QUALEQUEST_API_KEY": "your-api-key"
      }
    }
  }
}
```

Restart Claude Desktop and verify tools are available.

#### Option 2: Test via MCP Inspector

```bash
# Install MCP Inspector globally
npm install -g @modelcontextprotocol/inspector

# Run inspector
mcp-inspector node server.js
```

This opens a web interface to test all MCP tools interactively.

### Environment Variables

- `QUALEQUEST_API_KEY` - Your API key from intelligence.qualequest.com (required)
- `DB_PATH` - Custom database path (optional, defaults to `~/.qualequest/coordination.db`)
- `CONFIG_PATH` - Custom config path (optional, defaults to `~/.qualequest/config.json`)

### Graceful Degradation

The server includes intelligent fallbacks for ML predictions when the ML server is unavailable:

- **predict_task_duration** - Falls back to rule-based estimation using task type and complexity
- **suggest_optimal_agent** - Falls back to keyword-based routing with pattern matching
- **predict_success_probability** - Falls back to conservative probability based on complexity and duration

All fallback responses include:
- Clear explanation of fallback method used
- Helpful recommendations for the user
- Automatic resumption when ML server becomes available

### Node.js Version

Minimum required: **Node.js 18.0.0**

The server automatically checks your Node.js version at startup and provides helpful guidance if an upgrade is needed.

## Support

- Documentation: [docs.qualequest.com](https://docs.qualequest.com)
- Issues: [GitHub Issues](https://github.com/intelligence-qualequest/qualequest-orchestration/issues)
- Email: support@qualequest.com

## License

MIT License - see [LICENSE](LICENSE) file

---

**Built by [QualeQuest](https://qualequest.com)** | Powered by [Model Context Protocol](https://modelcontextprotocol.io)