ProjectFlow

Un sistema de gestión de flujos de trabajo para desarrollo asistido por IA con soporte MCP, que ofrece almacenamiento flexible mediante sistema de archivos o PostgreSQL.

GitHub

Prueba este MCPPatrocinado

Documentación

ProjectFlow

Un sistema de gestión de flujos de trabajo para desarrollo asistido por IA, similar a Jira o Azure DevOps. Admite tanto interacciones basadas en API como el Protocolo de Contexto de Modelo para una integración fluida de agentes de IA.

Características

Gestión jerárquica de tareas (Épicas, Historias, Subtareas)
🚀 NUEVO: Interfaz de Chat en Lenguaje Natural - Interactúa con ProjectFlow usando comandos conversacionales
API REST para acceso programático
Soporte para el Protocolo de Contexto de Modelo (MCP) para agentes de IA
Interfaz web para usuarios humanos
Almacenamiento flexible: sistema de archivos (JSON) o base de datos PostgreSQL
Interfaz limpia y moderna con funciones de accesibilidad
Despliegue contenerizado

Stack Tecnológico

Backend: Go 1.24
Almacenamiento: sistema de archivos (JSON) o base de datos PostgreSQL
Frontend: HTML templates, CSS, JavaScript
Contenerización: Docker/Podman
Protocolos: API REST HTTP + Protocolo de Contexto de Modelo

Inicio Rápido

Requisitos Previos

Go 1.24 o posterior
Docker/Podman (para despliegue contenerizado)

Ejecución Local

Clona el repositorio:

git clone https://github.com/aykay76/projectflow.git
cd projectflow

Ejecuta la aplicación:
```
go run cmd/server/main.go
```
Abre tu navegador y navega a http://localhost:16191

💬 Interfaz de Chat en Lenguaje Natural

ProjectFlow ahora incluye una interfaz de chat impulsada por IA que te permite gestionar tareas y proyectos usando comandos en lenguaje natural. Simplemente haz clic en el botón de chat (💬) en el encabezado o usa el atajo de teclado ⌘+/ (Mac) o Ctrl+/ (Windows/Linux) para comenzar.

Ejemplos Rápidos

Create a high priority task to fix the login bug
List all tasks in the PF project  
Mark task PF-123 as done
Show me overdue tasks
Create a new project called "Website Redesign"

Cómo Empezar con el Chat

Abre la interfaz de chat: Haz clic en el botón 💬 del encabezado o presiona ⌘+/
Escribe tu solicitud: Usa lenguaje natural para describir lo que quieres hacer
Obtén resultados instantáneos: La IA interpretará tu solicitud y realizará la acción

Para comandos de chat detallados y ejemplos, consulta la Guía de Interfaz de Chat.

Configuración del LLM

La interfaz de chat admite múltiples proveedores de LLM:

🚀 Ollama: Usa modelos LLM locales para privacidad y capacidad sin conexión
OpenAI GPT: Usa los modelos GPT de OpenAI para comprensión de lenguaje natural
Groq: Inferencia LLM rápida basada en la nube
Anthropic Claude: Aprovecha la IA Claude de Anthropic para interacciones conversacionales

Configuración Rápida con Ollama (LLM Local)

Para la configuración más rápida con privacidad y sin costos de API:

# Install Ollama
brew install ollama  # macOS
# or curl -fsSL https://ollama.com/install.sh | sh  # Linux

# Start Ollama and install a model
ollama serve &
ollama pull llama3.2

# Configure ProjectFlow
export LLM_PROVIDER=ollama
export LLM_OLLAMA_MODEL=llama3.2
./projectflow

Consulta la Guía de Inicio Rápido de Ollama para instrucciones detalladas de configuración.

Proveedores de LLM en la Nube

Para LLM basados en la nube, configura tu clave de API:

# For OpenAI
export LLM_PROVIDER=openai
export LLM_API_KEY=your-openai-key
export LLM_MODEL=gpt-4

# For Groq
export LLM_PROVIDER=groq
export LLM_API_KEY=your-groq-key
export LLM_MODEL=llama-3.1-8b-instant

Variables de Entorno

Configuración del Servidor:

PORT: Puerto del servidor (predeterminado: 16191)
SHUTDOWN_TIMEOUT: Tiempo de espera de apagado elegante en segundos (predeterminado: 30)
LOG_LEVEL: Nivel de registro - DEBUG, INFO, WARN, ERROR (predeterminado: INFO)
LOG_FORMAT: Formato de registro - json o text (predeterminado: text)

Configuración de Almacenamiento:

STORAGE_TYPE: Backend de almacenamiento - file o postgres (predeterminado: file)

Almacenamiento de Archivos:

DATA_DIR: Directorio para almacenamiento de datos (predeterminado: ./data)

Almacenamiento PostgreSQL:

DB_HOST: Host de la base de datos (predeterminado: localhost)
DB_PORT: Puerto de la base de datos (predeterminado: 5432)
DB_NAME: Nombre de la base de datos (predeterminado: projectflow)
DB_USER: Usuario de la base de datos (predeterminado: projectflow)
DB_PASSWORD: Contraseña de la base de datos (requerida para postgres)
DB_SSL_MODE: Modo SSL - disable, require, verify-ca, verify-full, prefer, allow (predeterminado: prefer)

Configuración del LLM (para la Interfaz de Chat):

LLM_PROVIDER: Proveedor de LLM - ollama, groq, openai, disabled (predeterminado: disabled)
LLM_API_KEY: Clave de API para proveedores de LLM en la nube (requerida para groq, openai)
LLM_BASE_URL: URL base personalizada para el proveedor de LLM (opcional)
LLM_MODEL: Nombre del modelo a usar (el predeterminado varía según el proveedor)
LLM_TIMEOUT: Tiempo de espera de solicitud en segundos (predeterminado: 60)
LLM_MAX_TOKENS: Máximo de tokens por respuesta (predeterminado: 1000)

Específico de Ollama (para LLM local):

LLM_OLLAMA_HOST: URL del servidor Ollama (predeterminado: http://localhost:11434)
LLM_OLLAMA_MODEL: Nombre del modelo Ollama (predeterminado: llama3.2)

Para una configuración detallada de PostgreSQL, consulta la Documentación de Almacenamiento PostgreSQL.

Usando Docker

Construye la imagen:
```
podman build -t projectflow .
```

Ejecuta el contenedor:

podman run -p 16191:16191 -v $(pwd)/data:/app/data projectflow

Documentación de la API

Chat API

POST /api/chat - Envía un mensaje en lenguaje natural a la interfaz de chat
GET /api/chat/history - Recupera el historial de conversación

LLM API

GET /api/llm/info - Obtén información y estado del proveedor de LLM
GET /api/llm/health - Verifica el estado de salud del proveedor de LLM
POST /api/llm/chat - Envía mensajes directos al LLM (omite la traducción de ProjectFlow)

Solicitud/Respuesta del Chat

Enviar Mensaje:

POST /api/chat
{
  "message": "Create a high priority task to fix the login bug",
  "conversation_id": "optional-uuid"
}

Respuesta:

{
  "response": "I've created task PF-123: 'Fix login bug' with high priority.",
  "actions_taken": ["create_task"],
  "task_ids": ["PF-123"],
  "conversation_id": "uuid",
  "confidence": 0.95,
  "intent": "create_task"
}

Obtener Historial:

GET /api/chat/history?conversation_id=uuid

{
  "id": "uuid",
  "messages": [
    {
      "id": "msg-uuid",
      "role": "user",
      "content": "Create a task...",
      "timestamp": "2025-06-22T15:17:44.334579Z"
    }
  ],
  "created": "2025-06-22T15:17:44.334574Z",
  "updated": "2025-06-22T15:17:44.334574Z"
}

Ejemplos de la API LLM

Obtener Información del LLM:

GET /api/llm/info

{
  "enabled": true,
  "provider": "ollama",
  "model": "llama3.2",
  "status": "healthy",
  "timestamp": "2025-06-23T08:56:47.927Z",
  "metadata": {
    "host": "http://localhost:11434",
    "version": "0.1.17"
  }
}

Verificar Salud del LLM:

GET /api/llm/health

{
  "healthy": true,
  "status": "healthy",
  "provider": "ollama",
  "timestamp": "2025-06-23T08:56:47.927Z",
  "duration_ms": 45,
  "suggestions": []
}

Chat Directo con LLM:

POST /api/llm/chat
{
  "messages": [
    {"role": "user", "content": "Hello!"}
  ],
  "max_tokens": 1000,
  "temperature": 0.7
}

Response:
{
  "response": {
    "choices": [
      {
        "message": {
          "role": "assistant",
          "content": "Hello! How can I help you today?"
        },
        "finish_reason": "stop"
      }
    ]
  },
  "provider": "ollama",
  "model": "llama3.2"
}

API de Tareas

GET /api/tasks - Lista todas las tareas
POST /api/tasks - Crea una nueva tarea
GET /api/tasks/{id} - Obtén una tarea por ID
PUT /api/tasks/{id} - Actualiza una tarea
DELETE /api/tasks/{id} - Elimina una tarea
GET /api/hierarchy - Obtén tareas en estructura jerárquica

Estructura de Tareas

{
  "id": "string",
  "title": "string",
  "description": "string",
  "status": "string",
  "priority": "string",
  "parent_id": "string",
  "children": ["string"],
  "created_at": "timestamp",
  "updated_at": "timestamp"
}

Estructura Jerárquica

El endpoint /api/hierarchy devuelve tareas en una estructura anidada:

[
  {
    "task": {
      "id": "string",
      "title": "string",
      "description": "string",
      "status": "string",
      "priority": "string",
      "type": "string",
      "parent_id": "string",
      "children": ["string"],
      "created_at": "timestamp",
      "updated_at": "timestamp"
    },
    "child_tasks": [
      {
        "task": { /* nested task */ },
        "child_tasks": [ /* recursively nested */ ]
      }
    ]
  }
]

Desarrollo

Estructura del Proyecto

├── cmd/server/          # Application entry point
├── internal/
│   ├── handlers/        # HTTP handlers
│   ├── models/          # Data models
│   └── storage/         # Storage implementations
├── pkg/api/            # Public API definitions
├── web/
│   ├── templates/      # HTML templates
│   └── static/         # CSS, JS, images
├── data/               # Local data storage
└── Dockerfile          # Container definition

Ejecución de Pruebas

go test ./...

Compilación

go build -o bin/projectflow cmd/server/main.go

Model Context Protocol (MCP)

ProjectFlow incluye un servidor del Protocolo de Contexto de Modelo (MCP) que permite a los agentes de IA interactuar con tareas de forma programática. Esto permite a los asistentes de IA crear, leer, actualizar y eliminar tareas como parte de su flujo de trabajo.

Configuración del Servidor MCP

Inicia el servidor MCP:
```
go run cmd/mcp-server/main.go
```
El servidor MCP se ejecuta en el puerto 3001 de forma predeterminada.

Configura tu cliente MCP: Usa el archivo mcp-config.json proporcionado o configura manualmente:

{
  "mcpServers": {
    "projectflow": {
      "command": "go",
      "args": ["run", "cmd/mcp-server/main.go"],
      "cwd": "/path/to/projectflow"
    }
  }
}

Herramientas MCP Disponibles

El servidor MCP proporciona estas herramientas para la gestión de tareas:

list_tasks - Lista todas las tareas con filtrado opcional
create_task - Crea una nueva tarea
get_task - Obtén una tarea específica por ID
update_task - Actualiza una tarea existente
delete_task - Elimina una tarea
get_task_hierarchy - Obtén tareas en estructura jerárquica

Recursos MCP Disponibles

El servidor MCP expone estos recursos:

tasks://all - Lista de todas las tareas
tasks://hierarchy - Estructura jerárquica de tareas
tasks://summary - Resumen del proyecto con estadísticas

Ejemplo de Uso

# Start both servers
go run cmd/server/main.go &          # HTTP server on :16191
go run cmd/mcp-server/main.go &      # MCP server on :3001

# Use with MCP-compatible AI clients
# The AI can now create, manage, and query tasks programmatically

Integración con Agentes de IA

Los agentes de IA pueden usar la interfaz MCP para:

Crear y gestionar tareas de desarrollo
Realizar seguimiento del progreso del proyecto
Generar informes y resúmenes
Automatizar procesos de flujo de trabajo
Integrarse con otras herramientas de desarrollo

Para documentación detallada de MCP, consulta docs/mcp.md.

Integración del Proyecto con VS Code

ProjectFlow se puede integrar perfectamente en tus proyectos de VS Code, permitiéndote almacenar y gestionar tareas junto con tu código en Git. Esto habilita potentes flujos de trabajo de desarrollo asistido por IA donde los agentes de codificación pueden crear, actualizar y realizar seguimiento de tareas de desarrollo directamente dentro del contexto de tu proyecto.

Configuración `.vscode/mcp.json`

Agrega un archivo .vscode/mcp.json a la raíz de tu proyecto para configurar ProjectFlow como servidor MCP:

{
  "mcpServers": {
    "projectflow": {
      "command": "go",
      "args": ["run", "cmd/mcp-server/main.go"],
      "cwd": "/path/to/projectflow",
      "env": {
        "STORAGE_DIR": "./.projectflow/data"
      }
    }
  }
}

Almacenamiento de Tareas Específico del Proyecto

Cuando se integra con tu proyecto, ProjectFlow almacenará las tareas en un directorio .projectflow/data/ dentro de tu proyecto:

your-project/
├── .vscode/
│   └── mcp.json              # MCP configuration
├── .projectflow/
│   └── data/
│       └── tasks/            # Project-specific tasks
│           ├── epic-1.json   # Your development epics
│           ├── story-1.json  # User stories
│           └── task-1.json   # Development tasks
├── src/                      # Your application code
├── README.md
└── .gitignore

Beneficios de la Integración del Proyecto

Control de Versiones Unificado: Las tareas se versionan junto con tu código
IA Consciente del Contexto: Los agentes de codificación comprenden tanto el código como el contexto de las tareas
Colaboración en Equipo: Gestión compartida de tareas a través de Git
Tareas Específicas por Rama: Diferentes ramas pueden tener diferentes estados de tareas
Flujos de Trabajo Automatizados: Los agentes de IA pueden crear tareas a partir del análisis de código

Ejemplo de Flujo de Trabajo

Inicializa ProjectFlow en tu proyecto:

mkdir -p .projectflow/data/projects
echo ".projectflow/data/projects/*/*.json" >> .gitignore  # Optional: exclude project and task files

Configura el MCP de VS Code:

{
  "mcpServers": {
    "projectflow": {
      "command": "go",
      "args": ["run", "/path/to/projectflow/cmd/mcp-server/main.go"],
      "env": {
        "STORAGE_DIR": "./.projectflow/data"
      }
    }
  }
}

Usa con Agentes de Codificación de IA:
- Los agentes de IA pueden crear tareas basadas en el análisis de código
- Realiza seguimiento del progreso de desarrollo junto con los cambios de código
- Genera tareas a partir de comentarios TODO en el código
- Vincula tareas a commits o pull requests específicos

Integración con el Flujo de Trabajo de Desarrollo

La integración MCP de ProjectFlow habilita potentes flujos de trabajo de desarrollo:

Creación Automatizada de Tareas: Los agentes de IA analizan el código y crean tareas relevantes
Seguimiento de Progreso: Vincula tareas a commits y pull requests
Tareas de Revisión de Código: Genera tareas de revisión para cambios de código específicos
Seguimiento de Errores: Crea y realiza seguimiento de errores directamente desde el análisis de código
Planificación de Funcionalidades: Planifica funcionalidades como tareas jerárquicas (Épica → Historia → Tarea)

Acceso al Frontend

Aunque la interfaz principal es a través de MCP y agentes de IA, aún puedes acceder al frontend web:

Inicia el servidor de ProjectFlow apuntando a los datos de tu proyecto:

STORAGE_DIR=./.projectflow/data go run /path/to/projectflow/cmd/server/main.go

Abre http://localhost:16191 para ver y gestionar tareas en la interfaz web

Mejores Prácticas de Integración con Git

Confirma los cambios de tareas: Incluye actualizaciones de tareas en tus commits
Tareas específicas por rama: Usa diferentes estados de tareas por rama
Sincronización de equipo: Extrae actualizaciones de tareas al sincronizar con el equipo
Limpieza de tareas: Archiva tareas completadas periódicamente

Documentación

Documentación de Usuario

Guía de Usuario - Guía completa para usuarios finales
Guía de Interfaz de Chat - Comandos en lenguaje natural y ejemplos
FAQ - Preguntas frecuentes y respuestas

Documentación de Administrador

Guía de Despliegue - Opciones de despliegue en producción
Guía de Configuración de LLM - Configura proveedores de IA
Almacenamiento PostgreSQL - Configuración y ajustes de la base de datos
Guía de Solución de Problemas - Problemas comunes y soluciones

Documentación de Desarrollador

Guía de Desarrollador - Extender y personalizar ProjectFlow
Documentación de MCP - Integración del Protocolo de Contexto de Modelo
Guía de Configuración - Variables de entorno y ajustes
Sistema de Ayuda en la Aplicación - Implementación de ayuda del frontend

Contribuciones

Haz un fork del repositorio
Crea una rama de funcionalidad
Realiza tus cambios con las pruebas adecuadas
Envía un pull request

Consulta nuestra Guía de Desarrollador para pautas detalladas de contribución.

Licencia

Licencia MIT - consulta el archivo LICENSE para más detalles.

ProjectFlow

Documentación

ProjectFlow

Características

Stack Tecnológico

Inicio Rápido

Requisitos Previos

Ejecución Local

💬 Interfaz de Chat en Lenguaje Natural

Ejemplos Rápidos

Cómo Empezar con el Chat

Configuración del LLM

Configuración Rápida con Ollama (LLM Local)

Proveedores de LLM en la Nube

Variables de Entorno

Usando Docker

Documentación de la API

Chat API

LLM API

Solicitud/Respuesta del Chat

Ejemplos de la API LLM

API de Tareas

Estructura de Tareas

Estructura Jerárquica

Desarrollo

Estructura del Proyecto

Ejecución de Pruebas

Compilación

Model Context Protocol (MCP)

Configuración del Servidor MCP

Herramientas MCP Disponibles

Recursos MCP Disponibles

Ejemplo de Uso

Integración con Agentes de IA

Integración del Proyecto con VS Code

Configuración .vscode/mcp.json

Almacenamiento de Tareas Específico del Proyecto

Beneficios de la Integración del Proyecto

Ejemplo de Flujo de Trabajo

Integración con el Flujo de Trabajo de Desarrollo

Acceso al Frontend

Mejores Prácticas de Integración con Git

Documentación

Documentación de Usuario

Documentación de Administrador

Documentación de Desarrollador

Contribuciones

Licencia

Configuración `.vscode/mcp.json`