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

[![MCP Protocol](https://img.shields.io/badge/Model%20Context%20Protocol-Enabled-blue.svg)](https://modelcontextprotocol.io)
[![API Endpoints](https://img.shields.io/badge/Webex%20APIs-4%2C500%2B%20Endpoints-00bceb.svg)](https://developer.webex.com)

**An MCP (Model Context Protocol) server providing fast, local full-text search and complete OpenAPI JSON schemas for all Webex Developer APIs & RoomOS xAPI.**

---

## 💡 What Problem Does This Solve? (Why Use This MCP Server?)

### 🔴 The Problem: Hallucinations & Massive Token Cost
When AI Agents or developers work with Webex APIs, they face three major bottlenecks:
- **LLM Hallucinations:** Large language models frequently guess incorrect HTTP methods, outdated REST paths, or invent required OAuth scopes (`spark-admin:...`) that lead to `401 Unauthorized` or `404 Not Found` errors.
- **Context Window Exhaustion:** The official Webex OpenAPI and RoomOS xAPI specifications span over **4,500 endpoints** across Admin, Calling, Meetings, Messaging, and RoomOS—equaling more than **15 MB of raw documentation**. Loading this into an LLM context window is slow, expensive, and impractical.
- **Slow Web Scraping:** Relying on live web searches to fetch developer documentation during an agentic coding workflow causes latency and fragile HTML parsing.

### 🟢 The Solution: Zero-Token Local Search & Exact Schemas
This MCP server acts as an **authoritative, local technical reference** for your AI Assistant. Instead of guessing or browsing the web, the AI can query the local **SQLite FTS5 database in <5 milliseconds**, discover the exact endpoint, and retrieve its complete, verified OpenAPI JSON schema on demand.

### 🎯 Real-World Examples & Use Cases

Here are examples of questions and tasks your AI Agent can solve instantly using this MCP server:

1. **🔒 Security & Admin Audit Logging**
   - **User Prompt:** *"I need to write a script that logs who deleted a user account in Webex Control Hub. What endpoint should I call and what permissions do I need?"*
   - **MCP Action:** Uses `search_webex_api_docs("audit events")` -> Returns `GET /adminAudit/events` -> Uses `get_webex_endpoint_schema` to inspect `actorEmail`, `eventDescription`, and the required `audit:events_read` scope.

2. **📞 Telephony & AI Receptionist Automation**
   - **User Prompt:** *"How do I programmatically create an AI Receptionist Knowledge Base in Webex Calling?"*
   - **MCP Action:** Uses `search_webex_api_docs("knowledge base")` -> Locates `POST /telephony/config/knowledgeBases` -> Retrieves the exact JSON Request Body schema showing mandatory fields (`name`, `description`).

3. **📝 Meeting Summaries & Transcripts**
   - **User Prompt:** *"What is the REST API path to download post-meeting transcripts and AI summaries?"*
   - **MCP Action:** Searches `meetings` domain for `"transcripts"` -> Finds `GET /meetings/{meetingId}/transcripts` and `GET /meetings/{meetingId}/summaries` along with query parameters.

4. **🤖 Messaging Bots & Webhooks**
   - **User Prompt:** *"I want my bot to receive real-time notifications when a message is posted in a Webex room."*
   - **MCP Action:** Locates `POST /webhooks` in the `messaging` domain and returns the required payload structure for `messages/created` events.

5. **📺 RoomOS xAPI Device Automation & AirPlay**
   - **User Prompt:** *"How do I control AirPlay or adjust volume on a Cisco Room Bar using xAPI?"*
   - **MCP Action:** Searches `roomos` domain -> Finds `xCommand AirPlay KeyEvent Back` and `xCommand Audio Volume Set` -> Retrieves syntax for Webex Cloud REST API (`POST /v1/xapi/command/...`), Node.js `jsxapi`, and on-device CLI/Macros.

---

## 🌟 Why This Architecture? (Dual-Layer Documentation)

This repository implements a **scalable, reproducible, and Git-versioned documentation pipeline** designed specifically for AI Agents and developers:

1. **Layer 1: Markdown Artifacts in Git (`docs/<domain>.md`)**
   - Clean, structured Markdown documentation for **Webex Admin, Webex Cloud Calling, Webex Meetings, Webex Messaging, and Webex RoomOS xAPI** is generated automatically and stored in `/docs/`.
   - Every time Webex updates an API, running the ETL pipeline produces a standard Git diff so you can track API changes over time.
2. **Layer 2: SQLAlchemy + SQLite FTS5 Index (`data/webex_docs.db`)**
   - An optimized SQLite relational database managed via **SQLAlchemy 2.0 ORM** combined with **SQLite FTS5 (Full-Text Search)**.
   - Provides sub-millisecond keyword and semantic search across **4,539 endpoints** without loading multi-megabyte files into memory or context.

---

## 📦 What's Included?

The server indexes **4,539 official Webex endpoints** across 5 major service domains:

| Domain | Categories | Endpoints | Generated Document | Description |
| :--- | :---: | :---: | :--- | :--- |
| **`admin`** | 34 | 146 | `docs/admin.md` | Webex Admin APIs (People, SCIM, Licenses, Roles, Audit Events, Real-time Events, Security). |
| **`calling`** | 54 | 1,081 | `docs/calling.md` | Webex Cloud Calling APIs (AI Receptionist, Call Queues, Auto Attendant, Routing, DECT, Voicemail). |
| **`meetings`** | 22 | 166 | `docs/meetings.md` | Webex Meetings APIs (Meetings, Participants, Transcripts, Closed Captions, Recordings, Q&A). |
| **`messaging`** | 12 | 63 | `docs/messaging.md` | Webex Messaging APIs (Rooms, Messages, Memberships, Teams, Webhooks, Hybrid Data Security). |
| **`roomos`** | 4 | 3,083 | `docs/roomos.md` | Webex RoomOS xAPI (`xCommand`, `xConfiguration`, `xStatus`, `xEvent`) for Cisco Room Kit, Board, Desk Pro, and Collaboration Devices. |
| **TOTAL** | **126** | **4,539** | — | — |

---

## 🛠️ Installation & Setup

1. **Clone the repository and install dependencies:**
   ```bash
   git clone https://github.com/santime27/mcp-server-webex-docs.git
   cd mcp-server-webex-docs
   pip install -r requirements.txt
   ```

2. **Run the automated ETL pipeline (Optional - Rebuild docs and DB index):**
   ```bash
   python3 -m src.pipeline.build_all
   ```
   *This extracts the OpenAPI schemas, generates the 4 Markdown files in `docs/`, and builds the SQLite FTS5 database at `data/webex_docs.db`.*

3. **Start the MCP Server:**
   ```bash
   python3 -m src.server
   ```

---

## 🔌 How to Connect This MCP Server (Configuration)

Thanks to automatic path resolving in `src/server.py`, connecting this server to any MCP client is **ultra-simple**—no `PYTHONPATH`, `cwd`, or `-m` flags required!

### 1. Gemini CLI / Google Antigravity / Gemini Code Assist
Add this to your Gemini MCP settings file (e.g., `~/.gemini/settings.json` or your project's MCP configuration):

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

### 2. Claude Desktop / Cursor / Generic MCP Client (`claude_desktop_config.json`)
```json
{
  "mcpServers": {
    "webex-api-docs": {
      "command": "python3",
      "args": [
        "/path/to/mcp-server-webex-docs/src/server.py"
      ]
    }
  }
}
```
*Note: Replace `/path/to/mcp-server-webex-docs` with the absolute path where you cloned this repository on your machine.*

---


## 🤖 MCP Tools Exposed for AI Agents

When connected to an MCP client (such as Claude Desktop, Antigravity, or custom agents), this server exposes the following tools:

- `search_webex_api_docs(query, domain=None, category=None, limit=15)`
  - Sub-millisecond FTS5 search across all 1,456 endpoints. Returns endpoint titles, HTTP method/path, summary, and exact line numbers in the documentation file.
- `get_webex_endpoint_schema(domain, section_number)`
  - Reads the exact line range from `docs/<domain>.md` and returns the complete OpenAPI JSON schema, parameter table, required scopes, and HTTP response codes for a specific endpoint.
- `list_webex_domains()`
  - Lists the 4 available Webex domains and their endpoint counts.
- `list_webex_categories(domain)`
  - Lists all categories available within a specific domain.

---

## 📁 Repository Structure

```text
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
```

---

## 🧠 AI Agent Skill (`agent-skills/webex-api-assistant`)

This repository includes an official **Agent Skill** in `agent-skills/webex-api-assistant/SKILL.md` designed to teach any AI Assistant (such as Antigravity, Claude, or Cursor) how to act as a **Senior Webex Developer Companion**.

The skill instructs the model on:
1. **The 2-Step MCP Workflow:** Always discovering APIs via `search_webex_api_docs` first, then inspecting full OpenAPI schemas and OAuth scopes via `get_webex_endpoint_schema`.
2. **Interactive Sandbox Exploration:** Generating and executing clean Python exploration scripts in a sandbox/temporary environment to test live APIs.
3. **Security Best Practices:** Reading `WEBEX_ACCESS_TOKEN` from environment variables without ever hardcoding tokens.

---

## 👨‍💻 Authors & Credits

Built with ❤️ by **[Santiago Meneses Garcia](https://github.com/santime27)**, Software Engineer, in pair-programming collaboration with **Antigravity** (Google DeepMind Agentic AI Assistant).

---

## 📄 License

This project is licensed under the permissive **[MIT License](LICENSE)** — feel free to use, copy, modify, distribute, and build upon this software for both personal and commercial projects without restrictions.