English | 한국어 | 日本語 | 中文

MonkeyPlanner

Локальная память задач для ваших AI-агентов по программированию. Одобряйте одним кликом; ваши агенты сделают остальное. Никакого облака. Никакой телеметрии. Всегда бесплатно, всегда под лицензией MIT.

Работает с Claude Code · Claude Desktop · Cursor · Continue · любым MCP-совместимым клиентом.

👁 MonkeyPlanner Demo

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

# Docker (recommended)
docker run -p 8080:8080 -v $(pwd)/data:/data ghcr.io/kjm99d/monkeyplanner:latest

# then wire up your agent
monkey-planner mcp install --for claude-code # or --for cursor / --for claude-desktop

Откройте http://localhost:8080 — встроенная доска приветствия поможет вам освоиться.

Related MCP server: task-orchestrator

Функции

Управление задачами и досками

• Канбан-доска — Drag and drop, горизонтальная прокрутка, фильтрация, сортировка и переключение в табличный вид

• Создание задач — Заголовок, описание в формате markdown и пользовательские свойства

• Пользовательские свойства — Поддерживается шесть типов:

  • Текст

  • Число

  • Выбор (Select)

  • Множественный выбор (Multi-select)

  • Дата

  • Чекбокс

Шлюз подтверждения (Approval Gate)

• Ожидание → Одобрено через специальный эндпоинт подтверждения (невозможно выполнить через обычный PATCH)

• Очередь подтверждений — Массовое одобрение всех задач со статусом «Ожидание» на всех досках

• Одобрено → В работе → Готово — Гибкие переходы между статусами

• Статус «Отклонено» — Запись причины отклонения

Функции для агентов

• Поле инструкций для агента — Предоставление подробных инструкций для выполнения MCP-агентами

• Критерии успеха — Управление условиями завершения в виде чек-листа

• Комментарии — Логирование прогресса и общение по каждой задаче

• Зависимости — Определение блокирующих связей между задачами

Визуализация данных

• Календарь — Ежемесячная сетка + ежедневная активность (количество созданных, одобренных и завершенных задач)

• Дашборд — Карточки статистики + график еженедельной активности

• Боковая панель — Список досок, количество задач и недавние элементы

Пользовательский опыт

• Глобальный поиск — Быстрый поиск через Cmd+K

• Горячие клавиши

  • h — Перейти на дашборд

  • a — Перейти в очередь подтверждений

  • ? — Показать справку по клавишам

  • Cmd+S — Сохранить

  • Escape — Закрыть модальное окно/диалог

• Сворачиваемая боковая панель — Максимизация рабочего пространства

• Темная тема — Переключатель темы

• Интернационализация — Корейский, английский, японский и китайский языки

Автоматизация и интеграции

• Вебхуки — Поддержка Discord, Slack и Telegram

  • События: issue.created, issue.approved, issue.status_changed, issue.updated, issue.deleted, comment.created

• Синхронизация UI в реальном времени (SSE) — Изменения через MCP/CLI автоматически отображаются в открытых вкладках браузера, обновление страницы не требуется

• Экспорт в JSON — Экспорт всех данных о задачах

• Контекстное меню правой кнопки мыши — Быстрые действия

• Шаблоны задач — Сохранение в localStorage для каждой доски

MCP-сервер (Интеграция с AI-агентами)

Тринадцать инструментов для автоматизации AI-агентов:

1. list_boards — Список всех досок

2. list_issues — Запрос задач (фильтрация по boardId, статусу)

3. get_issue — Детали задачи, включая инструкции, критерии и комментарии

4. create_issue — Создание новой задачи

5. approve_issue — Одобрение: Ожидание → Одобрено

6. claim_issue — Взять в работу: Одобрено → В работе

7. submit_qa — Отправить на QA: В работе → QA

8. complete_issue — Завершить: QA → Готово (опциональный комментарий)

9. reject_issue — Отклонить: QA → В работе с обязательным указанием причины

10. add_comment — Добавить комментарий к задаче

11. update_criteria — Отметить или снять отметку с критерия успеха

12. search_issues — Поиск задач по заголовку

13. get_version — Получить версию MCP-сервера (для диагностики)

Технологический стек

Бэкенд

• Язык: Go 1.26

• Роутер: chi/v5

• База данных: SQLite / PostgreSQL (настраиваемо)

• Миграции: goose/v3

• Встроенные файлы: embed.FS (развертывание одним бинарным файлом)

Фронтенд

• Фреймворк: React 18

• Язык: TypeScript

• Сборщик: Vite 6

• CSS: Tailwind CSS

• Управление состоянием: React Query (TanStack)

• Drag and drop: @dnd-kit/core, @dnd-kit/sortable

• Иконки: lucide-react

• Графики: recharts

• i18n: react-i18next

• Markdown: react-markdown + rehype-sanitize

MCP

• Протокол: JSON-RPC 2.0 через stdio

• Цели: Claude Code, Claude Desktop

Начало работы

Требования

• Go 1.26 или новее

• Node.js 18 или новее

• npm или yarn

Установка и запуск

1. Клонирование и инициализация

git clone https://github.com/kjm99d/MonkeyPlanner.git
cd monkey-planner
make init

2. Сборка для продакшена (один бинарный файл)

make build
./bin/monkey-planner

Сервер запускается на http://localhost:8080 со встроенным фронтендом.

3. Режим разработки (отдельные процессы)

Терминал 1 — бэкенд:

make run-backend

Терминал 2 — фронтенд (Vite dev server, :5173):

make run-frontend

Фронтенд автоматически проксирует запросы /api на :8080.

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

# Server address (default: :8080)
export MP_ADDR=":8080"

# Database connection string
# SQLite (default: sqlite://./data/monkey.db)
export MP_DSN="sqlite://./data/monkey.db"

# PostgreSQL example
export MP_DSN="postgres://user:password@localhost:5432/monkey_planner"

Настройка MCP-сервера

Рекомендуется: автоконфигурация через CLI

# Claude Code (writes .mcp.json in the current directory)
monkey-planner mcp install --for claude-code

# Claude Desktop (writes the OS-native config file)
monkey-planner mcp install --for claude-desktop

# Cursor (writes .cursor/mcp.json)
monkey-planner mcp install --for cursor

Флаги: --dry-run для предварительного просмотра, --scope user для глобальной записи (~/.mcp.json), --force для перезаписи, --base-url <url> для указания на нестандартный сервер.

После этого перезапустите клиент, чтобы он перечитал конфигурацию.

Ручная настройка

Работает идентично для Claude Code (.mcp.json), Claude Desktop (конфиг ОС) и Cursor (.cursor/mcp.json):

{
 "mcpServers": {
 "monkey-planner": {
 "command": "/path/to/monkey-planner",
 "args": ["mcp"],
 "env": {
 "MP_BASE_URL": "http://localhost:8080"
 }
 }
 }
}

Бинарный файл должен иметь доступ к HTTP-серверу (устанавливается через MP_BASE_URL). Оставьте значение по умолчанию, если запускаете оба на одной машине.

Примеры использования инструментов MCP

AI: List all boards
→ list_boards()

AI: Find issues related to "authentication"
→ search_issues(query="authentication")

AI: Approve the first pending issue, claim it, work on it, and submit for QA
→ approve_issue() → claim_issue() → submit_qa()

Рабочий процесс — Реальный сценарий использования

Ниже представлен реальный рабочий процесс исправления ошибки переключателя языка, показывающий, как человек и AI-агент сотрудничают через MonkeyPlanner.

Поток статусов

Pending → Approved → InProgress → QA → Done
 ↑ │ (reject with reason)
 └──────────────┘

Пошагово

1. Создание задачи — Человек находит ошибку, просит AI зарегистрировать её

Human: "The language selector dropdown doesn't appear when clicking the button. Create an issue."
AI: create_issue(boardId, title, body, instructions) → status: Pending

2. Одобрение — Человек проверяет и одобряет

Human: (clicks Approve on the board or tells AI)
AI: approve_issue(issueId) → status: Approved

3. Начало работы — AI берет задачу и начинает писать код

AI: claim_issue(issueId) → status: InProgress
 - Reads code, identifies root cause
 - Implements fix, runs tests
 - Commits changes

4. Отправка на QA — AI завершает работу и отправляет на проверку

AI: submit_qa(issueId, comment: "commit abc1234 — fixed click handler")
 → status: QA
 add_comment(issueId, "Commit info: ...")

5. Проверка — Человек тестирует исправление

Human: Tests in browser, finds the dropdown is clipped by sidebar
 → reject_issue(issueId, reason: "Dropdown is hidden behind sidebar")
 → status: InProgress (back to step 3)

Human: Tests again after fix, everything works
 → complete_issue(issueId) → status: Done

6. Цикл обратной связи — Общение через комментарии на протяжении всего процесса

Human: add_comment("Dropdown is clipped on the left side, fix it")
AI: get_issue() → reads comment → fixes → commit → submit_qa()
Human: Tests → complete_issue() → Done ✓

Основные выводы

• Человек контролирует шлюзы: Одобрение, прохождение/отклонение QA, Завершение

• AI выполняет работу: Анализ кода, реализация, тестирование, коммиты

• Комментарии — канал связи: Обе стороны используют add_comment для обмена отзывами

• Цикл QA предотвращает преждевременное завершение: Задачи должны пройти проверку человеком перед переходом в статус «Готово»

Справочник API

Спецификация OpenAPI 3.0: backend/docs/swagger.yaml

Основные эндпоинты

Доски

GET /api/boards # List boards
POST /api/boards # Create board
PATCH /api/boards/{id} # Update board
DELETE /api/boards/{id} # Delete board

Задачи

GET /api/issues # List issues (filter: boardId, status, parentId)
POST /api/issues # Create issue
GET /api/issues/{id} # Issue detail + child issues
PATCH /api/issues/{id} # Update issue (status, properties, title, etc.)
DELETE /api/issues/{id} # Delete issue
POST /api/issues/{id}/approve # Approve issue (Pending → Approved)

Комментарии

GET /api/issues/{issueId}/comments # List comments
POST /api/issues/{issueId}/comments # Add comment
DELETE /api/comments/{commentId} # Delete comment

Свойства (Пользовательские атрибуты)

GET /api/boards/{boardId}/properties # List property definitions
POST /api/boards/{boardId}/properties # Create property
PATCH /api/boards/{boardId}/properties/{propId} # Update property
DELETE /api/boards/{boardId}/properties/{propId} # Delete property

Вебхуки

GET /api/boards/{boardId}/webhooks # List webhooks
POST /api/boards/{boardId}/webhooks # Create webhook
PATCH /api/boards/{boardId}/webhooks/{whId} # Update webhook
DELETE /api/boards/{boardId}/webhooks/{whId} # Delete webhook

Календарь

GET /api/calendar # Monthly stats (year, month required)
GET /api/calendar/day # Daily issue list (date required)

Полную схему см. в backend/docs/swagger.yaml.

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

monkey-planner/
├── backend/
│ ├── cmd/monkey-planner/
│ │ ├── main.go # Entry point (HTTP server)
│ │ └── mcp.go # MCP server (JSON-RPC stdio)
│ ├── internal/
│ │ ├── domain/ # Domain models (Issue, Board, etc.)
│ │ ├── service/ # Business logic
│ │ ├── storage/ # Database layer (SQLite/PostgreSQL)
│ │ ├── http/ # HTTP handlers & router
│ │ └── migrations/ # goose migration files
│ ├── web/ # Embedded frontend (embed.FS)
│ ├── docs/
│ │ └── swagger.yaml # OpenAPI 3.0 spec
│ ├── go.mod
│ └── go.sum
│
├── frontend/
│ ├── src/
│ │ ├── components/ # Reusable components
│ │ ├── features/ # Page & feature components
│ │ │ ├── home/ # Dashboard
│ │ │ ├── board/ # Board & Kanban
│ │ │ ├── issue/ # Issue detail
│ │ │ ├── calendar/ # Calendar
│ │ │ └── approval/ # Approval queue
│ │ ├── api/ # API hooks & client
│ │ ├── design/ # Tailwind tokens
│ │ ├── i18n/ # Translations (en.json, ko.json, ja.json, zh.json)
│ │ ├── App.tsx # Router
│ │ ├── index.css # Global styles
│ │ └── main.tsx
│ ├── package.json
│ ├── vite.config.ts
│ ├── tsconfig.json
│ └── tailwind.config.js
│
├── .mcp.json # Claude Code MCP config
├── Makefile # Build & dev commands
├── .githooks/ # Git hooks
└── data/ # SQLite database (default)

Тестирование

Тесты бэкенда

make test-backend

Тесты фронтенда

make test-frontend

Тесты доступности

make test-a11y

Все тесты

make test

Общие команды

# Initial setup after cloning
make init

# Production build
make build

# Run production server
./bin/monkey-planner

# Development mode
make run-backend # Terminal 1
make run-frontend # Terminal 2

# Clean build artifacts
make clean

Правила перехода статусов

Pending
 ↓ (approve endpoint)
Approved
 ↓ (PATCH status)
InProgress
 ↓ (PATCH status)
Done

Pending → Approved: POST /api/issues/{id}/approve (dedicated endpoint only)
Approved ↔ InProgress ↔ Done: Free transitions via PATCH
Pending: Cannot be re-entered from other statuses
Rejected: Separate rejection state with reason tracking

Лицензия

MIT

Участие в разработке

Запросы на добавление (pull requests) и сообщения об ошибках приветствуются.

Контакты

По вопросам или отзывам о проекте, пожалуйста, откройте GitHub Issue.

Maintenance

Resources

• GitHub Repository
Need Help?Related Servers