amulen-mcp-server 0.2.0
MCP server para integración con AMULEN - Sistema de Gestión de Proyectos
License: MIT
Requires Python: >=3.12

# amulen-mcp-server

[![PyPI version](https://img.shields.io/pypi/v/amulen-mcp-server)](https://pypi.org/project/amulen-mcp-server/)
[![Python](https://img.shields.io/pypi/pyversions/amulen-mcp-server)](https://pypi.org/project/amulen-mcp-server/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)

**Servidor MCP (Model Context Protocol) para integración con [AMULEN](https://amulen.app) — Sistema de Gestión de Proyectos**

Permite a clientes MCP (Kiro, Claude Desktop, Cursor, Zed, etc.) interactuar con la API REST de AMULEN para gestionar proyectos, tableros, tareas y comentarios.

## Features

- **Gestión de proyectos** — crear, actualizar, listar proyectos y consultar dashboards con métricas
- **Tableros y tareas** — CRUD completo de tableros y tareas, mover estados (kanban), filtros por estado/fecha/usuario
- **Mis tareas** — consulta cross-proyecto de tareas asignadas al usuario autenticado
- **Comentarios** — agregar comentarios a tareas
- **Dual format** — respuestas en markdown (optimizado para LLMs) o JSON (datos estructurados)

## Requisitos previos

1. [uv](https://docs.astral.sh/uv/getting-started/installation/) instalado
2. Python >= 3.12
3. Cuenta activa en una instancia de [AMULEN](https://amulen.app)

## Validar la instalación

Para validar la instalación, ejecuta el siguiente comando:

```bash
uvx amulen-mcp-server --version
```

## Instalación rápida

[![Add to Kiro](https://kiro.dev/images/add-to-kiro.svg)](https://kiro.dev/launch/mcp/add?name=amulen-mcp-server&config=%7B%22command%22%3A%22uvx%22%2C%22args%22%3A%5B%22amulen-mcp-server%40latest%22%5D%2C%22env%22%3A%7B%22AMULEN_BASE_URL%22%3A%22%24%7BAMULEN_BASE_URL%7D%22%2C%22AMULEN_EMAIL%22%3A%22%24%7BAMULEN_EMAIL%7D%22%2C%22AMULEN_PASSWORD%22%3A%22%24%7BAMULEN_PASSWORD%7D%22%7D%7D)

## Configuración en MCP Clients

### Variables de entorno requeridas

| Variable | Descripción | Ejemplo |
|---|---|---|
| `AMULEN_BASE_URL` | URL de tu instancia AMULEN | `https://mi-empresa.amulen.app` |
| `AMULEN_EMAIL` | Email de usuario | `usuario@empresa.com` |
| `AMULEN_PASSWORD` | Contraseña | `*****` |

Variables opcionales:

| Variable | Default | Descripción |
|---|---|---|
| `AMULEN_TIMEOUT_S` | `20` | Timeout HTTP en segundos |
| `AMULEN_CSRF_TTL_S` | `600` | TTL del cache CSRF en segundos |

### Kiro CLI

Archivo `.kiro/settings/mcp.json`:

```json
{
  "mcpServers": {
    "amulen-mcp-server": {
      "command": "uvx",
      "args": ["amulen-mcp-server@latest"],
      "env": {
        "AMULEN_BASE_URL": "${AMULEN_BASE_URL}",
        "AMULEN_EMAIL": "${AMULEN_EMAIL}",
        "AMULEN_PASSWORD": "${AMULEN_PASSWORD}"
      }
    }
  }
}
```

La sintaxis `${VARIABLE}` referencia variables de entorno de tu shell. Configúralas antes de iniciar el cliente:

```bash
export AMULEN_BASE_URL="https://mi-empresa.amulen.app"
export AMULEN_EMAIL="usuario@empresa.com"
export AMULEN_PASSWORD="tu-contraseña"
```

> Más detalles en la [documentación de Kiro CLI — MCP Configuration](https://kiro.dev/docs/cli/mcp/configuration/#security-considerations).

El mismo formato aplica para Claude Desktop, Cursor, Zed y otros clientes MCP compatibles.

> **Nota:** La sintaxis `${VAR}` está verificada en Kiro CLI. En otros clientes (Claude Desktop, Cursor, Zed) es posible que las credenciales deban ir hardcodeadas en el JSON de configuración. Si es tu caso, consulta la documentación de tu cliente MCP para la forma recomendada de manejar secretos. Hardcodear credenciales funciona pero no es recomendable.

## Seguridad

- Usa referencias a variables de entorno (`${VAR}`) en vez de valores hardcodeados en archivos de configuración
- No commitees archivos de configuración con credenciales a control de versiones
- Agrega `mcp.json` y `claude_desktop_config.json` a tu `.gitignore`

## Tools disponibles (19)

### Lectura
- `amulen_health` — Verificar conectividad e identificar usuario autenticado
- `amulen_list_projects` — Listar todos los proyectos
- `amulen_get_project` — Obtener detalles de un proyecto
- `amulen_get_project_dashboard` — Métricas y dashboard de un proyecto
- `amulen_list_boards` — Listar tableros de un proyecto
- `amulen_get_board` — Obtener detalles de un tablero
- `amulen_list_tasks` — Listar tareas de un tablero con filtros opcionales
- `amulen_get_task` — Obtener detalles de una tarea
- `amulen_my_tasks` — Listar mis tareas asignadas (cross-proyecto)

### Escritura
- `amulen_create_project` — Crear un nuevo proyecto
- `amulen_update_project` — Actualizar un proyecto existente
- `amulen_create_board` — Crear un nuevo tablero
- `amulen_create_task` — Crear una nueva tarea
- `amulen_update_task` — Actualizar una tarea existente
- `amulen_move_task_state` — Mover tarea a otro estado (TO DO, DOING, DONE, PENDING, BACKLOG)
- `amulen_add_comment` — Agregar comentario a una tarea
- `amulen_create_checklist_item` — Crear item de checklist en una tarea
- `amulen_update_checklist_item` — Actualizar item de checklist (título, descripción o marcar completado)
- `amulen_delete_checklist_item` — Eliminar item de checklist de una tarea

### Formato de respuesta

Todas las tools soportan `response_format`: `"markdown"` (default, optimizado para LLMs) o `"json"` (datos estructurados).

## Desarrollo

```bash
git clone <repo-url>
cd amulen-mcp-server
uv sync
uv run mcp dev -e . src/amulen_mcp_server/server_core.py:app
```

## Licencia

MIT