# Planner MCP Server

A Model Context Protocol (MCP) server that enables Claude to interact with Microsoft Planner through the Microsoft Graph API.

## Features

- **Authentication**: OAuth 2.0 device code flow for secure authentication
- **Plans Management**: List and view Planner plans
- **Buckets Management**: List, create, and manage buckets within plans
- **Tasks Management**: Create, update, delete, and view tasks
- **Checklists**: Add, update, and remove checklist items on tasks
- **Token Persistence**: Stores access tokens across server restarts

## Prerequisites

- Node.js 18+ or newer
- npm or yarn
- Microsoft account with access to Planner

## Installation

1. Clone or download this repository
2. Install dependencies:

```bash
cd planner-mcp
npm install
```

3. Build the project:

```bash
npm run build
```

## Authentication

Before using the Planner tools, you need to authenticate:

1. Start the authentication flow by calling the `auth_start` tool
2. Visit the displayed verification URL
3. Enter the provided code
4. Sign in with your Microsoft account
5. Use the `auth_poll` tool to check if authentication is complete

The access token will be saved locally and reused for future sessions.

## Configuration

### Option 1: Using CLI (Recommended)

```bash
claude mcp add --transport stdio planner node /path/to/planner-mcp/build/index.js
```

### Option 2: Manual Configuration

Add this server to your Claude Desktop configuration file:

**Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
**macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`

```json
{
  "mcpServers": {
    "planner": {
      "command": "node",
      "args": ["/path/to/planner-mcp/build/index.js"]
    }
  }
}
```

> **Note:** Replace `/path/to/planner-mcp/build/index.js` with the actual path to your cloned repository.

## Available Tools

### Authentication Tools

- **`auth_start`**: Start the Planner authentication flow (device code)
- **`auth_poll`**: Check if authentication is complete

### Plan Tools

- **`list_plans`**: List all Microsoft Planner plans for the current user
- **`get_plan`**: Get detailed information about a specific plan

### Bucket Tools

- **`list_buckets`**: List all buckets in a plan
- **`create_bucket`**: Create a new bucket in a plan

### Task Tools

- **`list_tasks`**: List tasks in a plan or bucket with filtering options (priority, due date, status, etc.)
- **`get_task`**: Get detailed information about a specific task
- **`create_task`**: Create a new task in a bucket with title, description, priority, and due date
- **`update_task`**: Update an existing task (title, description, priority, bucket, due date, checklist, etc.)
- **`delete_task`**: Delete a task

**Checklist parameter** (on `create_task` and `update_task`): pass `checklist` as an object keyed by item ID, same style as `assignments`:
- To **add** an item, use any unique string as the key with `{"title": "...", "isChecked": false}`
- To **update** an item, use its existing item ID (from `get_task`/`list_tasks` with `includeDetails: true`) with just the fields to change
- To **remove** an item, set its ID's value to `null`

Example:
```json
{
  "taskId": "your-task-id",
  "checklist": {
    "buy-milk": { "title": "Buy milk", "isChecked": false },
    "existing-item-id-from-get-task": { "isChecked": true },
    "item-id-to-remove": null
  }
}
```

Checklist items are visible on any task fetched via `get_task` or `list_tasks` with `includeDetails: true` (under `details.checklist`, keyed by item ID).

**Priority Levels:**
- `1` = Urgent (highest priority)
- `3` = Important (high priority)
- `5` = Medium (normal priority)
- `9` = Low (lowest priority)

## Required Permissions

The Microsoft Graph API requires the following permissions for Planner:

- `Group.Read.All` - To list plans and buckets
- `Tasks.ReadWrite` - To read, create, update, and delete tasks

## Example Workflows

### Create a new task

1. List plans: `list_plans`
2. List buckets in a plan: `list_buckets` with the plan ID
3. Create a task: `create_task` with plan ID, bucket ID, title, and priority (1=urgent, 3=important, 5=medium, 9=low)

Example:
```json
{
  "planId": "your-plan-id",
  "bucketId": "your-bucket-id",
  "title": "Complete project proposal",
  "description": "Write and submit the Q1 project proposal",
  "priority": 1,
  "dueDateTime": "2026-03-30T17:00:00Z"
}
```

### Move a task to another bucket

1. Get task details: `get_task`
2. Update task: `update_task` with the new bucket ID

### Filter tasks by priority

1. List tasks with priority filter: `list_tasks` with plan ID and priority parameter

Example:
```json
{
  "planId": "your-plan-id",
  "priority": 1
}
```

This will show only urgent tasks (priority 1).

### Update task due date

1. Get task details: `get_task`
2. Update task: `update_task` with the new due date in ISO 8601 format (e.g., "2025-12-31T23:59:59Z")

## Troubleshooting

### Authentication Issues

If authentication fails, try these steps:

1. Delete the `.access-token.txt` file
2. Call `auth_start` again
3. Make sure you're using a Microsoft account that has access to Planner

### "Not authenticated" Error

If you get a "Not authenticated" error:

1. Make sure you've completed the authentication flow
2. Check that the `.access-token.txt` file exists and contains a valid token
3. If the token has expired, run `auth_start` again

### Permission Errors

If you get permission errors:

- Make sure your Microsoft account has access to the specified plan
- Check that the required permissions are granted in your Azure AD app

## Development

### Build

```bash
npm run build
```

### Watch mode

```bash
npm run watch
```

### Start server

```bash
npm start
```

## License

ISC

## Contributing

Contributions are welcome! Please feel free to submit issues or pull requests.