MCP Gateway – API & Portal de Autoatendimento

Este repositório contém o MCP Gateway, uma solução corporativa para expor, gerenciar e consumir ferramentas (APIs internas) de forma segura, escalável e auditável, com autenticação RBAC e portal de autoatendimento. (Atualizado em 2025-05-10 para refletir o estado atual do projeto)

Sumário

• Visão Geral

• Estrutura de Pastas

• Como Rodar (Desenvolvimento)

• Funcionalidades Principais

• Exemplo de Estrutura RBAC

• Segurança

• Documentação da API

• Requisitos do Sistema

• Documentação Completa

• Boas Práticas e Observações

Related MCP server: Model Context Provider (MCP) Server

Visão Geral

O MCP Gateway é composto por:

• Backend: FastAPI (Python) responsável pela lógica de negócio, autenticação (JWT), autorização (RBAC), e exposição de APIs RESTful. Atualmente, persiste dados em arquivos JSON, com planos de migração para um banco de dados mais robusto.

• Frontend: React (Vite + TypeScript) como portal de autoatendimento, consumindo as APIs do backend. O build de produção do frontend é servido estaticamente pelo backend FastAPI.

Estrutura de Pastas

Como Rodar (Desenvolvimento)

1. Backend (FastAPI)

No diretório raiz mcp-server/:

O backend estará disponível em http://localhost:8000.

2. Frontend (React)

Em um novo terminal, navegue até o diretório frontend/:

O frontend estará disponível em http://localhost:5173 (ou outra porta, se a 5173 estiver ocupada) e fará requisições para o backend em http://localhost:8000.

3. Build do Frontend para Produção

Para gerar a versão de produção do frontend que será servida pelo FastAPI:

Os arquivos estáticos serão gerados em frontend/dist/. O backend FastAPI já está configurado para servir esses arquivos quando não estiver em modo de desenvolvimento Vite.

Funcionalidades Principais

• Autenticação e Autorização:

  • Login de usuários com JWT (suportando papéis: user, admin, global_admin).

  • Refresh token para manutenção da sessão.

  • Controle de Acesso Baseado em Papéis (RBAC) para proteger endpoints e funcionalidades.

• Gerenciamento de Usuários (por Admin Global):

  • CRUD completo de usuários (criar, listar, detalhar, atualizar, deletar).

  • Migração de senhas legadas para formato hasheado.

  • Definição de requisitos de senha e funcionalidade para alteração de senha pelo próprio usuário.

• Gerenciamento de Grupos:

  • Admin Global: CRUD de grupos, designação de administradores de grupo.

  • Admin de Grupo (ou Global): Adicionar/remover usuários de seus grupos, promover membros a admin do grupo.

• Gerenciamento de Ferramentas:

  • Admin de Grupo (ou Global): Associar/desassociar ferramentas a grupos.

  • Usuários podem visualizar e acessar as ferramentas para as quais seus grupos concedem permissão.

• Workflow de Solicitação de Acesso a Grupos (RF06):

  • Usuários podem solicitar acesso a grupos.

  • Administradores (de grupo ou globais) podem revisar (aprovar/rejeitar) essas solicitações.

• Portal Frontend:

  • Interface para login, dashboard, visualização de ferramentas, solicitação de acesso a grupos e administração de solicitações.

  • Navegação e componentes dinâmicos baseados no papel do usuário.

• API Backend:

  • Endpoints RESTful para todas as funcionalidades mencionadas.

  • Documentação automática da API via Swagger UI (/docs) e ReDoc (/redoc).

  • Healthcheck (/tools/health).

Exemplo de Estrutura RBAC

Consulte o arquivo data/rbac.json para um exemplo da estrutura de dados que define usuários, senhas (hasheadas ou legadas para migração), papéis, grupos, membros de grupos, administradores de grupos e ferramentas associadas a grupos.

Segurança

• Autenticação baseada em JWT.

• Controle de Acesso Baseado em Papéis (RBAC) em todos os endpoints sensíveis.

• Hashing de senhas com bcrypt.

• Validação de força de senha.

• CORS configurado para desenvolvimento.

• Planejamento para headers de segurança adicionais (HSTS, CSP), rate limiting, e trilha de auditoria detalhada (ver docs/SEGURANCA.md e docs/TODO.md).

Documentação da API

A documentação interativa e detalhada da API está disponível automaticamente através do FastAPI:

• Swagger UI: http://localhost:8000/docs

• ReDoc: http://localhost:8000/redoc

Nota: Um resumo dos endpoints também está disponível em docs/API.md, mas a documentação gerada automaticamente é a fonte mais precisa e completa. A documentação técnica detalhada do backend, incluindo modelos e fluxos, pode ser encontrada em docs/BACKEND_DOCUMENTATION.md.

Requisitos do Sistema

Consulte o arquivo docs/REQUISITOS.md para uma lista detalhada de requisitos funcionais, não-funcionais, de negócio e operacionais, incluindo o status de implementação de muitos deles.

Documentação Completa

A documentação detalhada do projeto está centralizada na pasta docs/:

• docs/REQUISITOS.md: Requisitos do sistema

• docs/API.md: Resumo dos endpoints da API

• docs/BACKEND_DOCUMENTATION.md: Documentação técnica detalhada do Backend

• docs/ARQUITETURA.md: Arquitetura técnica do sistema

• docs/SEGURANCA.md: Práticas e considerações de segurança

• docs/GOVERNANCA.md: Governança, papéis e responsabilidades

• docs/OPERACIONAL.md: Operação, monitoramento e troubleshooting

• docs/CHANGELOG.md: Histórico de versões e mudanças

• docs/TODO.md: Lista de melhorias e pendências

• frontend/README.md: Documentação específica do Frontend

Boas Práticas e Observações

• Mantenha as dependências atualizadas (requirements.txt para o backend, package.json para o frontend).

• Utilize ambientes virtuais Python para isolar as dependências do backend.

• Sempre gere o build de produção do frontend (npm run build) antes de realizar o deploy da aplicação integrada.

• Consulte a documentação específica de cada módulo/pasta para informações mais detalhadas.

• Utilize o sistema de issues do repositório para rastrear bugs, solicitar features e discutir melhorias.

• Contribuições são bem-vindas! Siga as diretrizes de contribuição (se houver) e utilize Pull Requests para propor mudanças.

Este documento deve ser revisado e atualizado periodicamente para refletir o estado atual e a evolução do projeto.