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

npm install -g aipm-mcp

2. Configure

npx aipm-mcp configure

3. Start in Dual Mode (Recommended)

npx aipm-mcp start --dual-mode --port=3002

4. Verify Installation

# 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:

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

# 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

# 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

npm run build

Development Mode

npm run dev

Publishing

npm publish

📚 Documentation

• AIPM Documentation
• MCP Protocol
• Cursor IDE

🤝 Support

• Issues: GitHub Issues
• Documentation: AIPM Docs
• Community: AIPM Discord

Made with ❤️ by the AIPM Team