webex-bot-mcp 0.1.1__tar.gz

webex_bot_mcp-0.1.1/.env.example

@@ -0,0 +1,5 @@
+# Webex Bot MCP Environment Variables
+
+# Your Webex Access Token (required)
+# Get this from https://developer.webex.com/docs/getting-started
+WEBEX_ACCESS_TOKEN=your_webex_access_token_here

webex_bot_mcp-0.1.1/.env.template

@@ -0,0 +1,33 @@
+# Environment Configuration Template
+# Copy this to .env and fill in your actual values
+
+# Required: Webex Bot Access Token
+# Get this from https://developer.webex.com after creating a bot
+WEBEX_ACCESS_TOKEN=your_bot_token_here
+
+# Optional: Enable debug logging (true/false)
+WEBEX_DEBUG=false
+
+# Optional: Rate limiting configuration
+WEBEX_RATE_LIMIT_MESSAGES_PER_SECOND=10
+WEBEX_RATE_LIMIT_API_CALLS_PER_MINUTE=300
+
+# Optional: Default room settings
+WEBEX_DEFAULT_ROOM_TYPE=group
+WEBEX_DEFAULT_MESSAGE_FORMAT=markdown
+
+# Optional: Organization settings
+WEBEX_ORG_DOMAIN=your-company.com
+WEBEX_DEFAULT_MODERATORS=admin@your-company.com
+
+# Optional: Logging configuration
+LOG_LEVEL=INFO
+LOG_FORMAT=json
+
+# Optional: Monitoring and metrics
+METRICS_ENABLED=false
+METRICS_ENDPOINT=http://localhost:9090
+
+# Security settings
+WEBEX_VALIDATE_SSL=true
+WEBEX_TIMEOUT_SECONDS=30

webex_bot_mcp-0.1.1/.github/workflows/publish.yml

@@ -0,0 +1,63 @@
+name: Publish to PyPI
+
+on:
+  push:
+    tags:
+      - "v*"
+  workflow_dispatch:
+
+jobs:
+  build:
+    name: Build distribution
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+
+      - name: Install build tools
+        run: pip install build
+
+      - name: Build package
+        run: python -m build
+
+      - uses: actions/upload-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+  publish-testpypi:
+    name: Publish to TestPyPI
+    needs: build
+    runs-on: ubuntu-latest
+    environment: testpypi
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+      - name: Publish to TestPyPI
+        uses: pypa/gh-action-pypi-publish@release/v1
+        with:
+          repository-url: https://test.pypi.org/legacy/
+
+  publish-pypi:
+    name: Publish to PyPI
+    needs: publish-testpypi
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/download-artifact@v4
+        with:
+          name: dist
+          path: dist/
+
+      - name: Publish to PyPI
+        uses: pypa/gh-action-pypi-publish@release/v1

webex_bot_mcp-0.1.1/.gitignore

@@ -0,0 +1,13 @@
+# Python-generated files
+__pycache__/
+*.py[oc]
+build/
+dist/
+wheels/
+*.egg-info
+
+# Virtual environments
+.venv
+
+# Environment variables
+.env

webex_bot_mcp-0.1.1/.python-version

@@ -0,0 +1 @@
+3.12

webex_bot_mcp-0.1.1/CLAUDE.md

@@ -0,0 +1,121 @@
+# Webex Bot MCP — Developer Guide
+
+## Project Overview
+
+A Model Context Protocol (MCP) server that bridges AI assistants with the Webex Teams API.
+It exposes tools for managing rooms, messages, and memberships, plus resources (contextual
+guides) and prompt templates for common workflows.
+
+## Repository Layout
+
+```
+main.py              — MCP server entry point; registers all tools/resources/prompts
+config.py            — WebexConfig dataclass; loaded via get_config() or WebexConfig.from_env()
+health_check.py      — Standalone diagnostic script; validates env and API connectivity
+pyproject.toml       — Project metadata and dependencies (uses uv)
+Dockerfile           — Multi-stage build; non-root user, health checks
+docker-compose.yml   — Compose stack with optional Prometheus + Grafana
+
+tools/
+  __init__.py        — Re-exports every tool function
+  common.py          — Shared: WebexAPI client, create_error_response, create_success_response,
+                       WebexErrorCodes, version constants
+  rooms.py           — Room/space CRUD (list, create, update, get, delete) + space aliases
+  messages.py        — Message send/list/delete + mention helpers + space aliases
+  memberships.py     — Membership CRUD (list, add, update, delete) + space aliases
+  people.py          — get_webex_me, list_webex_people
+
+tests/
+  test_messages.py   — Unit tests (38 cases); mocks webexpythonsdk at sys.modules level
+```
+
+## Key Conventions
+
+### Tool count
+31 tools total: 5 room + 5 space-room aliases + 4 message + 2 space-message aliases +
+4 membership + 2 space-membership aliases + 2 people + 4 space-room/membership aliases.
+Update `tools_count` in the `server_version` resource (`main.py`) when adding tools.
+
+### Error handling — always use structured responses
+Every tool must return via `create_error_response` or `create_success_response` from
+`tools/common.py`. Never return a bare `{'success': False, 'error': str(e)}` dict.
+Map exceptions with a local `_map_exception_to_error(e)` helper (see any tool module for
+the pattern).
+
+Error code ranges:
+- `E001–E003` — client/argument errors (do not retry)
+- `E401–E404` — auth/access errors (do not retry)
+- `E500–E504` — server errors (retry with backoff)
+- `E600–E602` — Webex-specific errors
+
+### Response shape
+```python
+# Error
+{'success': False, 'error_code': 'E001', 'message': '...', 'timestamp': '<ISO>', 'server_version': '...'}
+
+# Success
+{'success': True, 'data': {...}, 'timestamp': '<ISO>', 'server_version': '...', 'metadata': {...}}
+```
+
+### Space aliases
+Every room/message/membership tool has a "space" alias that delegates to the room variant
+and renames keys in the response (`room` → `space`, `rooms` → `spaces`, etc.).
+Aliases live in the same module file as the canonical tool.
+
+### `files` parameter
+Always wrap a string URL in a list before sending to the SDK:
+```python
+params['files'] = [files] if isinstance(files, str) else files
+```
+
+## Running the Server
+
+```bash
+# stdio (default — for Claude Desktop / MCP clients)
+uv run python main.py
+
+# HTTP transport
+uv run python main.py --transport streamable-http --host 0.0.0.0 --port 8000
+```
+
+Required environment variable: `WEBEX_ACCESS_TOKEN`
+
+## Running Tests
+
+```bash
+python -m unittest discover -s tests -v
+```
+
+Tests mock `webexpythonsdk` via `sys.modules` so no real credentials are needed.
+
+## Adding a New Tool
+
+1. Implement the function in the appropriate `tools/*.py` module.
+2. Use `create_error_response` / `create_success_response` for all returns.
+3. Add a `_map_exception_to_error` call in the `except` block.
+4. Export from `tools/__init__.py`.
+5. Register with `mcp.tool()(your_function)` in `main.py`.
+6. Update `tools_count` in the `server_version` resource in `main.py`.
+7. Add unit tests in `tests/test_messages.py` (or a new test file).
+
+## Environment Variables
+
+| Variable | Required | Default | Description |
+|---|---|---|---|
+| `WEBEX_ACCESS_TOKEN` | ✅ | — | Bot token from developer.webex.com |
+| `WEBEX_DEBUG` | | `false` | Enable debug logging |
+| `WEBEX_RATE_LIMIT_MESSAGES_PER_SECOND` | | `10` | Message rate limit |
+| `WEBEX_RATE_LIMIT_API_CALLS_PER_MINUTE` | | `300` | API rate limit |
+| `WEBEX_TIMEOUT_SECONDS` | | `30` | HTTP timeout |
+| `LOG_LEVEL` | | `INFO` | `DEBUG`, `INFO`, `WARNING`, or `ERROR` |
+| `LOG_FORMAT` | | `text` | `text` or `json` |
+| `METRICS_ENABLED` | | `false` | Enable metrics endpoint |
+| `METRICS_ENDPOINT` | | — | Prometheus push endpoint |
+
+## Dependency Management
+
+Uses `uv`. The declared runtime dependency for dotenv is `python-dotenv>=1.0.0`
+(not the unrelated `dotenv` PyPI package). After changing `pyproject.toml` run:
+```bash
+uv lock && uv sync
+```

webex_bot_mcp-0.1.1/DEPLOYMENT.md

@@ -0,0 +1,183 @@
+# Webex Bot MCP Server Configuration
+
+This file provides deployment guidance and configuration options for production use.
+
+## Production Deployment Checklist
+
+### Security Configuration
+- [ ] Bot token stored in secure environment variables (not in code)
+- [ ] SSL/TLS enabled for all communications
+- [ ] Regular token rotation schedule established
+- [ ] Access logging enabled
+- [ ] Rate limiting configured
+- [ ] Input validation implemented
+
+### Monitoring & Observability
+- [ ] Application logs configured (structured logging recommended)
+- [ ] Metrics collection enabled
+- [ ] Health check endpoints configured
+- [ ] Error tracking and alerting set up
+- [ ] Performance monitoring dashboard created
+
+### High Availability & Scale
+- [ ] Container orchestration configured (if using containers)
+- [ ] Load balancing configured (for HTTP transport)
+- [ ] Graceful shutdown handling implemented
+- [ ] Resource limits defined
+- [ ] Auto-scaling policies configured
+
+### Compliance & Governance
+- [ ] Data retention policies defined
+- [ ] Audit logging enabled
+- [ ] Compliance framework alignment verified
+- [ ] Privacy policies updated
+- [ ] User consent mechanisms implemented
+
+## Environment Variables Reference
+
+### Required
+- `WEBEX_ACCESS_TOKEN`: Bot access token from Webex Developer Portal
+
+### Optional Configuration
+- `WEBEX_DEBUG`: Enable debug logging (default: false)
+- `WEBEX_RATE_LIMIT_MESSAGES_PER_SECOND`: Message rate limit (default: 10)
+- `WEBEX_RATE_LIMIT_API_CALLS_PER_MINUTE`: API call rate limit (default: 300)
+- `LOG_LEVEL`: Logging verbosity (DEBUG, INFO, WARN, ERROR)
+- `METRICS_ENABLED`: Enable metrics collection (default: false)
+
+### Transport Configuration
+- `MCP_TRANSPORT`: Transport type (stdio, streamable-http)
+- `MCP_HOST`: Host binding for HTTP transport (default: localhost)
+- `MCP_PORT`: Port binding for HTTP transport (default: 8000)
+
+## Docker Deployment
+
+```dockerfile
+FROM python:3.12-slim
+
+WORKDIR /app
+COPY requirements.txt .
+RUN pip install -r requirements.txt
+
+COPY . .
+EXPOSE 8000
+
+CMD ["python", "main.py", "--transport", "streamable-http", "--host", "0.0.0.0"]
+```
+
+## Kubernetes Deployment
+
+```yaml
+apiVersion: apps/v1
+kind: Deployment
+metadata:
+  name: webex-bot-mcp
+spec:
+  replicas: 2
+  selector:
+    matchLabels:
+      app: webex-bot-mcp
+  template:
+    metadata:
+      labels:
+        app: webex-bot-mcp
+    spec:
+      containers:
+      - name: webex-bot-mcp
+        image: webex-bot-mcp:latest
+        ports:
+        - containerPort: 8000
+        env:
+        - name: WEBEX_ACCESS_TOKEN
+          valueFrom:
+            secretKeyRef:
+              name: webex-secrets
+              key: access-token
+        resources:
+          limits:
+            memory: "512Mi"
+            cpu: "500m"
+          requests:
+            memory: "256Mi"
+            cpu: "250m"
+---
+apiVersion: v1
+kind: Service
+metadata:
+  name: webex-bot-mcp-service
+spec:
+  selector:
+    app: webex-bot-mcp
+  ports:
+  - port: 80
+    targetPort: 8000
+  type: LoadBalancer
+```
+
+## Claude Desktop Configuration
+
+Add to your Claude Desktop config:
+
+```json
+{
+  "mcpServers": {
+    "webex-bot": {
+      "command": "python",
+      "args": ["/path/to/webex-bot-mcp/main.py"],
+      "env": {
+        "WEBEX_ACCESS_TOKEN": "your_token_here"
+      }
+    }
+  }
+}
+```
+
+## Common Issues & Solutions
+
+### Issue: "Token Invalid" Errors
+**Solution**: Check token expiration, regenerate if needed, ensure proper environment variable setup.
+
+### Issue: Rate Limiting
+**Solution**: Implement exponential backoff, respect API limits, consider request batching.
+
+### Issue: Memory Usage
+**Solution**: Monitor for memory leaks, implement connection pooling, tune garbage collection.
+
+### Issue: High Latency
+**Solution**: Use connection pooling, implement caching, optimize database queries if used.
+
+## Performance Tuning
+
+### Message Throughput Optimization
+- Use bulk operations where possible
+- Implement message queuing for high-volume scenarios
+- Consider async/await patterns for concurrent operations
+
+### Resource Optimization
+- Connection pooling for HTTP transport
+- Memory-efficient data structures
+- Proper cleanup of resources
+
+### Monitoring Metrics
+- Message send success rate
+- API response times
+- Error rates by operation type
+- Resource utilization (CPU, memory, network)
+
+## Security Best Practices
+
+### Token Management
+- Store tokens in secure key management systems
+- Implement token rotation automation
+- Monitor for token compromise
+
+### Network Security
+- Use HTTPS only in production
+- Implement proper firewall rules
+- Consider VPN or private network deployment
+
+### Data Protection
+- Encrypt sensitive data at rest
+- Implement audit logging
+- Follow data retention policies
+- Regular security assessments

webex_bot_mcp-0.1.1/Dockerfile

@@ -0,0 +1,63 @@
+# Multi-stage build for Webex Bot MCP Server
+FROM python:3.12-slim as builder
+
+# Install build dependencies
+RUN apt-get update && apt-get install -y \
+    build-essential \
+    && rm -rf /var/lib/apt/lists/*
+
+# Set working directory
+WORKDIR /app
+
+# Copy requirements and install dependencies
+COPY pyproject.toml ./
+RUN pip install --no-cache-dir -e .
+
+# Production stage
+FROM python:3.12-slim as production
+
+# Create non-root user for security
+RUN groupadd -r webexbot && useradd -r -g webexbot webexbot
+
+# Install runtime dependencies
+RUN apt-get update && apt-get install -y \
+    ca-certificates \
+    && rm -rf /var/lib/apt/lists/*
+
+# Set working directory
+WORKDIR /app
+
+# Copy installed packages from builder
+COPY --from=builder /usr/local/lib/python3.12/site-packages /usr/local/lib/python3.12/site-packages
+COPY --from=builder /usr/local/bin /usr/local/bin
+
+# Copy application code
+COPY main.py ./
+COPY tools/ ./tools/
+COPY config.py ./
+COPY health_check.py ./
+COPY .env.template ./
+
+# Change ownership to non-root user
+RUN chown -R webexbot:webexbot /app
+
+# Switch to non-root user
+USER webexbot
+
+# Create volume for configuration
+VOLUME ["/app/config"]
+
+# Expose port for HTTP transport
+EXPOSE 8000
+
+# Health check
+HEALTHCHECK --interval=30s --timeout=10s --start-period=5s --retries=3 \
+    CMD python health_check.py --skip-rooms --exit-code || exit 1
+
+# Default command
+CMD ["python", "main.py", "--transport", "streamable-http", "--host", "0.0.0.0", "--port", "8000"]
+
+# Metadata
+LABEL maintainer="Webex Bot MCP Team"
+LABEL description="Webex Bot Model Context Protocol Server"
+LABEL version="1.0.0"

webex_bot_mcp-0.1.1/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 WebexCommunity
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.