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
- 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.
demonstracao.mp4
| 🎯 Seu Objetivo | 📋 Comece Aqui | ⏱️ Tempo |
|---|---|---|
| Entender a pesquisa | 📚 Guia Rápido - Acadêmico | 5-15 min |
| Usar a ferramenta | 💻 Guia Rápido - Desenvolvedor | 5-10 min |
| Reproduzir experimentos | 🔬 Guia Rápido - Pesquisador | 20 min |
| Avaliar comercialmente | 🏢 Guia Rápido - Empresa | 15 min |
| Navegar documentação | 📚 Índice Completo | Referência |
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.
"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?"
- 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
| Métrica | Resultado | Observações |
|---|---|---|
| Conversão OpenAPI→MCP | 100% sucesso (10/10 endpoints) | Automação completa |
| Taxa de Sucesso Operacional | 100% (8/8 consultas) | Robustez funcional |
| Experiência do Usuário | 4.0/5.0 | Satisfação geral |
| Proteção de Segurança | 100% (16/16 ataques bloqueados) | Resistência a ataques básicos |
| Tempo de Resposta Médio | 3.757ms | Variação: 1.335-5.823ms |
- Geração Automática de Ferramentas MCP: Conversão sistemática OpenAPI→MCP
- Orquestração Multi-Servidor: Coordenação inteligente de múltiplos servidores MCP
- Integração Padronizada: Ponte entre LLMs e APIs existentes
- Metodologia Reproduzível: Framework experimental com métricas objetivas
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
- 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
- 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
- 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
- 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
- 📖 Artigo Principal - Documento completo em PDF
- 📝 Fonte Markdown - Texto fonte em Markdown
- 📚 Referências - Bibliografia em BibTeX
- 🎯 Pré-Projeto - Objetivos, problema e justificativa
- 📖 Notas de Desenvolvimento - Anotações e ideias durante o desenvolvimento
- 💡 Ideias de Tema - Processo de escolha e refinamento do tema
- 🔖 Bookmarks - Links de pesquisa organizados
- 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
Este TCC foi desenvolvido seguindo um workflow orientado a código e versionamento, com várias vantagens:
- 📚 Versionamento Completo: Todo conteúdo (código + texto acadêmico) versionado com Git
- ✍️ Markdown + LaTeX: Facilidade de escrita + poder de formatação acadêmica
- 🔗 Gestão de Referências: BibTeX para consistência bibliográfica
- ⚙️ Automação: Scripts para conversão Markdown → LaTeX → PDF
- 🔧 Integração: Código e documentação no mesmo repositório
- 🔁 Reprodutibilidade: Qualquer pessoa pode reproduzir o ambiente
- 👥 Colaboração: Formato texto facilita revisões e sugestões
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
@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
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
Este projeto está sob a licença MIT. Veja o arquivo LICENSE para detalhes.