TCC

Genera automáticamente servidores MCP a partir de especificaciones OpenAPI, permitiendo que agentes de IA conversacional interactúen con sistemas web existentes.

GitHub

Prueba este MCPPatrocinado

Documentación

TCC - Transformando APIs en Interfaces Conversacionales

<-- Conversa con el proyecto

Validación del Enfoque OpenAPI-MCP para Agentes Basados en IA
Trabajo de Conclusión de Curso - Ingeniería de Software
Autor: Lucas de Castro Zanoni | Orientador: Thyerri Fernandes Mezzari
Institución: Centro Universitário UniSATC

🤖 ¿Cómo Funciona el Sistema?

El usuario escribe algo como "quiero buscar el equipo 123".
El modelo de lenguaje entiende la intención.
La intención es convertida por el modelo de lenguaje en llamadas de función.
La llamada de función se convierte en llamada de herramientas MCP.
El cliente mediante protocolo MCP llama a las herramientas correspondientes a la intención del usuario.
En los servidores MCP la llamada se transforma en una solicitud HTTP real basada en la especificación SWAGGER de la aplicación destino.
La respuesta de la API se formatea y se envía de vuelta al modelo de lenguaje que interpreta y responde, como si fuera un chat.

🎥 Demostración

Tu navegador no soporta el video. Haz clic aquí para descargar el video.

📖 Navegación Rápida

🎯 Tu Objetivo	📋 Empieza Aquí	⏱️ Tiempo
Entender la investigación	📚 Guía Rápida - Académico	5-15 min
Usar la herramienta	💻 Guía Rápida - Desarrollador	5-10 min
Reproducir experimentos	🔬 Guía Rápida - Investigador	20 min
Evaluar comercialmente	🏢 Guía Rápida - Empresa	15 min
Navegar documentación	📚 Índice Completo	Referencia

📖 Sobre la Investigación

Este TCC investiga cómo las especificaciones OpenAPI pueden convertirse automáticamente en servidores MCP (Model Context Protocol), permitiendo que modelos de lenguaje de gran escala (LLMs) interactúen con sistemas existentes a través de interfaces conversacionales naturales.

🎯 Problema de Investigación

"¿Cómo la combinación de la especificación OpenAPI con el protocolo MCP puede facilitar la integración eficiente y segura de agentes conversacionales basados en IA con sistemas web existentes, contribuyendo a la democratización del acceso a tecnologías complejas?"

🎯 Principales Objetivos

Desarrollar un generador automático de servidores MCP a partir de especificaciones OpenAPI
Implementar un cliente de chat capaz de gestionar múltiples servidores MCP simultáneamente
Validar el enfoque mediante pruebas experimentales rigurosas
Evaluar rendimiento, seguridad y experiencia del usuario

🏆 Principales Contribuciones Científicas

✅ Resultados Experimentales Validados

Métrica	Resultado	Observaciones
Conversión OpenAPI→MCP	100% éxito (10/10 endpoints)	Automatización completa
Tasa de Éxito Operacional	100% (8/8 consultas)	Robustez funcional
Experiencia del Usuario	4.0/5.0	Satisfacción general
Protección de Seguridad	100% (16/16 ataques bloqueados)	Resistencia a ataques básicos
Tiempo de Respuesta Medio	3.757ms	Variación: 1.335-5.823ms

🔬 Innovaciones Técnicas

Generación Automática de Herramientas MCP: Conversión sistemática OpenAPI→MCP
Orquestación Multi-Servidor: Coordinación inteligente de múltiples servidores MCP
Integración Estandarizada: Puente entre LLMs y APIs existentes
Metodología Reproducible: Framework experimental con métricas objetivas

🏗️ Arquitectura de la Solución

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 Principales

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

Análisis Sintáctico: Parser y validación de especificaciones OpenAPI 3.0+
Mapeo Semántico: Conversión inteligente OpenAPI → herramientas MCP
Generación de Herramientas: Creación automática de servidores MCP funcionales
Transporte Dual: Soporte para stdio y HTTP

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

Interfaz Minimalista: Diseño estandarizado para pruebas objetivas
Coordinación Distribuida: Gestión de múltiples servidores MCP
Descubrimiento Automático: Identificación dinámica de herramientas disponibles
Pruebas E2E: Suite completa con Playwright

3. Aplicaciones de Prueba (`equipments-dummy-app/` & `professionals-dummy-app/`)

APIs RESTful: Implementaciones con Hono.js, TypeScript y PostgreSQL
Documentación OpenAPI: Especificaciones completas para validación
Escenarios Reales: Simulación de sistemas empresariales

4. Framework de Validación

Pruebas Automatizadas: Métricas de rendimiento, seguridad y UX
Red Teaming: Pruebas adversarias para validación de seguridad
Instrumentación: Recolección objetiva de datos experimentales

📚 Documentación Académica

📄 Artículo Completo

📖 Artículo Principal - Documento completo en PDF
📝 Fuente Markdown - Texto fuente en Markdown
📚 Referencias - Bibliografía en BibTeX

📋 Documentación de Investigación

🎯 Pre-Proyecto - Objetivos, problema y justificación
📖 Notas de Desarrollo - Anotaciones e ideas durante el desarrollo
💡 Ideas de Tema - Proceso de elección y refinamiento del tema
🔖 Bookmarks - Enlaces de investigación organizados

🔬 Metodología Científica

Enfoque Experimental: Validación empírica con control de variables
Métricas Objetivas: Rendimiento, seguridad y experiencia del usuario
Pruebas Reproducibles: Framework automatizado para validación
Análisis Estadístico: Datos cuantitativos con intervalos de confianza

🔄 Workflow de Desarrollo Académico

📝 ¿Por qué este Workflow?

Este TCC fue desarrollado siguiendo un workflow orientado a código y versionamiento, con varias ventajas:

📚 Versionamiento Completo: Todo el contenido (código + texto académico) versionado con Git
✍️ Markdown + LaTeX: Facilidad de escritura + poder de formato académico
🔗 Gestión de Referencias: BibTeX para consistencia bibliográfica
⚙️ Automatización: Scripts para conversión Markdown → LaTeX → PDF
🔧 Integración: Código y documentación en el mismo repositorio
🔁 Reproducibilidad: Cualquier persona puede reproducir el entorno
👥 Colaboración: El formato texto facilita revisiones y sugerencias

📁 Estructura del Proyecto

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

📚 Citación Académica

📄 Formato BibTeX

@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}
}

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

👤 Autor y Contacto

Lucas de Castro Zanoni
📧 castro [dot] lucas290 [at] gmail [dot] com
🐙 @Castrozan
🎓 Graduando en Ingeniería de Software - UniSATC

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

📄 Licencia

Este proyecto está bajo la licencia MIT. Consulta el archivo LICENSE para más detalles.

TCC