Merge pull request #7 from WebexCommunity/claude/streaming-server-aws-Sgava

Author: adamweeks

DEPLOYMENT.md

@@ -1,183 +1,160 @@
-# 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"]
+# AWS Deployment Guide — Webex Bot MCP
+
+This guide covers deploying the server on an EC2 instance with an Application Load Balancer
+providing TLS termination.
+
+```
+MCP Client
+    │  HTTPS :443  Authorization: Bearer <webex_token>
+    ▼
+┌─────────────────────────────────┐
+│  Application Load Balancer      │  ← ACM certificate (TLS termination)
+│  Listener: HTTPS 443            │
+└──────────────┬──────────────────┘
+               │  HTTP :8000
+               ▼
+┌─────────────────────────────────┐
+│  EC2 instance                   │
+│  docker-compose                 │
+│  webex-bot-mcp container :8000  │
+└─────────────────────────────────┘
+```
+
+## Prerequisites
+
+- AWS account with permissions to create EC2, ALB, ACM, and security group resources
+- A domain name with DNS you can update (required for the ACM certificate)
+- Docker and Docker Compose installed on the EC2 instance
+
+## 1. Build and push the image
+
+Build locally and push to ECR, or build directly on the instance.
+
+**Option A — build on the EC2 instance (simpler):**
+```bash
+git clone https://github.com/WebexCommunity/webex-bot-mcp.git
+cd webex-bot-mcp
+docker compose build
 ```
 
-## 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
+**Option B — ECR:**
+```bash
+aws ecr create-repository --repository-name webex-bot-mcp
+# follow the ECR push commands shown in the console
 ```
 
-## Claude Desktop Configuration
+## 2. Security groups
+
+Create two security groups.
 
-Add to your Claude Desktop config:
+**ALB security group (`sg-alb`):**
+| Type  | Protocol | Port | Source    |
+|-------|----------|------|-----------|
+| HTTPS | TCP      | 443  | 0.0.0.0/0 |
+
+**EC2 security group (`sg-ec2`):**
+| Type        | Protocol | Port | Source   |
+|-------------|----------|------|----------|
+| Custom TCP  | TCP      | 8000 | sg-alb   |
+| SSH         | TCP      | 22   | your IP  |
+
+Port 8000 is only reachable from the ALB — never directly from the internet.
+
+## 3. ACM certificate
+
+1. Go to **AWS Certificate Manager → Request certificate**
+2. Request a public certificate for your domain (e.g. `mcp.example.com`)
+3. Validate via DNS — add the CNAME record ACM gives you to your DNS provider
+4. Wait for status to show **Issued** before continuing
+
+## 4. Target group
+
+1. Go to **EC2 → Target Groups → Create target group**
+2. Settings:
+   - Target type: **Instances**
+   - Protocol: **HTTP**, Port: **8000**
+   - Health check path: **`/health`**
+   - Healthy threshold: 2, Unhealthy threshold: 3, Interval: 30s
+3. Register your EC2 instance as a target
+
+## 5. Application Load Balancer
+
+1. Go to **EC2 → Load Balancers → Create load balancer → Application Load Balancer**
+2. Settings:
+   - Scheme: **Internet-facing**
+   - IP address type: **IPv4**
+   - VPC and subnets: select at least two AZs
+   - Security group: `sg-alb`
+3. **Listeners:**
+   - HTTPS :443 → forward to your target group
+   - Select your ACM certificate
+4. Create the load balancer and note the DNS name (e.g. `my-alb-123456.us-east-1.elb.amazonaws.com`)
+
+## 6. DNS
+
+Add a CNAME record pointing your domain to the ALB DNS name:
+```
+mcp.example.com  CNAME  my-alb-123456.us-east-1.elb.amazonaws.com
+```
+
+## 7. Run the container
+
+On the EC2 instance:
+```bash
+cd webex-bot-mcp
+docker compose up -d
+```
+
+No environment variables are required — each MCP client supplies its own Webex bot token
+via the `Authorization: Bearer` header. If you want to run in stdio mode on the same host
+you can still set `WEBEX_ACCESS_TOKEN` in a `.env` file.
+
+## 8. Verify
+
+```bash
+# Health check (no auth required)
+curl https://mcp.example.com/health
+# → {"status":"ok"}
+
+# Confirm auth is enforced on the MCP endpoint
+curl https://mcp.example.com/mcp
+# → 401 Authorization: Bearer <webex_bot_token> header required
+```
+
+## 9. MCP client configuration
+
+Point your MCP client at the HTTPS URL. Example for Claude Desktop (`claude_desktop_config.json`):
 
 ```json
 {
   "mcpServers": {
     "webex-bot": {
-      "command": "python",
-      "args": ["/path/to/webex-bot-mcp/main.py"],
-      "env": {
-        "WEBEX_ACCESS_TOKEN": "your_token_here"
+      "url": "https://mcp.example.com/mcp",
+      "headers": {
+        "Authorization": "Bearer <your_webex_bot_token>"
       }
     }
   }
 }
 ```
 
-## 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
+Each user or team connects with their own Webex bot token. The server itself holds no token.
 
-### Monitoring Metrics
-- Message send success rate
-- API response times
-- Error rates by operation type
-- Resource utilization (CPU, memory, network)
+## Environment variables reference
 
-## Security Best Practices
+All variables are optional for HTTP transport.
 
-### Token Management
-- Store tokens in secure key management systems
-- Implement token rotation automation
-- Monitor for token compromise
+| Variable | Default | Description |
+|---|---|---|
+| `WEBEX_ACCESS_TOKEN` | — | Token for stdio transport only |
+| `WEBEX_DEBUG` | `false` | Enable verbose logging |
+| `LOG_LEVEL` | `INFO` | `DEBUG` / `INFO` / `WARNING` / `ERROR` |
+| `LOG_FORMAT` | `text` | `text` or `json` |
+| `METRICS_ENABLED` | `false` | Enable Prometheus metrics |
 
-### Network Security
-- Use HTTPS only in production
-- Implement proper firewall rules
-- Consider VPN or private network deployment
+## Scaling note
 
-### Data Protection
-- Encrypt sensitive data at rest
-- Implement audit logging
-- Follow data retention policies
-- Regular security assessments
+MCP sessions are stateful — a client initializes a session and reuses it for subsequent
+tool calls. If you run multiple EC2 instances behind the ALB, enable **sticky sessions**
+(duration-based) on the target group so all requests from one client land on the same
+instance. A single instance is fine for most deployments.

Dockerfile

@@ -1,63 +1,44 @@
 # Multi-stage build for Webex Bot MCP Server
-FROM python:3.12-slim as builder
+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 .
+# Copy everything needed for a PEP 517 build
+COPY pyproject.toml README.md ./
+COPY src/ ./src/
 
-# Production stage
-FROM python:3.12-slim as production
+# Non-editable install so the package lands fully in site-packages
+RUN pip install --no-cache-dir .
+
+
+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 --from=builder /usr/local/bin/webex-bot-mcp* /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
+    CMD webex-bot-mcp-health --skip-api --exit-code || exit 1
 
-# Default command
-CMD ["python", "main.py", "--transport", "streamable-http", "--host", "0.0.0.0", "--port", "8000"]
+CMD ["webex-bot-mcp", "--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"