Spec Workflow Mcp

Spec Workflow MCP

Spec Workflow MCP v2.0.0 — a productivity toolkit for spec-driven development workflows served via the Model Context Protocol (MCP). Manage tasks, plan sprints, track progress, review deliverables, set reminders, prioritize work, and run weekly reviews — all from the command line with timestamped log entries.

Commands

The script (scripts/script.sh) exposes the following commands via a case dispatcher:

| Command | Description | |---------|-------------| | add | Add a new spec/task entry. Without args, shows the 20 most recent add entries. | | plan | Record a planning entry (sprint planning, iteration goals). Without args, lists recent plans. | | track | Track progress on a task or deliverable. Without args, lists recent tracking entries. | | review | Record a review note (code review, spec review). Without args, lists recent reviews. | | streak | Log a streak entry (daily consistency tracking). Without args, lists recent streaks. | | remind | Set a reminder or log a reminder note. Without args, lists recent reminders. | | prioritize | Record a prioritization decision. Without args, lists recent prioritizations. | | archive | Archive a completed item. Without args, lists recent archive entries. | | tag | Tag or categorize an entry. Without args, lists recent tags. | | timeline | Record a timeline/milestone entry. Without args, lists recent timeline entries. | | report | Generate or log a report entry. Without args, lists recent reports. | | weekly-review | Record a weekly review summary. Without args, lists recent weekly reviews. | | stats | Show summary statistics across all log files (entry counts per type, total, disk usage). | | export | Export all data in json, csv, or txt format to $DATA_DIR/export.. | | search | Search all log files for a term (case-insensitive grep). | | recent | Show the 20 most recent lines from history.log. | | status | Health check — shows version, data directory, total entries, disk usage, last activity. | | help | Display the full help/usage message. | | version | Print spec-workflow-mcp v2.0.0. |

How Each Entry Command Works

1. If called without arguments, it tails the last 20 lines of .log. 2. If called with arguments, it: - Timestamps the input (YYYY-MM-DD HH:MM|) - Appends it to $DATA_DIR/.log - Prints confirmation with the current total count - Logs the action to history.log

Data Storage

All data is stored as plain-text log files under:

~/.local/share/spec-workflow-mcp/
├── add.log
├── plan.log
├── track.log
├── review.log
├── streak.log
├── remind.log
├── prioritize.log
├── archive.log
├── tag.log
├── timeline.log
├── report.log
├── weekly-review.log
└── history.log          # unified activity log

Each log line uses pipe-delimited format: YYYY-MM-DD HH:MM|

The history.log uses: MM-DD HH:MM :

Requirements

When to Use

1. Sprint planning — use plan to record iteration goals, then track to log progress against them throughout the sprint 2. Task management — use add to capture new specs or tasks, prioritize to rank them, and archive when complete 3. Daily standups — use streak to maintain consistency tracking and recent to review what happened yesterday 4. Code/spec reviews — use review to log review notes and decisions for future reference 5. Weekly retrospectives — use weekly-review to capture weekly summaries, then export to generate reports for stakeholders

Examples

Add a task and plan a sprint

# Add a new spec
bash scripts/script.sh add "API rate limiting — sliding window implementation"
Plan the sprint
bash scripts/script.sh plan "Sprint 8: rate limiter, caching layer, monitoring"

Track progress and review

# Track completion
bash scripts/script.sh track "rate limiter: Redis backend done, unit tests passing"
Log a review
bash scripts/script.sh review "rate limiter PR #87: approved, added integration tests"

Set reminders and manage priorities

# Set a reminder
bash scripts/script.sh remind "demo prep for Friday stakeholder meeting"
Prioritize
bash scripts/script.sh prioritize "P1: cache invalidation edge case in multi-region"

Weekly review and export

# Record weekly summary
bash scripts/script.sh weekly-review "shipped rate limiter, started caching layer, blocked on Redis cluster config"
Export all data as CSV
bash scripts/script.sh export csv

Search and view timeline

# Find all entries mentioning "cache"
bash scripts/script.sh search "cache"
Log a milestone
bash scripts/script.sh timeline "v2.1 release candidate tagged"
View overall statistics
bash scripts/script.sh stats

Configuration

Set the DATA_DIR variable (or modify it in the script) to change the storage directory. Default: ~/.local/share/spec-workflow-mcp/

Output

All commands print to stdout. Redirect to a file as needed:

bash scripts/script.sh weekly-review > retro-notes.txt

Add a task and plan a sprint

# Add a new spec
bash scripts/script.sh add "API rate limiting — sliding window implementation"
Plan the sprint
bash scripts/script.sh plan "Sprint 8: rate limiter, caching layer, monitoring"

Track progress and review

# Track completion
bash scripts/script.sh track "rate limiter: Redis backend done, unit tests passing"
Log a review
bash scripts/script.sh review "rate limiter PR #87: approved, added integration tests"

Set reminders and manage priorities

# Set a reminder
bash scripts/script.sh remind "demo prep for Friday stakeholder meeting"
Prioritize
bash scripts/script.sh prioritize "P1: cache invalidation edge case in multi-region"

Weekly review and export

# Record weekly summary
bash scripts/script.sh weekly-review "shipped rate limiter, started caching layer, blocked on Redis cluster config"
Export all data as CSV
bash scripts/script.sh export csv

Search and view timeline

# Find all entries mentioning "cache"
bash scripts/script.sh search "cache"
Log a milestone
bash scripts/script.sh timeline "v2.1 release candidate tagged"
View overall statistics
bash scripts/script.sh stats

Set the DATA_DIR variable (or modify it in the script) to change the storage directory. Default: ~/.local/share/spec-workflow-mcp/