aipm-mcp/README.md

Complete AIPM integration for Cursor IDE - Get tasks, manage features, track time, and build features with AI. Supports both MCP stdio mode and HTTP server mode.

# AIPM MCP - Complete AIPM Integration for Cursor IDE

Get tasks, manage features, track time, and build features with AI. Supports both MCP stdio mode and HTTP server mode.

## 🚀 Quick Start

### 1. Install
```bash
npm install -g aipm-mcp
```

### 2. Configure
```bash
npx aipm-mcp configure
```

### 3. Start in Dual Mode (Recommended)
```bash
npx aipm-mcp start --dual-mode --port=3002
```

### 4. Verify Installation
```bash
# Check server health
npm run polling:health

# Check polling status
npm run polling:status
```

## 📋 Usage Modes

### **Stdio Mode** (For Cursor Integration)
- Cursor can use all 16 MCP tools directly
- Natural language interaction with AIPM
- Perfect for daily development workflow

### **HTTP Mode** (For AIPM Backend Integration)
- AIPM web app can communicate with local MCP
- Build features from web interface
- Real-time task management

### **Dual Mode** (Best of Both Worlds)
- Both stdio and HTTP servers run simultaneously
- Full functionality in both contexts
- Recommended for most users

## 🎯 Build Feature Implementation Guide

When you use the build feature functionality, several documents are created to guide your implementation. Here's how to effectively use them:

### **📁 File Structure Created:**
```
aipm-features/{featureId}/
├── FEATURE_SPEC.md          # Complete feature requirements
├── AI_INSTRUCTIONS.md       # Instructions for Cursor AI
├── IMPLEMENTATION_PLAN.md   # Structured implementation checklist
├── README.md               # Quick start guide
└── .cursor-feature.json    # Feature metadata
```

### **📖 How to Handle Each Document:**

#### **1. FEATURE_SPEC.md - Start Here!**
**Purpose**: Complete feature specification and requirements
**How to Use**:
- **Read this first** to understand what needs to be built
- **Analyze the requirements** and acceptance criteria
- **Identify the scope** of the feature
- **Note any constraints** or special requirements

**Example AI Command**:
```
"Read the FEATURE_SPEC.md file and break down the requirements into implementable components"
```

#### **2. AI_INSTRUCTIONS.md - Implementation Guide**
**Purpose**: Detailed instructions for Cursor AI
**How to Use**:
- **Follow the step-by-step instructions**
- **Use the suggested AI commands**
- **Reference this when stuck** or need guidance
- **Check off completed steps**

**Example AI Commands from this file**:
```
"Start implementing this feature in the current AIPM codebase"
"Create the necessary components and integrate with existing code"
"Write tests for the feature implementation"
```

#### **3. IMPLEMENTATION_PLAN.md - Your Checklist**
**Purpose**: Structured implementation checklist
**How to Use**:
- **Review the analysis** of what the feature needs
- **Check off items** as you complete them
- **Use as a progress tracker**
- **Ensure nothing is missed**

**Key Sections to Follow**:
- ✅ **UI Components** - React components needed
- ✅ **API Integration** - Backend endpoints required
- ✅ **Data Models** - Database models and relationships
- ✅ **Testing** - Test coverage requirements

#### **4. README.md - Quick Reference**
**Purpose**: Quick start and integration notes
**How to Use**:
- **Quick overview** of the feature
- **Integration points** with existing AIPM codebase
- **Reference for project structure**

### **🚀 Step-by-Step Implementation Process:**

#### **Phase 1: Analysis & Planning (5-10 minutes)**
1. **Open FEATURE_SPEC.md** in Cursor
2. **Ask AI**: "Analyze this feature specification and create an implementation plan"
3. **Review IMPLEMENTATION_PLAN.md** and customize it
4. **Identify integration points** with existing AIPM code

#### **Phase 2: Architecture Design (10-15 minutes)**
1. **Ask AI**: "Design the architecture for this feature within the AIPM codebase"
2. **Plan component structure** and data flow
3. **Identify existing components** to reuse
4. **Design API endpoints** if needed

#### **Phase 3: Implementation (30-60 minutes)**
1. **Start with core components**:
   ```
   "Create the main component for this feature following AIPM patterns"
   ```
2. **Add API integration**:
   ```
   "Create the API service for this feature using the existing AIPM API structure"
   ```
3. **Implement data models**:
   ```
   "Create the database models for this feature using Prisma schema"
   ```

#### **Phase 4: Testing & Integration (15-30 minutes)**
1. **Write unit tests**:
   ```
   "Write comprehensive tests for the components I just created"
   ```
2. **Integration testing**:
   ```
   "Test the integration with existing AIPM components"
   ```
3. **End-to-end testing**:
   ```
   "Create end-to-end tests for the complete feature flow"
   ```

#### **Phase 5: Polish & Documentation (10-15 minutes)**
1. **Code review**:
   ```
   "Review the implementation and suggest improvements"
   ```
2. **Documentation**:
   ```
   "Add proper documentation and comments to the code"
   ```
3. **Accessibility**:
   ```
   "Ensure the feature meets accessibility standards"
   ```

### **💡 Pro Tips for Effective Implementation:**

#### **1. Use the Documents as Conversation Starters**
Instead of reading everything at once, use each document to guide AI conversations:
```
"Based on the FEATURE_SPEC.md, what's the most critical component to implement first?"
```

#### **2. Leverage Existing AIPM Patterns**
Always ask AI to follow existing patterns:
```
"Create this component following the same patterns as other AIPM components"
```

#### **3. Iterative Development**
Build in small, testable increments:
```
"Let's implement this feature step by step. What's the smallest working version we can build first?"
```

#### **4. Use the Checklist**
Regularly reference IMPLEMENTATION_PLAN.md:
```
"Let's review our progress against the implementation plan. What's next?"
```

#### **5. Integration-First Approach**
Always consider how it fits into the existing codebase:
```
"How does this feature integrate with the existing AIPM authentication and authorization system?"
```

### **🎯 Common AI Commands for Implementation:**

#### **Analysis & Planning**
```
"Analyze the feature requirements and create a detailed implementation plan"
"What are the key components needed for this feature?"
"How does this feature fit into the existing AIPM architecture?"
```

#### **Component Creation**
```
"Create a React component for this feature following AIPM design patterns"
"Add proper TypeScript types for this component"
"Implement responsive design and accessibility features"
```

#### **API Integration**
```
"Create API endpoints for this feature using the existing AIPM backend structure"
"Add proper error handling and validation"
"Implement authentication and authorization"
```

#### **Testing**
```
"Write unit tests for this component using React Testing Library"
"Create integration tests for the API endpoints"
"Add end-to-end tests for the complete user flow"
```

#### **Code Quality**
```
"Review this code and suggest improvements for performance and maintainability"
"Add proper error boundaries and loading states"
"Ensure this follows AIPM coding standards"
```

### **🔧 Troubleshooting Common Issues:**

#### **If AI seems confused about the feature:**
```
"Let me clarify the requirements. Read the FEATURE_SPEC.md again and ask me any questions you have"
```

#### **If integration is challenging:**
```
"Show me how similar features are implemented in the existing AIPM codebase"
```

#### **If you're stuck on a specific part:**
```
"I'm having trouble with [specific issue]. Can you help me debug this step by step?"
```

#### **If you need to refactor existing code:**
```
"Help me refactor this to better integrate with the new feature requirements"
```

### **📊 Success Metrics:**

A successful implementation should have:
- ✅ **All requirements** from FEATURE_SPEC.md implemented
- ✅ **All checklist items** in IMPLEMENTATION_PLAN.md completed
- ✅ **Proper integration** with existing AIPM codebase
- ✅ **Comprehensive tests** written and passing
- ✅ **Accessibility** and responsive design implemented
- ✅ **Code quality** meets AIPM standards

### **🎉 Completion Checklist:**

Before marking a feature complete:
- [ ] All acceptance criteria met
- [ ] Tests written and passing
- [ ] Code reviewed and polished
- [ ] Documentation updated
- [ ] Integration tested
- [ ] Performance verified
- [ ] Accessibility validated

---

## 🔧 Available MCP Tools

### Task Management
- `get_tasks` - Get tasks/tickets assigned to the user
- `get_task_details` - Get detailed information about a specific task
- `start_task` - Start working on a task
- `complete_task` - Mark a task as completed
- `create_task` - Create a new task/ticket
- `search_tasks` - Search for tasks using natural language

### Feature Management
- `get_features` - Get features from AIPM
- `breakdown_feature` - Use AI to break down a feature into tasks
- `build_feature` - Build a feature using AI (creates implementation workspace)
- `implement_feature` - Implement a feature directly in the codebase

### Time Tracking
- `log_time` - Log time spent on a task or feature
- `get_time_logs` - Get time logs for tasks, features, or date ranges

### Development Support
- `get_development_guidance` - Get contextual development guidance
- `update_task_implementation` - Update task with implementation details
- `get_current_user` - Get information about the current user
- `get_products` - Get all products from AIPM

## 🌐 HTTP Server Endpoints

### Core Endpoints
- `GET /health` - Health check
- `POST /build-feature` - Build a feature (creates implementation workspace)
- `GET /user` - Get current user information

### Task Management
- `GET /tasks` - Get all tasks
- `GET /tasks/:id` - Get specific task details
- `POST /tasks/:id/start` - Start a task
- `POST /tasks/:id/complete` - Complete a task
- `POST /tasks` - Create a new task
- `POST /tasks/:id/implementation` - Update task implementation

### Feature Management
- `GET /features` - Get all features
- `POST /features/:id/breakdown` - Break down a feature

### Time Tracking
- `GET /time-logs` - Get time logs
- `POST /time-logs` - Log time

### Search & Utilities
- `GET /search/tasks` - Search tasks
- `GET /products` - Get all products

## 🔐 Authentication

The MCP server uses the same authentication as your AIPM account. Configure your API token during setup:

```bash
npx aipm-mcp configure
```

## 🌐 User-Based Device Targeting

When using the build feature from AIPM:

1. **AIPM backend** sends the user ID with the build request
2. **Local MCP server** receives the request for that specific user
3. **Cursor opens** on the user's device with the feature workspace
4. **Implementation** happens on the correct user's machine

This ensures that when you click "Build Feature" in AIPM, it opens Cursor on YOUR device, not someone else's.

## 🎛️ Polling Management

The MCP server polls the AIPM backend for build requests. You can control this behavior:

### Quick Commands
```bash
# Check polling status
npm run polling:status

# Stop polling (if flooding occurs)
npm run polling:stop

# Start polling
npm run polling:start

# Restart polling with cleanup
npm run polling:restart

# Check server health
npm run polling:health
```

### HTTP API
```bash
# Check polling status
curl http://localhost:3002/polling/status

# Stop polling
curl -X POST http://localhost:3002/polling/stop

# Start polling
curl -X POST http://localhost:3002/polling/start

# Restart polling
curl -X POST http://localhost:3002/polling/restart
```

### Troubleshooting Polling Issues

If you experience console flooding or excessive logging:

1. **Immediate Stop**: `npm run polling:stop`
2. **Check Status**: `npm run polling:status`
3. **Restart Clean**: `npm run polling:restart`
4. **Monitor**: Watch the logs for any issues

**Common Issues**:
- **Multiple Instances**: Ensure only one MCP server is running
- **Network Issues**: Check AIPM backend connectivity
- **Authentication**: Verify API token is valid
- **Rate Limiting**: Check if backend is rate limiting requests

## 🚀 Development

### Building
```bash
npm run build
```

### Development Mode
```bash
npm run dev
```

### Publishing
```bash
npm publish
```

## 📚 Documentation

- [AIPM Documentation](https://docs.aipm.com)
- [MCP Protocol](https://modelcontextprotocol.io)
- [Cursor IDE](https://cursor.sh)

## 🤝 Support

- **Issues**: [GitHub Issues](https://github.com/aipm/aipm-mcp/issues)
- **Documentation**: [AIPM Docs](https://docs.aipm.com/cursor-integration)
- **Community**: [AIPM Discord](https://discord.gg/aipm)

---

**Made with ❤️ by the AIPM Team**