plane-mcp-server: Instructions file for Claude Code

CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

Project Overview

Plane MCP Server — a Python-based Model Context Protocol server that exposes Plane's project management API as MCP tools. Built on FastMCP with the official plane-sdk. Supports three transport modes: stdio (local), HTTP (with OAuth or header auth), and SSE (legacy).

Common Commands

# Install dependencies (uses uv)
uv pip install -e ".[dev]"

# Run the server locally (stdio mode)
PLANE_API_KEY=... PLANE_WORKSPACE_SLUG=... python -m plane_mcp stdio

# Run HTTP server
python -m plane_mcp http

# Run all tests
pytest

# Run a single test
pytest tests/test_integration.py::test_full_integration -v

# Run tests with env vars from file
export $(cat .env.test.local | xargs) && pytest tests/ -v

# Format code (line length: 120)
ruff format plane_mcp/

# Lint (rules: E, F, I, UP, B; line length: 120)
ruff check plane_mcp/

Architecture

Entry Point & Transport Modes

plane_mcp/__main__.py parses a positional arg (stdio, http, or sse) and launches the corresponding server:

• stdio: Requires PLANE_API_KEY + PLANE_WORKSPACE_SLUG env vars. Runs locally.
• http: Starts on port 8211 with two auth endpoints — OAuth (/oauth/mcp) and header-based PAT (/http/api-key/mcp).
• sse: Legacy OAuth-only SSE transport.

Server Factories (server.py)

Three factory functions (get_oauth_mcp, get_header_mcp, get_stdio_mcp) each create a FastMCP instance and configure the appropriate auth provider, then hand it to _configured() for the middleware stack and tools — one place, so a transport cannot be left a middleware behind. OAuth/HTTP modes use Redis for token storage (falls back to in-memory).

Middleware (middleware.py)

Ordered as registered; the earlier one wraps the later:

Middleware	Does
PlaneLoggingMiddleware	structured logging, plus the tool name
CoerceArguments	repairs arguments a client encoded as strings, before validation (coercion.py)
ValidateActionArguments	refuses a call with no action, and arguments the chosen action does not accept, from the ACTIONS declaration