ProjectFlow

Um sistema de gerenciamento de fluxo de trabalho para desenvolvimento assistido por IA com suporte a MCP, oferecendo armazenamento flexível via sistema de arquivos ou PostgreSQL.

GitHub

Experimente este MCPPatrocinado

Documentação

ProjectFlow

Um sistema de gerenciamento de fluxo de trabalho para desenvolvimento assistido por IA, semelhante ao Jira ou Azure DevOps. Suporta interações orientadas por API e o Model Context Protocol para integração perfeita com agentes de IA.

Funcionalidades

Gerenciamento hierárquico de tarefas (Épicos, Histórias, Subtarefas)
🚀 NOVO: Interface de Chat em Linguagem Natural - Interaja com o ProjectFlow usando comandos conversacionais
API REST para acesso programático
Suporte ao Model Context Protocol (MCP) para agentes de IA
Interface web para usuários humanos
Armazenamento flexível: sistema de arquivos (JSON) ou banco de dados PostgreSQL
Interface limpa e moderna com recursos de acessibilidade
Implantação conteinerizada

Stack de Tecnologias

Backend: Go 1.24
Armazenamento: Sistema de arquivos (JSON) ou banco de dados PostgreSQL
Frontend: Modelos HTML, CSS, JavaScript
Conteinerização: Docker/Podman
Protocolos: API REST HTTP + Model Context Protocol

Início Rápido

Pré-requisitos

Go 1.24 ou posterior
Docker/Podman (para implantação conteinerizada)

Executando Localmente

Clone o repositório:

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

Execute a aplicação:
```
go run cmd/server/main.go
```
Abra seu navegador e acesse http://localhost:16191

💬 Interface de Chat em Linguagem Natural

O ProjectFlow agora possui uma interface de chat com tecnologia de IA que permite gerenciar tarefas e projetos usando comandos em linguagem natural. Basta clicar no botão de chat (💬) no cabeçalho ou usar o atalho de teclado ⌘+/ (Mac) ou Ctrl+/ (Windows/Linux) para começar.

Exemplos 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"

Começando com o Chat

Abra a interface de chat: Clique no botão 💬 no cabeçalho ou pressione ⌘+/
Digite sua solicitação: Use linguagem natural para descrever o que deseja fazer
Obtenha resultados instantâneos: A IA interpretará sua solicitação e executará a ação

Para comandos de chat detalhados e exemplos, consulte o Guia da Interface de Chat.

Configuração do LLM

A interface de chat suporta vários provedores de LLM:

🚀 Ollama: Use modelos LLM locais para privacidade e capacidade offline
OpenAI GPT: Use os modelos GPT da OpenAI para compreensão de linguagem natural
Groq: Inferência LLM rápida baseada em nuvem
Anthropic Claude: Aproveite a IA Claude da Anthropic para interações conversacionais

Configuração Rápida com Ollama (LLM Local)

Para a configuração mais rápida com privacidade e sem custos 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

Consulte o Guia de Início Rápido do Ollama para instruções detalhadas de configuração.

Provedores de LLM em Nuvem

Para LLMs baseados em nuvem, configure sua chave 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

Variáveis de Ambiente

Configuração do Servidor:

PORT: Porta do servidor (padrão: 16191)
SHUTDOWN_TIMEOUT: Tempo limite de desligamento gracioso em segundos (padrão: 30)
LOG_LEVEL: Nível de log - DEBUG, INFO, WARN, ERROR (padrão: INFO)
LOG_FORMAT: Formato de log - json ou text (padrão: text)

Configuração de Armazenamento:

STORAGE_TYPE: Backend de armazenamento - file ou postgres (padrão: file)

Armazenamento de Arquivos:

DATA_DIR: Diretório para armazenamento de dados (padrão: ./data)

Armazenamento PostgreSQL:

DB_HOST: Host do banco de dados (padrão: localhost)
DB_PORT: Porta do banco de dados (padrão: 5432)
DB_NAME: Nome do banco de dados (padrão: projectflow)
DB_USER: Usuário do banco de dados (padrão: projectflow)
DB_PASSWORD: Senha do banco de dados (obrigatória para postgres)
DB_SSL_MODE: Modo SSL - disable, require, verify-ca, verify-full, prefer, allow (padrão: prefer)

Configuração do LLM (para a Interface de Chat):

LLM_PROVIDER: Provedor LLM - ollama, groq, openai, disabled (padrão: disabled)
LLM_API_KEY: Chave de API para provedores LLM em nuvem (obrigatória para groq, openai)
LLM_BASE_URL: URL base personalizada para o provedor LLM (opcional)
LLM_MODEL: Nome do modelo a ser usado (o padrão varia conforme o provedor)
LLM_TIMEOUT: Tempo limite de solicitação em segundos (padrão: 60)
LLM_MAX_TOKENS: Máximo de tokens por resposta (padrão: 1000)

Específico do Ollama (para LLM local):

LLM_OLLAMA_HOST: URL do servidor Ollama (padrão: http://localhost:11434)
LLM_OLLAMA_MODEL: Nome do modelo Ollama (padrão: llama3.2)

Para configuração detalhada do PostgreSQL, consulte a Documentação de Armazenamento PostgreSQL.

Usando Docker

Construa a imagem:
```
podman build -t projectflow .
```

Execute o contêiner:

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

Documentação da API

Chat API

POST /api/chat - Envie uma mensagem em linguagem natural para a interface de chat
GET /api/chat/history - Recupere o histórico da conversa

LLM API

GET /api/llm/info - Obtenha informações e status do provedor LLM
GET /api/llm/health - Verifique a saúde do provedor LLM
POST /api/llm/chat - Envie mensagens diretas ao LLM (ignora a tradução do ProjectFlow)

Solicitação/Resposta do Chat

Enviar Mensagem:

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

Resposta:

{
  "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"
}

Obter Histórico:

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"
}

Exemplos da API LLM

Obter Informações do 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 Saúde do LLM:

GET /api/llm/health

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

Chat Direto com 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 Tarefas

GET /api/tasks - Liste todas as tarefas
POST /api/tasks - Crie uma nova tarefa
GET /api/tasks/{id} - Obtenha uma tarefa por ID
PUT /api/tasks/{id} - Atualize uma tarefa
DELETE /api/tasks/{id} - Exclua uma tarefa
GET /api/hierarchy - Obtenha tarefas em estrutura hierárquica

Estrutura de Tarefas

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

Estrutura Hierárquica

O endpoint /api/hierarchy retorna tarefas em uma estrutura aninhada:

[
  {
    "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 */ ]
      }
    ]
  }
]

Desenvolvimento

Estrutura do Projeto

├── 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

Executando Testes

go test ./...

Compilação

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

Model Context Protocol (MCP)

O ProjectFlow inclui um servidor Model Context Protocol (MCP) que permite que agentes de IA interajam com tarefas programaticamente. Isso permite que assistentes de IA criem, leiam, atualizem e excluam tarefas como parte de seu fluxo de trabalho.

Configuração do Servidor MCP

Inicie o servidor MCP:
```
go run cmd/mcp-server/main.go
```
O servidor MCP é executado na porta 3001 por padrão.

Configure seu cliente MCP: Use o arquivo mcp-config.json fornecido ou configure manualmente:

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

Ferramentas MCP Disponíveis

O servidor MCP fornece estas ferramentas para gerenciamento de tarefas:

list_tasks - Liste todas as tarefas com filtragem opcional
create_task - Crie uma nova tarefa
get_task - Obtenha uma tarefa específica por ID
update_task - Atualize uma tarefa existente
delete_task - Exclua uma tarefa
get_task_hierarchy - Obtenha tarefas em estrutura hierárquica

Recursos MCP Disponíveis

O servidor MCP expõe estes recursos:

tasks://all - Lista de todas as tarefas
tasks://hierarchy - Estrutura hierárquica de tarefas
tasks://summary - Resumo do projeto com estatísticas

Exemplo 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

Integração com Agentes de IA

Agentes de IA podem usar a interface MCP para:

Criar e gerenciar tarefas de desenvolvimento
Acompanhar o progresso do projeto
Gerar relatórios e resumos
Automatizar processos de fluxo de trabalho
Integrar com outras ferramentas de desenvolvimento

Para documentação detalhada do MCP, consulte docs/mcp.md.

Integração do Projeto com VS Code

O ProjectFlow pode ser integrado perfeitamente aos seus projetos VS Code, permitindo armazenar e gerenciar tarefas junto com seu código no Git. Isso possibilita fluxos de trabalho poderosos de desenvolvimento assistido por IA, onde agentes de codificação podem criar, atualizar e acompanhar tarefas de desenvolvimento diretamente no contexto do seu projeto.

Configuração `.vscode/mcp.json`

Adicione um arquivo .vscode/mcp.json à raiz do seu projeto para configurar o ProjectFlow como servidor MCP:

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

Armazenamento de Tarefas Específico do Projeto

Quando integrado ao seu projeto, o ProjectFlow armazenará tarefas em um diretório .projectflow/data/ dentro do seu projeto:

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

Benefícios da Integração do Projeto

Controle de Versão Unificado: Tarefas são versionadas junto com seu código
IA Ciente do Contexto: Agentes de codificação entendem tanto o código quanto o contexto das tarefas
Colaboração em Equipe: Gerenciamento compartilhado de tarefas via Git
Tarefas Específicas por Branch: Branches diferentes podem ter estados de tarefas diferentes
Fluxos de Trabalho Automatizados: Agentes de IA podem criar tarefas a partir da análise de código

Exemplo de Fluxo de Trabalho

Inicialize o ProjectFlow no seu projeto:

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

Configure o MCP do VS Code:

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

Use com Agentes de Codificação de IA:
- Agentes de IA podem criar tarefas com base na análise de código
- Acompanhe o progresso do desenvolvimento junto com as alterações de código
- Gere tarefas a partir de comentários TODO no código
- Vincule tarefas a commits ou pull requests específicos

Integração com o Fluxo de Trabalho de Desenvolvimento

A integração MCP do ProjectFlow possibilita fluxos de trabalho de desenvolvimento poderosos:

Criação Automatizada de Tarefas: Agentes de IA analisam o código e criam tarefas relevantes
Acompanhamento de Progresso: Vincule tarefas a commits e pull requests
Tarefas de Revisão de Código: Gere tarefas de revisão para alterações específicas de código
Rastreamento de Bugs: Crie e acompanhe bugs diretamente da análise de código
Planejamento de Funcionalidades: Planeje funcionalidades como tarefas hierárquicas (Épico → História → Tarefa)

Acesso ao Frontend

Embora a interface principal seja por meio do MCP e agentes de IA, você ainda pode acessar o frontend web:

Inicie o servidor ProjectFlow apontando para os dados do seu projeto:

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

Abra http://localhost:16191 para visualizar e gerenciar tarefas na interface web

Melhores Práticas de Integração com Git

Faça commit das alterações de tarefas: Inclua atualizações de tarefas em seus commits
Tarefas específicas por branch: Use estados de tarefas diferentes por branch
Sincronização da equipe: Puxe atualizações de tarefas ao sincronizar com a equipe
Limpeza de tarefas: Arquive tarefas concluídas periodicamente

Documentação

Documentação do Usuário

Guia do Usuário - Guia abrangente para usuários finais
Guia da Interface de Chat - Comandos em linguagem natural e exemplos
FAQ - Perguntas frequentes e respostas

Documentação do Administrador

Guia de Implantação - Opções de implantação em produção
Guia de Configuração do LLM - Configure provedores de IA
Armazenamento PostgreSQL - Configuração e instalação do banco de dados
Guia de Solução de Problemas - Problemas comuns e soluções

Documentação do Desenvolvedor

Guia do Desenvolvedor - Estendendo e personalizando o ProjectFlow
Documentação MCP - Integração com o Model Context Protocol
Guia de Configuração - Variáveis de ambiente e configurações
Sistema de Ajuda no Aplicativo - Implementação de ajuda no frontend

Contribuindo

Faça um fork do repositório
Crie um branch de funcionalidade
Faça suas alterações com testes adequados
Envie um pull request

Consulte nosso Guia do Desenvolvedor para diretrizes detalhadas de contribuição.

Licença

Licença MIT - consulte o arquivo LICENSE para obter detalhes.

ProjectFlow

Documentação

ProjectFlow

Funcionalidades

Stack de Tecnologias

Início Rápido

Pré-requisitos

Executando Localmente

💬 Interface de Chat em Linguagem Natural

Exemplos Rápidos

Começando com o Chat

Configuração do LLM

Configuração Rápida com Ollama (LLM Local)

Provedores de LLM em Nuvem

Variáveis de Ambiente

Usando Docker

Documentação da API

Chat API

LLM API

Solicitação/Resposta do Chat

Exemplos da API LLM

API de Tarefas

Estrutura de Tarefas

Estrutura Hierárquica

Desenvolvimento

Estrutura do Projeto

Executando Testes

Compilação

Model Context Protocol (MCP)

Configuração do Servidor MCP

Ferramentas MCP Disponíveis

Recursos MCP Disponíveis

Exemplo de Uso

Integração com Agentes de IA

Integração do Projeto com VS Code

Configuração .vscode/mcp.json

Armazenamento de Tarefas Específico do Projeto

Benefícios da Integração do Projeto

Exemplo de Fluxo de Trabalho

Integração com o Fluxo de Trabalho de Desenvolvimento

Acesso ao Frontend

Melhores Práticas de Integração com Git

Documentação

Documentação do Usuário

Documentação do Administrador

Documentação do Desenvolvedor

Contribuindo

Licença

Configuração `.vscode/mcp.json`