# Microsoft Planner Task Creator CLI + MCP Server

A command-line tool and MCP (Model Context Protocol) server for creating and managing Microsoft Planner tasks. This project provides both a standalone Python CLI and a Node.js MCP server wrapper for AI assistant integration.

**Created by:** [Babak Bandpey](https://linkedin.com/in/babakbandpey)
**Website:** [cocode.dk](https://cocode.dk)

## Website
- [English](https://cocodedk.github.io/Planner-Task-Creator-CLI-MCP/)
- [فارسی (Persian)](https://cocodedk.github.io/Planner-Task-Creator-CLI-MCP/fa/)

## Features

- 🔐 **Secure OAuth Authentication**: Device code flow with token caching
- 📋 **Task Management**: Create tasks with titles, descriptions, due dates, and labels
- 💬 **Task Comments**: Read and add comments to tasks via conversation threads
- 📝 **Task Descriptions**: Automatically included in all task listings and searches
- 🎯 **Smart Resolution**: Case-insensitive plan and bucket name resolution
- ⚙️ **Flexible Configuration**: CLI flags, environment variables, and config file support
- 🤖 **MCP Integration**: Expose Planner functionality to AI assistants like Claude
- 🧪 **Comprehensive Testing**: Full test suite with pytest

## Architecture

```
┌─────────────────┐
│  AI Assistant   │
│ (Claude, etc.)  │
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│  MCP Server     │
│  (Node.js/TS)   │
└────────┬────────┘
         │ spawns
         ▼
┌─────────────────┐
│  Python CLI     │
│  (planner.py)   │
└────────┬────────┘
         │
         ▼
┌─────────────────┐
│ Microsoft Graph │
│      API        │
└─────────────────┘
```

## Installation

### Prerequisites

- Python 3.8+ with pip
- Node.js 18+ with npm (for MCP server)
- Azure AD app registration with required permissions
- Access to Microsoft Planner

### Azure AD Setup

> **💡 Don't have an Azure subscription?** No problem! You don't need one. See [SETUP_WITHOUT_AZURE_SUBSCRIPTION.md](SETUP_WITHOUT_AZURE_SUBSCRIPTION.md) for free options including the Microsoft 365 Developer Program.

1. Register an app in [Azure Portal](https://portal.azure.com)
2. Set redirect URI to `http://localhost` (Public client/native)
3. Add API permissions:
   - `Tasks.ReadWrite` (required for all task operations)
   - `Group.Read.All` (required for reading task comments)
   - `Group.ReadWrite.All` (required for adding task comments)
   - `offline_access` (optional, for token refresh)
4. Grant admin consent for permissions (required for Group permissions)
5. Note your `Tenant ID` and `Client ID`

> **Note:** The Group permissions require admin consent. After adding them, click "Grant admin consent" in the Azure Portal to enable comment functionality.

### Quick Install (Automated)

#### Linux/macOS

```bash
# Clone the repository
git clone <repo-url>
cd planner-task-creator-cli-mcp

# Run the installation script
./scripts/INSTALLATION.sh
```

#### Windows (PowerShell)

```powershell
# Clone the repository
git clone <repo-url>
cd planner-task-creator-cli-mcp

# Allow script execution (if needed)
Set-ExecutionPolicy -Scope CurrentUser RemoteSigned

# Run the installation script
.\scripts\INSTALLATION.ps1
```

#### Windows (Command Prompt)

```cmd
REM Clone the repository
git clone <repo-url>
cd planner-task-creator-cli-mcp

REM Run the installation script
scripts\INSTALLATION.bat
```

### Manual Install

#### Python CLI Setup (Linux/macOS)

```bash
# Clone the repository
git clone <repo-url>
cd planner-task-creator-cli-mcp

# Install Python dependencies
pip install -r requirements.txt

# Make CLI executable
chmod +x planner.py

# Optional: Create symlink for global access
mkdir -p ~/.planner-cli
cp planner.py ~/.planner-cli/
ln -s ~/.planner-cli/planner.py /usr/local/bin/planner
```

#### Python CLI Setup (Windows)

```powershell
# Clone the repository
git clone <repo-url>
cd planner-task-creator-cli-mcp

# Create and activate virtual environment
python -m venv venv
.\venv\Scripts\Activate.ps1

# Install Python dependencies
pip install -r requirements.txt

# Optional: Copy CLI to user directory
mkdir "$env:USERPROFILE\.planner-cli" -Force
Copy-Item planner.py "$env:USERPROFILE\.planner-cli\"
```

#### MCP Server Setup

```bash
# Install Node dependencies
npm install

# Build TypeScript
npm run build

# The compiled server will be in dist/server.js
```

## Configuration

### Environment Variables

**Linux/macOS (bash):**
```bash
export TENANT_ID="your-tenant-id"
export CLIENT_ID="your-client-id"
export PLANNER_DEFAULT_PLAN="My Plan"
export PLANNER_DEFAULT_BUCKET="To Do"
export PLANNER_CONFIG_PATH="~/.planner-cli/config.json"  # Optional
```

**Windows (PowerShell):**
```powershell
$env:TENANT_ID = "your-tenant-id"
$env:CLIENT_ID = "your-client-id"
$env:PLANNER_DEFAULT_PLAN = "My Plan"
$env:PLANNER_DEFAULT_BUCKET = "To Do"
```

**Windows (Command Prompt):**
```cmd
set TENANT_ID=your-tenant-id
set CLIENT_ID=your-client-id
set PLANNER_DEFAULT_PLAN=My Plan
set PLANNER_DEFAULT_BUCKET=To Do
```

### Config File

Create config file at:
- **Linux/macOS:** `~/.planner-cli/config.json`
- **Windows:** `%USERPROFILE%\.planner-cli\config.json`

```json
{
  "tenant_id": "your-tenant-id",
  "client_id": "your-client-id",
  "default_plan": "My Plan",
  "default_bucket": "To Do"
}
```

### Configuration Precedence

1. CLI flags (highest priority)
2. Environment variables
3. Config file
4. Prompt for missing values (lowest priority)

## Usage

### Python CLI

#### Initialize Authentication

```bash
python planner.py init-auth
```

This will display a device code and URL for authentication. Visit the URL and enter the code to complete authentication.

#### Set Default Plan and Bucket

```bash
python planner.py set-defaults --plan "My Plan" --bucket "To Do"
```

#### List Plans

```bash
python planner.py list-plans
```

#### List Buckets

```bash
python planner.py list-buckets --plan "My Plan"
```

#### Create a Task

**Minimal:**
```bash
python planner.py add --title "Complete project report"
```

**With all options:**
```bash
python planner.py add \
  --title "Complete project report" \
  --plan "Q4 Projects" \
  --bucket "In Progress" \
  --desc "Write and submit quarterly report with metrics" \
  --due "2024-12-31" \
  --labels "Label1,Label3" \
  --verbose
```

### MCP Server

#### Configuration

Add to your MCP client configuration (e.g., Claude Desktop):

```json
{
  "mcpServers": {
    "planner": {
      "command": "node",
      "args": ["/path/to/planner-mcp-server/dist/server.js"],
      "env": {
        "TENANT_ID": "your-tenant-id",
        "CLIENT_ID": "your-client-id",
        "PLANNER_DEFAULT_PLAN": "My Plan",
        "PLANNER_DEFAULT_BUCKET": "To Do"
      }
    }
  }
}
```

#### Available Tools

**Core Tools:**
1. **planner_initAuth**: Initialize authentication
2. **planner_createTask**: Create a new task
3. **planner_setDefaults**: Set default plan and bucket
4. **planner_listPlans**: List available plans
5. **planner_listBuckets**: List buckets in a plan

**Task Management:**
6. **planner_listTasks**: List tasks in a plan or bucket (includes descriptions)
7. **planner_findTask**: Find a task by ID or title (includes description)
8. **planner_completeTask**: Mark a task as complete
9. **planner_moveTask**: Move a task to a different bucket
10. **planner_updateTask**: Update task properties (title, description, labels)
11. **planner_deleteTask**: Delete a task

**Subtasks:**
12. **planner_addSubtask**: Add a subtask (checklist item)
13. **planner_listSubtasks**: List subtasks for a task
14. **planner_completeSubtask**: Mark a subtask as complete

**Comments:**
15. **planner_listComments**: List all comments on a task
16. **planner_addComment**: Add a comment to a task

**User Management:**
17. **planner_searchUsers**: Search for users by name
18. **planner_lookupUser**: Resolve user identifier to full details

**Bucket Management:**
19. **planner_createBucket**: Create a new bucket
20. **planner_deleteBucket**: Delete a bucket
21. **planner_renameBucket**: Rename a bucket
22. **planner_moveBucketTasks**: Move all tasks from one bucket to another

## API Reference

### CLI Commands

#### `init-auth`
Initialize OAuth authentication with Microsoft.

**Usage:** `python planner.py init-auth`

#### `set-defaults`
Set default plan and bucket for task creation.

**Options:**
- `--plan TEXT`: Default plan name or ID (required)
- `--bucket TEXT`: Default bucket name or ID (required)

#### `list-plans`
List all available plans accessible to the user.

**Usage:** `python planner.py list-plans`

#### `list-buckets`
List all buckets in a specific plan.

**Options:**
- `--plan TEXT`: Plan name or ID (required)

#### `add`
Create a new task in Microsoft Planner.

**Options:**
- `--title TEXT`: Task title (required)
- `--plan TEXT`: Plan name or ID (optional if default is set)
- `--bucket TEXT`: Bucket name or ID (optional if default is set)
- `--desc TEXT`: Task description (optional)
- `--due TEXT`: Due date in YYYY-MM-DD format (optional)
- `--labels TEXT`: Comma-separated labels like "Label1,Label3" (optional)
- `--verbose`: Enable verbose output (optional)

#### `list-tasks-cmd`
List tasks in a plan or bucket. Task descriptions are automatically included.

**Options:**
- `--plan TEXT`: Plan name or ID (required)
- `--bucket TEXT`: Bucket name or ID (optional)
- `--incomplete`: Show only incomplete tasks (optional)

#### `find-task-cmd`
Find a task by ID or title. Returns full task details including description.

**Options:**
- `--task TEXT`: Task ID or title (required)
- `--plan TEXT`: Plan name or ID (required for title-based search)

#### `list-comments-cmd`
List all comments on a task.

**Options:**
- `--task TEXT`: Task ID or title (required)
- `--plan TEXT`: Plan name or ID (required)

#### `add-comment-cmd`
Add a comment to a task. Note: Comments can only be added to tasks that already have a conversation thread (typically created via Planner UI).

**Options:**
- `--task TEXT`: Task ID or title (required)
- `--comment TEXT`: Comment text to add (required)
- `--plan TEXT`: Plan name or ID (required)

### Label Format

Labels should be specified as comma-separated values: `Label1,Label2,Label3`

These are mapped to Planner categories:
- `Label1` → `category1`
- `Label2` → `category2`
- etc.

## Development

### Running Tests

```bash
# Run all tests
pytest

# Run with coverage
pytest --cov=planner --cov-report=html

# Run specific test file
pytest tests/test_auth.py

# Run with verbose output
pytest -v
```

### Project Structure

```
.
├── planner.py              # Main Python CLI
├── src/
│   └── server.ts          # MCP server implementation
├── tests/
│   ├── conftest.py        # Test fixtures
│   ├── test_auth.py       # Authentication tests
│   ├── test_config.py     # Configuration tests
│   ├── test_resolution.py # Resolution tests
│   ├── test_task_creation.py # Task creation tests
│   └── test_cli_commands.py  # CLI command tests
├── 0-docs/
│   ├── prd.md             # Product requirements
│   └── implementation steps/  # Detailed specs
├── requirements.txt        # Python dependencies
├── package.json           # Node.js dependencies
└── README.md              # This file
```

### Module Overview

1. **Authentication (001)**: OAuth device code flow with MSAL
2. **Graph Client (002)**: HTTP client for Microsoft Graph API
3. **Configuration (003)**: Config file management
4. **Resolution (004)**: Plan and bucket name-to-ID resolution
5. **Task Creation (005)**: Task creation with all fields
6. **CLI Commands (006)**: Typer-based CLI interface
7. **Error Handling (007)**: Structured JSON error responses
8. **MCP Server (008)**: Node.js wrapper for AI integration
9. **Testing (009)**: Comprehensive test suite

## Error Handling

All errors are returned as structured JSON:

```json
{
  "code": "ErrorCode",
  "message": "Human-readable error message",
  "candidates": [{"id": "...", "name": "..."}]
}
```

### Error Codes

- `ConfigError`: Missing required configuration
- `NotFound`: Resource not found (with candidates)
- `Ambiguous`: Multiple matches (with candidates)
- `AuthError`: Authentication failure
- `UpstreamError`: Graph API error

## Security

- 🔐 Tokens are stored securely:
  - Linux/macOS: `~/.planner-cli/msal_cache.bin` with 0600 permissions
  - Windows: `%USERPROFILE%\.planner-cli\msal_cache.bin`
- 🔒 Config file permissions are set to 0600 (Unix) or user-only access (Windows)
- 🚫 Tokens are never logged or exposed in output
- ✅ OAuth device code flow for secure authentication

## Troubleshooting

### Authentication Issues

**Problem:** Device code flow times out

**Solution:** Ensure you complete authentication within 15 minutes and have the required permissions

### Resolution Issues

**Problem:** "Plan not found" error

**Solution:** Use `list-plans` to see available plans. Plan names are case-insensitive but must match exactly.

**Problem:** "Multiple plans match" (Ambiguous)

**Solution:** Use the plan ID instead of name, or ensure unique naming

### Permission Issues

**Problem:** "Authorization failed: insufficient permissions"

**Solution:** Ensure your Azure AD app has the required API permissions and admin consent

### MCP Server Issues

**Problem:** MCP server not connecting

**Solution:**
1. Ensure Python CLI is working standalone first
2. Check that `PLANNER_CLI_PATH` points to correct location
3. Verify environment variables are set in MCP config

## Project Structure

```
planner-task-creator-cli-mcp/
├── planner.py              # Main CLI entry point
├── planner_lib/            # Modular Python library (25 files)
│   ├── auth.py            # Authentication
│   ├── config.py          # Configuration
│   ├── graph_client.py    # Graph API client
│   ├── resolution*.py     # Plan/bucket resolution
│   ├── task_*.py          # Task operations
│   └── cli_*.py           # CLI commands
├── src/                   # TypeScript MCP server
│   ├── server.ts          # Main entry point
│   └── server/            # Modular server (7 files)
├── tests/                 # Test suite (68 tests)
│   ├── test_*.py          # Unit tests
│   └── test_task_*/       # Modular test suites
├── docs/                  # Documentation
│   ├── README.md          # Documentation index
│   ├── QUICKSTART.md      # Quick start guide
│   ├── SETUP_GUIDE.md     # Complete setup
│   └── *.md               # Other guides
├── scripts/               # Installation & setup scripts
│   ├── INSTALLATION.sh    # Automated installer (Linux/macOS)
│   ├── INSTALLATION.ps1   # Automated installer (Windows PowerShell)
│   ├── INSTALLATION.bat   # Automated installer (Windows CMD)
│   ├── setup-cursor-mcp.sh # Cursor setup
│   └── test-*.sh          # Test scripts
├── 0-docs/                # Implementation specs
│   ├── implementation steps/ # Detailed specs
│   ├── prd.md            # Product requirements
│   └── ROADMAP.md        # Project roadmap
├── package.json           # Node.js dependencies
├── requirements.txt       # Python dependencies
└── README.md              # This file
```

## Contributing

Contributions are welcome! Please:

1. Follow the existing code structure
2. Add tests for new features
3. Update documentation
4. Ensure all tests pass

## License

MIT License - see LICENSE file for details

## Support

For issues and questions:
- Check the troubleshooting section
- Review the detailed specifications in `0-docs/implementation steps/`
- Open an issue on GitHub

## Author

**Babak Bandpey** — [cocode.dk](https://cocode.dk) | [LinkedIn](https://linkedin.com/in/babakbandpey) | [GitHub](https://github.com/cocodedk)

## License

Apache-2.0 | © 2026 [Cocode](https://cocode.dk) | Created by [Babak Bandpey](https://linkedin.com/in/babakbandpey)

## Acknowledgments

- Microsoft Graph API for Planner integration
- MSAL Python library for authentication
- Typer and Rich for CLI framework
- MCP SDK for AI assistant integration