Project Planner MCP Server

An MCP (Model Context Protocol) server that transforms app ideas into comprehensive, TDD-driven implementation plans with GitHub integration.

What It Does

• Generates structured project plans from requirements documents
• Creates GitHub issues, milestones, and labels automatically
• Tracks progress through GitHub issue status
• Enforces TDD workflow (RED-GREEN-REFACTOR) for every session

Installation

Via npm (recommended)

npm install -g project-planner-mcp

Via npx (no install)

npx project-planner-mcp

Configuration

Claude Code

Add to ~/.claude.json:

{
  "mcpServers": {
    "project-planner": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "project-planner-mcp"],
      "env": {
        "GITHUB_TOKEN": "your-github-token"
      }
    }
  }
}

Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json (Mac):

{
  "mcpServers": {
    "project-planner": {
      "command": "npx",
      "args": ["-y", "project-planner-mcp"],
      "env": {
        "GITHUB_TOKEN": "your-github-token"
      }
    }
  }
}

GitHub Token

Create a Personal Access Token with repo scope.

Available Tools

Tool	Description
generateProjectPlan	Create PROJECT_PLAN.md from requirements
setupGitHubProject	Create GitHub issues, milestones, labels
trackProgress	Query GitHub for progress metrics
analyzeRequirements	Validate requirements for completeness
critiquePlan	Review plan for issues
findNextSession	Get next available session
reviewArchitecture	Technical feasibility analysis
estimateEffort	Time and complexity estimates

See PLANNING_GUIDE.md for detailed usage.

Development

Clone and Setup

git clone https://github.com/hmesfin/pm-mcp.git
cd pm-mcp/mcp-plan
npm install

Build

npm run build       # Compile TypeScript
npm run watch       # Watch mode

Test

npm test            # Run tests
npm run type-check  # Type checking only

Project Structure

pm-mcp/
├── mcp-plan/           # MCP server source
│   ├── src/
│   │   ├── tools/      # Tool implementations
│   │   ├── services/   # Business logic
│   │   └── types/      # TypeScript types
│   └── index.ts        # Entry point
├── templates/          # Plan generation templates
├── project-plans/      # Generated plans (output)
└── docs/               # Documentation

Documentation

• PLANNING_GUIDE.md - User guide
• CLAUDE.md - Architecture & development notes
• REQUIREMENTS.md - Full specification

Contributing

Contributions welcome! Please read REQUIREMENTS.md for the complete specification.

License

MIT