Inglés | 한국어 | 日本語 | 中文

MonkeyPlanner

Memoria de tareas con prioridad local para tus agentes de codificación IA. Aprueba con un clic; tus agentes hacen el resto. Sin nube. Sin telemetría. Siempre gratis, siempre bajo licencia MIT.

Funciona con Claude Code · Claude Desktop · Cursor · Continue · cualquier cliente compatible con MCP.

👁 MonkeyPlanner Demo

Inicio rápido

# 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

Abre http://localhost:8080 — el tablero de bienvenida integrado te guiará a través del resto.

Related MCP server: task-orchestrator

Características

Gestión de problemas y tableros

• Tablero Kanban — Arrastrar y soltar, desplazamiento horizontal, filtrado, ordenación y alternancia de vista de tabla

• Creación de problemas — Título, cuerpo en markdown y propiedades personalizadas

• Propiedades personalizadas — Seis tipos admitidos:

  • Texto

  • Número

  • Selección

  • Selección múltiple

  • Fecha

  • Casilla de verificación

Control de aprobación

• Pendiente → Aprobado mediante un punto de conexión de aprobación dedicado (no se puede realizar mediante un PATCH genérico)

• Cola de aprobación — Aprobar en masa todos los problemas pendientes en todos los tableros

• Aprobado → En progreso → Hecho — Transiciones de estado flexibles

• Estado rechazado — Registrar un motivo de rechazo

Características del agente

• Campo de instrucciones del agente — Proporciona instrucciones detalladas para que las sigan los agentes MCP

• Criterios de éxito — Gestiona las condiciones de finalización como una lista de verificación

• Comentarios — Registra el progreso y comunícate por problema

• Dependencias — Expresa relaciones de bloqueo entre problemas

Visualización de datos

• Calendario — Cuadrícula mensual + actividad diaria (recuentos de creados, aprobados y completados)

• Panel de control — Tarjetas de estadísticas + gráfico de actividad semanal

• Barra lateral — Lista de tableros, recuentos de problemas y elementos recientes

Experiencia de usuario

• Búsqueda global — Búsqueda rápida con Cmd+K

• Atajos de teclado

  • h — Ir al panel de control

  • a — Ir a la cola de aprobación

  • ? — Mostrar ayuda de atajos

  • Cmd+S — Guardar

  • Escape — Cerrar modal/diálogo

• Barra lateral plegable — Maximiza el espacio en pantalla

• Modo oscuro — Alternancia de tema

• Internacionalización — Coreano, inglés, japonés y chino

Automatización e integraciones

• Webhooks — Soporte para Discord, Slack y Telegram

  • Eventos: issue.created, issue.approved, issue.status_changed, issue.updated, issue.deleted, comment.created

• Sincronización de interfaz en tiempo real (SSE) — Los cambios realizados a través de MCP/CLI se reflejan automáticamente en las pestañas del navegador abiertas, sin necesidad de actualizar

• Exportación JSON — Exportar todos los datos de problemas

• Menú contextual de clic derecho — Acciones rápidas

• Plantillas de problemas — Persistencia en localStorage por tablero

Servidor MCP (Integración de agente IA)

Trece herramientas para la automatización de agentes IA:

1. list_boards — Listar todos los tableros

2. list_issues — Consultar problemas (filtrar por boardId, estado)

3. get_issue — Detalle del problema, incluidas instrucciones, criterios y comentarios

4. create_issue — Crear un nuevo problema

5. approve_issue — Aprobar: Pendiente → Aprobado

6. claim_issue — Reclamar: Aprobado → En progreso

7. submit_qa — Enviar para control de calidad: En progreso → QA

8. complete_issue — Completar: QA → Hecho (comentario opcional)

9. reject_issue — Rechazar: QA → En progreso con motivo obligatorio

10. add_comment — Añadir un comentario a un problema

11. update_criteria — Marcar o desmarcar un criterio de éxito

12. search_issues — Buscar problemas por título

13. get_version — Obtener la versión del servidor MCP (para diagnóstico)

Stack tecnológico

Backend

• Lenguaje: Go 1.26

• Enrutador: chi/v5

• Base de datos: SQLite / PostgreSQL (configurable)

• Migraciones: goose/v3

• Archivos incrustados: embed.FS (despliegue de binario único)

Frontend

• Framework: React 18

• Lenguaje: TypeScript

• Empaquetador: Vite 6

• CSS: Tailwind CSS

• Gestión de estado: React Query (TanStack)

• Arrastrar y soltar: @dnd-kit/core, @dnd-kit/sortable

• Iconos: lucide-react

• Gráficos: recharts

• i18n: react-i18next

• Markdown: react-markdown + rehype-sanitize

MCP

• Protocolo: JSON-RPC 2.0 sobre stdio

• Objetivos: Claude Code, Claude Desktop

Primeros pasos

Requisitos

• Go 1.26 o posterior

• Node.js 18 o posterior

• npm o yarn

Instalación y ejecución

1. Clonar e inicializar

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

2. Compilación de producción (binario único)

make build
./bin/monkey-planner

El servidor se ejecuta en http://localhost:8080 con el frontend incrustado.

3. Modo de desarrollo (procesos separados)

Terminal 1 — backend:

make run-backend

Terminal 2 — frontend (servidor de desarrollo Vite, :5173):

make run-frontend

El frontend redirige automáticamente las solicitudes /api a :8080.

Variables de entorno

# 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"

Configuración del servidor MCP

Recomendado: configuración automática mediante 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

Flags: --dry-run para previsualizar, --scope user para una entrada global (~/.mcp.json), --force para sobrescribir, --base-url <url> para apuntar a un servidor no predeterminado.

Reinicia el cliente después para que vuelva a leer la configuración.

Configuración manual

Funciona de forma idéntica para Claude Code (.mcp.json), Claude Desktop (configuración nativa del SO) y Cursor (.cursor/mcp.json):

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

El binario debe poder acceder al servidor HTTP (configurado con MP_BASE_URL). Déjalo en el valor predeterminado cuando ejecutes ambos en la misma máquina.

Ejemplos de uso de herramientas 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()

Flujo de trabajo — Escenario de uso real

A continuación se muestra un flujo de trabajo real para corregir un error en el selector de idioma, mostrando cómo un humano y un agente de IA colaboran a través de MonkeyPlanner.

Flujo de estado

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

Paso a paso

1. Crear problema — El humano encuentra un error, pide a la IA que lo registre

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. Aprobar — El humano revisa y aprueba

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

3. Comenzar trabajo — La IA reclama el problema y comienza a codificar

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

4. Enviar para QA — La IA termina y envía para revisión

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

5. Revisión — El humano prueba la corrección

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. Bucle de retroalimentación — Comunicación mediante comentarios durante todo el proceso

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 ✓

Puntos clave

• El humano controla las puertas: Aprobar, pasar/rechazar QA, Completar

• La IA hace el trabajo: Análisis de código, implementación, pruebas, confirmaciones

• Los comentarios son el canal de comunicación: Ambas partes usan add_comment para intercambiar comentarios

• El bucle de QA evita la finalización prematura: Los problemas deben pasar la revisión humana antes de marcarse como Hecho

Referencia de API

Especificación OpenAPI 3.0: backend/docs/swagger.yaml

Puntos de conexión clave

Tableros

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

Problemas

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)

Comentarios

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

Propiedades (Atributos personalizados)

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

Webhooks

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

Calendario

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

Para obtener detalles completos del esquema, consulta backend/docs/swagger.yaml.

Estructura del proyecto

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)

Pruebas

Pruebas de backend

make test-backend

Pruebas de frontend

make test-frontend

Pruebas de accesibilidad

make test-a11y

Todas las pruebas

make test

Comandos comunes

# 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

Reglas de transición de estado

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

Licencia

MIT

Contribución

Los problemas y las solicitudes de extracción son bienvenidos.

Contacto

Para preguntas o comentarios sobre el proyecto, por favor abre un Issue en GitHub.

Maintenance

Resources

• GitHub Repository
Need Help?Related Servers