@epoch-ai/deliver-cli

v3.0.2

Published

4 days ago

Streamlined MCP server for managing spec workflow (requirements, design, implementation)

0High
0Medium
0Low

benjamesmurray

mcp workflow spec requirements design implementation openapi

Deliver CLI

English | 简体中文

Deliver CLI is a senior-grade, state-aware Model Context Protocol (MCP) server that transforms your AI agent into a spec-driven product engineer. Version 3.0 (Agent-Optimized) is redesigned for high-density, low-token communication.

Why Deliver CLI v3?

The traditional approach to AI coding often leads to scope creep and forgotten requirements. deliver-cli (v3) is optimized for senior AI agents:

TOON Status Output (Context Efficiency): sc_status now returns a compact, YAML-like format instead of verbose Markdown. This reduces token usage per turn by ~70%, keeping your context window lean.
State-Aware Autopilot: The tool knows exactly what stage the project is in. The AI doesn't have to track whether it's doing "Requirements" or "Design"—it just calls mcpx with server="spec" tool="sc_plan" and instruction="Use PostgreSQL" and the tool handles the transition automatically.
Zero-Overhead Execution: Subprocesses have been eliminated; the MCP server invokes the CLI logic directly for maximum speed and reliable error handling.
Minimalist Syntax: Feature names and project identifiers are now optional. The tool defaults to the last-used project, reducing payload size for every subsequent tool call.
One-Shot vs. Step-Through Modes: Users can toggle between Step-Through (the default "Draft -> Approve -> Confirm" cycle) and One-Shot mode. In One-Shot mode, the AI progresses through all phases—including archiving the project—without stopping for human approval.
Lifecycle Directory Management: Automatically organizes work into projects/active/ and projects/completed/.
Persistent Task-Epoch Memory: A "short-term memory" system (.epoch-context.md) that tracks active focus, pending intentions, and hypotheses via mcpx with server="spec" tool="sc_epoch" and focus="implement auth".
The "GPS Breadcrumb" System: At the end of every tool call, deliver-cli outputs an explicit "Next Step" directive.

TOON Format (New in v3)

Instead of verbose Markdown, mcpx with server="spec" and tool="sc_status" returns a compact block:

spec_status:
  feature: code-analytics
  phase: requirements
  status: drafting
  next_step: write Requirements.md
  blockers: [template_tags_present]
  mode: one-shot

Workflow Diagram

stateDiagram-v2
    direction TB

    state "Phase 1: Requirements (PRD)" as REQ {
        [*] --> InitReq: sc_init
        InitReq --> EditReq: AI Drafts
        EditReq --> ReviewReq: Remove tags
        ReviewReq --> ApproveReq: sc_approve
        ApproveReq --> [*]: sc_plan
    }

    state "Phase 2: Technical Design" as DES {
        [*] --> ScaffoldDes: Reset Epoch Context
        ScaffoldDes --> EditDes: AI Drafts
        EditDes --> ReviewDes: Remove tags
        ReviewDes --> ApproveDes: sc_approve
        ApproveDes --> [*]: sc_plan
    }

    state "Phase 3: Implementation Tasks" as TSK {
        [*] --> ScaffoldTasks: Reset Epoch Context
        ScaffoldTasks --> EditTsk: AI Drafts
        EditTsk --> ReviewTsk: Remove tags
        ReviewTsk --> ApproveTsk: sc_approve
        ApproveTsk --> [*]: sc_plan
    }

    state "Phase 4: Implementation" as IMP {
        [*] --> StartTask: sc_todo_start
        StartTask --> Work: Coding & Epoch Updates
        Work --> CompleteTask: sc_todo_complete
        CompleteTask --> [*]: All Tasks [x]
    }
    
    state Archive {
        [*] --> MoveToCompleted: sc_plan (Archive)
    }

    REQ --> DES
    DES --> TSK
    TSK --> IMP
    IMP --> Archive
    Archive --> [*]: Feature Delivered

MCP Semantic Tools

Spec CLI provides a suite of surgical MCP tools to guide the AI agent through the workflow.

| Tool Name | Purpose | Example Arguments | | :--- | :--- | :--- | | mcpx with server="spec" tool="sc_init" and name="auth-system" | Initialize a new feature specification in projects/active/. | {"name": "auth-system", "mode": "one-shot"} | | mcpx with server="spec" tool="sc_plan" and instruction="Use PostgreSQL" | Progress the workflow state. Automatically archives when finished. | {"instruction": "Use PostgreSQL"} | | mcpx with server="spec" and tool="sc_approve" | Explicitly approve the current drafted phase after review. | {} | | mcpx with server="spec" tool="sc_feedback" and feedback="..." | Provide user feedback or answers to questions. | {"feedback": "The logo should be blue"} | | mcpx with server="spec" tool="sc_status" and feature="auth-system" | Get a health check of the active project and snappy next steps. | {"feature": "auth-system"} | | mcpx with server="spec" and tool="sc_todo_list" | List all implementation tasks and their status. | {} | | mcpx with server="spec" tool="sc_todo_start" and id="1.1" | Mark a specific task as being actively worked on. | {"id": "1.1"} | | mcpx with server="spec" tool="sc_todo_complete" and id="1.1" | Mark a specific task as completed. | {"id": "1.1"} | | mcpx with server="spec" tool="sc_epoch" and focus="implement auth" | Update the task-epoch context for short-term memory. | {"focus": "implement auth"} | | mcpx with server="spec" tool="sc_mode" and mode="one-shot" | Toggle project mode between one-shot and step-through. | {"mode": "one-shot"} | | mcpx with server="spec" and tool="sc_archive" | Manually move the project to the projects/completed/ folder. | {} | | mcpx with server="spec" tool="sc_help" and topic="sc_plan" | Learn how to use the tools and get deep documentation. | {"topic": "sc_plan"} | | mcpx with server="spec" and tool="sc_verify" | A dedicated tool to validate that the last action worked. | {} | | mcpx with server="spec" and tool="sc_refresh" | Force a refresh and synchronization of the internal workflow state machine. | {} |

Command Line Interface

While primarily used via MCP, Spec CLI also provides a powerful standalone interface.

Installation & Setup

Prerequisites

Node.js: Version 18.0.0 or higher.
Package Manager: npm, yarn, or pnpm.

Installation Options

Option 1: Quick Start (npx)

Run it without installing globally:

npx -y @epoch-ai/deliver-cli

Option 2: Global Installation

For frequent use as a standalone CLI:

npm install -g @epoch-ai/deliver-cli

Option 3: MCP Client Configuration

To use this with AI assistants, add it to your configuration file:

Claude Desktop Add to ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows):

{
  "mcpServers": {
    "deliver-cli": {
      "command": "npx",
      "args": ["-y", "@epoch-ai/deliver-cli"]
    }
  }
}

Gemini CLI Configure deliver-cli globally in ~/.gemini/settings.json or locally in .gemini/settings.json:

{
  "mcpServers": {
    "deliver-cli": {
      "command": "npx",
      "args": ["-y", "@epoch-ai/deliver-cli"]
    }
  }
}

Claude Code

claude mcp add deliver-cli -s user -- npx -y @epoch-ai/deliver-cli

Development

Getting Started

Clone the Repo:

git clone https://github.com/benjamesmurray/deliver-cli.git
cd deliver-cli

Install Dependencies:
```
npm install
```
Build the Project:
```
npm run build
```
Run Tests:
```
npm test
```

License

MIT