@mikey-semy/plane-mcp

v0.1.1

Published

a month ago

Plane MCP Server - Python implementation with NPM wrapper for easy usage

Downloads

16,634

0High
0Medium
0Low

mikey-semy

mcp model-context-protocol plane plane-so mcp-server python fastmcp

Plane MCP Server - Python Implementation

Plane's Model Context Protocol Server - Python реализация 🔌 ⌨️ 🔥

Предоставляет 48 инструментов для работы с проектами, задачами, модулями и циклами в Plane.

Оригинальный проект: makeplane/plane-mcp-server (TypeScript) plane.so | Topics: model-context-protocol mcp-server python fastmcp

📚 Документация

ARCHITECTURE.md - Архитектура и сравнение stdio vs
USAGE.md - Подробная инструкция по использованию NPM пакета
COPILOT_USAGE.md - Как использовать с GitHub Copilot в VSCode
CONTRIBUTING.md - Руководство для контрибьюторов
CHANGELOG.md - История изменений
NPM_PUBLISH.md - Публикация форка в NPM

✨ Возможности

✅ 48 инструментов - полное покрытие Plane API
✅ ** Transport** - HTTP сервер для удалённого доступа
✅ stdio Transport - для локальной интеграции с Claude Desktop
✅ Полный CRUD для Issues, Projects, Modules, Cycles
✅ Metadata Management - полное управление типами задач, метками, статусами
✅ Module/Cycle Issues - управление задачами в модулях и циклах
✅ Worklogs - отслеживание времени работы
✅ Issue Comments - работа с комментариями
✅ Readable Identifiers - поддержка PROJECT-123 формата
✅ Асинхронная архитектура - быстрая обработка запросов
✅ Docker Ready - готовые конфигурации для контейнеризации

📊 Краткий обзор инструментов

User (2 tools)

get_current_user - информация о текущем пользователе
get_workspace_members - список участников workspace

Metadata (14 tools)

Issue Types (4):

get_issue_type, create_issue_type, update_issue_type, delete_issue_type

States (5):

list_states, get_state, create_state, update_state, delete_state

Labels (5):

list_labels, get_label, create_label, update_label, delete_label

Projects (3 tools)

get_projects - список всех проектов
create_project - создание нового проекта
list_project_issues - список задач проекта

Issues (7 tools)

get_issue - детали конкретной задачи
get_issue_using_readable_identifier - получить задачу по читаемому ID (FIRST-123)
create_issue - создание задачи
update_issue - обновление задачи
delete_issue - удаление задачи
get_issue_comments - получить комментарии к задаче
add_issue_comment - добавить комментарий к задаче

Modules (5 tools)

list_modules - список модулей проекта
get_module - детали модуля
create_module - создание модуля
update_module - обновление модуля
delete_module - удаление модуля

Module Issues (3 tools)

list_module_issues - список задач в модуле
add_module_issues - добавить задачи в модуль
delete_module_issue - удалить задачу из модуля

Cycles (5 tools)

list_cycles - список циклов проекта
get_cycle - детали цикла
create_cycle - создание цикла
update_cycle - обновление цикла
delete_cycle - удаление цикла

Cycle Issues (4 tools)

list_cycle_issues - список задач в цикле
add_cycle_issues - добавить задачи в цикл
delete_cycle_issue - удалить задачу из цикла
transfer_cycle_issues - перенести задачи из одного цикла в другой

Worklogs (5 tools)

get_issue_worklogs - список рабочих логов задачи
get_total_worklogs - общее время логов проекта
create_worklog - создать рабочий лог
update_worklog - обновить рабочий лог
delete_worklog - удалить рабочий лог

Всего: 48 инструментов

🚀 Быстрый старт

Вариант 1: NPM (рекомендуется для локального использования)

Требования: Node.js 18+, uv

✅ Пакет опубликован в NPM: @mikey-semy/plane-mcp

# Использование без установки (npx)
npx -y @mikey-semy/plane-mcp

# Или глобальная установка
npm install -g @mikey-semy/plane-mcp
plane-mcp

Переменные окружения:

# Windows PowerShell
$env:PLANE_API_KEY="plane_xxxxxxxxxxxxxxxxxxxx"
$env:PLANE_WORKSPACE_SLUG="your-workspace-slug"
$env:PLANE_API_HOST_URL="https://api.plane.so/"  # опционально

# Linux/macOS
export PLANE_API_KEY="plane_xxxxxxxxxxxxxxxxxxxx"
export PLANE_WORKSPACE_SLUG="your-workspace-slug"
export PLANE_API_HOST_URL="https://api.plane.so/"  # опционально

Вариант 2: Docker (для продакшена)

1. Создайте `.env` файл:

cp .env.example .env

Отредактируйте .env и добавьте свои данные:

# Обязательные переменные
PLANE_API_KEY=plane_xxxxxxxxxxxxxxxxxxxx
PLANE_WORKSPACE_SLUG=your-workspace-slug

# Опциональные (значения по умолчанию)
PLANE_API_HOST_URL=https://api.plane.so/
MCP_HOST=0.0.0.0
MCP_PORT=8000

# Порт на хосте (если 8000 занят, измените на другой)
HOST_PORT=8000

Примечание: Если порт 8000 уже занят, измените HOST_PORT на другой (например, 8001, 9000).

2. Запуск с Docker Compose:

docker-compose up -d

Сервер будет доступен на http://localhost:HOST_PORT/ (по умолчанию http://localhost:8000/)

3. Проверка работы:

# Проверка здоровья контейнера
docker-compose ps

# Просмотр логов
docker-compose logs -f

# Остановка
docker-compose down

Локальная установка (для разработки)

Требования

Python 3.12+
uv (для управления пакетами)

Установка

# Установка uv (если ещё не установлен)
curl -LsSf https://astral.sh/uv/install.sh | sh

# Клонирование и установка зависимостей
cd plane-mcp
uv sync

# Создание .env файла
cp .env.example .env
# Отредактируйте .env, добавьте свои ключи

# Запуск сервера
uv run plane-mcp

Конфигурация

Переменные окружения

| Переменная | Описание | По умолчанию | Обязательная | |-----------|----------|--------------|--------------| | PLANE_API_KEY | API ключ Plane | - | ✅ | | PLANE_WORKSPACE_SLUG | Slug вашего workspace | - | ✅ | | PLANE_API_HOST_URL | URL Plane API | https://api.plane.so/ | ❌ | | MCP_HOST | Хост для HTTP сервера | 0.0.0.0 | ❌ | | MCP_PORT | Порт контейнера (внутренний) | 8000 | ❌ | | HOST_PORT | Порт хоста (внешний) для Docker | 8000 | ❌ |

Для продакшена: используйте .env.production с вашими настройками.

🌐 Развёртывание

Публичный NPM пакет

✅ Пакет опубликован и доступен: @mikey-semy/plane-mcp

Любой пользователь может использовать:

npx -y @mikey-semy/plane-mcp

Docker развёртывание

Используйте Docker Compose для продакшен развёртывания. Сервер будет доступен по HTTP на указанном порту.

Пример URL после развёртывания:

https://your-domain.com:9000/

Настройте свой домен в .env.production и используйте reverse proxy (Traefik/Nginx) для SSL.

⚠️ Безопасность развёртывания

ВАЖНО: endpoint предоставляет полный доступ к вашему Plane API!

Рекомендуемые меры защиты:

🔒 Не публикуйте URL публично - SSE endpoint содержит ваш API ключ
🛡️ Используйте VPN - ограничьте доступ только для вашей сети
🔐 Basic Auth - добавьте authentication на уровне Traefik/Nginx
🌐 IP Whitelist - разрешите доступ только с определённых IP
📝 Логирование - отслеживайте все подключения
🔄 Регулярно ротируйте API ключи

Пример Traefik с Basic Auth:

labels:
  - "traefik.http.middlewares.auth.basicauth.users=user:$$apr1$$..."
  - "traefik.http.routers.mcp.middlewares=auth"

Для личного использования рекомендуем stdio, а не публичный SSE сервер.

Использование с MCP клиентами

FastMCP автоматически поддерживает:

SSE (Server-Sent Events) - HTTP транспорт на http://host:port/sse
stdio - стандартный ввод/вывод для локальных клиентов

🤔 Какой вариант выбрать?

stdio (локальный) - рекомендуется:

✅ Можно работать с несколькими workspace одновременно
✅ Разные API ключи для разных workspace
✅ Полный контроль над конфигурацией
⚠️ Требует установку uv локально

SSE (удалённый) - для централизованного использования:

✅ Не требует Python/uv на клиентской машине
✅ Быстрое подключение (сервер уже работает)
✅ Единая конфигурация для команды
⚠️ Фиксированный workspace на сервере
⚠️ Требует сетевое подключение к серверу
🔒 Не публикуйте публичные URL - используйте VPN или authentication!

📖 Подробнее: COPILOT_USAGE.md

Подключение через VSCode

Добавьте конфигурацию в .vscode/mcp.json или mcp.json в корне проекта:

Вариант 1: NPM пакет (stdio) - для работы с разными workspace

Позволяет переключаться между workspace просто меняя env:

{
  "servers": {
    "plane-profitool": {
      "command": "npx",
      "args": ["-y", "@mikey-semy/plane-mcp"],
      "env": {
        "PLANE_API_KEY": "YOUR_PLANE_API_KEY",
        "PLANE_API_HOST_URL": "https://plane.equiply.ru/",
        "PLANE_WORKSPACE_SLUG": "profitool-store"
      }
    },
    "plane-another-project": {
      "command": "npx",
      "args": ["-y", "@mikey-semy/plane-mcp"],
      "env": {
        "PLANE_API_KEY": "YOUR_PLANE_API_KEY",
        "PLANE_API_HOST_URL": "https://plane.equiply.ru/",
        "PLANE_WORKSPACE_SLUG": "another-workspace"
      }
    }
  }
}

Вариант 2: Удалённое подключение (SSE)

Подключение к вашему развёрнутому серверу. Внимание: workspace фиксирован на сервере!

Без авторизации:

{
  "servers": {
    "plane": {
      "url": "https://your-mcp-server.example.com:9000/sse"
    }
  }
}

С Basic Auth (рекомендуется для production):

{
  "servers": {
    "plane": {
      "url": "https://mcp.plane.lol.ru:9000/sse",
      "headers": {
        "Authorization": "Basic YWRtaW46UlolXJlUGFzc3dvcmQxMjM="
      }
    }
  }
}

Примечание:

Замените your-mcp-server.example.com на адрес вашего сервера.
Для генерации Authorization заголовка см. _AUTH.md
НЕ используйте формат https://user:pass@host/ - не поддерживается клиентами MCP

Для работы с несколькими workspace через : разверните отдельный сервер для каждого workspace.

Подключение через Claude Desktop

Добавьте конфигурацию в claude_desktop_config.json:

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

Вариант 1: NPM пакет (рекомендуется)

{
  "mcpServers": {
    "plane": {
      "command": "npx",
      "args": ["-y", "@mikey-semy/plane-mcp"],
      "env": {
        "PLANE_API_KEY": "plane_xxxxxxxxxxxxxxxxxxxx",
        "PLANE_WORKSPACE_SLUG": "your-workspace-slug",
        "PLANE_API_HOST_URL": "https://api.plane.so/"
      }
    }
  }
}

Вариант 2: Локальная установка (uv)

{
  "mcpServers": {
    "plane": {
      "command": "uv",
      "args": ["run", "plane-mcp"],
      "env": {
        "PLANE_API_KEY": "plane_xxxxxxxxxxxxxxxxxxxx",
        "PLANE_WORKSPACE_SLUG": "your-workspace-slug",
        "PLANE_API_HOST_URL": "https://api.plane.so/"
      }
    }
  }
}

После сохранения конфигурации перезапустите VSCode или Claude Desktop.

Разработка

Структура проекта

plane-mcp/
├── src/
│   └── plane_mcp/
│       ├── __init__.py
│       ├── server.py          # Основной сервер
│       ├── schemas/           # Pydantic модели (новая структура)
│       │   ├── __init__.py
│       │   ├── base.py        # Базовые классы и миксины
│       │   ├── project.py     # Project
│       │   ├── issue.py       # Issue, IssueType
│       │   ├── module.py      # Module, ModuleIssue
│       │   ├── cycle.py       # Cycle, CycleIssue
│       │   ├── metadata.py    # State, Label
│       │   └── worklog.py     # IssueWorkLog
│       ├── common/
│       │   ├── request_helper.py  # HTTP клиент для Plane API
│       │   └── version.py
│       └── tools/
│           ├── cycle_issues.py
│           ├── cycles.py
│           ├── issue_comments.py
│           ├── issues.py
│           ├── metadata.py
│           ├── module_issues.py
│           ├── modules.py
│           ├── projects.py
│           ├── user.py
│           └── worklogs.py
├── pyproject.toml
├── Dockerfile
└── docker-compose.yml

Архитектура схем

Все Pydantic модели организованы с использованием наследования для DRY-кода:

Базовые классы (base.py):

PlaneBaseModel - корневой класс с общими настройками
TimestampedModel - добавляет created_at, updated_at
AuditedModel - добавляет created_by, updated_by
WorkspaceOwnedModel - добавляет workspace
ProjectOwnedModel - добавляет project
SoftDeletableModel - добавляет deleted_at
ArchivableModel - добавляет archived_at
ExternallyIdentifiableModel - добавляет external_id, external_source
SortableModel - добавляет sort_order
FullAuditModel - объединяет все вышеперечисленные + id

Доменные модели:

project.py - Project (наследуется от FullAuditModel)
issue.py - Issue, IssueType
module.py - Module, ModuleIssue
cycle.py - Cycle, CycleIssue
metadata.py - State, Label
worklog.py - IssueWorkLog

Каждая схема полностью документирована с описанием всех полей, типов и ограничений.

Запуск тестов

uv run pytest

Форматирование кода

uv run ruff check --fix
uv run ruff format

Получение API ключа Plane

Войдите в Plane
Перейдите в Settings → API Tokens
Создайте новый токен
Скопируйте и сохраните в .env или используйте как переменную окружения

📦 Публикация в NPM

Если вы хотите опубликовать свой форк пакета, следуйте инструкциям в NPM_PUBLISH.md.

Лицензия

MIT

Автор

Сгенерировано на основе официального Plane MCP Server