mcp-server-webex-docs

Um servidor MCP (Model Context Protocol) que fornece busca rápida em texto completo local e schemas JSON completos de OpenAPI para todas as APIs de Desenvolvedor Webex e RoomOS xAPI.

GitHub
2

Documentação

Webex API Docs MCP Server (webex-api-docs-mcp)

MCP Protocol API Endpoints

Um servidor MCP (Model Context Protocol) que fornece busca local rápida de texto completo e esquemas JSON OpenAPI completos para todas as APIs de Desenvolvedor Webex e RoomOS xAPI.

💡 Que Problema Isso Resolve? (Por Que Usar Este Servidor MCP?)

🔴 O Problema: Alucinações e Custo Massivo de Tokens

Quando Agentes de IA ou desenvolvedores trabalham com APIs Webex, eles enfrentam três grandes gargalos:

  • Alucinações de LLM: Modelos de linguagem grandes frequentemente adivinham métodos HTTP incorretos, caminhos REST desatualizados ou inventam escopos OAuth necessários (spark-admin:...) que levam a erros 401 Unauthorized ou 404 Not Found.
  • Esgotamento da Janela de Contexto: As especificações oficiais do Webex OpenAPI e RoomOS xAPI abrangem mais de 4.500 endpoints em Admin, Calling, Meetings, Messaging e RoomOS—totalizando mais de 15 MB de documentação bruta. Carregar isso na janela de contexto de um LLM é lento, caro e impraticável.
  • Web Scraping Lento: Depender de buscas web ao vivo para obter documentação de desenvolvedor durante um fluxo de trabalho de codificação agêntico causa latência e parsing HTML frágil.

🟢 A Solução: Busca Local de Zero Token e Esquemas Exatos

Este servidor MCP atua como uma referência técnica local e autoritativa para seu Assistente de IA. Em vez de adivinhar ou navegar na web, a IA pode consultar o banco de dados SQLite FTS5 local em <5 milissegundos, descobrir o endpoint exato e recuperar seu esquema JSON OpenAPI completo e verificado sob demanda.

🎯 Exemplos do Mundo Real e Casos de Uso

Aqui estão exemplos de perguntas e tarefas que seu Agente de IA pode resolver instantaneamente usando este servidor MCP:

  1. 🔒 Segurança e Registro de Auditoria Admin
    • Prompt do Usuário: "Preciso escrever um script que registre quem excluiu uma conta de usuário no Webex Control Hub. Qual endpoint devo chamar e quais permissões preciso?"
    • Ação do MCP: Usa search_webex_api_docs("audit events") -> Retorna GET /adminAudit/events -> Usa get_webex_endpoint_schema para inspecionar actorEmail, eventDescription e o escopo audit:events_read necessário.
  2. 📞 Telefonia e Automação de Recepcionista de IA
    • Prompt do Usuário: "Como crio programaticamente uma Base de Conhecimento de Recepcionista de IA no Webex Calling?"
    • Ação do MCP: Usa search_webex_api_docs("knowledge base") -> Localiza POST /telephony/config/knowledgeBases -> Recupera o esquema exato do Corpo da Requisição JSON mostrando campos obrigatórios (name, description).
  3. 📝 Resumos de Reuniões e Transcrições
    • Prompt do Usuário: "Qual é o caminho da API REST para baixar transcrições pós-reunião e resumos de IA?"
    • Ação do MCP: Busca no domínio meetings por "transcripts" -> Encontra GET /meetings/{meetingId}/transcripts e GET /meetings/{meetingId}/summaries junto com parâmetros de consulta.
  4. 🤖 Bots de Mensagens e Webhooks
    • Prompt do Usuário: "Quero que meu bot receba notificações em tempo real quando uma mensagem for postada em uma sala Webex."
    • Ação do MCP: Localiza POST /webhooks no domínio messaging e retorna a estrutura de payload necessária para eventos messages/created.
  5. 📺 Automação de Dispositivos RoomOS xAPI e AirPlay
    • Prompt do Usuário: "Como controlo o AirPlay ou ajusto o volume em um Cisco Room Bar usando xAPI?"
    • Ação do MCP: Busca no domínio roomos -> Encontra xCommand AirPlay KeyEvent Back e xCommand Audio Volume Set -> Recupera a sintaxe para a API REST Webex Cloud (POST /v1/xapi/command/...), Node.js jsxapi e CLI/Macros no dispositivo.

🌟 Por Que Esta Arquitetura? (Documentação em Duas Camadas)

Este repositório implementa um pipeline de documentação escalável, reproduzível e versionado em Git projetado especificamente para Agentes de IA e desenvolvedores:

  1. Camada 1: Artefatos Markdown no Git (docs/<domain>.md)
    • Documentação Markdown limpa e estruturada para Webex Admin, Webex Cloud Calling, Webex Meetings, Webex Messaging e Webex RoomOS xAPI é gerada automaticamente e armazenada em /docs/.
    • Toda vez que a Webex atualiza uma API, executar o pipeline ETL produz um diff Git padrão para que você possa acompanhar as mudanças da API ao longo do tempo.
  2. Camada 2: Índice SQLAlchemy + SQLite FTS5 (data/webex_docs.db)
    • Um banco de dados relacional SQLite otimizado gerenciado via ORM SQLAlchemy 2.0 combinado com SQLite FTS5 (Full-Text Search).
    • Fornece busca por palavra-chave e semântica em sub-milissegundos em 4.539 endpoints sem carregar arquivos de vários megabytes na memória ou no contexto.

📦 O Que Está Incluído?

O servidor indexa 4.539 endpoints oficiais da Webex em 5 grandes domínios de serviço:

DomínioCategoriasEndpointsDocumento GeradoDescrição
admin34146docs/admin.mdAPIs de Admin Webex (People, SCIM, Licenses, Roles, Audit Events, Real-time Events, Security).
calling541.081docs/calling.mdAPIs de Webex Cloud Calling (AI Receptionist, Call Queues, Auto Attendant, Routing, DECT, Voicemail).
meetings22166docs/meetings.mdAPIs de Webex Meetings (Meetings, Participants, Transcripts, Closed Captions, Recordings, Q&A).
messaging1263docs/messaging.mdAPIs de Webex Messaging (Rooms, Messages, Memberships, Teams, Webhooks, Hybrid Data Security).
roomos43.083docs/roomos.mdWebex RoomOS xAPI (xCommand, xConfiguration, xStatus, xEvent) para Cisco Room Kit, Board, Desk Pro e Collaboration Devices.
TOTAL1264.539——

🛠️ Instalação e Configuração

  1. Clone o repositório e instale as dependências:
    git clone https://github.com/santime27/mcp-server-webex-docs.git
    cd mcp-server-webex-docs
    pip install -r requirements.txt
  2. Execute o pipeline ETL automatizado (Opcional - Reconstruir docs e índice do banco de dados):
    python3 -m src.pipeline.build_all
    Isso extrai os esquemas OpenAPI, gera os 4 arquivos Markdown em docs/ e constrói o banco de dados SQLite FTS5 em data/webexdocs.db.
  3. Inicie o Servidor MCP:
    python3 -m src.server

🔌 Como Conectar Este Servidor MCP (Configuração)

Graças à resolução automática de caminhos em src/server.py, conectar este servidor a qualquer cliente MCP é ultrassimples—nenhuma flag PYTHONPATH, cwd ou -m é necessária!

1. Gemini CLI / Google Antigravity / Gemini Code Assist

Adicione isso ao seu arquivo de configurações MCP do Gemini (por exemplo, ~/.gemini/settings.json ou a configuração MCP do seu projeto):

{ "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: Substitua /path/to/mcp-server-webex-docs pelo caminho absoluto onde você clonou este repositório em sua máquina.

🤖 Ferramentas MCP Expostas para Agentes de IA

Quando conectado a um cliente MCP (como Claude Desktop, Antigravity ou agentes personalizados), este servidor expõe as seguintes ferramentas:

  • search_webex_api_docs(query, domain=None, category=None, limit=15)
    • Busca FTS5 em sub-milissegundos em todos os 1.456 endpoints. Retorna títulos de endpoints, método/caminho HTTP, resumo e números de linha exatos no arquivo de documentação.
  • get_webex_endpoint_schema(domain, section_number)
    • Lê o intervalo de linhas exato de docs/<domain>.md e retorna o esquema JSON OpenAPI completo, tabela de parâmetros, escopos necessários e códigos de resposta HTTP para um endpoint específico.
  • list_webex_domains()
    • Lista os 4 domínios Webex disponíveis e suas contagens de endpoints.
  • list_webex_categories(domain)
    • Lista todas as categorias disponíveis dentro de um domínio específico.

📁 Estrutura do Repositório

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

🧠 Habilidade de Agente de IA (agent-skills/webex-api-assistant)

Este repositório inclui uma Agent Skill oficial em agent-skills/webex-api-assistant/SKILL.md projetada para ensinar qualquer Assistente de IA (como Antigravity, Claude ou Cursor) a atuar como um Companheiro Sênior de Desenvolvimento Webex.

A skill instrui o modelo sobre:

  1. O Fluxo de Trabalho MCP em 2 Etapas: Sempre descobrir APIs via search_webex_api_docs primeiro, depois inspecionar esquemas OpenAPI completos e escopos OAuth via get_webex_endpoint_schema.
  2. Exploração Interativa em Sandbox: Gerar e executar scripts Python de exploração limpos em um ambiente sandbox/temporário para testar APIs ao vivo.
  3. Melhores Práticas de Segurança: Ler WEBEX_ACCESS_TOKEN de variáveis de ambiente sem nunca codificar tokens diretamente.

👨‍💻 Autores e Créditos

Construído com ❤️ por Santiago Meneses Garcia, Engenheiro de Software, em colaboração de pair-programming com Antigravity (Assistente de IA Agêntica do Google DeepMind).

📄 Licença

Este projeto está licenciado sob a permissiva Licença MIT — sinta-se à vontade para usar, copiar, modificar, distribuir e construir sobre este software para projetos pessoais e comerciais sem restrições.