ASD MCP - Lightweight Project Orchestration for Claude Code & Cursor

Solve the "context preparation tax" problem when using AI development tools.

Instead of spending 5-10 minutes explaining project context every session, ASD MCP maintains project state and generates perfect handoff context in 30 seconds.

🎯 The Problem

When using Claude Code or Cursor, every new session starts the same way:

• "I'm working on X feature..."
• "Here's what I've built so far..."
• "My current task is..."

Result: 5-10 minutes of context preparation per session, destroying AI productivity gains.

🚀 The Solution

ASD MCP is a lightweight orchestrator that provides structured workflows and maintains project state, letting AI tools focus on what they do best: implementation.

Core Innovation: Don't replace AI capabilities - give AI tools the context they need to excel.

✨ Features

🏗️ Project Lifecycle Management

• Interactive PRD Creation: Guided interview process for comprehensive requirements
• Design & Technical Specs: Automated generation from PRD data
• Task Breakdown: Phase-based organization with dependencies
• Approval Workflows: Checkpoints ensure quality and alignment

🔄 Implementation Workflow

• 7-Step Process: Structured workflow for consistent development
• Progress Tracking: Visual hierarchy with completion percentages
• Feature Management: Individual feature PRDs with automatic main PRD updates
• Quality Gates: Automated testing integration before git operations

📊 State Management

• Hybrid State: Simple JSON core + rich state calculated from PRD files
• Context Generation: Perfect handoff context in 30 seconds
• Zero Context Loss: State preserved between sessions
• Error Recovery: Graceful handling of corrupted state

🛠️ MCP Integration

• 12 Core Tools: Complete project lifecycle orchestration
• Template Engine: Variable substitution with conditional blocks
• File Operations: Safe atomic writes with error handling
• Git Integration: Automated commits with conventional commit messages

🧪 Beta Testing

ASD MCP v0.1.0 is now in beta! We're looking for developers to test the core workflows and provide feedback.

👉 Join the Beta Test Program

Beta Testing Focus Areas

• Installation & MCP Setup: Test npm install and Claude Code/Cursor integration
• Core Workflows: Validate PRD creation, task breakdown, and implementation cycles
• Context Handoff: Verify zero context loss between sessions
• Real Projects: Use ASD MCP on actual development work

How to Provide Feedback

• GitHub Issues: Report bugs and feature requests
• Beta Guide: Follow structured testing scenarios in BETA_TESTING.md
• Success Metrics: Help us validate the 95% time savings goal (10min → 30sec)

🚀 Quick Start

1. Install

# Install from NPM (Production Release)
npm install -g asd-mcp

# Or install for development
git clone https://github.com/tylerbarnard/asd-mcp.git
cd asd-mcp

# Install dependencies
npm install

# Build the project
npm run build

2. Configure MCP

Add to your Claude Code/Cursor MCP configuration:

{
  "mcpServers": {
    "asd-mcp": {
      "command": "node",
      "args": ["/path/to/asd-mcp/build/index.js"],
      "env": {}
    }
  }
}

3. Start Your First Project

In Claude Code, say:

"Let's create a PRD for a user authentication system"

The MCP will guide you through a structured interview to create your project.

📋 Core Workflows

Project Initialization

# Single command project setup
"Initialize a new feature project for user authentication"

What it creates:

• Complete project structure
• PRD, design specs, and task breakdown
• Approval checkpoints
• Implementation workflow

Daily Development

# Get project status
"Show me the current project status"

# Continue implementation
"Keep going on the project"

# Update progress
"Mark the OAuth integration task as complete"

Adding Features

# Create feature PRD
"Create a feature PRD for password reset functionality"

# Feature automatically added to main PRD
# Continue with implementation workflow

🛠️ MCP Tools

Project Lifecycle

• asd_initialize_project - Complete project setup
• asd_create_prd - Interactive PRD creation
• asd_create_discovery - Design and technical specs
• asd_create_tasks - Comprehensive task breakdown
• asd_keep_going - Implementation workflow

Approval Workflow

• asd_approve_prd - Approve PRD and advance to discovery
• asd_approve_discovery - Approve specs and advance to tasks
• asd_approve_tasks - Approve tasks and start implementation
• asd_check_approval - Check current approval status

Feature Management

• asd_create_feature_prd - Create feature-specific PRDs
• asd_update_progress - Update task completion status
• asd_milestone_reached - Document milestone completion

Status & Information

• asd_get_status - Enhanced progress display
• asd_get_template - Access project templates
• asd_generate_handoff - Create context for AI tools

📁 Project Structure

your-project/
├── .asd/                    # ASD MCP state and data
│   ├── state.json          # Project state and approvals
│   ├── templates/          # Project templates
│   └── milestones/         # Progress documentation
├── docs/                   # Project documentation
│   ├── PRD_Main.md        # Main product requirements
│   ├── Design_Spec.md     # Design specifications
│   ├── Technical_Spec.md  # Technical specifications
│   ├── Tasks.md           # Task breakdown and progress
│   └── features/          # Feature-specific PRDs
└── src/                   # Your project source code

🎯 Success Metrics

Time Savings

• Context prep: 10 minutes → 30 seconds (95% reduction)
• Session startup: Instant AI context
• Project onboarding: 2 minutes for any project

Quality Improvements

• Context accuracy: Perfect every time
• Zero context loss between sessions
• Clear next steps always available

🔧 Development

Prerequisites

• Node.js 18+
• TypeScript 5+
• Jest for testing

Setup

# Install dependencies
npm install

# Build the project
npm run build

# Run tests
npm test

# Run tests with coverage
npm run test:coverage

Project Structure

src/
├── core/                   # Core functionality
│   ├── state-manager.ts   # State management
│   ├── template-engine.ts # Template processing
│   └── markdown-parser.ts # PRD parsing
├── tools/                  # MCP tool implementations
│   ├── prd-creation.ts    # PRD creation workflow
│   ├── discovery-phase.ts # Design and technical specs
│   ├── task-breakdown.ts  # Task generation
│   └── ...                # Other tools
├── types/                  # TypeScript interfaces
├── utils/                  # Utility functions
└── index.ts               # MCP server entry point

Testing

# Run all tests
npm test

# Run specific test file
npm test -- src/core/state-manager.test.ts

# Run tests with coverage
npm run test:coverage

# Run tests in watch mode
npm run test:watch

📚 Documentation

• User Guide - Comprehensive usage guide
• Troubleshooting - Common issues and solutions
• PRD - Product requirements document
• Design - Technical architecture
• Tasks - Implementation task breakdown

🤝 Contributing

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Make your changes
4. Add tests for new functionality
5. Run the test suite (npm test)
6. Commit your changes (git commit -m 'Add amazing feature')
7. Push to the branch (git push origin feature/amazing-feature)
8. Open a Pull Request

Development Guidelines

• Follow TypeScript best practices
• Maintain test coverage above 80%
• Use conventional commit messages
• Update documentation for new features
• Follow the established project structure

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

🙏 Acknowledgments

• Built for Claude Code and Cursor users
• Inspired by the need to eliminate context preparation overhead
• Designed to enhance AI development tool effectiveness

Stop building AI capabilities. Start orchestrating AI tools effectively.

ASD MCP recognizes that:

• AI tools excel at implementation when properly contextualized
• Developers waste enormous time on manual context preparation
• Simple state tracking solves 90% of AI collaboration problems
• Orchestration beats duplication

Result: You focus on decisions. AI handles implementation. Nothing gets lost.