# kanboard_mcp.py
"""
Servidor FastMCP para controlar Kanboard desde un LLM.

Este módulo expone las funciones del paquete `kanboard_utils`
como herramientas del protocolo MCP (Model Context Protocol),
permitiendo a modelos de lenguaje (LLMs) listar, crear, mover
y editar tareas en Kanboard de forma segura y programática.

Requisitos:
    uv add fastmcp requests
"""

from fastmcp import FastMCP
from kanboard_utils import (
    listar_proyectos,
    listar_usuarios,
    listar_tareas,
    listar_subtareas,
    listar_tareas_por_columna,
    mover_tarea_columna,
    crear_tarea,
    editar_tarea,
)

# Instancia principal del servidor MCP
mcp = FastMCP("Kanboard Controller", instructions="""
Controlador MCP para Kanboard que permite a un LLM gestionar tareas,
proyectos y usuarios de un tablero Kanboard mediante JSON-RPC.
""")


# === Herramientas expuestas ===

@mcp.tool
def list_projects(api_url: str, usuario: str, token: str) -> list[dict]:
    """
    📁 Listar todos los proyectos de Kanboard.

    Permite recuperar todos los proyectos accesibles para un usuario.
    Ideal para que el modelo entienda qué tableros existen antes de operar.

    Parámetros:
        api_url (str): URL del endpoint JSON-RPC, por ejemplo http://localhost:8080/jsonrpc.php
        usuario (str): Nombre de usuario con permisos API
        token (str): Token de autenticación

    Retorna:
        list[dict]: Proyectos con campos como 'id', 'name', 'identifier', etc.
    """
    return listar_proyectos(api_url, usuario, token)


@mcp.tool
def list_users(api_url: str, usuario: str, token: str) -> list[dict]:
    """
    👥 Listar todos los usuarios disponibles en Kanboard.

    Devuelve la lista de usuarios con sus IDs, nombres y nombres de usuario.
    """
    return listar_usuarios(api_url, usuario, token)


@mcp.tool
def list_tasks(api_url: str, usuario: str, token: str, project_id: int) -> list[dict]:
    """
    🗂️ Listar todas las tareas de un proyecto.

    Permite a un LLM inspeccionar las tareas dentro de un proyecto específico.
    """
    return listar_tareas(api_url, usuario, token, project_id)


@mcp.tool
def list_subtasks(api_url: str, usuario: str, token: str, task_id: int) -> list[dict]:
    """
    📋 Listar las subtareas de una tarea específica.

    Útil para analizar el desglose de una tarea compleja.
    """
    return listar_subtareas(api_url, usuario, token, task_id)


@mcp.tool
def list_tasks_by_column(api_url: str, usuario: str, token: str, project_id: int) -> dict:
    """
    🧩 Agrupa las tareas por columna del tablero Kanboard.

    Permite al modelo entender la estructura actual del flujo de trabajo.
    """
    return listar_tareas_por_columna(api_url, usuario, token, project_id)


@mcp.tool
def move_task(api_url: str, usuario: str, token: str, project_id: int,
              task_id: int, column_id: int, position: int = 1, swimlane_id: int = 0) -> bool:
    """
    🔄 Mover una tarea entre columnas del tablero.

    Permite cambiar el estado de una tarea dentro del flujo de trabajo (por ejemplo, de "To Do" a "En progreso").
    """
    return mover_tarea_columna(api_url, usuario, token, project_id, task_id, column_id, position, swimlane_id)


@mcp.tool
def create_task(api_url: str, usuario: str, token: str, project_id: int, titulo: str,
                descripcion: str = "", swimlane_id: int | None = None, assignee_id: int | None = None,
                tags: list[str] | None = None, priority: int | None = None) -> dict:
    """
    ➕ Crear una nueva tarea en un proyecto Kanboard.

    Ideal para automatizar la creación de tickets desde prompts naturales.
    """
    return crear_tarea(api_url, usuario, token, project_id, titulo, descripcion,
                       swimlane_id, assignee_id, tags, priority)


@mcp.tool
def edit_task(api_url: str, usuario: str, token: str, task_id: int,
              titulo: str | None = None, descripcion: str | None = None,
              swimlane_id: int | None = None, assignee_id: int | None = None,
              tags: list[str] | None = None, priority: int | None = None) -> dict:
    """
    ✏️ Editar una tarea existente en Kanboard.

    Actualiza campos específicos sin alterar los demás.
    Permite editar título, descripción, prioridad o etiquetas.
    """
    return editar_tarea(api_url, usuario, token, task_id, titulo, descripcion,
                        swimlane_id, assignee_id, tags, priority)


# === Punto de entrada del servidor ===
if __name__ == "__main__":
    mcp.run()