devrev-Python-SDK 2.4.1__tar.gz → 2.7.0__tar.gz

{devrev_python_sdk-2.4.1 → devrev_python_sdk-2.7.0}/Dockerfile

@@ -39,11 +39,11 @@ FROM python:3.11-slim AS runtime
 # Metadata labels
 LABEL maintainer="Matthew G. Monteleone <matthewm@augmentcode.com>" \
       description="DevRev MCP Server - A Model Context Protocol server for the DevRev platform" \
-      version="2.3.0" \
+      version="2.6.0" \
       org.opencontainers.image.source="https://github.com/mgmonteleone/py-dev-rev" \
       org.opencontainers.image.title="DevRev MCP Server" \
       org.opencontainers.image.description="Production-ready MCP server for DevRev API integration" \
-      org.opencontainers.image.version="2.3.0" \
+      org.opencontainers.image.version="2.6.0" \
       org.opencontainers.image.licenses="MIT"
 
 # Set environment variables for Python

{devrev_python_sdk-2.4.1 → devrev_python_sdk-2.7.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: devrev-Python-SDK
-Version: 2.4.1
+Version: 2.7.0
 Summary: A modern, type-safe Python SDK for the DevRev API
 Project-URL: Homepage, https://github.com/mgmonteleone/py-dev-rev
 Project-URL: Documentation, https://github.com/mgmonteleone/py-dev-rev
@@ -97,6 +97,7 @@ A modern, type-safe Python SDK for the DevRev API.
 - [Configuration](#configuration)
 - [Error Handling](#error-handling)
 - [Logging](#logging)
+- [MCP Server](#mcp-server)
 - [Development](#development)
 - [Testing Strategy](#testing-strategy)
 - [CI/CD Pipeline](#cicd-pipeline)
@@ -153,6 +154,15 @@ This SDK is generated and maintained from the official DevRev OpenAPI specificat
 - ✅ **Health Checks** - Built-in health check endpoints for monitoring
 - ✅ **High Test Coverage** - 80%+ code coverage with unit and integration tests
 
+### MCP Server (AI Integration)
+
+- ✅ **78+ MCP Tools** — Full CRUD for tickets, accounts, users, articles, and all DevRev resources
+- ✅ **7 Resource Templates** — `devrev://` URI scheme for AI-accessible data browsing
+- ✅ **8 Workflow Prompts** — Pre-built triage, escalation, investigation, and reporting workflows
+- ✅ **3 Transport Modes** — stdio (local), Streamable HTTP (production), SSE (legacy)
+- ✅ **Per-User Authentication** — DevRev PAT auth mode for team deployments
+- ✅ **Cloud Run Deployment** — One-command deploy to Google Cloud Run with auto-scaling
+
 ---
 
 ## Installation

{devrev_python_sdk-2.4.1 → devrev_python_sdk-2.7.0}/README.md

@@ -25,6 +25,7 @@ A modern, type-safe Python SDK for the DevRev API.
 - [Configuration](#configuration)
 - [Error Handling](#error-handling)
 - [Logging](#logging)
+- [MCP Server](#mcp-server)
 - [Development](#development)
 - [Testing Strategy](#testing-strategy)
 - [CI/CD Pipeline](#cicd-pipeline)
@@ -81,6 +82,15 @@ This SDK is generated and maintained from the official DevRev OpenAPI specificat
 - ✅ **Health Checks** - Built-in health check endpoints for monitoring
 - ✅ **High Test Coverage** - 80%+ code coverage with unit and integration tests
 
+### MCP Server (AI Integration)
+
+- ✅ **78+ MCP Tools** — Full CRUD for tickets, accounts, users, articles, and all DevRev resources
+- ✅ **7 Resource Templates** — `devrev://` URI scheme for AI-accessible data browsing
+- ✅ **8 Workflow Prompts** — Pre-built triage, escalation, investigation, and reporting workflows
+- ✅ **3 Transport Modes** — stdio (local), Streamable HTTP (production), SSE (legacy)
+- ✅ **Per-User Authentication** — DevRev PAT auth mode for team deployments
+- ✅ **Cloud Run Deployment** — One-command deploy to Google Cloud Run with auto-scaling
+
 ---
 
 ## Installation

{devrev_python_sdk-2.4.1 → devrev_python_sdk-2.7.0}/deploy/README.md

@@ -461,7 +461,94 @@ curl -X POST https://devrev-mcp-server-xxx.run.app/mcp/v1/initialize \
 
 ### Audit and Monitoring
 
-1. **Cloud Logging**: All requests logged in JSON format
+#### Application-Level Audit Logging
+
+The MCP server includes built-in structured audit logging for compliance. When enabled (default), every authentication event and tool invocation is logged with structured JSON fields.
+
+**Audit Event Schema:**
+```json
+{
+  "event_type": "audit",
+  "action": "tool_invocation",
+  "user": {"id": "don:...", "email": "user@example.com", "pat_hash": "sha256:..."},
+  "tool": {"name": "devrev_works_list", "category": "read"},
+  "request": {"client_ip": "203.0.113.42"},
+  "outcome": "success",
+  "duration_ms": 142
+}
+```
+
+**Configuration:**
+```bash
+# Enable/disable audit logging (default: true)
+MCP_AUDIT_LOG_ENABLED=true
+```
+
+**Querying audit logs:**
+```bash
+# View recent audit events
+gcloud logging read 'resource.type="cloud_run_revision" AND jsonPayload.event_type="audit"' \
+  --project=PROJECT_ID --limit=50 --format=json
+
+# View auth failures only
+gcloud logging read 'jsonPayload.event_type="audit" AND jsonPayload.action="auth_failure"' \
+  --project=PROJECT_ID --limit=50
+
+# View tool invocations for a specific user
+gcloud logging read 'jsonPayload.event_type="audit" AND jsonPayload.user.email="user@example.com"' \
+  --project=PROJECT_ID --limit=50
+```
+
+#### Immutable Audit Log Storage
+
+For compliance with immutable log requirements, set up a WORM-compliant Cloud Storage bucket with a Cloud Logging sink:
+
+```bash
+# Run the setup script
+./deploy/audit-logging-setup.sh --project=YOUR_PROJECT_ID
+
+# With WORM lock (IRREVERSIBLE — enables permanent retention):
+./deploy/audit-logging-setup.sh --project=YOUR_PROJECT_ID --lock
+```
+
+This creates:
+1. A GCS bucket with a 365-day retention policy
+2. A Cloud Logging sink that exports `event_type="audit"` entries
+3. IAM bindings for the sink's service account
+
+See `deploy/audit-logging-setup.sh --help` for all options.
+
+#### Monitoring and Alerting
+
+Alert policies and a dashboard are provided in `deploy/monitoring/`:
+
+```bash
+# Validate prerequisites
+./deploy/monitoring/validate-config.sh YOUR_PROJECT_ID
+
+# Create a notification channel
+gcloud alpha monitoring channels create \
+  --display-name="MCP Audit Alerts" \
+  --type=email \
+  --channel-labels=email_address=alerts@yourcompany.com
+
+# Apply alert policies (edit alert-policies.yaml first with your project/channel IDs)
+gcloud alpha monitoring policies create \
+  --policy-from-file=deploy/monitoring/alert-policies.yaml
+
+# Import dashboard
+gcloud monitoring dashboards create \
+  --config-from-file=deploy/monitoring/dashboard.json
+```
+
+**Alert policies include:**
+- High auth failure rate (>10 failures in 5 min)
+- High destructive operation rate (>20 deletes in 10 min)
+- Elevated tool error rate (>20% failure over 5 min)
+
+See `deploy/monitoring/README.md` for full details.
+
+1. **Cloud Logging**: All requests and audit events logged in JSON format
    ```bash
    gcloud run services logs read devrev-mcp-server --region=us-central1
    ```

devrev_python_sdk-2.7.0/deploy/audit-logging-setup.sh

@@ -0,0 +1,270 @@
+#!/usr/bin/env bash
+# Audit Logging Infrastructure Setup for DevRev MCP Server
+# Sets up immutable audit log storage for compliance.
+#
+# Usage:
+#   ./deploy/audit-logging-setup.sh --project=my-project
+#   ./deploy/audit-logging-setup.sh --project=my-project --retention=730 --lock
+#
+# This script creates:
+#   1. A GCS bucket with a retention policy for audit log storage
+#   2. A Cloud Logging sink that exports audit events to the bucket
+#   3. IAM bindings for the sink's service account
+#
+# The --lock flag enables WORM (Write Once Read Many) compliance by
+# permanently locking the bucket retention policy. THIS IS IRREVERSIBLE.
+
+set -euo pipefail
+
+# Color codes for output
+RED='\033[0;31m'
+GREEN='\033[0;32m'
+YELLOW='\033[1;33m'
+BLUE='\033[0;34m'
+NC='\033[0m' # No Color
+
+# Default values
+REGION="${REGION:-us-central1}"
+RETENTION_DAYS="${RETENTION_DAYS:-365}"
+BUCKET_NAME=""
+SINK_NAME="${SINK_NAME:-mcp-audit-log-sink}"
+SERVICE_NAME="${SERVICE_NAME:-devrev-mcp-server}"
+PROJECT_ID="${PROJECT_ID:-}"
+LOCK_BUCKET=false
+
+# Helper functions
+log_info() {
+    echo -e "${BLUE}[INFO]${NC} $1"
+}
+
+log_success() {
+    echo -e "${GREEN}[SUCCESS]${NC} $1"
+}
+
+log_warning() {
+    echo -e "${YELLOW}[WARNING]${NC} $1"
+}
+
+log_error() {
+    echo -e "${RED}[ERROR]${NC} $1"
+}
+
+show_usage() {
+    cat << EOF
+Usage: $0 [OPTIONS]
+
+Required:
+  --project=PROJECT_ID          GCP project ID
+
+Optional:
+  --region=REGION               GCS bucket region (default: us-central1)
+  --retention=DAYS              Retention period in days (default: 365)
+  --bucket=BUCKET_NAME          GCS bucket name (default: PROJECT_ID-mcp-audit-logs)
+  --sink=SINK_NAME              Cloud Logging sink name (default: mcp-audit-log-sink)
+  --service=SERVICE_NAME        Cloud Run service name (default: devrev-mcp-server)
+  --lock                        Lock bucket retention policy (IRREVERSIBLE!)
+  -h, --help                    Show this help message
+
+Examples:
+  $0 --project=my-project
+  $0 --project=my-project --retention=730 --lock
+
+EOF
+}
+
+# Parse command line arguments
+for arg in "$@"; do
+    case $arg in
+        --project=*)
+            PROJECT_ID="${arg#*=}"
+            shift
+            ;;
+        --region=*)
+            REGION="${arg#*=}"
+            shift
+            ;;
+        --retention=*)
+            RETENTION_DAYS="${arg#*=}"
+            shift
+            ;;
+        --bucket=*)
+            BUCKET_NAME="${arg#*=}"
+            shift
+            ;;
+        --sink=*)
+            SINK_NAME="${arg#*=}"
+            shift
+            ;;
+        --service=*)
+            SERVICE_NAME="${arg#*=}"
+            shift
+            ;;
+        --lock)
+            LOCK_BUCKET=true
+            shift
+            ;;
+        -h|--help)
+            show_usage
+            exit 0
+            ;;
+        *)
+            log_error "Unknown option: $arg"
+            show_usage
+            exit 1
+            ;;
+    esac
+done
+
+# Validate required parameters
+if [ -z "$PROJECT_ID" ]; then
+    log_error "PROJECT_ID is required"
+    show_usage
+    exit 1
+fi
+
+# Set default bucket name if not provided
+if [ -z "$BUCKET_NAME" ]; then
+    BUCKET_NAME="${PROJECT_ID}-mcp-audit-logs"
+fi
+
+log_info "Starting audit logging infrastructure setup"
+log_info "Project: $PROJECT_ID"
+log_info "Region: $REGION"
+log_info "Bucket: $BUCKET_NAME"
+log_info "Retention: $RETENTION_DAYS days"
+log_info "Sink: $SINK_NAME"
+log_info "Service: $SERVICE_NAME"
+log_info "Lock bucket: $LOCK_BUCKET"
+echo ""
+
+# Step 1: Create GCS bucket with retention policy
+log_info "Step 1: Creating GCS bucket with retention policy..."
+if gsutil ls -b "gs://$BUCKET_NAME" &>/dev/null; then
+    log_warning "Bucket gs://$BUCKET_NAME already exists, skipping creation"
+else
+    log_info "Creating bucket gs://$BUCKET_NAME..."
+    gsutil mb -p "$PROJECT_ID" -l "$REGION" -b on "gs://$BUCKET_NAME"
+    log_success "Bucket created"
+fi
+
+# Set retention policy (skip if bucket is already locked)
+LOCK_STATUS=$(gsutil retention get "gs://$BUCKET_NAME" 2>/dev/null | grep -i "Locked" || echo "")
+if echo "$LOCK_STATUS" | grep -qi "true"; then
+    log_warning "Bucket retention policy is locked; skipping retention update"
+else
+    log_info "Setting retention policy to $RETENTION_DAYS days..."
+    gsutil retention set "${RETENTION_DAYS}d" "gs://$BUCKET_NAME"
+    log_success "Retention policy set"
+fi
+
+# Step 2: Lock the bucket (optional, IRREVERSIBLE)
+if [ "$LOCK_BUCKET" = true ]; then
+    log_warning "Checking if bucket retention policy is already locked..."
+
+    # Check if already locked
+    LOCK_STATUS=$(gsutil retention get "gs://$BUCKET_NAME" | grep -i "Retention Policy Locked" || echo "")
+
+    if echo "$LOCK_STATUS" | grep -qi "true"; then
+        log_warning "Bucket retention policy is already locked"
+    else
+        echo ""
+        log_warning "⚠️  WARNING: You are about to PERMANENTLY LOCK the bucket retention policy!"
+        log_warning "This action is IRREVERSIBLE and enforces WORM (Write Once Read Many) compliance."
+        log_warning "Once locked, you CANNOT:"
+        log_warning "  - Reduce the retention period"
+        log_warning "  - Delete the bucket until all objects expire"
+        log_warning "  - Remove the retention policy"
+        echo ""
+        read -p "Type 'LOCK' to confirm: " confirmation
+
+        if [ "$confirmation" = "LOCK" ]; then
+            log_info "Locking bucket retention policy..."
+            gsutil retention lock "gs://$BUCKET_NAME"
+            log_success "Bucket retention policy locked (WORM compliance enabled)"
+        else
+            log_warning "Bucket lock cancelled"
+        fi
+    fi
+else
+    log_info "Skipping bucket lock (use --lock flag to enable WORM compliance)"
+fi
+
+# Step 3: Create Cloud Logging sink
+log_info "Step 3: Creating Cloud Logging sink..."
+if gcloud logging sinks describe "$SINK_NAME" --project="$PROJECT_ID" &>/dev/null; then
+    log_warning "Sink $SINK_NAME already exists, skipping creation"
+else
+    log_info "Creating sink $SINK_NAME..."
+
+    # Create the sink with filter for audit events
+    gcloud logging sinks create "$SINK_NAME" \
+        "storage.googleapis.com/$BUCKET_NAME" \
+        --project="$PROJECT_ID" \
+        --log-filter="resource.type=\"cloud_run_revision\" AND resource.labels.service_name=\"$SERVICE_NAME\" AND jsonPayload.event_type=\"audit\""
+
+    log_success "Sink created"
+fi
+
+# Step 4: Grant sink service account write access to bucket
+log_info "Step 4: Granting sink service account write access..."
+
+# Get the sink's writer identity
+SINK_SA=$(gcloud logging sinks describe "$SINK_NAME" --project="$PROJECT_ID" --format='value(writerIdentity)')
+
+if [ -z "$SINK_SA" ]; then
+    log_error "Failed to get sink service account"
+    exit 1
+fi
+
+log_info "Sink service account: $SINK_SA"
+
+# Grant objectCreator role
+log_info "Granting objectCreator role to sink service account..."
+gsutil iam ch "${SINK_SA}:objectCreator" "gs://$BUCKET_NAME"
+log_success "IAM binding created"
+
+# Step 5: Enable Data Access Audit Logs
+log_info "Step 5: Data Access Audit Logs configuration..."
+echo ""
+log_warning "MANUAL STEP REQUIRED:"
+log_warning "Enable Data Access audit logs in Cloud Console for:"
+log_warning "  1. Cloud Run API:"
+log_warning "     IAM & Admin > Audit Logs > Cloud Run API"
+log_warning "     ✓ Enable 'Data Read'"
+log_warning "     ✓ Enable 'Data Write'"
+log_warning ""
+log_warning "  2. Secret Manager API:"
+log_warning "     IAM & Admin > Audit Logs > Secret Manager API"
+log_warning "     ✓ Enable 'Data Read'"
+log_warning ""
+log_warning "Or use gcloud to update the IAM policy:"
+log_warning "  gcloud projects get-iam-policy $PROJECT_ID > policy.yaml"
+log_warning "  # Edit policy.yaml to add auditConfigs"
+log_warning "  gcloud projects set-iam-policy $PROJECT_ID policy.yaml"
+echo ""
+
+# Step 6: Verify setup
+log_info "Step 6: Verifying setup..."
+echo ""
+log_info "=== Sink Configuration ==="
+gcloud logging sinks describe "$SINK_NAME" --project="$PROJECT_ID"
+echo ""
+log_info "=== Bucket Configuration ==="
+gsutil ls -L -b "gs://$BUCKET_NAME"
+echo ""
+
+log_success "✅ Audit logging infrastructure setup complete!"
+echo ""
+log_info "Summary:"
+log_info "  • Bucket: gs://$BUCKET_NAME"
+log_info "  • Retention: $RETENTION_DAYS days"
+log_info "  • Sink: $SINK_NAME"
+log_info "  • Service: $SERVICE_NAME"
+log_info "  • Locked: $LOCK_BUCKET"
+echo ""
+log_info "Next steps:"
+log_info "  1. Enable Data Access audit logs (see manual step above)"
+log_info "  2. Deploy your Cloud Run service with audit logging enabled"
+log_info "  3. Verify logs are being exported: gsutil ls gs://$BUCKET_NAME"
+echo ""
+

{devrev_python_sdk-2.4.1 → devrev_python_sdk-2.7.0}/deploy/cloudbuild.yaml

@@ -17,8 +17,6 @@ steps:
     args:
       - 'build'
       - '-t'
-      - '${_REGION}-docker.pkg.dev/$PROJECT_ID/${_REPO}/devrev-mcp-server:$COMMIT_SHA'
-      - '-t'
       - '${_REGION}-docker.pkg.dev/$PROJECT_ID/${_REPO}/devrev-mcp-server:latest'
       - '-t'
       - '${_REGION}-docker.pkg.dev/$PROJECT_ID/${_REPO}/devrev-mcp-server:${_TAG_NAME}'
@@ -45,18 +43,18 @@ steps:
       - 'run'
       - 'deploy'
       - '${_SERVICE_NAME}'
-      - '--image=${_REGION}-docker.pkg.dev/$PROJECT_ID/${_REPO}/devrev-mcp-server:$COMMIT_SHA'
+      - '--image=${_REGION}-docker.pkg.dev/$PROJECT_ID/${_REPO}/devrev-mcp-server:${_TAG_NAME}'
       - '--region=${_REGION}'
       - '--platform=managed'
       - '--allow-unauthenticated'
       - '--port=8080'
       - '--memory=${_MEMORY}'
       - '--cpu=${_CPU}'
-      - '--min-instances=0'
+      - '--min-instances=1'
       - '--max-instances=10'
       - '--timeout=300s'
       - '--concurrency=80'
-      - '--set-env-vars=MCP_TRANSPORT=streamable-http,MCP_HOST=0.0.0.0,MCP_PORT=8080,MCP_LOG_FORMAT=json,MCP_LOG_LEVEL=INFO,MCP_AUTH_MODE=devrev-pat,MCP_AUTH_ALLOWED_DOMAINS=["augmentcode.com"]'
+      - '--set-env-vars=MCP_TRANSPORT=streamable-http,MCP_HOST=0.0.0.0,MCP_PORT=8080,MCP_LOG_FORMAT=json,MCP_LOG_LEVEL=INFO,MCP_AUTH_MODE=devrev-pat,MCP_AUTH_ALLOWED_DOMAINS=["augmentcode.com"],MCP_ENABLE_DNS_REBINDING_PROTECTION=true,MCP_ALLOWED_HOSTS=["devrev-mcp-server-ucpy26yrfa-uc.a.run.app"]'
       # Uncomment the next line if you need DEVREV_API_TOKEN for stdio/testing fallback
       # - '--set-secrets=DEVREV_API_TOKEN=devrev-api-token:latest'
     waitFor: ['push']
@@ -66,7 +64,6 @@ substitutions:
   _REGION: 'us-central1'
   _SERVICE_NAME: 'devrev-mcp-server'
   _REPO: 'devrev-mcp'
-  _IMAGE: 'devrev-mcp-server'
   _CPU: '1'
   _MEMORY: '512Mi'
   _TAG_NAME: 'latest'
@@ -81,7 +78,6 @@ timeout: '1200s'
 
 # Images to be pushed to Artifact Registry
 images:
-  - '${_REGION}-docker.pkg.dev/$PROJECT_ID/${_REPO}/devrev-mcp-server:$COMMIT_SHA'
   - '${_REGION}-docker.pkg.dev/$PROJECT_ID/${_REPO}/devrev-mcp-server:latest'
   - '${_REGION}-docker.pkg.dev/$PROJECT_ID/${_REPO}/devrev-mcp-server:${_TAG_NAME}'