mcp-product-manager/README-NPM.md

MCP Orchestrator for task and project management with web interface

# 🚀 MCP Product Manager

A powerful task orchestration and project management system with MCP (Model Context Protocol) support for Claude Desktop and other AI assistants.

## Quick Start

```bash
# Install globally
npm install -g mcp-product-manager

# Start the server
product-manager start

# Or use npx (no installation needed)
npx mcp-product-manager start
```

Visit http://localhost:1234/terminal for the web UI!

## Features

- 📋 **Task Management** - Create, track, and organize tasks with intelligent prefixing
- 🤖 **AI Agent Orchestration** - Spawn and manage AI agents for automated task completion
- 📦 **Smart Task Bundling** - Automatically group related tasks for efficient execution
- 🔄 **MCP Integration** - Full support for Claude Desktop and MCP protocol
- 🌐 **REST API** - Complete HTTP API for integrations
- 💻 **Web Terminal** - Interactive web-based terminal UI
- 📊 **Project Analytics** - Track progress, performance, and resource usage

## CLI Commands

```bash
# Core commands
product-manager start    # Start the server
product-manager stop     # Stop the server
product-manager restart  # Restart the server
product-manager status   # Check server status

# Advanced commands
product-manager mcp      # Start in MCP mode for Claude Desktop
product-manager reset    # Reset the database
product-manager config   # View configuration
```

Short alias: Use `pm` instead of `product-manager`

## Claude Desktop Integration

Add to your Claude Desktop config (`~/Library/Application Support/Claude/claude_desktop_config.json`):

```json
{
  "mcpServers": {
    "product-manager": {
      "command": "npx",
      "args": ["mcp-product-manager", "mcp"]
    }
  }
}
```

## Task Format

Tasks use a structured prefix format: `[PREFIX-AREA-###] Description`

**Examples:**
- `[FEAT-API-001] Add user authentication`
- `[BUG-UI-002] Fix dashboard layout`
- `[DOC-README-003] Update installation guide`

**Prefixes:** FEAT, BUG, REFACTOR, TEST, DOC, TASK  
**Areas:** MCP, API, UI, DB, AUTH, SECURITY, PERF, GENERAL

## API Access

Once started, access the API at `http://localhost:1234/api`

### Quick API Examples

```bash
# Create a task
curl -X POST http://localhost:1234/api/tasks \
  -H "Content-Type: application/json" \
  -H "X-Agent: my-agent" \
  -d '{
    "description": "[FEAT-API-001] Add login endpoint",
    "project": "my-project",
    "priority": "high"
  }'

# List tasks
curl http://localhost:1234/api/tasks/my-project

# View API documentation
open http://localhost:1234/api
```

## Configuration

Configuration is stored in `~/.product-manager/config.json`

```json
{
  "port": 1234,
  "database": "~/.product-manager/product-manager.db",
  "autoPrefix": true,
  "skipPrefixForAPI": true,
  "mcp": {
    "enabled": true,
    "stdio": true
  }
}
```

## MCP Tools Available

When integrated with Claude Desktop, these tools become available:

- `create_task` - Create new tasks
- `list_tasks` - List tasks for a project
- `claim_task` - Claim a task for work
- `complete_task` - Mark task as complete
- `spawn_agent` - Create AI agents
- `bundle_analyze` - Analyze tasks for bundling
- `list_projects` - View all projects
- `orchestrate` - Get AI recommendations

## Web Terminal

The web terminal provides an interactive interface at `http://localhost:1234/terminal`

Features:
- Real-time task updates
- Interactive command execution
- Project visualization
- Agent monitoring
- Bundle management

## Database

The database is automatically created at `~/.product-manager/product-manager.db`

- SQLite database (portable, no setup needed)
- Automatic backups before reset
- All data persists between restarts

## Troubleshooting

### Server won't start
```bash
# Check if port is in use
lsof -i:1234

# Use a different port
# Edit ~/.product-manager/config.json and change "port"
```

### Reset everything
```bash
product-manager stop
product-manager reset
rm -rf ~/.product-manager
```

### View logs
```bash
tail -f ~/.product-manager/server.log
```

## Development

```bash
# Clone the repository
git clone https://github.com/buildooor/product-manager
cd product-manager

# Install dependencies
npm install

# Run in development mode
npm run dev
```

## Support

- 📖 Documentation: [GitHub Wiki](https://github.com/buildooor/product-manager/wiki)
- 🐛 Issues: [GitHub Issues](https://github.com/buildooor/product-manager/issues)
- 💬 Discussions: [GitHub Discussions](https://github.com/buildooor/product-manager/discussions)

## License

MIT © buildooor