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.

Related MCP server: Project Manager MCP

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