Proyectos

Código Abierto — GitScrum MCP Server es código abierto bajo la licencia MIT. Disponible en npm y en GitHub. Servidor Model Context Protocol para GitScrum — Claude, GitHub Copilot, Cursor y cualquier cliente compatible con MCP tienen acceso operacional completo a tu stack de gestión de proyectos.

La herramienta project proporciona 11 acciones que cubren la gestión del ciclo de vida del proyecto y el acceso a metadatos. Más allá de crear y listar proyectos, esta herramienta es la puerta de entrada a la configuración del proyecto — flujos de trabajo, tipos de tarea, niveles de esfuerzo, etiquetas y miembros del equipo. Estos endpoints de metadatos son esenciales porque proporcionan los IDs y nombres que otras herramientas (especialmente task) requieren para crear y actualizar elementos.

Entender las acciones de metadatos de la herramienta project es clave para un uso efectivo de MCP. Cuando le pides a tu asistente de IA que cree una tarea con "alta prioridad" asignada a "@sarah" en la columna "In Progress", el asistente primero consulta project action=efforts, project action=members y project action=workflows para resolver esos nombres legibles en los IDs numéricos que la API espera. El servidor MCP maneja esta resolución automáticamente en la mayoría de los casos, pero conocer las acciones de metadatos te ayuda a entender cómo funciona el sistema.

Resumen de acciones

Crear proyectos

La acción create configura un nuevo proyecto dentro de un workspace. El proyecto está inmediatamente disponible para creación de tareas, planificación de sprints y colaboración del equipo.

Parámetros requeridos

Parámetros opcionales

Ejemplos de prompts

Tú:   "Crea un nuevo proyecto llamado 'Mobile App' en mi workspace"
IA:   Llama a project action=create con name="Mobile App", company_slug

Tú:   "Crea un proyecto privado 'Auditoría de Seguridad' vinculado a Acme Corp"
IA:   Llama a project action=create con name, visibility="private", client_uuid

Tú:   "Configura un nuevo proyecto 'API v3' con descripción 'Rediseño de REST API para Q1'"
IA:   Llama a project action=create con name, description

Buscar y listar proyectos

List

La acción list devuelve todos los proyectos dentro de un workspace. Puedes filtrar opcionalmente por estado. Cada proyecto en la respuesta incluye su project_slug, necesario para todas las operaciones específicas del proyecto.

Tú:   "Lista todos los proyectos en mi workspace"
IA:   Llama a project action=list → devuelve proyectos con slugs y estadísticas

Tú:   "Muestra solo los proyectos activos"
IA:   Llama a project action=list con status="in_progress"

Tú:   "¿Qué proyectos están archivados?"
IA:   Llama a project action=list con status="archived"

Find

La acción find busca un proyecto por nombre en todos tus workspaces. Esto es útil cuando conoces el nombre del proyecto pero no el slug o workspace. El parámetro company_slug es opcional — si se omite, la búsqueda cubre todos los workspaces accesibles.

Tú:   "Encuentra el proyecto Backend"
IA:   Llama a project action=find con name="Backend" → devuelve proyecto con slug y workspace

Tú:   "¿Cuál workspace tiene el proyecto Mobile App?"
IA:   Llama a project action=find con name="Mobile App" → devuelve información del workspace

Detalles y estadísticas del proyecto

Get

La acción get devuelve el objeto completo del proyecto — nombre, descripción, configuración, fechas, tamaño del equipo y enlaces. Esto proporciona el contexto completo sobre un proyecto.

Tú:   "Muéstrame los detalles del proyecto Backend"
IA:   Llama a project action=get → devuelve configuración completa del proyecto y metadatos

Stats

La acción stats devuelve estadísticas a nivel de proyecto — total de tareas, tasas de completado, sprints activos, actividad del equipo y más. Estos números alimentan el dashboard del proyecto en la aplicación web de GitScrum.

Tú:   "Muestra estadísticas del proyecto Mobile App"
IA:   Llama a project action=stats → devuelve conteos de tareas, tasas de completado, datos del sprint

Tú:   "¿Qué proyecto tiene más tareas abiertas?"
IA:   Lista proyectos → llama a stats para cada uno → compara conteos de tareas abiertas

Tasks

La acción tasks devuelve todas las tareas dentro de un proyecto. Mientras que la acción filter de la herramienta task proporciona filtrado más granular, la acción tasks del proyecto es una forma rápida de obtener una visión general de todos los elementos de trabajo.

Tú:   "Muestra todas las tareas en el proyecto Backend"
IA:   Llama a project action=tasks → devuelve lista completa de tareas

Metadatos del proyecto

Las acciones de metadatos son el puente entre nombres legibles por humanos y los IDs numéricos que la API de GitScrum requiere. Cuando tu asistente de IA crea o actualiza tareas, depende de estos endpoints para traducir tu lenguaje natural en llamadas de API precisas.

Workflows (columnas Kanban)

La acción workflows devuelve las columnas del tablero Kanban del proyecto con sus IDs y títulos. Cada entrada de workflow representa una columna en el tablero — "To Do", "In Progress", "Code Review", "Done", etc.

Por qué es importante: Cuando dices "mueve esta tarea a In Progress", el asistente de IA necesita el workflow_id para la columna "In Progress". El servidor MCP maneja esta resolución automáticamente cuando usas el parámetro column en la herramienta task, pero entender los workflows te ayuda a configurar tableros y resolver problemas con columnas.

Tú:   "¿Cuáles son las columnas disponibles en el proyecto Backend?"
IA:   Llama a project action=workflows → devuelve lista de columnas:
      [{ id: 1, title: "Backlog" }, { id: 2, title: "In Progress" }, { id: 3, title: "Done" }]

Tú:   "¿Qué etapas de flujo de trabajo usa el proyecto Mobile App?"
IA:   Llama a project action=workflows → devuelve la configuración Kanban del proyecto

Types (tipos de tarea)

La acción types devuelve los tipos de tarea disponibles — Feature, Bug, Improvement, Chore, etc. Cada tipo tiene un id y un title.

Por qué es importante: Cuando dices "crea un bug", el asistente de IA necesita el typeid para el tipo "Bug". El servidor MCP usa esto para establecer el campo typeid en la tarea.

Tú:   "¿Qué tipos de tarea están disponibles en este proyecto?"
IA:   Llama a project action=types → devuelve lista de tipos:
      [{ id: 1, title: "Feature" }, { id: 2, title: "Bug" }, { id: 3, title: "Improvement" }]

Efforts (niveles de prioridad)

La acción efforts devuelve los niveles de esfuerzo o prioridad disponibles — Low, Medium, High, Critical, etc. Cada esfuerzo tiene un id y un title.

Por qué es importante: Cuando dices "crea una tarea de alta prioridad", el asistente de IA necesita el effortid para el nivel "High". El servidor MCP usa esto para establecer el campo effortid en la tarea.

Tú:   "¿Qué niveles de prioridad están disponibles?"
IA:   Llama a project action=efforts → devuelve lista de esfuerzos:
      [{ id: 1, title: "Low" }, { id: 2, title: "Medium" }, { id: 3, title: "High" }]

Labels

La acción labels devuelve todas las etiquetas configuradas para el proyecto, cada una con un id y un title. Las etiquetas se usan para categorización y filtrado entre tareas.

Por qué es importante: Cuando dices "etiqueta esta tarea como 'frontend' y 'urgent'", el asistente de IA necesita los label_ids para esas etiquetas. La acción filter de la herramienta task también resuelve nombres de etiquetas automáticamente, pero conocer las etiquetas disponibles te ayuda a organizar el trabajo efectivamente.

Tú:   "¿Qué etiquetas están disponibles en este proyecto?"
IA:   Llama a project action=labels → devuelve lista de etiquetas:
      [{ id: 1, title: "frontend" }, { id: 2, title: "backend" }, { id: 3, title: "urgent" }]

Members

La acción members devuelve todos los miembros del equipo asignados al proyecto, incluyendo nombre para mostrar, nombre de usuario, URL de avatar y rol. Los nombres de usuario se usan para asignación de tareas.

Por qué es importante: Cuando dices "asigna esto a @sarah", el asistente de IA necesita verificar que "sarah" sea un nombre de usuario válido en la lista de miembros del proyecto. El parámetro usernames en la herramienta task acepta estos valores directamente.

Tú:   "¿Quiénes son los miembros del equipo en este proyecto?"
IA:   Llama a project action=members → devuelve lista de miembros:
      [{ name: "Sarah Chen", username: "sarah", role: "developer" }, ...]

Tú:   "¿A quién puedo asignar tareas en el proyecto Backend?"
IA:   Llama a project action=members → lista los miembros del equipo asignables

Flujo de resolución de metadatos

Así es como el asistente de IA usa los metadatos para crear una tarea completamente configurada:

Tú:   "Crea un bug de alta prioridad 'Timeout de login' asignado a @sarah
       en la columna In Progress del proyecto Backend"

IA internamente:
  1. project action=efforts   → encuentra "High" → effort_id=3
  2. project action=workflows → encuentra "In Progress" → workflow_id=2
  3. project action=members   → valida que "sarah" existe
  4. task action=create       → pasa title, effort_id=3, column="In Progress",
                                 usernames=["sarah"], is_bug=true

En la práctica, el servidor MCP maneja gran parte de esta resolución automáticamente. Cuando pasas column: "In Progress" a la herramienta task, obtiene los workflows internamente y resuelve el ID. Pero entender este flujo ayuda al depurar o cuando el asistente de IA hace preguntas clarificadoras sobre las opciones disponibles.

Flujo de trabajo de configuración del proyecto

Al configurar un nuevo proyecto a través de MCP, sigue esta secuencia:

1. Crear el proyecto

Tú:   "Crea un proyecto llamado 'Mobile App' con descripción 'Cliente iOS y Android'"
IA:   Llama a project action=create → devuelve project_slug

2. Revisar configuración predeterminada

Los nuevos proyectos vienen con flujos de trabajo, tipos y esfuerzos predeterminados. Verifica qué está disponible.

Tú:   "Muéstrame los flujos de trabajo, tipos y niveles de esfuerzo de Mobile App"
IA:   Llama a workflows, types, efforts → muestra la configuración del proyecto

3. Comenzar a crear tareas

Usa los metadatos del paso 2 para crear tareas bien configuradas.

Tú:   "Crea una tarea 'Diseñar pantalla de inicio' como Feature, prioridad media, asigna a @alex"
IA:   Usa metadatos almacenados → crea tarea con IDs correctos

4. Monitorear progreso

Rastrea la salud del proyecto a través de estadísticas.

Tú:   "¿Cómo va el proyecto Mobile App?"
IA:   Llama a project action=stats → resume completado de tareas, sprints activos, actividad del equipo

Auto-resolución de contexto

La herramienta project soporta resolución automática de contexto. Si tu asistente de IA conoce el projectslug pero no el companyslug, intenta resolver el workspace automáticamente buscando en tus workspaces accesibles. Esto significa que a menudo puedes referenciar proyectos por nombre en lugar de proporcionar ambos slugs explícitamente.

La acción find es particularmente útil aquí — busca por nombre de proyecto y devuelve tanto el projectslug como el companyslug, estableciendo contexto para todas las operaciones subsiguientes en la conversación.

Visibilidad y permisos

La visibilidad del proyecto determina quién puede acceder al proyecto dentro de un workspace:

• Public — Todos los miembros del workspace pueden ver el proyecto y sus tareas. Este es el valor por defecto.
• Private — Solo los miembros explícitamente invitados pueden acceder al proyecto. Los proyectos privados no aparecen en los listados de tareas del workspace para los no miembros.

El servidor MCP respeta estas reglas de visibilidad. Si no tienes acceso a un proyecto privado, no aparecerá en los resultados de list y las llamadas directas a get fallarán con un error de permisos.

Próximos pasos

• Tareas: Crea y gestiona tareas dentro de tus proyectos.
• Sprints: Planifica y da seguimiento a sprints para entrega iterativa.
• Seguimiento de tiempo: Registra tiempo en las tareas del proyecto.
• Inicio Rápido: Configura el servidor MCP si aún no lo has hecho.