Skip to content

Commit 4eaa546

Browse files
committed
feat: Add Origin header for cloud authentication and update Pages API documentation
This commit completes the Pages API implementation with session authentication support: ## Changes ### Authentication Fix (Critical) - Added Origin header alongside Referer in session authentication requests - Required for cloud Plane instances (api.plane.so) CORS validation - Fixes authentication failures on cloud instances while maintaining self-hosted compatibility **Files modified:** - `src/common/auth.ts`: Added Origin header to CSRF token request and login POST ### Documentation Updates - Added comprehensive Pages API documentation to README - Documented all 18 new Pages API tools with parameters - Added session authentication setup instructions - Included examples for both Claude Desktop and VSCode configurations - Documented new environment variables: PLANE_EMAIL, PLANE_PASSWORD - Clarified authentication method differences (API Key vs Session Auth) **Files modified:** - `README.md`: Added Pages API section, session auth configuration examples ## Verification - ✅ All 18 Pages API tools tested and working on cloud instance (api.plane.so) - ✅ Session authentication works on both cloud and self-hosted instances - ✅ Build succeeds with no TypeScript errors - ✅ No secrets committed in code - ✅ Backward compatible with existing API key authentication ## Pages API Tools Added 18 new MCP tools for Plane Pages management: - Core CRUD: list, create, get, update, delete - Lock management: lock, unlock - Organization: favorite, unfavorite, duplicate - Archive: archive, unarchive - Content: get/update description, set access - History: get versions, get version, get summary - Authentication: plane_login for session auth Closes #43
1 parent 01cfbe2 commit 4eaa546

4 files changed

Lines changed: 434 additions & 48 deletions

File tree

README.md

Lines changed: 152 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -324,21 +324,126 @@ This server unlocks all sorts of useful capabilities for anyone working with Pla
324324
- Parameters:
325325
- `project_id` (string, required): UUID of the project
326326
- `issue_id` (string, required): UUID of the issue
327-
- `worklog_id` (string, required): UUID of the worklog
327+
- `worklog_id` (string, required): UUID of the worklog
328+
329+
### Pages (Session Authentication Required)
330+
331+
**Note:** Pages API tools require session authentication. Use `plane_login` first with your email and password.
332+
333+
- `plane_login`
334+
- Authenticate with Plane using email and password
335+
- Parameters:
336+
- `email` (string, required): Your Plane account email
337+
- `password` (string, required): Your Plane account password
338+
- `api_host_url` (string, optional): Plane API URL (defaults to https://api.plane.so/)
339+
340+
- `list_pages`
341+
- List all pages in a project
342+
- Parameters:
343+
- `project_id` (string, required): UUID of the project
344+
345+
- `get_page`
346+
- Get details of a specific page
347+
- Parameters:
348+
- `project_id` (string, required): UUID of the project
349+
- `page_id` (string, required): UUID of the page
350+
351+
- `create_page`
352+
- Create a new page
353+
- Parameters:
354+
- `project_id` (string, required): UUID of the project
355+
- `name` (string, required): Page name
356+
- `description` (string, optional): Page description
357+
- `access` (integer, optional): Access level (0=public, 1=private)
358+
359+
- `update_page`
360+
- Update a page's properties
361+
- Parameters:
362+
- `project_id` (string, required): UUID of the project
363+
- `page_id` (string, required): UUID of the page
364+
- `name` (string, optional): New page name
365+
- `description` (string, optional): New description
366+
- `access` (integer, optional): New access level
367+
368+
- `delete_page`
369+
- Delete a page permanently
370+
- Parameters:
371+
- `project_id` (string, required): UUID of the project
372+
- `page_id` (string, required): UUID of the page
373+
374+
- `lock_page` / `unlock_page`
375+
- Lock or unlock a page for editing
376+
- Parameters:
377+
- `project_id` (string, required): UUID of the project
378+
- `page_id` (string, required): UUID of the page
379+
380+
- `favorite_page` / `unfavorite_page`
381+
- Add or remove page from favorites
382+
- Parameters:
383+
- `project_id` (string, required): UUID of the project
384+
- `page_id` (string, required): UUID of the page
385+
386+
- `archive_page` / `unarchive_page`
387+
- Archive or restore a page
388+
- Parameters:
389+
- `project_id` (string, required): UUID of the project
390+
- `page_id` (string, required): UUID of the page
391+
392+
- `duplicate_page`
393+
- Create a copy of a page
394+
- Parameters:
395+
- `project_id` (string, required): UUID of the project
396+
- `page_id` (string, required): UUID of the page to duplicate
397+
398+
- `get_page_description` / `update_page_description`
399+
- Get or update page HTML content
400+
- Parameters:
401+
- `project_id` (string, required): UUID of the project
402+
- `page_id` (string, required): UUID of the page
403+
- `description_html` (string, required for update): HTML content
404+
405+
- `get_page_versions` / `get_page_version`
406+
- Get page version history
407+
- Parameters:
408+
- `project_id` (string, required): UUID of the project
409+
- `page_id` (string, required): UUID of the page
410+
- `version_id` (string, required for specific version): UUID of the version
411+
412+
- `get_pages_summary`
413+
- Get pages statistics for a project
414+
- Parameters:
415+
- `project_id` (string, required): UUID of the project
328416

329417

330418
## Configuration Parameters
331419

420+
### For API Key Authentication (Most Tools)
332421
- `PLANE_API_KEY` - Your Plane API token. You can generate one from the Workspace Settings > API Tokens page (`/settings/api-tokens/`) in the Plane app.
333422
- `PLANE_WORKSPACE_SLUG` - The workspace slug for your Plane instance. The workspace-slug represents the unique workspace identifier for a workspace in Plane. It can be found in the URL.
334423
- `PLANE_API_HOST_URL` (optional) - The host URL of the Plane API Server. Defaults to https://api.plane.so/
335424

425+
### For Session Authentication (Pages API Only)
426+
Pages API tools require session authentication using email/password instead of API key. Use the `plane_login` tool before accessing Pages tools.
427+
428+
**Environment variables for Pages authentication:**
429+
- `PLANE_EMAIL` (optional) - Your Plane account email for session authentication
430+
- `PLANE_PASSWORD` (optional) - Your Plane account password for session authentication
431+
432+
**Note:** You can either:
433+
1. Set these environment variables in your MCP client configuration, OR
434+
2. Call `plane_login` tool manually with email/password when needed
435+
436+
**Authentication methods by feature:**
437+
- **Projects, Issues, Modules, Cycles, Labels, States, Work Logs**: API Key (PLANE_API_KEY)
438+
- **Pages**: Session Auth (email/password via `plane_login` tool)
439+
336440
## Usage
337441

338442
### Claude Desktop
339443

340444
You can add Plane to [Claude Desktop](https://modelcontextprotocol.io/quickstart/user) by updating your `claude_desktop_config.json`:
341445

446+
**For standard API key authentication (Projects, Issues, etc.):**
342447
```json
343448
{
344449
"mcpServers": {
@@ -358,10 +463,35 @@ You can add Plane to [Claude Desktop](https://modelcontextprotocol.io/quickstart
358463
}
359464
```
360465

466+
**To also use Pages API (with session authentication):**
467+
```json
468+
{
469+
"mcpServers": {
470+
"plane": {
471+
"command": "npx",
472+
"args": [
473+
"-y",
474+
"@makeplane/plane-mcp-server"
475+
],
476+
"env": {
477+
"PLANE_API_KEY": "<YOUR_API_KEY>",
478+
"PLANE_API_HOST_URL": "<HOST_URL_FOR_SELF_HOSTED>",
479+
"PLANE_WORKSPACE_SLUG": "<YOUR_WORKSPACE_SLUG>",
480+
"PLANE_EMAIL": "<YOUR_EMAIL>",
481+
"PLANE_PASSWORD": "<YOUR_PASSWORD>"
482+
}
483+
}
484+
}
485+
}
486+
```
487+
488+
**Note:** If you don't set `PLANE_EMAIL` and `PLANE_PASSWORD`, you can still use Pages tools by calling `plane_login` manually in your conversation.
489+
361490
### VSCode
362491

363492
You can also connect Plane to [VSCode](https://code.visualstudio.com/docs/copilot/chat/mcp-servers#_add-an-mcp-server) by editing your `.vscode.json` or `mcp.json` file:
364493

494+
**For standard API key authentication:**
365495
```json
366496
{
367497
"servers": {
@@ -379,7 +509,28 @@ You can also connect Plane to [VSCode](https://code.visualstudio.com/docs/copilo
379509
}
380510
}
381511
}
512+
```
382513

514+
**To also use Pages API (with session authentication):**
515+
```json
516+
{
517+
"servers": {
518+
"plane": {
519+
"command": "npx",
520+
"args": [
521+
"-y",
522+
"@makeplane/plane-mcp-server"
523+
],
524+
"env": {
525+
"PLANE_API_KEY": "<YOUR_API_KEY>",
526+
"PLANE_API_HOST_URL": "<HOST_URL_FOR_SELF_HOSTED>",
527+
"PLANE_WORKSPACE_SLUG": "<YOUR_WORKSPACE_SLUG>",
528+
"PLANE_EMAIL": "<YOUR_EMAIL>",
529+
"PLANE_PASSWORD": "<YOUR_PASSWORD>"
530+
}
531+
}
532+
}
533+
}
383534
```
384535

385536
## License

0 commit comments

Comments
 (0)