MCP Gateway Specification

Complete set of MCP gateways exposing CLEO capabilities through 8 domain-specific interfaces

CLEO MCP Gateway Specification

Version: 1.0.0 Status: DRAFT Date: 2026-01-31

Overview

This specification defines a complete set of MCP (Model Context Protocol) gateways that expose CLEO’s capabilities through a unified interface. The gateways are designed for LLM agents to interact with CLEO without requiring direct CLI invocation.

Design Principles

1. Domain Cohesion: Each gateway groups related operations
2. Consistent Response Format: All gateways return structured JSON with _meta, success, data/error
3. Protocol Enforcement: Gateways enforce RCSD-IVTR lifecycle where applicable
4. Exit Code Mapping: CLI exit codes map to structured error responses

Architecture Alignment

MCP Gateways
    │
    ├── cleo_tasks      ─────► Task CRUD (66 scripts)
    ├── cleo_session    ─────► Session + Focus Management
    ├── cleo_orchestrate ────► Multi-Agent Coordination
    ├── cleo_research   ─────► Research Protocol + Manifest
    ├── cleo_lifecycle  ─────► RCSD-IVTR Gate Management
    ├── cleo_validate   ─────► Protocol Validation + Compliance
    ├── cleo_release    ─────► Release Workflow
    └── cleo_system     ─────► Config, Backup, Health

---

Gateway 1: cleo_tasks

Purpose: Task CRUD operations and hierarchy management

Operations

Operation	Parameters	Returns	CLI Mapping
create	title, description?, parent?, depends?[], labels?[], priority?	Task JSON	cleo add
read	id	Task JSON with full details	cleo show
update	id, title?, description?, status?, priority?, notes?, labels?[]	Updated task	cleo update
complete	id, notes?	Completion confirmation	cleo complete
delete	id, strategy? (orphan|cascade|reparent)	Deletion confirmation	cleo delete
reopen	id	Reopened task	cleo reopen
reparent	id, newParent	Updated task	cleo reparent
promote	id, toType (task|epic)	Promoted task	cleo promote

---

Gateway 2: cleo_session

Purpose: Session lifecycle and focus management

Operations

Operation	Parameters	Returns	CLI Mapping
start	scope, name?, autoFocus?, focus?	Session JSON	cleo session start
end	note?	Session summary	cleo session end
status	-	Current session state	cleo session status
list	status?	Session list	cleo session list
focus.set	taskId	Focus confirmation	cleo focus set
focus.show	-	Current focus	cleo focus show
focus.clear	-	Clear confirmation	cleo focus clear

---

Gateway 3: cleo_orchestrate

Purpose: Multi-agent coordination and subagent spawning

Operations

Operation	Parameters	Returns	CLI Mapping
start	epicId	Session + context state	cleo orchestrator start
analyze	epicId	Dependency waves	cleo orchestrator analyze
ready	epicId, phase?	Parallel-safe tasks	cleo orchestrator ready
next	epicId	Next task suggestion	cleo orchestrator next
spawn	taskId	Spawn prompt JSON	cleo orchestrator spawn
context	-	Context budget status	cleo orchestrator context

---

Gateway 4: cleo_research

Purpose: Research protocol and manifest management

Operations

Operation	Parameters	Returns	CLI Mapping
list	status?, limit?, filter?	Manifest entries	cleo research list
show	id	Entry details	cleo research show
pending	-	Followup items	cleo research pending
link	taskId, researchId	Link confirmation	cleo research link

---

Gateway 5: cleo_lifecycle

Purpose: RCSD-IVTR gate management

Operations

Operation	Parameters	Returns	CLI Mapping
phase.show	-	Current phase	cleo phase show
phase.advance	-	Phase transition	cleo phase advance
phases.stats	-	Phase statistics	cleo phases stats
gate.check	epicId, targetStage	Gate status	N/A (internal)

---

Gateway 6: cleo_validate

Purpose: Protocol validation and compliance

Operations

Operation	Parameters	Returns	CLI Mapping
protocol	taskId, protocol	Validation result	cleo validate protocol
compliance	period?	Compliance metrics	cleo compliance value
schema	file	Schema validation	cleo validate

---

Gateway 7: cleo_release

Purpose: Release workflow management

Operations

Operation	Parameters	Returns	CLI Mapping
bump	type (patch|minor|major), dryRun?	Version info	dev/bump-version.sh
release	type, push?	Release result	dev/release-version.sh
changelog	version?	Changelog content	scripts/generate-changelog.sh

---

Gateway 8: cleo_system

Purpose: Configuration, backup, and health

Operations

Operation	Parameters	Returns	CLI Mapping
config.get	key	Config value	cleo config get
config.set	key, value	Updated config	cleo config set
backup.create	type?	Backup info	cleo backup
backup.restore	id	Restore confirmation	cleo restore
health	-	System health	cleo doctor
version	-	Version info	cleo version

---

Response Format

All gateways return consistent JSON structure:

{
  "_meta": {
    "gateway": "cleo_tasks",
    "operation": "create",
    "timestamp": "2026-01-31T10:30:00Z",
    "version": "0.80.0"
  },
  "success": true,
  "data": { ... },
  "error": null
}

Error Response

{
  "_meta": { ... },
  "success": false,
  "data": null,
  "error": {
    "code": "E_NOT_FOUND",
    "exitCode": 4,
    "message": "Task T9999 not found",
    "fix": "Use 'cleo find' to discover valid task IDs"
  }
}

---

References

• MCP-SERVER: Two-tool CQRS gateway
• PROTOCOL-ENFORCEMENT: Exit code system