TCC

Automatically generates MCP servers from OpenAPI specifications, enabling conversational AI agents to interact with existing web systems.

GitHub

TCC - Transformando APIs em Interfaces Conversacionais

Ask DeepWiki <-- Converse com o projeto

Validação da Abordagem OpenAPI-MCP para Agentes Baseados em IA
Trabalho de Conclusão de Curso - Engenharia de Software
Autor: Lucas de Castro Zanoni | Orientador: Thyerri Fernandes Mezzari
Instituição: Centro Universitário UniSATC

🤖 Como Funciona o Sistema?

  • O usuário escreve algo como “quero buscar o equipamento 123”.
  • O modelo de linguagem entende a intenção.
  • A intenção é convertida pelo modelo de linguagem em chamadas de função.
  • A chamada de função é convertida em chamada de ferramentas MCP.
  • O cliente via protocolo MCP chama as ferramentas correspondentes a intenção do usuároo.
  • Nos servidores MCP a chamada é transformada em uma requisição HTTP real com base na especificação SWAGGER da aplicação destino.
  • A resposta da API é formatada e enviada de volta ao modelo de linguagem que interpreta e responde, como se fosse um bate-papo.

🎥 Demonstração

Seu navegador não suporta o vídeo. Clique aqui para baixar o vídeo.

📖 Navegação Rápida

🎯 Seu Objetivo📋 Comece Aqui⏱️ Tempo
Entender a pesquisa📚 Guia Rápido - Acadêmico5-15 min
Usar a ferramenta💻 Guia Rápido - Desenvolvedor5-10 min
Reproduzir experimentos🔬 Guia Rápido - Pesquisador20 min
Avaliar comercialmente🏢 Guia Rápido - Empresa15 min
Navegar documentação📚 Índice CompletoReferência

📖 Sobre a Pesquisa

Este TCC investiga como especificações OpenAPI podem ser automaticamente convertidas em servidores MCP (Model Context Protocol), permitindo que modelos de linguagem de grande escala (LLMs) interajam com sistemas existentes através de interfaces conversacionais naturais.

🎯 Problema de Pesquisa

"Como a combinação da especificação OpenAPI com o protocolo MCP pode facilitar a integração eficiente e segura de agentes conversacionais baseados em IA com sistemas web existentes, contribuindo para a democratização do acesso a tecnologias complexas?"

🎯 Principais Objetivos

  • Desenvolver um gerador automático de servidores MCP a partir de especificações OpenAPI
  • Implementar um cliente de chat capaz de gerenciar múltiplos servidores MCP simultaneamente
  • Validar a abordagem através de testes experimentais rigorosos
  • Avaliar desempenho, segurança e experiência do usuário

🏆 Principais Contribuições Científicas

✅ Resultados Experimentais Validados

MétricaResultadoObservações
Conversão OpenAPI→MCP100% sucesso (10/10 endpoints)Automação completa
Taxa de Sucesso Operacional100% (8/8 consultas)Robustez funcional
Experiência do Usuário4.0/5.0Satisfação geral
Proteção de Segurança100% (16/16 ataques bloqueados)Resistência a ataques básicos
Tempo de Resposta Médio3.757msVariação: 1.335-5.823ms

🔬 Inovações Técnicas

  1. Geração Automática de Ferramentas MCP: Conversão sistemática OpenAPI→MCP
  2. Orquestração Multi-Servidor: Coordenação inteligente de múltiplos servidores MCP
  3. Integração Padronizada: Ponte entre LLMs e APIs existentes
  4. Metodologia Reproduzível: Framework experimental com métricas objetivas

🏗️ Arquitetura da Solução

graph TB
    UI[Interface do Usuário]
    CI[Chat Interface]
    AC[Agente Conversacional]
    LLM[LLM]
    AI[Analisador de Intenção]
    VR[Validador de Requisição]
    FR[Formatador de Resposta]
    
    CamInt[Camada de Integração]
    MCP[Servidor MCP]
    
    Backend[Sistemas de Backend]
    APIs[APIs Externas]
    
    UI --> CI
    CI --> AC
    AC -.-> |Consulta do Usuário| LLM
    LLM -.-> |Resposta em Linguagem Natural| AC
    LLM --> |Intenção Estruturada| AI
    AI --> VR
    VR -.-> |Requisição Validada| CamInt
    LLM --> |Resposta Formatada| FR
    FR --> AC
    
    CamInt --> MCP
    MCP --> |Requisição HTTP| Backend
    Backend --> APIs
    APIs -.-> |Resultado da Operação| Backend
    Backend -.-> MCP
    MCP -.-> CamInt

🧩 Componentes Principais

1. Gerador Automático de Servidores MCP (mcp-openapi-server/)

  • Análise Sintática: Parser e validação de especificações OpenAPI 3.0+
  • Mapeamento Semântico: Conversão inteligente OpenAPI → ferramentas MCP
  • Geração de Ferramentas: Criação automática de servidores MCP funcionais
  • Transporte Dual: Suporte para stdio e HTTP

2. Cliente de Chat Multi-Servidor (chat-client/)

  • Interface Minimalista: Design padronizado para testes objetivos
  • Coordenação Distribuída: Gerenciamento de múltiplos servidores MCP
  • Descoberta Automática: Identificação dinâmica de ferramentas disponíveis
  • Testes E2E: Suite completa com Playwright

3. Aplicações de Teste (equipments-dummy-app/ & professionals-dummy-app/)

  • APIs RESTful: Implementações com Hono.js, TypeScript e PostgreSQL
  • Documentação OpenAPI: Especificações completas para validação
  • Cenários Reais: Simulação de sistemas empresariais

4. Framework de Validação

  • Testes Automatizados: Métricas de performance, segurança e UX
  • Red Teaming: Testes adversários para validação de segurança
  • Instrumentação: Coleta objetiva de dados experimentais

📚 Documentação Acadêmica

📄 Artigo Completo

📋 Documentação de Pesquisa

🔬 Metodologia Científica

  • Abordagem Experimental: Validação empírica com controle de variáveis
  • Métricas Objetivas: Performance, segurança e experiência do usuário
  • Testes Reproduzíveis: Framework automatizado para validação
  • Análise Estatística: Dados quantitativos com intervalos de confiança

🔄 Workflow de Desenvolvimento Acadêmico

📝 Por que este Workflow?

Este TCC foi desenvolvido seguindo um workflow orientado a código e versionamento, com várias vantagens:

  1. 📚 Versionamento Completo: Todo conteúdo (código + texto acadêmico) versionado com Git
  2. ✍️ Markdown + LaTeX: Facilidade de escrita + poder de formatação acadêmica
  3. 🔗 Gestão de Referências: BibTeX para consistência bibliográfica
  4. ⚙️ Automação: Scripts para conversão Markdown → LaTeX → PDF
  5. 🔧 Integração: Código e documentação no mesmo repositório
  6. 🔁 Reprodutibilidade: Qualquer pessoa pode reproduzir o ambiente
  7. 👥 Colaboração: Formato texto facilita revisões e sugestões

📁 Estrutura do Projeto

TCC/
├── 📄 README.md                     # Este arquivo
├── 📄 pre-projeto.md                # Proposta inicial da pesquisa
├── 📄 CITATION.md                   # Formatos de citação
├── 📄 DOCUMENTATION_INDEX.md        # Índice completo da documentação
├── 📄 QUICK_START.md                # Guias de início rápido
├── 📄 RESEARCH_SUMMARY.md           # Resumo executivo da pesquisa
├── 🛠️ Makefile                     # Comandos de automação
│
├── 📚 article/                      # Documentação acadêmica
│   ├── 📖 article.md               # Artigo principal (fonte)
│   ├── 📄 article.pdf              # Artigo final compilado
│   ├── 📚 references.bib           # Referências bibliográficas
│   ├── 🖼️ images/                  # Figuras e diagramas
│   └── ⚙️ Makefile                 # Compilação LaTeX
│
├── 🤖 mcp-openapi-server/          # Gerador automático MCP
│   ├── 📦 package.json             # Dependências e scripts
│   ├── 🔧 src/                     # Código fonte
│   ├── 🧪 test/                    # Testes unitários
│   └── 📖 README.md                # Documentação técnica
│
├── 💬 chat-client/                  # Cliente multi-servidor
│   ├── 🌐 chat.html                # Interface web
│   ├── ⚙️ backend-server.js        # Servidor backend
│   ├── 📦 package.json             # Scripts específicos do sistema
│   ├── 🧪 tests/                   # Testes E2E (Playwright)
│   └── 📊 test-results/            # Resultados experimentais
│
├── 🏭 equipments-dummy-app/         # App teste - Equipamentos
│   ├── 📦 package.json             # Scripts e dependências
│   └── 🔧 src/                     # API REST Hono.js + TypeScript
│
├── 👥 professionals-dummy-app/      # App teste - Profissionais  
│   ├── 📦 package.json             # Scripts e dependências
│   └── 🔧 src/                     # API REST Hono.js + TypeScript
│
└── 🔖 bookmarks/                    # Pesquisa organizada
    ├── 📚 bookmarks.json           # Links de referência
    └── 💾 save-bookmarks.sh        # Script de backup

📚 Citação Acadêmica

📄 BibTeX Format

@mastersthesis{zanoni2025openapi,
  title = {Transformando APIs em Interfaces Conversacionais: Validação da Abordagem OpenAPI-MCP para Agentes Baseados em IA},
  author = {Zanoni, Lucas de Castro},
  school = {Centro Universitário UniSATC},
  year = {2025},
  type = {Trabalho de Conclusão de Curso},
  program = {Engenharia de Software},
  address = {Criciúma, SC, Brasil},
  url = {https://github.com/Castrozan/TCC}
}

📋 Outros formatos (ABNT, APA, IEEE): CITATION.md

👤 Autor & Contato

Lucas de Castro Zanoni
📧 castro [dot] lucas290 [at] gmail [dot] com
🐙 @Castrozan
🎓 Graduando em Engenharia de Software - UniSATC

Orientador: Prof. Thyerri Fernandes Mezzari
📧 thyerri [dot] mezzari [at] satc [dot] edu [dot] br

📄 Licença

Este projeto está sob a licença MIT. Veja o arquivo LICENSE para detalhes.

Servidores relacionados