ProjectFlow — Detalhes técnicos

Componentes

agente desktop (WPF) + API central (ASP.NET Core) + Postgres

Protocolo

MCP — Model Context Protocol, sobre HTTP

Compatibilidade

qualquer cliente MCP — validado com Claude Code e Cursor

Autenticação

X-Client-Id / X-Client-Secret, hash PBKDF2-SHA256

Estado

homologação — fase de teste, acesso por credencial individual

1. O problema

Toda ferramenta de IA que trabalha em código tem o mesmo limite: a janela de conversa é a única memória que existe. Fechou a janela, trocou de sessão, ou a conversa ficou longa demais — o contexto acumulado (o que já foi decidido, onde uma tarefa parou, por que uma abordagem foi escolhida) desaparece.

Isso se agrava em dois pontos: o estado do código — o que mudou desde a última vez que alguém olhou — não é algo que a IA veja sozinha sem reler o repositório inteiro; e o estado da tarefa — uma decisão fechada, um "porquê" que não está no código, um próximo passo combinado — não existe em lugar nenhum fora da conversa que já terminou.

2. A solução, em uma frase

Um agente desktop observa o repositório local e mantém um resumo do código sempre atualizado dentro do próprio projeto; uma API central expõe esse mesmo projeto como um servidor MCP, com duas ferramentas — save_memory e get_memory — que qualquer cliente MCP (Claude Code, Cursor, ou o que vier depois) pode chamar para gravar e recuperar o contexto de uma tarefa em andamento.

3. Arquitetura

Dois processos rodam na máquina de quem desenvolve — o repositório git e a ferramenta de IA — mais um terceiro, o agente do ProjectFlow, que faz a ponte entre eles e a API central.

O agente WPF e a ferramenta de IA nunca conversam diretamente entre si — os dois falam apenas com a API, e é a API quem guarda o estado real. Isso permite trocar de ferramenta sem perder nada: o dado nunca pertenceu à ferramenta.

4. Captura de contexto do código

O agente roda em segundo plano e, a cada ciclo (padrão: alguns minutos, configurável), executa um git diff contra o repositório local — tanto o que ainda não foi commitado quanto o que mudou desde o último ciclo. O diff é parseado em blocos por arquivo/namespace/classe (granularidade real via Roslyn para .cs; conteúdo completo para os demais tipos rastreados) e enviado para a API, que persiste cada bloco como contexto vinculado ao projeto.

Em seguida, o agente busca de volta um snapshot consolidado e escreve, dentro do próprio repositório, o arquivo docs/project/current-state.md — um resumo legível do estado atual do código, sem exigir configuração especial de nenhuma ferramenta de IA pra ser lido.

5. Governança via arquivos-padrão

No cadastro de um projeto, o agente grava automaticamente na raiz do repositório um pequeno conjunto de arquivos, reconciliados por diff a cada atualização — nunca sobrescrevem algo que já foi preenchido manualmente:

6. Memória de continuidade (MCP)

A API expõe um servidor MCP real (SDK oficial ModelContextProtocol, transporte HTTP) no endpoint /mcp, com duas ferramentas:

• save_memory — grava um título + resumo da tarefa em andamento. Sempre um insert, nunca sobrescreve o que já existe.
• get_memory — recupera as últimas N entradas daquele projeto (padrão 10, teto 50), mais recentes primeiro.

A memória pertence ao projeto, não à ferramenta — salvar usando Claude Code hoje e abrir o mesmo projeto no Cursor amanhã recupera exatamente a mesma informação.

Confiabilidade observada: nem Claude Code nem Cursor chamam essas ferramentas de forma confiável só por estarem descritas no AGENTS.md — funciona de forma consistente quando a instrução é explícita, e — ao abrir uma janela nova — quando get_memory é pedido explicitamente, sem contar com recuperação automática. O próprio Cursor recomenda citar o nome da ferramenta (save_memory/get_memory) para garantir essa confiabilidade; no Claude Code, pedir de forma natural já costuma funcionar.

7. Suporte multi-ferramenta

O mesmo cadastro de projeto gera, sem escolha prévia do usuário, um arquivo de configuração MCP para cada cliente conhecido:

Ambos apontam para o mesmo endpoint /mcp, com os mesmos headers de autenticação. Um cliente Codex, ou qualquer outro que fale MCP sobre HTTP com autenticação por header, se conecta ao mesmo endpoint sem nenhuma mudança do lado da API.

8. Modelo de segurança

• Autenticação por header estático — X-Client-Id / X-Client-Secret em toda rota, exceto /health. Segredo nunca em texto puro: hash PBKDF2-SHA256, 100 mil iterações, salt por credencial.
• Isolamento por tenant — toda consulta filtra por dono; projeto de outro tenant retorna 404, nunca 403.
• Credencial master separada — só emite/revoga credenciais; bloqueada nas rotas de projeto.
• Credencial emissora separada — usada pelo site público para emitir credencial de teste (10 dias, 1 projeto, fixos no servidor) via POST /agent-credentials/test-request; não revoga nem acessa rotas de projeto/admin.
• Expiração e limite de projeto opcionais — credenciais de terceiros podem ter prazo de validade e teto de projetos; credencial expirada é removida automaticamente ao ser solicitada de novo para o mesmo e-mail.
• Rate limiting — 100 requisições/minuto por X-Client-Id, rejeitado na hora com 429.

9. Stack