# Planview MCP Server

MCP server for Planview Enterprise One with Okta passwordless authentication and automated timesheet completion.

## What This Does

- 🔐 Authenticate to Planview using Okta Verify (no passwords)
- 📊 Access Planview API (work items, projects, users)
- 🤖 Auto-complete timesheets with `/complete-timesheets` command

## Quick Start

### Step 1: Clone and Install

```bash
git clone <your-repo-url>
cd planview-mcp
npm install
npx playwright install chromium
```

### Step 2: Configure

**Linux/macOS:**
```bash
cp .mcp.json.example .mcp.json
nano .mcp.json  # or use any text editor
```

**Windows:**
```bash
copy .mcp.json.windows.example .mcp.json
notepad .mcp.json  # or use any text editor
```

Edit the `env` section in `.mcp.json` with your Planview details:
- `PLANVIEW_BASE_URL`: Your company's Planview URL
- `OKTA_USERNAME`: Your email address

### Step 3: Authenticate

```bash
npm run okta-login
```

This opens a browser and waits for you to approve the Okta Verify notification on your phone.

### Step 4: Build and Restart Claude

```bash
npm run build
```

Then restart Claude Code to load the MCP server.

## Usage

### Available Commands

| Command | Description |
|---------|-------------|
| `/complete-timesheets` | Auto-fills all overdue timesheets (8h/day, 40h/week) |

### Available Tools

Use these directly in Claude:

- `planview_get_work_items` - List work items
- `planview_get_projects` - List projects
- `planview_get_current_user` - Get your user info
- `planview_update_work_item` - Update a work item
- `planview_execute_request` - Make custom API calls

### More Examples

See [EXAMPLES.md](EXAMPLES.md) for detailed usage examples including:
- Timesheet automation workflows
- Work item management
- Custom API requests
- Creating your own commands
- Troubleshooting tips

## How It Works

This setup uses **two MCP servers**:

1. **Planview MCP** (this repo) - Handles Planview API and authentication
2. **Playwright MCP** (auto-installed) - Handles browser automation for timesheets

Both are configured in your `.mcp.json` file. Playwright MCP downloads automatically when Claude starts.

**Authentication flow:**
1. You run `npm run okta-login` once
2. Creates `planview-auth.json` with your session
3. Both MCP servers use this session file
4. Re-authenticate when session expires

## Troubleshooting

| Problem | Solution |
|---------|----------|
| "Authentication error" | Run `npm run okta-login` |
| "Can't see browser during login" | Add `HEADLESS=true` before `npm run okta-login` |
| Windows npx warning | Use `.mcp.json.windows.example` (has `cmd /c` wrapper) |
| "Timesheet automation fails" | Check `.mcp.json` has both `planview` and `playwright` servers |
| "Missing PLANVIEW_BASE_URL" | Check the `env` section in `.mcp.json` |

## Configuration

### Local Setup (Recommended)

Use `.mcp.json` in this repo directory.

**Linux/macOS:** Uses `npx` directly
```json
{
  "mcpServers": {
    "planview": {
      "command": "node",
      "args": ["dist/index.js"],
      "env": {
        "PLANVIEW_BASE_URL": "https://yourcompany.pvcloud.com/planview",
        "PLANVIEW_STORAGE_STATE": "planview-auth.json",
        "OKTA_USERNAME": "your.email@company.com"
      }
    },
    "playwright": {
      "command": "npx",
      "args": ["-y", "@playwright/mcp@latest"]
    }
  }
}
```

**Windows:** Requires `cmd /c` wrapper
```json
{
  "mcpServers": {
    "planview": {
      "command": "node",
      "args": ["dist/index.js"],
      "env": {
        "PLANVIEW_BASE_URL": "https://yourcompany.pvcloud.com/planview",
        "PLANVIEW_STORAGE_STATE": "planview-auth.json",
        "OKTA_USERNAME": "your.email@company.com"
      }
    },
    "playwright": {
      "command": "cmd",
      "args": ["/c", "npx", "-y", "@playwright/mcp@latest"]
    }
  }
}
```

### Global Setup (All Projects)

Add to Claude Code MCP settings with **absolute paths**.

**Linux/macOS:**
```json
{
  "mcpServers": {
    "planview": {
      "command": "node",
      "args": ["/full/path/to/planview-mcp/dist/index.js"],
      "env": {
        "PLANVIEW_BASE_URL": "https://yourcompany.pvcloud.com/planview",
        "PLANVIEW_STORAGE_STATE": "/full/path/to/planview-mcp/planview-auth.json",
        "OKTA_USERNAME": "your.email@company.com"
      }
    },
    "playwright": {
      "command": "npx",
      "args": ["-y", "@playwright/mcp@latest"]
    }
  }
}
```

**Windows:**
```json
{
  "mcpServers": {
    "planview": {
      "command": "node",
      "args": ["C:\\full\\path\\to\\planview-mcp\\dist\\index.js"],
      "env": {
        "PLANVIEW_BASE_URL": "https://yourcompany.pvcloud.com/planview",
        "PLANVIEW_STORAGE_STATE": "C:\\full\\path\\to\\planview-mcp\\planview-auth.json",
        "OKTA_USERNAME": "your.email@company.com"
      }
    },
    "playwright": {
      "command": "cmd",
      "args": ["/c", "npx", "-y", "@playwright/mcp@latest"]
    }
  }
}
```

## Why Clone Instead of Direct Install?

This MCP requires cloning because:
- Authentication creates `planview-auth.json` locally
- Both MCP servers need access to the same auth file
- Each company has different Planview URLs
- Configuration is set in `.mcp.json` (committed to repo)

**Direct GitHub URL installation won't work** due to these local file requirements.

## Development

```bash
npm run dev    # Watch mode (auto-rebuild)
npm run build  # Build once
npm start      # Run server manually
```

## API Documentation

View Planview API docs at: `https://yourcompany.pvcloud.com/planview/swagger/index.html`

## Security

**Never commit these files** (already in `.gitignore`):
- `.mcp.json` - Your configuration with credentials
- `planview-auth.json` - Your session

## License

MIT