Project Bridge

Uma ponte segura entre agentes de IA e um sistema de projetos: a IA pode consultar contexto e propor mudanças, mas uma pessoa continua responsável por decidir o que realmente será alterado.

Documentação: Português (este arquivo) · English

Em resumo: o Project Bridge não é um Jira completo e não é um gerenciador de APIs. É um MVP de integração e governança para agentes de IA, usando a gestão de projetos como caso de uso.

Entenda o projeto em dois minutos

O que ele é

O Project Bridge demonstra como permitir que um agente de IA participe de um fluxo de trabalho real sem receber acesso irrestrito ao sistema.

Por meio do Model Context Protocol (MCP), um cliente de IA pode:

• consultar apenas o contexto necessário de um projeto;

• ler tarefas, bloqueios, riscos e decisões;

• propor a criação ou atualização de uma tarefa;

• propor a resolução de um bloqueio;

• acompanhar o resultado de uma solicitação.

As propostas não alteram os dados imediatamente. Elas entram em uma fila de revisão, na qual um usuário autorizado pode aprovar ou rejeitar a ação. O backend valida identidade, permissões, escopo, versão dos dados e idempotência antes de realizar qualquer mudança.

Isso separa claramente duas responsabilidades:

• a IA sugere, com base no contexto e nas ferramentas permitidas;

• o sistema e a pessoa decidem, aplicando regras de autorização e governança.

O que ele não é

• Não é um gerenciador de projetos completo. A interface apresenta projetos, tarefas, riscos, decisões e bloqueios para demonstrar o domínio, mas não oferece toda a experiência de produtos como Jira, Linear ou Trello.

• Não é um gerenciador de APIs. A API e o servidor MCP são os meios de integração, não o produto final.

• Não é um chatbot. O foco está em contexto estruturado, ferramentas tipadas, autorização, aprovação e rastreabilidade.

• Não contém um modelo generativo embutido. Ele expõe uma infraestrutura que pode ser consumida por clientes compatíveis com MCP, como o Codex.

• Não aprova ou rejeita projetos. A aprovação decide se uma ação proposta — por exemplo, criar uma tarefa — deve ou não modificar o projeto.

No MVP atual, tarefas, riscos, decisões e bloqueios aparecem como resumos dentro do projeto e não possuem páginas individuais clicáveis. Essa é uma limitação deliberada de escopo: o objetivo principal é demonstrar a integração segura com agentes de IA, e não reproduzir todas as funções de um sistema de gestão.

Para quem este repositório é útil

• Usuários e avaliadores: para visualizar um fluxo em que uma sugestão automatizada sempre passa por controle humano.

• Recrutadores: para avaliar aplicação prática de MCP, human-in-the-loop, segurança, idempotência, concorrência, observabilidade e testes.

• Desenvolvedores: para estudar uma referência local e reproduzível de servidor MCP e aplicação web compartilhando o mesmo domínio.

Related MCP server: infrahub-mcp

Exemplo prático

Imagine que um agente esteja analisando o projeto fictício Atlas e identifique que uma tarefa crítica precisa mudar de prioridade:

1. O agente consulta o contexto permitido do projeto pelo MCP.

2. Ele chama a ferramenta propose_task_update, informando a alteração e a justificativa.

3. O servidor valida o token, os escopos, os argumentos e a existência da tarefa no projeto.

4. A proposta aparece na Central de Aprovações como pendente.

5. Uma pessoa revisa a ação, os dados anteriores, a alteração proposta e a justificativa.

6. Ao aprovar, o backend atualiza a tarefa; ao rejeitar, nenhuma alteração é aplicada ao projeto.

7. A decisão e a execução ficam registradas na auditoria e nos traces.

8. Clientes MCP conectados podem receber a notificação de que o recurso foi atualizado.

Depois da decisão, o cartão permanece na Central de Aprovações como histórico auditável. Os itens internos do projeto continuam exibidos como resumos porque não fazem parte de um módulo completo de gestão nesta versão.

Problema que a arquitetura resolve

Dar acesso direto de um agente ao banco de dados ou a endpoints administrativos cria riscos difíceis de controlar:

• exposição de contexto além do necessário;

• escalada indevida de permissões;

• operações duplicadas após retries;

• sobrescrita de alterações concorrentes;

• falhas entre a gravação de uma mudança e a publicação de um evento;

• ausência de evidências sobre quem propôs, aprovou e executou uma ação.

O Project Bridge trata o agente como um participante limitado do sistema. Contexto e ferramentas são publicados por contrato; mutações são propostas; autorizações são verificadas no servidor; e toda ação relevante produz rastros verificáveis.

Fluxo principal

flowchart LR
    A[Cliente de IA] -->|Consulta| M[Servidor MCP]
    M -->|Resources e tools de leitura| C[Contexto do projeto]
    A -->|Tool propose_*| V[Validação e autorização]
    V --> P[Solicitação pendente]
    P --> H{Revisão humana}
    H -->|Rejeitar| N[Nenhuma mudança]
    H -->|Aprovar| D[Alteração no domínio]
    D --> O[Outbox transacional]
    O --> R[Recurso atualizado]
    M --> T[Auditoria e OpenTelemetry]
    H --> T
    D --> T

As tools propose_* nunca executam a mudança de domínio diretamente. A mutação só ocorre após uma decisão humana válida e uma nova verificação das regras no backend.

O que pode ser avaliado no portfólio

• servidor MCP com resources, tools, prompt, notificações e contratos tipados;

• transportes HTTP Streamable e stdio;

• validação de entrada e saída com Zod;

• autenticação Bearer e autorização por escopos MCP;

• senhas derivadas com scrypt, sessões revogáveis e RBAC;

• fluxo human-in-the-loop para todas as mutações propostas por IA;

• idempotência na criação e na decisão de solicitações;

• concorrência otimista com versão esperada;

• outbox transacional com nova tentativa após falha de publicação;

• notificações resources/updated após publicação;

• auditoria persistida de leituras, propostas e decisões;

• spans OpenTelemetry e exportação OTLP opcional;

• testes de contrato executados sem depender de um modelo pago;

• CI para testes, tipos, build e auditoria de dependências.

Experiência disponível na interface

A aplicação web foi desenhada como um produto administrativo comum, sem aparência de chatbot:

• login com perfis de administrador, revisor e visualizador;

• tutorial no primeiro acesso;

• visão geral dos projetos e indicadores;

• criação e edição das informações principais de um projeto;

• projeto fictício Atlas com dados prontos para demonstração;

• resumos de tarefas, riscos, decisões e bloqueios;

• Central de Aprovações com comparação entre estado atual e alteração proposta;

• histórico de solicitações aprovadas e rejeitadas;

• página de integrações com instruções MCP;

• visualização de auditoria;

• visualizador de traces com duração, atributos, erros e correlação.

Arquitetura

project-bridge/
├── apps/server/
│   ├── API HTTP e aplicação web
│   ├── autenticação, sessões e RBAC
│   ├── servidor MCP HTTP e stdio
│   ├── domínio compartilhado
│   ├── SQLite, migrations e outbox
│   ├── auditoria e OpenTelemetry
│   └── testes de contrato
├── apps/web/
│   ├── Central de Projetos
│   ├── Central de Aprovações
│   ├── Integrações e auditoria
│   └── visualizador de traces
├── docs/
│   ├── imagens da demonstração
│   └── validação com o Codex
├── .codex/
│   └── exemplo de configuração MCP
├── Dockerfile
└── compose.yaml

A API web e os dois transportes MCP usam o mesmo domínio e a mesma camada de persistência. O servidor MCP não acessa o arquivo SQLite diretamente, evitando regras duplicadas ou caminhos alternativos de autorização.

Capacidades MCP

Resources

Tools

Prompt

project-status-review entrega uma sequência reutilizável para revisar o contexto estruturado com foco executivo, em riscos ou em entrega. O prompt orienta o cliente a separar fatos, riscos e recomendações e a nunca afirmar que uma proposta já foi executada.

Notificações

Após a publicação de um evento da outbox, clientes MCP inscritos recebem notifications/resources/updated. Assim, uma alteração aprovada pode invalidar o contexto anteriormente lido pelo agente.

Persistência e concorrência

• SQLite com migrations versionadas e aplicação automática;

• transações para dados de domínio, auditoria e eventos da outbox;

• expected_version nas edições de projeto feitas pela interface humana;

• conflito explícito quando a tarefa mudou depois da proposta;

• Idempotency-Key na criação de solicitações;

• decisão idempotente no backend;

• worker periódico para publicar eventos pendentes;

• evento marcado como processado somente depois da publicação;

• eventos preservados após falha para nova tentativa no ciclo seguinte.

O desenho é apropriado para execução local e instância única. SQLite não é apresentado como substituto de uma infraestrutura distribuída de produção.

Segurança demonstrada

• autenticação Bearer no MCP HTTP;

• comparação de tokens MCP por hash e em tempo constante;

• escopos específicos para leitura, consulta de aprovações e cada tipo de proposta, como projects:read, approvals:read e tasks:propose;

• autorização por escopo específico para cada categoria de tool;

• escopo projects:read aplicado também à leitura direta de Resources;

• sessões web revogáveis;

• RBAC no backend para leitura, revisão e administração;

• proteção de origem, cookie SameSite=Strict e opção Secure;

• limitação de tentativas de login por identidade e endereço de rede;

• Content Security Policy, bloqueio de iframes e outros cabeçalhos defensivos;

• validação estrita de schemas;

• rejeição de chaves idempotentes reaproveitadas com conteúdo diferente;

• decisão concluída protegida contra inversão por repetição da requisição;

• bloqueio de mutações sem aprovação humana;

• auditoria de leituras, propostas e decisões;

• traces limitados a metadados operacionais, sem registrar tokens ou senhas.

Observabilidade

Cada operação instrumentada recebe traceId e spanId. Os spans são persistidos localmente para a tela de inspeção e também podem ser enviados a um coletor compatível com OTLP.

Exemplos de operações instrumentadas:

• requisições HTTP, incluindo chamadas ao endpoint MCP;

• criação e atualização de projetos;

• decisão humana;

• tentativa de publicação da outbox.

Para habilitar exportação externa:

$env:OTEL_EXPORTER_OTLP_ENDPOINT = "http://localhost:4318"
$env:OTEL_SERVICE_NAME = "project-bridge"
pnpm dev

Sem OTEL_EXPORTER_OTLP_ENDPOINT, o projeto continua funcionando apenas com persistência local. Consulte a documentação oficial do OpenTelemetry.

Como executar

Requisitos

• Node.js 22 ou superior;

• pnpm 11 ou superior.

Instalação

pnpm install
pnpm dev

Endereços locais:

• interface: http://127.0.0.1:5174;

• API e MCP: http://127.0.0.1:8010;

• endpoint MCP: http://127.0.0.1:8010/mcp.

O frontend é servido pelo Vite em desenvolvimento. Alterações no backend exigem reiniciar pnpm dev.

Executar como artefato de produção

pnpm install --frozen-lockfile
pnpm build
$env:NODE_ENV = "production"
$env:PROJECT_BRIDGE_SEED_DEMO = "true" # somente para avaliação local
$env:PROJECT_BRIDGE_SECURE_COOKIES = "false" # somente enquanto usar HTTP local
pnpm --filter @project-bridge/server start

Nesse modo, o backend entrega a interface compilada e a API no endereço http://127.0.0.1:8010. Para uma instalação real, mantenha PROJECT_BRIDGE_SEED_DEMO=false e defina PROJECT_BRIDGE_ADMIN_EMAIL e uma PROJECT_BRIDGE_ADMIN_PASSWORD com ao menos 12 caracteres. Assim, contas demonstrativas com senhas conhecidas não são criadas acidentalmente.

Docker Compose

docker compose up --build

O Compose publica uma instância demonstrativa em http://localhost:8010 e preserva o SQLite no volume project_bridge_data. Antes de expor o serviço fora da máquina, troque a credencial MCP definida em PROJECT_BRIDGE_HTTP_CREDENTIALS, habilite cookies seguros, configure HTTPS no proxy e desative os dados demonstrativos.

Saúde, persistência e backup

• GET /api/health/live verifica se o processo está respondendo;

• GET /api/health/ready verifica o acesso ao SQLite e informa eventos pendentes na outbox;

• pnpm backup cria um snapshot verificado em .local/backups/ usando a API online de backup do SQLite;

• pnpm backup -- C:\caminho\seguro\project-bridge.db permite escolher um destino absoluto.

Para restaurar, pare o processo, preserve uma cópia do arquivo atual e substitua o banco configurado em PROJECT_BRIDGE_DB pelo snapshot. Os arquivos .db-wal e .db-shm não devem ser copiados separadamente com o serviço em execução.

Contas de demonstração

Essas credenciais são exclusivamente locais e não devem ser reutilizadas em produção.

Roteiro rápido de demonstração

1. Entre como administrador.

2. Conclua ou pule o tutorial inicial.

3. Abra o projeto Atlas e observe tarefas, riscos, decisões e bloqueios de exemplo.

4. Acesse Integrações para visualizar endpoint, transportes, resources, tools e escopos MCP.

5. Abra Aprovações e revise a solicitação de exemplo já incluída nos dados fictícios.

6. Aprove ou rejeite e confirme o resultado no histórico e no projeto.

7. Use Auditoria e Traces para acompanhar a trajetória completa da operação.

Conectar um cliente MCP

Transporte stdio

{
  "mcpServers": {
    "project-bridge": {
      "command": "pnpm",
      "args": ["--filter", "@project-bridge/server", "mcp:stdio"],
      "cwd": "CAMINHO_ABSOLUTO_DO_REPOSITORIO"
    }
  }
}

Transporte HTTP

Configure PROJECT_BRIDGE_HTTP_CREDENTIALS no processo do servidor, conforme o modelo de .env.example, e envie o token correspondente:

Authorization: Bearer pbmcp_...

O endpoint público /mcp exige Bearer token. Tokens ausentes ou inválidos retornam 401; chamadas a tools sem o escopo necessário retornam erro estruturado de autorização.

Há um exemplo em .codex/config.toml e um roteiro detalhado em docs/VALIDACAO_CODEX.md.

Scripts e qualidade

pnpm dev                                           # inicia API, MCP HTTP e frontend
pnpm --filter @project-bridge/server mcp:stdio     # inicia o servidor MCP por stdio
pnpm test                                          # executa os testes
pnpm typecheck                                     # valida os tipos
pnpm build                                         # gera os artefatos de produção
pnpm audit:deps                                    # audita dependências
pnpm backup                                        # cria um backup íntegro do SQLite

A suíte cobre 23 cenários, incluindo:

• autenticação e sessões;

• liveness, readiness, request ID e cabeçalhos de segurança;

• resposta segura para JSON malformado;

• limitação de tentativas de login e validação de origem;

• RBAC da aplicação web e escopos das tools MCP;

• escopos de tools e Resources MCP;

• schemas e contratos das tools;

• aprovação e rejeição;

• idempotência;

• conflito por reutilização incorreta de chave idempotente e decisão oposta;

• conflito de versão;

• outbox, nova tentativa após falha e notificações;

• propagação de contexto OpenTelemetry;

• exportação OTLP.

O workflow de CI executa testes, verificação de tipos, build, auditoria de dependências e build da imagem de produção.

Estado do MVP e limites de produção

Este repositório é um MVP de portfólio executável e empacotado, não um SaaS multiempresa pronto para internet pública.

• os dados são fictícios e voltados à demonstração;

• a execução é local e de instância única;

• a persistência usa SQLite;

• as contas são pré-configuradas, sem cadastro público;

• não há HTTPS, provedor de identidade externo ou recuperação de senha;

• não há integração real com Jira, Linear, Trello ou outros gestores;

• não há modelo generativo incorporado nem chave de IA obrigatória;

• tarefas, riscos, decisões e bloqueios não têm páginas individuais;

• não há comentários, anexos, busca avançada, filtros complexos ou colaboração em tempo real;

• a exportação OTLP fica desabilitada até que um endpoint seja configurado.

• o limitador de login é mantido na memória do processo; uma implantação distribuída exigiria armazenamento compartilhado;

• backup, retenção, TLS, secrets e monitoramento externo continuam sendo responsabilidades da implantação.

O objetivo desta versão é tornar verificável a camada que costuma faltar em demos de agentes: contratos claros, contexto mínimo, autorização, aprovação humana, consistência, auditoria, observabilidade e testes.

Resumo em inglês

Project Bridge is a governed integration layer between AI agents and a project-domain application. It is not a full project manager, an API management product, or a chatbot.

Through MCP, an authenticated agent can read scoped project context and submit typed proposals for task creation, task updates, or blocker resolution. Every proposed mutation is held for human review. Approval triggers server-side authorization, optimistic concurrency checks, an idempotent domain change, transactional outbox publication, audit records, and trace data; rejection leaves the project unchanged.

The repository demonstrates MCP resources, tools, prompts and notifications, Streamable HTTP and stdio transports, TypeScript and Zod contracts, Bearer scopes, project-level authorization, human-in-the-loop workflows, SQLite migrations, optimistic concurrency, durable outbox processing, OpenTelemetry instrumentation, security controls, container packaging, contract tests, and CI. See the complete English documentation.

Referências oficiais

• Model Context Protocol

• MCP TypeScript SDK

• OpenTelemetry

• Codex MCP

Licença

Distribuído sob a licença MIT.