136 lines
4.4 KiB
Python
136 lines
4.4 KiB
Python
# 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()
|