sprint-mcp

MCP server providing Sprint Protocol tooling for LLM-driven development workflows

---

Overview

sprint-mcp is a Model Context Protocol (MCP) server that implements the Sprint Protocol, enabling structured, traceable development workflows for LLM-powered coding assistants like Claude.

What is Sprint Protocol?

Sprint Protocol is a structured methodology for LLM-driven development that provides:

• Phased execution (Plan → Approve → Implement → Validate → Verify → Publish → Retro → Learn)
• Git worktree isolation for each sprint
• Comprehensive artifacts (implementation plans, verification reports, retrospectives)
• Full traceability through request logs
• Quality gates ensuring code quality and testing

What is MCP?

Model Context Protocol enables Claude Desktop to interact with external tools and services. sprint-mcp exposes Sprint Protocol tools as MCP endpoints.

---

Features

• Sprint Lifecycle Management - Start, update, complete, and track sprints
• Git Worktree Integration - Isolated development environments per sprint
• Artifact Generation - Automated creation of plans, reports, retrospectives
• Sprint Index Management - Track all sprints across your projects
• Archive System - Organize completed sprints by year, free up active workspace
• Knowledge Extraction - Automatically extract lessons, patterns, and metrics from completed sprints
• Auto-Archive - Intelligent archival based on age, count, or hybrid criteria
• Cleanup Tools - Remove completed sprint worktrees safely
• Validation & Verification - Quality gates and artifact validation

---

Installation

Method 1: Global Installation (Recommended)

npm install -g sprint-mcp

Pros: Simple configuration, faster startup, works offline

Method 2: npx (No Installation)

No installation needed - use directly with npx.

Pros: Always latest version, no global packages, easy to try

Method 3: Project-Local

npm install --save-dev sprint-mcp

Pros: Project-specific version, locked in package.json

---

Configuration

For Claude Desktop

Add to your Claude Desktop configuration file:

Config Location:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json
• Linux: ~/.config/Claude/claude_desktop_config.json

Global Installation

{
  "mcpServers": {
    "sprint-mcp": {
      "command": "sprint-mcp"
    }
  }
}

With npx

{
  "mcpServers": {
    "sprint-mcp": {
      "command": "npx",
      "args": ["-y", "sprint-mcp"]
    }
  }
}

With Environment Variables

{
  "mcpServers": {
    "sprint-mcp": {
      "command": "sprint-mcp",
      "env": {
        "SPRINT_ROOT": "/path/to/your/project"
      }
    }
  }
}

After configuration:

1. Restart Claude Desktop completely (Cmd+Q / File → Exit)
2. Wait 5-10 seconds for MCP servers to initialize
3. Verify tools appear in Claude

---

Available Tools

sprint-mcp provides the following MCP tools:

Sprint Lifecycle

• start-sprint - Initialize a new sprint with manifest and directory structure

  • Creates sprint directory in planning/
  • Sets up git worktree for isolated development
  • Generates sprint manifest with metadata

• check-sprint-status - Verify current sprint state

  • Returns active sprint information
  • Checks for conflicts (multiple active sprints)
  • Validates sprint index integrity

• update-sprint-status - Update sprint status and metadata

  • Status transitions: planning → in-progress → validating → verifying → published → complete
  • Updates both manifest and sprint index
  • Atomic operations for consistency

• complete-sprint - Complete sprint with validation

  • Validates required artifacts (verification-report.md, retro.md, key-learnings.md)
  • Supports normal and forced completion modes
  • Updates status and timestamps

Sprint Index Management

• regenerate-sprint-index - Rebuild sprint index from manifests
  • Scans all sprint manifests in planning/
  • Rebuilds planning/sprint-index.yaml
  • Validates index integrity
  • Recovers from index corruption

Archive & Knowledge

• archive-sprint - Archive completed sprints to organized storage

  • Moves sprints from planning/active/ to planning/archive/{year}/
  • Updates sprint index with new location
  • Triggers knowledge extraction (if enabled)
  • Dry-run mode for preview

• auto-archive-sprints - Automatically archive eligible sprints

  • Age criteria: Archive sprints older than N days
  • Count criteria: Keep only N most recent sprints
  • Hybrid criteria: Must meet both age AND count thresholds
  • Batch processing with error handling
  • Configurable via planning/archive-config.yaml

Cleanup

• cleanup-sprint - Clean up completed sprint worktrees
  • Preview mode: Shows what will be deleted
  • Execution mode: Removes git worktrees
  • Safety checks: Only cleans completed sprints
  • Force option: Override uncommitted changes check

---

Usage Examples

Starting a Sprint

In Claude Desktop:

Start a new sprint to implement user authentication

Claude will use the start-sprint tool to:

1. Check no active sprints exist
2. Generate sprint ID (e.g., sprint-12-abc123)
3. Create planning/sprint-12-abc123/ directory
4. Create git worktree in .worktrees/sprint-12-abc123/
5. Generate sprint manifest
6. Update sprint index

Checking Sprint Status

Check the current sprint status

Returns information about active sprints and index health.

Completing a Sprint

Complete the current sprint

Claude validates artifacts and marks sprint as complete.

Cleaning Up Worktrees

Clean up completed sprint worktrees

Removes git worktrees for completed sprints, freeing disk space.

---

Sprint Protocol Overview

sprint-mcp implements the Sprint Protocol defined in AGENTS.md. Key concepts:

Sprint Phases

1. Plan - Create implementation plan, get user approval
2. Implement - Execute planned work, log all changes
3. Validate - Run validation script, verify deliverables
4. Verify - Create verification report, document gaps
5. Publish - Create GitHub PR, publish deliverables
6. Retro - Reflect on what went well / what didn't
7. Learn - Extract transferable learnings

Sprint Artifacts

Every sprint creates:

• sprint-manifest.yaml - Sprint metadata and status
• implementation-plan.md - Detailed execution plan
• request-log.md - All prompts and changes
• validate_deliverable.sh - Executable validation script
• verification-report.md - Completed/partial/deferred items
• retro.md - What worked, what didn't
• key-learnings.md - Lessons for future sprints

Note: publication.yaml was deprecated in Protocol v2.5. PR URL and publication metadata are now tracked in sprint-manifest.yaml.

Git Worktrees

Each sprint uses an isolated git worktree:

• Main worktree stays on main branch
• Sprint worktree on feature branch
• Independent working directories
• Separate git operations
• Easy cleanup after completion

Archive System

Completed sprints are organized in an archive hierarchy:

• Active sprints: planning/active/{sprint-id}/
• Archived sprints: planning/archive/{year}/{sprint-id}/
• Auto-archival: Configurable age/count/hybrid criteria
• Knowledge extraction: Automatic extraction of lessons and patterns
• Index tracking: All sprints remain in planning/sprint-index.yaml

Knowledge Base

The system automatically builds a knowledge base from sprint artifacts:

• Lessons learned: Extracted from key-learnings.md, retrospectives
• Patterns: Successful approaches from "what went well" sections
• Anti-patterns: Things to avoid from "what to improve" sections
• Metrics: Sprint duration, effort, velocity tracking
• Deduplication: Similar knowledge merged with frequency tracking
• Storage: planning/knowledge/knowledge-base.yaml

---

Requirements

• Node.js: v18.0.0 or higher
• npm: v8.0.0 or higher
• Git: v2.20 or higher (for worktree support)
• Claude Desktop: Latest version

---

Troubleshooting

Tools not appearing in Claude Desktop

1. Verify configuration file exists and is valid JSON
2. Check Claude Desktop logs for errors
3. Ensure sprint-mcp is installed (which sprint-mcp or npx -y sprint-mcp)
4. Restart Claude Desktop completely

"command not found: sprint-mcp"

Global installation:

npm install -g sprint-mcp
which sprint-mcp

npx usage:

npx -y sprint-mcp  # Test it works

Permission denied errors

Fix npm permissions:

mkdir ~/.npm-global
npm config set prefix '~/.npm-global'
echo 'export PATH=~/.npm-global/bin:$PATH' >> ~/.bashrc
source ~/.bashrc
npm install -g sprint-mcp

MCP server crashes

Check Node.js version:

node --version  # Must be v18+

Run manually to see errors:

sprint-mcp

---

Updating

Global Installation

npm update -g sprint-mcp

npx

No action needed - npx always uses latest version.

To pin version:

{
  "args": ["-y", "sprint-mcp@0.1.0"]
}

Project-Local

npm update sprint-mcp

---

Documentation

• Sprint Protocol: See AGENTS.md in package or GitHub
• Installation Guide: Full installation guide
• Examples: GitHub examples directory

---

Development

Running from Source

git clone https://github.com/cnavta/sprint-mcp.git
cd sprint-mcp
npm install
npm run build
npm link  # Use locally

Running Tests

npm test                # Run all tests
npm run test:coverage   # With coverage report

Current test coverage: 310 tests passing across 18 test suites

---

Contributing

Contributions welcome! Please:

1. Fork the repository
2. Create a feature branch
3. Follow Sprint Protocol (see AGENTS.md)
4. Include tests for new functionality
5. Submit pull request

See CLAUDE.md for development guidelines.

---

License

MIT License - see LICENSE file for details

---

Links

• npm Package: https://www.npmjs.com/package/sprint-mcp
• GitHub Repository: https://github.com/cnavta/sprint-mcp
• Issues: https://github.com/cnavta/sprint-mcp/issues
• MCP Specification: https://modelcontextprotocol.io/

---

Acknowledgments

• Built with Model Context Protocol SDK
• Designed for use with Claude Desktop
• Inspired by structured development methodologies

---

Support

• Documentation: See installation guide
• Issues: GitHub Issues
• Discussions: GitHub Discussions