@preks/aipm-mcp/README.md

MCP server for AIPM integration - connect your AIPM workspace to any MCP-compatible IDE or tool

# AIPM MCP

**Connect your AIPM workspace to any MCP-compatible IDE or tool with AI-powered task management**

Transform your development workflow by integrating AIPM's intelligent project management directly into your IDE. Manage tasks, track time, and leverage AI-powered features through natural language interactions with your AI assistant.

## 🚀 What This Enables

With AIPM Cursor MCP, you can:

- **Natural Language Task Management**: "Show me my high-priority tasks" or "Start working on the authentication feature"
- **Intelligent Code Generation**: AI generates code based on your AIPM task context and requirements
- **Automatic Progress Tracking**: Time logging and status updates happen seamlessly
- **Context-Aware Development**: AI understands your project requirements, acceptance criteria, and team context
- **Seamless Workflow**: No switching between tools - everything happens in Cursor

## 📋 Prerequisites

- **Node.js 18+** 
- **MCP-compatible IDE or tool** (Cursor, Claude Desktop, etc.)
- **AIPM Account** - Access to an AIPM workspace (hosted or self-hosted)
- **AIPM API Token** - Generated from your AIPM account

## 🛠️ Installation

### Quick Start

```bash
# Install the MCP server globally
npm install -g @preks/aipm-mcp

# Configure your AIPM connection
npx aipm-mcp configure

# Follow the setup instructions for your IDE
```

### Alternative: Local Installation

```bash
# Install locally in your project
npm install @preks/aipm-mcp

# Configure your AIPM connection
npx aipm-mcp configure
```

## ⚙️ Configuration

### Step 1: Get Your AIPM API Token

1. Log into your AIPM workspace
2. Go to your **Profile Settings** or **API Settings**
3. Generate a new API token
4. Copy the token for configuration

### Step 2: Configure the MCP Server

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

You'll be prompted for:
- **AIPM Instance URL**: Your AIPM workspace URL (e.g., `https://your-workspace.aipm.com`)
- **API Token**: The token you generated in Step 1
- **Organization ID**: (Optional) Your organization identifier
- **Server Name**: A name for this MCP server (default: `aipm-mcp`)

The configuration will be tested and saved to `~/.aipm-mcp/config.json`.

### Step 3: Add to Your IDE

After configuration, you'll see instructions to add the MCP server to your IDE:

#### Option A: Cursor IDE Settings UI
1. Open Cursor Settings (`Cmd/Ctrl + ,`)
2. Navigate to **Cursor Settings > MCP**
3. Click **"+ Add New MCP Server"**
4. Configure:
   - **Name**: `AIPM`
   - **Type**: `stdio`
   - **Command**: `npx aipm-mcp start`

#### Option B: JSON Configuration
Add to your IDE settings file:

```json
{
  "mcp": {
    "servers": {
      "aipm": {
        "command": "npx",
        "args": ["aipm-mcp", "start"]
      }
    }
  }
}
```

## 🎯 Usage Examples

Once configured, interact with AIPM through Cursor's AI assistant:

### Task Management
```
"Show me my current tasks"
"What high-priority tasks do I have?"
"Start working on task PROJ-123"
"Mark task PROJ-123 as completed with 4 hours logged"
"Create a bug fix task for the login issue"
```

### Feature Development
```
"Break down the user authentication feature into development tasks"
"Show me all features for the mobile app product"
"What are the acceptance criteria for this task?"
```

### Time Tracking
```
"Log 2 hours of work on the API integration"
"Show me my time logs for this week"
"How much time have I spent on the authentication feature?"
```

### Project Context
```
"What products are we working on?"
"Search for tasks related to database optimization"
"Who am I logged in as?"
```

## 🔧 Available Commands

| Command | Description |
|---------|-------------|
| `npx aipm-mcp configure` | Set up AIPM connection |
| `npx aipm-mcp start` | Start the MCP server |
| `npx aipm-mcp status` | Check configuration status |
| `npx aipm-mcp help` | Show help information |

## 🎮 MCP Tools Available in Cursor

Once configured, Cursor's AI can use these tools to interact with AIPM:

| Tool | Description | Example Usage |
|------|-------------|---------------|
| `get_tasks` | Retrieve tasks with filters | "Show me TODO tasks" |
| `get_task_details` | Get comprehensive task info | "Tell me about task PROJ-123" |
| `start_task` | Begin work with time tracking | "Start task PROJ-123" |
| `complete_task` | Mark tasks done | "Complete task PROJ-123" |
| `create_task` | Create new tasks | "Create a bug fix task" |
| `get_features` | Retrieve features | "Show me planned features" |
| `breakdown_feature` | AI-powered feature breakdown | "Break down the payment feature" |
| `get_products` | List all products | "What products exist?" |
| `log_time` | Manual time entry | "Log 1.5 hours on task PROJ-123" |
| `get_time_logs` | Retrieve time tracking data | "Show my time logs" |
| `search_tasks` | Natural language task search | "Find API-related tasks" |
| `get_current_user` | Get user information | "Who am I logged in as?" |

## 🔄 Typical Development Workflow

### Morning Standup
```
User: "Show me my high-priority tasks for today"
AI: [Lists prioritized tasks with details, estimates, and context]
```

### Starting Work
```
User: "Start working on the user authentication task"
AI: [Updates task status, starts time tracking, shows task details and AI prompts]
```

### During Development
```
User: "What's the acceptance criteria for this task?"
AI: [Shows detailed requirements, generated code suggestions, and context]
```

### Completing Work
```
User: "I've finished the login API. Mark it complete and log 3 hours."
AI: [Updates status, stops time tracking, logs hours, requests completion notes]
```

### Feature Planning
```
User: "Break down the 'User Profile Management' feature into tasks"
AI: [Uses AIPM's AI to generate detailed, prioritized development tasks]
```

## 🚨 Troubleshooting

### Common Issues

**"No configuration found"**
```bash
# Run the configuration wizard
npx aipm-mcp configure
```

**"Failed to connect to AIPM API"**
- Check your AIPM instance URL is correct
- Verify your API token is valid and not expired
- Ensure your AIPM instance is accessible

**"MCP server not found in Cursor"**
- Verify the command path: `npx aipm-mcp start`
- Check that Node.js is in your PATH
- Restart Cursor after adding the MCP server

### Debug Mode

Check your configuration:
```bash
npx aipm-mcp status
```

This will test your connection and show configuration details.

### Getting Help

```bash
# Show all available commands
npx aipm-mcp help

# Check configuration status
npx aipm-mcp status
```

## 🔒 Security & Privacy

- **API tokens are stored locally** in `~/.aipm-mcp/config.json`
- **No data is sent to third parties** - communication is only between Cursor and your AIPM instance
- **Tokens are transmitted over HTTPS** when connecting to hosted AIPM instances
- **Configuration files have restricted permissions** (readable only by your user)

## 📈 Benefits

### For Developers
- **No context switching** between project management tools and IDE
- **AI-powered code generation** based on real requirements
- **Automatic time tracking** without manual input
- **Intelligent task suggestions** and workflow guidance

### For Teams
- **Real-time progress visibility** for project managers
- **Accurate time tracking** without developer overhead
- **Better estimates** based on actual development data
- **Consistent workflows** across all team members

## 🔄 Updates

The MCP server will automatically use the latest version when you run `npx aipm-mcp`. To update:

```bash
# Update to latest version
npm update -g aipm-cursor-mcp

# Or for local installations
npm update aipm-cursor-mcp
```

## 🤝 Support

- **Documentation**: [https://docs.aipm.com/cursor-integration](https://docs.aipm.com/cursor-integration)
- **Issues**: [GitHub Issues](https://github.com/your-org/aipm-cursor-mcp/issues)
- **Email Support**: support@aipm.com

## 📄 License

MIT License - see [LICENSE](LICENSE) file for details.

---

**Transform your development workflow with AI-powered project management directly in Cursor!**

Built with ❤️ by the AIPM Team