MCP 服务器

moo-tasks

MCP server for agentic task orchestration and management, enabling AI agents to create goals, plan tasks with acceptance criteria, track dependencies, request human input, and provide proof of completion.

README

🐮 Moo Tasks

Agentic Task Orchestration & Management Engine built for AI coding agents (Claude Code, Cursor, Windsurf, Antigravity, Copilot) and human-in-the-loop pair programming.

Quick Start • Agent Setup • Agent Protocol • Architecture • MCP Tools

<br/>

</div>

🌟 Why Moo Tasks?

Standard AI coding agents often suffer from:

Scope Drift: Wandering away from original user intent into endless low-value refactorings.
Over-Planning: Generating 40 shallow tasks without executing any of them.
Looping / Thrashing: Attempting the same failed fix repeatedly without stopping.
Unverifiable Work: Claiming code is complete without running tests or producing evidence.
Re-Debating Decisions: Re-arguing settled architectural choices on every context reset.

Moo Tasks solves this by providing a local SQLite engine (WAL mode), a rich real-time Web UI, and a Model Context Protocol (MCP) server that enforces strict enterprise invariants at runtime.

✨ Key Capabilities & Feature Matrix

🎯 1. Goals & Scope Control

Verbatim Human Prompts: Sits above tasks, preserving the exact original user request.
Goal Coverage & Loose Ends: Live metrics on task completion percentage and lingering open tasks.
Scope Drift Detection: Automatically identifies and flags orphan tasks with no linked goal.
Goal Open Caps: Hard cap on maximum open tasks per goal (default: 10), preventing agents from over-planning.
Cascade Operations: Atomically drop, kill, or reopen all tasks under a goal with mandatory reasons.

📋 2. Task Lifecycle & DAG Dependencies

Subtask Nesting Constraint: Exactly 1 level of subtasks under a parent task.
Finite State Machine: todo, doing, blocked-on-dependency, waiting-on-human, done, dropped.
DAG Dependency Graph: Automatic cycle detection and automatic unblocking of downstream tasks.
Parent Closure Guard: Prevents closing parent tasks while any subtask remains open.
Status Undo & History: Roll back accidental state transitions using full transition audit history.

🛡️ 3. Completion, Verification & Proof of Work

Acceptance Criteria: Mandatory criteria written in Markdown before work starts.
Evidence Requirement: Closing a task requires verifiable proof (commands run, stdout output, test proofs).
Two-Phase Verification: Distinguishes agent_completed from human verified_done.
Rejection with Reason: Humans or peer agents can reject completed work with feedback; the task reverts to todo and increments the reopen counter.

🙋 4. Human Collaboration & Blocking

Waiting-on-Human Queue: Agents pause blockers with attached questions (clarification, approval, credential, decision).
Reactive Resume: Answering a question via Web UI or MCP automatically transitions the task back into the ready queue without agent restarts.
Dedicated Human Inbox: Real-time queue of everything needing human attention.

🔍 5. Discovered Work

Mid-Task Work Capture: Capture new work found mid-flight without relinquishing current task claim.
Must-Fix vs Deferred: Mark as must-fix-now (inserted as blocker) or deferred (backlog pile).

🤖 6. Ownership, Concurrency & Leases

Exclusive Task Claims: Leases with automatic timeout (default 5 minutes) when agents go silent.
Heartbeat Mechanism: Extend leases during long-running tasks.
Agent Concurrency Limits: Cap simultaneous tasks held per agent (default: 1).
File Touch Conflict Warnings: Declared files are checked for overlaps against other active claims.

🔄 7. Stall & Thrash Detection

Attempt Counter: Incremented on each claim/attempt.
Auto-Escalation: After $N$ attempts (default: 3), automatically pauses task to waiting-on-human instead of endless looping.
Time-in-State Tracking: Audits time spent in doing and detects repeated reopens.

🏛️ 8. Settled Architectural Decisions (ADR)

Project-Level Record: Preserves choices and rationales that outlive tasks.
Pre-Planning Consultation: Agents read settled decisions before planning.
Supersede Support: Cleanly update and link superseded decisions with mandatory reasons.

🚀 Quick Start & Installation

Option A: Install Globally (Recommended for `moo` command)

Install moo-tasks globally to access the short moo command anywhere:

npm install -g moo-tasks
# or: pnpm add -g moo-tasks | bun add -g moo-tasks

Once installed, you can use moo directly:

moo init       # Initialize .moo workspace in current project
moo start      # Launch real-time Web UI (http://127.0.0.1:4242)
moo ws         # List registered global workspaces
moo status     # Show Where-Did-I-Leave-Off context
moo search     # Full-text SQLite search

💡 Note on moo vs npx:
Bare moo <command> works when installed globally via npm install -g moo-tasks.

If running without global installation, use npx moo-tasks <command> (do not use npx moo, as moo on npm registry is an unrelated package).
If moo: command not found appears after global install, ensure npm's global bin directory is in your $PATH:
export PATH="$(npm prefix -g)/bin:$PATH"

Option B: On-Demand via `npx moo-tasks`

Run directly without global installation:

1. Initialize Workspace & Agent Protocols

Run in your project root:

npx moo-tasks init

This:

Initializes .moo/tasks.db SQLite database with WAL mode.
Generates AGENTS.md, CLAUDE.md, .cursorrules, and .windsurfrules.

2. Launch Local Web UI

npx moo-tasks start

Open http://127.0.0.1:4242 in your browser.

To access the Web UI from another device or tablet on your local network (LAN):

npx moo-tasks start --lan
# Automatically logs: http://192.168.x.x:4242/

🔌 Agent & MCP Setup

One-Command Multi-Agent Installer

# Configure all detected agent IDEs at once:
npx moo-tasks install all

# Or configure specific clients:
npx moo-tasks install claude       # Updates ~/.claude.json
npx moo-tasks install cursor       # Generates .cursor/mcp.json
npx moo-tasks install windsurf     # Updates ~/.codeium/windsurf/mcp_config.json
npx moo-tasks install antigravity  # Generates .gemini/settings.json

Manual Configuration

{
  "mcpServers": {
    "moo-tasks": {
      "command": "npx",
      "args": ["moo-tasks", "mcp"]
    }
  }
}

🤖 Mandatory Agent Protocol

All AI coding agents are instructed to follow this 6-step lifecycle:

1. SESSION RESUME  → Call moo_session_resume() & moo_list_decisions()
2. ANCHOR GOAL     → Call moo_create_goal(title, verbatimPrompt)
3. PLAN & CRITERIA → Call moo_create_task() with markdown criteria BEFORE code
4. EXCLUSIVE CLAIM → Call moo_claim_task(taskId, agentId, sessionId)
5. IMPLEMENTATION  → If blocked, call moo_ask_human() or link blockers
6. VERIFIED PROOF  → Call moo_complete_task() with test proof & output snippet
7. ADR RECORD      → Call moo_record_decision() for architectural choices

🛠️ MCP Tool Reference

Tool Name	Purpose
`moo_create_goal`	Record human's verbatim prompt and set open task cap
`moo_list_goals`	List project goals and statuses
`moo_get_goal_status`	View goal coverage, open vs cap, and loose ends
`moo_kill_goal`	Drop goal and cascade drop all child tasks with reason
`moo_reopen_goal`	Reopen goal and its tasks
`moo_create_task`	Create task under goal with acceptance criteria & declared files
`moo_create_tasks_batch`	Batch create multiple tasks atomically
`moo_quick_start`	⚡ 1-call express vibe tool: Atomically creates and claims task with lease and declared files
`moo_checkpoint`	⚡ Fast progress checkpoint: Appends attempt note & extends heartbeat
`moo_get_compact_context`	🧠 Ultra-dense token-optimized context block (< 400 tokens) for prompt injection
`moo_update_task`	Update title, criteria, priority, declared files, or goal
`moo_link_dependencies`	Link prerequisite blockers with cycle validation
`moo_unlink_dependencies`	Unlink prerequisite blocker
`moo_get_next_task`	Auto-surface next unblocked, highest-priority task
`moo_get_task`	Get full task details, subtasks, notes, dependencies
`moo_list_tasks`	Filter tasks by goal, status, priority, agent, deferred
`moo_claim_task`	Exclusively claim task (enforces lease & conflict checks)
`moo_heartbeat_task`	Extend active lease during long-running tasks
`moo_release_task`	Voluntarily release claim back to todo
`moo_handoff_task`	Handoff in-flight task to another agent with notes
`moo_complete_task`	Mark task done with mandatory commands/proof evidence
`moo_verify_task`	Verify task done (human or verification agent)
`moo_reject_task`	Reject completed task with mandatory reason
`moo_ask_human`	Escalate question to human and pause task
`moo_get_human_inbox`	List all tasks waiting on human guidance
`moo_answer_human`	Answer question and auto-resume task
`moo_capture_discovered_work`	Add discovered work (must-fix or deferred)
`moo_add_task_note`	Append timestamped, attributed context/attempt note
`moo_list_task_notes`	List context history and attempt logs
`moo_drop_task`	Drop task with mandatory reason
`moo_reopen_task`	Reopen task without losing audit history
`moo_undo_status_change`	Undo last status transition
`moo_bulk_drop_tasks`	Drop multiple tasks in single operation
`moo_bulk_reopen_tasks`	Reopen multiple tasks in single operation
`moo_record_decision`	Record project-level architectural decision
`moo_list_decisions`	List settled decisions before planning
`moo_supersede_decision`	Supersede decision with new rationale
`moo_merge_tasks`	Merge duplicate tasks
`moo_session_resume`	"Where did I leave off?" session summary
`moo_export_project`	Export project to Markdown, JSON, or Plain Text
`moo_archive_completed`	Archive done/dropped tasks out of active list

🏛️ Architecture & Clean Code

src/
├── domain/                    # Pure Enterprise Domain Rules & Invariants
│   ├── types.ts              # Domain interfaces & value types
│   ├── errors.ts             # Domain-specific typed error classes
│   ├── dependency.ts         # DAG cycle detector & unblocked evaluator
│   ├── conflict.ts           # File touch overlap conflict detector
│   └── similarity.ts         # Duplicate task similarity detector
│
├── infrastructure/            # Persistence & External Integrations
│   ├── db/database.ts        # SQLite manager (WAL mode, busy timeout)
│   ├── db/migrations.ts      # Schema DDL and versioning
│   ├── git/git-context.ts    # Git branch, commit, dirty status extractor
│   └── repositories/         # SQLite Repository Implementations
│
├── services/                  # Application Services (Use Cases)
│   ├── goal-service.ts        # Goal lifecycle & cap enforcement
│   ├── task-lifecycle-service.ts # State machine, ready queue, undo
│   ├── claim-service.ts       # Exclusive claims, leases, dead-agent timeout
│   ├── verification-service.ts# Proof of work & two-phase verification
│   ├── human-collab-service.ts# Human Q&A queue & reactive resume
│   ├── discovered-work-service.ts # Mid-flight discovered work
│   ├── decision-service.ts    # ADR logs & supersede linking
│   ├── duplicate-merge-service.ts # Idempotency & task merging
│   ├── session-service.ts     # Where-did-I-leave-off session resume
│   ├── housekeeping-service.ts# Archiving & multi-format export
│   └── index.ts               # Dependency Injection Container
│
├── mcp/                       # Model Context Protocol Stdio Server
├── server/                    # Fastify HTTP + Server-Sent Events (SSE) Engine
├── cli/                       # CLI Commands (start, init, install, mcp)
└── ui/                        # Vanilla JS + Tailwind + Lucide Icons Web UI

🤝 Contributing

Contributions are welcome! Please check out CONTRIBUTING.md for development setup, testing, and PR guidelines.

📄 License

This project is licensed under the MIT License.