FichaPao MCP Server

Servidor MCP HTTP para o agente FichaPao AI controlar fichas tecnicas de panificadora com Postgres.

O objetivo deste app e oferecer ferramentas seguras para o agente, sem expor SQL livre.

Arquitetura

OpenWebUI
  -> Agente FichaPao AI
  -> MCP HTTP /mcp
  -> fichapao-mcp-server
  -> Postgres

Ferramentas MCP

• search_recipe: busca ficha por nome.
• get_recipe: consulta ficha por recipe_id, version_id ou nome.
• create_recipe_draft: cria ficha em rascunho 0.1.
• update_draft: atualiza versao em rascunho ou revisao.
• create_new_version: cria nova versao em rascunho.
• approve_version: aprova versao se nao houver pendencias bloqueantes.
• list_pending_items: lista pendencias.
• register_production_test: registra teste de producao.
• compare_versions: compara duas versoes.
• archive_recipe: arquiva ficha.
• get_database_stats: resumo da base.

Regras Implementadas

• Ficha nova sempre entra como rascunho.
• Versao inicial e 0.1.
• Ficha aprovada nao pode ser editada diretamente.
• Alteracao em ficha aprovada deve virar nova versao em rascunho.
• Aprovacao bloqueia quando existem pendencias criticas.
• Primeira aprovacao de versao 0.x vira 1.0.
• O banco separa:
  • current_version_id: versao mais recente/em trabalho.
  • active_version_id: versao aprovada em producao.

Rodar Local

cp .env.example .env
docker compose up --build

Health check:

curl http://localhost:3001/health

A rota raiz tambem responde com o mesmo health check:

curl http://localhost:3001/

Endpoint MCP:

http://localhost:3001/mcp

No docker-compose.yml, a porta local esta mapeada como 3001:3000 para evitar conflito com apps comuns que ja usam 3000.

Se MCP_API_KEY estiver preenchida, envie:

Authorization: Bearer sua-chave

Deploy No EasyPanel

Crie dois serviços:

1. Postgres
2. App Docker apontando para este repositório

Variáveis do App:

NODE_ENV=production
PORT=3000
DATABASE_URL=postgresql://usuario:senha@host:5432/fichapao
AUTO_MIGRATE=true
MCP_API_KEY=troque-por-uma-chave-forte
CORS_ORIGIN=*

Depois de publicar, valide:

https://seu-dominio/health

No OpenWebUI:

Admin Settings -> External Tools -> Add MCP Server
URL: https://seu-dominio/mcp
Auth: Bearer token com o valor de MCP_API_KEY

Banco De Dados

Migration principal:

migrations/001_init.sql

Tabelas:

• recipes
• recipe_versions
• pending_items
• production_tests
• change_history

Desenvolvimento

npm install
npm run typecheck
npm run build
npm run dev