mcp-server-webex-docs

Servidor MCP de Documentación de Webex (webex-api-docs-mcp)

Un servidor MCP (Model Context Protocol) que proporciona búsqueda local de texto completo rápida y esquemas completos de OpenAPI JSON para todas las APIs de desarrollador de Webex y RoomOS xAPI.

---

💡 ¿Qué problema resuelve esto? (¿Por qué usar este servidor MCP?)

🔴 El problema: Alucinaciones y coste masivo de tokens

Cuando los agentes de IA o los desarrolladores trabajan con las APIs de Webex, se enfrentan a tres grandes cuellos de botella:

• Alucinaciones de LLM: Los grandes modelos de lenguaje frecuentemente adivinan métodos HTTP incorrectos, rutas REST obsoletas o inventan ámbitos OAuth requeridos (spark-admin:...) que conducen a errores 401 Unauthorized o 404 Not Found.
• Agotamiento de la ventana de contexto: Las especificaciones oficiales de Webex OpenAPI y RoomOS xAPI abarcan más de 4.500 endpoints en Admin, Calling, Meetings, Messaging y RoomOS, lo que equivale a más de 15 MB de documentación en bruto. Cargar esto en una ventana de contexto de LLM es lento, costoso e impráctico.
• Web scraping lento: Depender de búsquedas web en vivo para obtener documentación de desarrollador durante un flujo de trabajo de codificación agéntico causa latencia y un análisis HTML frágil.

🟢 La solución: Búsqueda local de cero tokens y esquemas exactos

Este servidor MCP actúa como una referencia técnica local y autoritativa para tu asistente de IA. En lugar de adivinar o navegar por la web, la IA puede consultar la base de datos local SQLite FTS5 en menos de 5 milisegundos, descubrir el endpoint exacto y recuperar su esquema completo y verificado de OpenAPI JSON bajo demanda.

🎯 Ejemplos del mundo real y casos de uso

Aquí hay ejemplos de preguntas y tareas que tu agente de IA puede resolver instantáneamente usando este servidor MCP:

1. 🔒 Seguridad y registro de auditoría de administración
   • Solicitud del usuario: "Necesito escribir un script que registre quién eliminó una cuenta de usuario en Webex Control Hub. ¿Qué endpoint debería llamar y qué permisos necesito?"
   • Acción MCP: Usa search_webex_api_docs("audit events") -> Devuelve GET /adminAudit/events -> Usa get_webex_endpoint_schema para inspeccionar actorEmail, eventDescription y el ámbito requerido audit:events_read.
2. 📞 Automatización de telefonía y recepcionista de IA
   • Solicitud del usuario: "¿Cómo creo programáticamente una base de conocimiento de recepcionista de IA en Webex Calling?"
   • Acción MCP: Usa search_webex_api_docs("knowledge base") -> Localiza POST /telephony/config/knowledgeBases -> Recupera el esquema exacto del cuerpo de la solicitud JSON que muestra los campos obligatorios (name, description).
3. 📝 Resúmenes y transcripciones de reuniones
   • Solicitud del usuario: "¿Cuál es la ruta de la API REST para descargar transcripciones y resúmenes de IA posteriores a la reunión?"
   • Acción MCP: Busca en el dominio meetings por "transcripts" -> Encuentra GET /meetings/{meetingId}/transcripts y GET /meetings/{meetingId}/summaries junto con los parámetros de consulta.
4. 🤖 Bots de mensajería y webhooks
   • Solicitud del usuario: "Quiero que mi bot reciba notificaciones en tiempo real cuando se publique un mensaje en una sala de Webex."
   • Acción MCP: Localiza POST /webhooks en el dominio messaging y devuelve la estructura de payload requerida para eventos messages/created.
5. 📺 Automatización de dispositivos RoomOS xAPI y AirPlay
   • Solicitud del usuario: "¿Cómo controlo AirPlay o ajusto el volumen en un Cisco Room Bar usando xAPI?"
   • Acción MCP: Busca en el dominio roomos -> Encuentra xCommand AirPlay KeyEvent Back y xCommand Audio Volume Set -> Recupera la sintaxis para la API REST de Webex Cloud (POST /v1/xapi/command/...), Node.js jsxapi y CLI/Macros en el dispositivo.

---

🌟 ¿Por qué esta arquitectura? (Documentación de doble capa)

Este repositorio implementa un pipeline de documentación escalable, reproducible y versionado con Git diseñado específicamente para agentes de IA y desarrolladores:

1. Capa 1: Artefactos Markdown en Git (docs/<domain>.md)
   • Documentación Markdown limpia y estructurada para Webex Admin, Webex Cloud Calling, Webex Meetings, Webex Messaging y Webex RoomOS xAPI se genera automáticamente y se almacena en /docs/.
   • Cada vez que Webex actualiza una API, ejecutar el pipeline ETL produce un diff estándar de Git para que puedas rastrear los cambios de la API a lo largo del tiempo.
2. Capa 2: Índice SQLAlchemy + SQLite FTS5 (data/webex_docs.db)
   • Una base de datos relacional SQLite optimizada gestionada mediante SQLAlchemy 2.0 ORM combinada con SQLite FTS5 (búsqueda de texto completo).
   • Proporciona búsqueda de palabras clave y semántica en menos de un milisegundo en 4.539 endpoints sin cargar archivos de varios megabytes en memoria o contexto.

---

📦 ¿Qué incluye?

El servidor indexa 4.539 endpoints oficiales de Webex en 5 dominios de servicios principales:

Dominio	Categorías	Endpoints	Documento generado	Descripción
admin	34	146	docs/admin.md	APIs de administración de Webex (People, SCIM, Licenses, Roles, Audit Events, Real-time Events, Security).
calling	54	1,081	docs/calling.md	APIs de Webex Cloud Calling (AI Receptionist, Call Queues, Auto Attendant, Routing, DECT, Voicemail).
meetings	22	166	docs/meetings.md	APIs de Webex Meetings (Meetings, Participants, Transcripts, Closed Captions, Recordings, Q&A).
messaging	12	63	docs/messaging.md	APIs de Webex Messaging (Rooms, Messages, Memberships, Teams, Webhooks, Hybrid Data Security).
roomos	4	3,083	docs/roomos.md	Webex RoomOS xAPI (xCommand, xConfiguration, xStatus, xEvent) para Cisco Room Kit, Board, Desk Pro y Dispositivos de Colaboración.
TOTAL	126	4,539	—	—

---

🛠️ Instalación y configuración

1. Clona el repositorio e instala las dependencias:
   git clone https://github.com/santime27/mcp-server-webex-docs.git
   cd mcp-server-webex-docs
   pip install -r requirements.txt
2. Ejecuta el pipeline ETL automatizado (opcional - Reconstruir documentos e índice de base de datos):
   python3 -m src.pipeline.build_all
   Esto extrae los esquemas OpenAPI, genera los 4 archivos Markdown en docs/ y construye la base de datos SQLite FTS5 en data/webexdocs.db.
3. Inicia el servidor MCP:
   python3 -m src.server

---

🔌 Cómo conectar este servidor MCP (Configuración)

Gracias a la resolución automática de rutas en src/server.py, conectar este servidor a cualquier cliente MCP es ultrasimple: no se requieren banderas PYTHONPATH, cwd o -m.

1. Gemini CLI / Google Antigravity / Gemini Code Assist

Añade esto a tu archivo de configuración MCP de Gemini (por ejemplo, ~/.gemini/settings.json o la configuración MCP de tu proyecto):

{ "mcpServers": { "webex-api-docs": { "command": "python3", "args": [ "/path/to/mcp-server-webex-docs/src/server.py" ] } } }

2. Claude Desktop / Cursor / Cliente MCP genérico (claude_desktop_config.json)

Nota: Reemplaza /path/to/mcp-server-webex-docs con la ruta absoluta donde clonaste este repositorio en tu máquina.

---

🤖 Herramientas MCP expuestas para agentes de IA

Cuando está conectado a un cliente MCP (como Claude Desktop, Antigravity o agentes personalizados), este servidor expone las siguientes herramientas:

• search_webex_api_docs(query, domain=None, category=None, limit=15)
  • Búsqueda FTS5 en menos de un milisegundo en todos los 1.456 endpoints. Devuelve títulos de endpoints, método/ruta HTTP, resumen y números de línea exactos en el archivo de documentación.
• get_webex_endpoint_schema(domain, section_number)
  • Lee el rango de líneas exacto de docs/<domain>.md y devuelve el esquema OpenAPI JSON completo, la tabla de parámetros, los ámbitos requeridos y los códigos de respuesta HTTP para un endpoint específico.
• list_webex_domains()
  • Enumera los 4 dominios de Webex disponibles y sus recuentos de endpoints.
• list_webex_categories(domain)
  • Enumera todas las categorías disponibles dentro de un dominio específico.

---

📁 Estructura del repositorio

mcp-server-webex-docs/
├── agent-skills/              # AI Agent Skills (instructions & templates)
│   └── webex-api-assistant/   # Methodology for discovering, inspecting, and exploring APIs
│       ├── SKILL.md
│       ├── examples/
│       │   └── explorer_template.py
│       └── references/
│           └── webex_api_cheatsheet.md
├── docs/                      # Git-versioned Markdown documentation
│   ├── admin.md
│   ├── calling.md
│   ├── meetings.md
│   ├── messaging.md
│   └── roomos.md              # Webex RoomOS xAPI Commands, Configurations, Statuses & Events
├── data/
│   ├── roomos_schema.json     # Cached official RoomOS xAPI schema (3,083 objects)
│   └── webex_docs.db          # SQLite FTS5 database indexed via SQLAlchemy
├── src/
│   ├── models/                # SQLAlchemy ORM models (Domain, Category, Endpoint)
│   │   ├── __init__.py
│   │   └── db.py
│   ├── pipeline/              # ETL pipeline for automated updates
│   │   ├── __init__.py
│   │   ├── build_all.py       # Main orchestrator CLI
│   │   ├── db_indexer.py      # SQLite FTS5 indexer
│   │   ├── fetcher.py         # Developer portal state extractor
│   │   ├── markdown_builder.py# Markdown generator (Admin, Calling, Meetings, Messaging)
│   │   └── roomos_builder.py  # RoomOS xAPI schema & Markdown generator
│   ├── __init__.py
│   └── server.py              # MCP FastMCP server implementation
├── requirements.txt

---

🧠 Habilidad de agente de IA (agent-skills/webex-api-assistant)

Este repositorio incluye una habilidad de agente oficial en agent-skills/webex-api-assistant/SKILL.md diseñada para enseñar a cualquier asistente de IA (como Antigravity, Claude o Cursor) cómo actuar como un compañero senior de desarrollo de Webex.

La habilidad instruye al modelo sobre:

1. El flujo de trabajo MCP en 2 pasos: Siempre descubrir APIs mediante search_webex_api_docs primero, luego inspeccionar esquemas OpenAPI completos y ámbitos OAuth mediante get_webex_endpoint_schema.
2. Exploración interactiva en sandbox: Generar y ejecutar scripts de exploración limpios en Python en un entorno sandbox/temporal para probar APIs en vivo.
3. Mejores prácticas de seguridad: Leer WEBEX_ACCESS_TOKEN de las variables de entorno sin codificar tokens en el código.

---

👨‍💻 Autores y créditos

Construido con ❤️ por Santiago Meneses Garcia, Ingeniero de Software, en colaboración de programación en pareja con Antigravity (Asistente de IA agéntico de Google DeepMind).

---

📄 Licencia

Este proyecto está bajo la Licencia MIT permisiva: siéntete libre de usar, copiar, modificar, distribuir y construir sobre este software tanto para proyectos personales como comerciales sin restricciones.