Scale computer-use 2.0 with open-source drivers, cross-OS sandboxes, and benchmarks for training, evaluation, and data generation.
Rust agentai-agentapplecomputer-usecomputer-use-agentcontainerizationcuadesktop-automationhacktoberfestlumemacosmanusoperatorswiftvirtualizationvirtualization-frameworkwindowswindows-sandbox
Add Docs MCP Server with vector and SQL query capabilities (#969)
r33drichards1b932bbb4dfe
diff --git a/.github/workflows/docs-mcp-server-build-push.yml b/.github/workflows/docs-mcp-server-build-push.ymlnew file mode 100644index 0000000000..1ed48825b6--- /dev/null+++ b/.github/workflows/docs-mcp-server-build-push.yml@@ -0,0 +1,229 @@+name: "CD: Docs MCP Server"++on:+ push:+ branches:+ - main+ paths:+ - "docs/scripts/docs-mcp-server/**"+ pull_request:+ branches:+ - main+ paths:+ - "docs/scripts/docs-mcp-server/**"+ workflow_dispatch:+ inputs:+ force_push:+ description: "Push image even on non-main branch"+ required: false+ default: false+ type: boolean++env:+ AWS_REGION: us-west-2+ ECR_REGISTRY: 296062593712.dkr.ecr.us-west-2.amazonaws.com+ ECR_REPOSITORY: docs-mcp-server+ SERVICE_DIR: docs/scripts/docs-mcp-server++permissions:+ id-token: write+ contents: read++jobs:+ build:+ runs-on: ${{ matrix.platform == 'linux/arm64' && 'ubuntu-24.04-arm' || 'ubuntu-latest' }}+ strategy:+ fail-fast: false+ matrix:+ platform:+ - linux/amd64+ - linux/arm64+ outputs:+ image_tag: ${{ steps.meta.outputs.version }}+ timestamp: ${{ steps.timestamp.outputs.ts }}++ steps:+ - name: Checkout+ uses: actions/checkout@v4++ - name: Prepare platform tag+ id: platform+ run: |+ TAG=$(echo "${{ matrix.platform }}" | sed 's/\//-/g')+ echo "tag=${TAG}" >> $GITHUB_OUTPUT++ - name: Configure AWS credentials+ uses: aws-actions/configure-aws-credentials@v4+ with:+ role-to-assume: arn:aws:iam::296062593712:role/github-actions-ecr-push-cua+ aws-region: ${{ env.AWS_REGION }}++ - name: Login to Amazon ECR+ id: login-ecr+ uses: aws-actions/amazon-ecr-login@v2++ - name: Set up Docker Buildx+ uses: docker/setup-buildx-action@v3++ - name: Generate timestamp+ id: timestamp+ run: echo "ts=$(date -u +'%Y%m%d%H%M%S')" >> $GITHUB_OUTPUT++ - name: Extract metadata+ id: meta+ uses: docker/metadata-action@v5+ with:+ images: ${{ env.ECR_REGISTRY }}/${{ env.ECR_REPOSITORY }}+ tags: |+ type=sha,prefix=,format=short+ type=ref,event=branch+ type=ref,event=pr+ type=raw,value=latest,enable=${{ github.ref == 'refs/heads/main' }}+ type=raw,value=main-${{ steps.timestamp.outputs.ts }},enable=${{ github.ref == 'refs/heads/main' }}++ - name: Determine if push is enabled+ id: push-check+ run: |+ if [[ "${{ github.event_name }}" == "pull_request" ]]; then+ echo "push=false" >> $GITHUB_OUTPUT+ elif [[ "${{ github.ref }}" == "refs/heads/main" ]]; then+ echo "push=true" >> $GITHUB_OUTPUT+ elif [[ "${{ inputs.force_push }}" == "true" ]]; then+ echo "push=true" >> $GITHUB_OUTPUT+ else+ echo "push=false" >> $GITHUB_OUTPUT+ fi++ - name: Build only (PR)+ if: steps.push-check.outputs.push == 'false'+ uses: docker/build-push-action@v5+ with:+ context: ./${{ env.SERVICE_DIR }}+ file: ./${{ env.SERVICE_DIR }}/Dockerfile+ push: false+ platforms: ${{ matrix.platform }}+ cache-from: type=gha,scope=${{ env.ECR_REPOSITORY }}-${{ steps.platform.outputs.tag }}+ cache-to: type=gha,mode=max,scope=${{ env.ECR_REPOSITORY }}-${{ steps.platform.outputs.tag }}++ - name: Build and push by digest+ if: steps.push-check.outputs.push == 'true'+ id: build+ uses: docker/build-push-action@v5+ with:+ context: ./${{ env.SERVICE_DIR }}+ file: ./${{ env.SERVICE_DIR }}/Dockerfile+ push: true+ platforms: ${{ matrix.platform }}+ outputs: type=image,name=${{ env.ECR_REGISTRY }}/${{ env.ECR_REPOSITORY }},push-by-digest=true,name-canonical=true+ labels: ${{ steps.meta.outputs.labels }}+ cache-from: type=gha,scope=${{ env.ECR_REPOSITORY }}-${{ steps.platform.outputs.tag }}+ cache-to: type=gha,mode=max,scope=${{ env.ECR_REPOSITORY }}-${{ steps.platform.outputs.tag }}++ - name: Export digest+ if: steps.push-check.outputs.push == 'true'+ run: |+ mkdir -p /tmp/digests+ digest="${{ steps.build.outputs.digest }}"+ if [ -n "$digest" ]; then+ echo "$digest" > "/tmp/digests/${{ steps.platform.outputs.tag }}.txt"+ echo "Digest exported for platform ${{ matrix.platform }}: $digest"+ else+ echo "No digest to export for platform ${{ matrix.platform }}"+ exit 1+ fi++ - name: Upload digest artifact+ if: steps.push-check.outputs.push == 'true'+ uses: actions/upload-artifact@v4+ with:+ name: digests-${{ steps.platform.outputs.tag }}+ path: /tmp/digests/*.txt+ retention-days: 1++ merge:+ runs-on: ubuntu-latest+ needs: build+ if: |+ github.event_name != 'pull_request' &&+ (github.ref == 'refs/heads/main' || inputs.force_push == true)++ steps:+ - name: Configure AWS credentials+ uses: aws-actions/configure-aws-credentials@v4+ with:+ role-to-assume: arn:aws:iam::296062593712:role/github-actions-ecr-push-cua+ aws-region: ${{ env.AWS_REGION }}++ - name: Login to Amazon ECR+ uses: aws-actions/amazon-ecr-login@v2++ - name: Set up Docker Buildx+ uses: docker/setup-buildx-action@v3++ - name: Extract metadata+ id: meta+ uses: docker/metadata-action@v5+ with:+ images: ${{ env.ECR_REGISTRY }}/${{ env.ECR_REPOSITORY }}+ tags: |+ type=sha,prefix=,format=short+ type=ref,event=branch+ type=raw,value=latest,enable=${{ github.ref == 'refs/heads/main' }}+ type=raw,value=main-${{ needs.build.outputs.timestamp }},enable=${{ github.ref == 'refs/heads/main' }}++ - name: Download all digest artifacts+ uses: actions/download-artifact@v4+ with:+ pattern: digests-*+ path: /tmp/digests+ merge-multiple: true++ - name: Check available digests+ id: check-digests+ run: |+ DIGEST_COUNT=$(find /tmp/digests -type f -name "*.txt" | wc -l)+ echo "digest_count=$DIGEST_COUNT" >> $GITHUB_OUTPUT++ if [ "$DIGEST_COUNT" -eq 0 ]; then+ echo "Error: No platform builds succeeded!"+ exit 1+ fi++ echo "Found $DIGEST_COUNT platform digest(s)"+ for f in $(find /tmp/digests -type f -name "*.txt"); do+ platform=$(basename "$f" .txt)+ echo " - $platform: $(cat $f)"+ done++ - name: Create and push multi-arch manifest+ run: |+ IMAGE="${{ env.ECR_REGISTRY }}/${{ env.ECR_REPOSITORY }}"++ # Collect all digests+ DIGEST_ARGS=""+ for f in $(find /tmp/digests -type f -name "*.txt"); do+ d=$(cat "$f")+ DIGEST_ARGS="$DIGEST_ARGS ${IMAGE}@${d}"+ done++ echo "Using digests:"+ echo "$DIGEST_ARGS"++ # Create manifest for each tag produced by metadata-action+ echo "${{ steps.meta.outputs.tags }}" | while read FULL_TAG; do+ if [ -n "$FULL_TAG" ]; then+ echo "Creating manifest: $FULL_TAG"+ docker buildx imagetools create --tag "$FULL_TAG" $DIGEST_ARGS+ fi+ done++ - name: Inspect pushed manifests+ run: |+ echo "Inspecting manifests:"+ echo "${{ steps.meta.outputs.tags }}" | while read FULL_TAG; do+ if [ -n "$FULL_TAG" ]; then+ echo ""+ echo "Inspecting: $FULL_TAG"+ docker buildx imagetools inspect "$FULL_TAG"+ fi+ donediff --git a/docs/scripts/docs-mcp-server/Dockerfile b/docs/scripts/docs-mcp-server/Dockerfilenew file mode 100644index 0000000000..183ea7f255--- /dev/null+++ b/docs/scripts/docs-mcp-server/Dockerfile@@ -0,0 +1,65 @@+# syntax=docker/dockerfile:1+FROM python:3.12-slim AS builder++# Install uv+COPY --from=ghcr.io/astral-sh/uv:latest /uv /uvx /bin/++# Set working directory+WORKDIR /app++# Copy project files+COPY pyproject.toml ./++# Create virtual environment and install dependencies+RUN uv venv /app/.venv+ENV VIRTUAL_ENV=/app/.venv+ENV PATH="/app/.venv/bin:$PATH"++# Install dependencies (without the project itself for better caching)+RUN uv pip install --no-cache -r pyproject.toml++# Copy application code+COPY main.py ./++# Production image+FROM python:3.12-slim AS runtime++# Create non-root user for security+RUN useradd --create-home --shell /bin/bash appuser++WORKDIR /app++# Copy virtual environment from builder+COPY --from=builder /app/.venv /app/.venv+COPY --from=builder /app/main.py /app/main.py++# Set environment variables+ENV VIRTUAL_ENV=/app/.venv+ENV PATH="/app/.venv/bin:$PATH"+ENV PYTHONUNBUFFERED=1+ENV PORT=8000+ENV HOST=0.0.0.0++# Database paths (mount volumes to these paths)+ENV DOCS_DB_PATH=/data/docs_db+ENV CODE_DB_PATH=/data/code_db++# OpenTelemetry configuration+ENV OTEL_ENDPOINT=https://otel.cua.ai+ENV OTEL_SERVICE_NAME=cua-docs-mcp++# Create data directory+RUN mkdir -p /data && chown appuser:appuser /data++# Switch to non-root user+USER appuser++# Expose port+EXPOSE 8000++# Health check+HEALTHCHECK --interval=30s --timeout=10s --start-period=5s --retries=3 \+ CMD python -c "import urllib.request; urllib.request.urlopen('http://localhost:8000/health')" || exit 1++# Run the server+CMD ["python", "main.py"]diff --git a/docs/scripts/docs-mcp-server/main.py b/docs/scripts/docs-mcp-server/main.pynew file mode 100644index 0000000000..0c1cf67688--- /dev/null+++ b/docs/scripts/docs-mcp-server/main.py@@ -0,0 +1,511 @@+"""+CUA Documentation and Code MCP Server++A standalone MCP server that provides read-only query access to:+1. CUA documentation (crawled from cua.ai/docs)+2. Versioned source code indexed across git tags++This server is designed to run as a containerized service, with databases+mounted from external volumes or cloud storage.++Usage:+ # Run the server+ python main.py++ # Or with uvicorn+ uvicorn main:app --host 0.0.0.0 --port 8000+"""++import os+import sqlite3+import time+from pathlib import Path+from typing import Optional++import lancedb+from fastmcp import FastMCP+from lancedb.embeddings import get_registry+from starlette.middleware import Middleware+from starlette.middleware.cors import CORSMiddleware++# Configuration from environment variables+OTEL_ENDPOINT = os.environ.get("OTEL_ENDPOINT", "https://otel.cua.ai")+OTEL_SERVICE_NAME = os.environ.get("OTEL_SERVICE_NAME", "cua-docs-mcp")++# Database paths (configurable via environment)+DOCS_DB_PATH = os.environ.get("DOCS_DB_PATH", "/data/docs_db")+CODE_DB_PATH = os.environ.get("CODE_DB_PATH", "/data/code_db")++# Initialize OpenTelemetry for metrics and tracing+_tracer = None+_meter = None+_request_counter = None+_request_duration = None+++def init_telemetry():+ """Initialize OpenTelemetry for metrics and tracing."""+ global _tracer, _meter, _request_counter, _request_duration++ try:+ from opentelemetry import metrics, trace+ from opentelemetry.exporter.otlp.proto.http.metric_exporter import OTLPMetricExporter+ from opentelemetry.exporter.otlp.proto.http.trace_exporter import OTLPSpanExporter+ from opentelemetry.sdk.metrics import MeterProvider+ from opentelemetry.sdk.metrics.export import PeriodicExportingMetricReader+ from opentelemetry.sdk.resources import Resource+ from opentelemetry.sdk.trace import TracerProvider+ from opentelemetry.sdk.trace.export import BatchSpanProcessor++ resource = Resource.create({+ "service.name": OTEL_SERVICE_NAME,+ "service.version": "1.0.0",+ })++ # Set up tracing+ trace_exporter = OTLPSpanExporter(endpoint=f"{OTEL_ENDPOINT}/v1/traces")+ tracer_provider = TracerProvider(resource=resource)+ tracer_provider.add_span_processor(BatchSpanProcessor(trace_exporter))+ trace.set_tracer_provider(tracer_provider)+ _tracer = trace.get_tracer(OTEL_SERVICE_NAME)++ # Set up metrics+ metric_exporter = OTLPMetricExporter(endpoint=f"{OTEL_ENDPOINT}/v1/metrics")+ metric_reader = PeriodicExportingMetricReader(metric_exporter, export_interval_millis=60000)+ meter_provider = MeterProvider(resource=resource, metric_readers=[metric_reader])+ metrics.set_meter_provider(meter_provider)+ _meter = metrics.get_meter(OTEL_SERVICE_NAME)++ # Create metrics instruments+ _request_counter = _meter.create_counter(+ name="mcp_requests_total",+ description="Total number of MCP tool requests",+ unit="1",+ )+ _request_duration = _meter.create_histogram(+ name="mcp_request_duration_seconds",+ description="Duration of MCP tool requests in seconds",+ unit="s",+ )++ print(f"OpenTelemetry initialized with endpoint: {OTEL_ENDPOINT}")+ except ImportError as e:+ print(f"OpenTelemetry packages not available: {e}")+ except Exception as e:+ print(f"Failed to initialize OpenTelemetry: {e}")+++def record_request(tool_name: str, duration: float, status: str = "success"):+ """Record metrics for a tool request."""+ if _request_counter is not None:+ _request_counter.add(1, {"tool": tool_name, "status": status})+ if _request_duration is not None:+ _request_duration.record(duration, {"tool": tool_name, "status": status})+++# Initialize telemetry+init_telemetry()++# Initialize the MCP server+mcp = FastMCP(+ name="CUA Docs & Code",+ instructions="""CUA Documentation and Code Server - provides direct read-only query access to Computer Use Agent (CUA) documentation and versioned source code.++=== AVAILABLE TOOLS ===++Documentation:+- query_docs_db: Execute SQL queries against the documentation SQLite database+- query_docs_vectors: Execute vector similarity searches against the documentation LanceDB++Code:+- query_code_db: Execute SQL queries against the code search SQLite database+- query_code_vectors: Execute vector similarity searches against the code LanceDB++All tools are READ-ONLY. Only SELECT queries are allowed for SQL databases.++=== DOCUMENTATION DATABASE ===++The documentation database contains crawled pages from cua.ai/docs covering:+- CUA SDK: Python library for building computer-use agents+- CUA Bench: Benchmarking framework for evaluating computer-use agents+- Agent Loop: Core execution loop for autonomous agent operation+- Sandboxes: Docker and cloud VM environments for safe agent execution+- Computer interfaces: Screen, mouse, keyboard, and bash interaction APIs++=== CODE DATABASE ===++The code database contains versioned source code indexed across all git tags.+Components include: agent, computer, mcp-server, som, etc.++=== WORKFLOW EXAMPLES ===++1. Find documentation about a topic:+ - Use query_docs_vectors with a natural language query for semantic search+ - Use query_docs_db with FTS5 MATCH for keyword search++2. Explore code across versions:+ - List components: SELECT component, COUNT(DISTINCT version) FROM code_files GROUP BY component+ - Search code: Use query_code_db with FTS5 on code_files_fts+ - Get file content: SELECT content FROM code_files WHERE component='agent' AND version='0.7.3' AND file_path='...'++3. Semantic code search:+ - Use query_code_vectors with natural language queries like "screenshot capture implementation"++IMPORTANT: Always cite sources - URLs for docs, component@version:path for code.""",+)++# Initialize embedding model - load eagerly to avoid cold start on first search+print("Initializing embedding model...")+model = get_registry().get("sentence-transformers").create(name="all-MiniLM-L6-v2")++# Eagerly initialize database connections at startup to reduce first-request latency+print("Initializing database connections...")++# Docs LanceDB+_docs_lance_db = None+_docs_lance_table = None+docs_db_path = Path(DOCS_DB_PATH)+if docs_db_path.exists():+ try:+ _docs_lance_db = lancedb.connect(docs_db_path)+ _docs_lance_table = _docs_lance_db.open_table("docs")+ print(f" Docs LanceDB loaded from {docs_db_path}")+ except Exception as e:+ print(f" Warning: Could not load docs LanceDB: {e}")++# Docs SQLite+_docs_sqlite_conn = None+sqlite_path = Path(DOCS_DB_PATH) / "docs.sqlite"+if sqlite_path.exists():+ try:+ _docs_sqlite_conn = sqlite3.connect(f"file:{sqlite_path}?mode=ro", uri=True)+ _docs_sqlite_conn.row_factory = sqlite3.Row+ print(f" Docs SQLite loaded from {sqlite_path}")+ except Exception as e:+ print(f" Warning: Could not load docs SQLite: {e}")++# Code LanceDB+_code_lance_db = None+_code_lance_table = None+code_lance_path = Path(CODE_DB_PATH) / "code_index.lancedb"+if code_lance_path.exists():+ try:+ _code_lance_db = lancedb.connect(code_lance_path)+ _code_lance_table = _code_lance_db.open_table("code")+ print(f" Code LanceDB loaded from {code_lance_path}")+ except Exception as e:+ print(f" Warning: Could not load code LanceDB: {e}")++# Code SQLite+_code_sqlite_conn = None+code_sqlite_path = Path(CODE_DB_PATH) / "code_index.sqlite"+if code_sqlite_path.exists():+ try:+ _code_sqlite_conn = sqlite3.connect(f"file:{code_sqlite_path}?mode=ro", uri=True)+ _code_sqlite_conn.row_factory = sqlite3.Row+ print(f" Code SQLite loaded from {code_sqlite_path}")+ except Exception as e:+ print(f" Warning: Could not load code SQLite: {e}")++print("Database initialization complete.")+++def get_lance_table():+ """Get LanceDB connection for docs (eagerly loaded)"""+ if _docs_lance_table is None:+ raise RuntimeError("Database not found. Ensure the docs database is mounted at DOCS_DB_PATH.")+ return _docs_lance_table+++def get_sqlite_conn():+ """Get read-only SQLite connection for docs (eagerly loaded)"""+ if _docs_sqlite_conn is None:+ raise RuntimeError("SQLite database not found. Ensure docs.sqlite is present in DOCS_DB_PATH.")+ return _docs_sqlite_conn+++def get_code_lance_table():+ """Get LanceDB connection for the aggregated code database (eagerly loaded)."""+ if _code_lance_table is None:+ raise RuntimeError(+ "Code LanceDB not found. Ensure code_index.lancedb is present in CODE_DB_PATH."+ )+ return _code_lance_table+++def get_code_sqlite_conn():+ """Get read-only SQLite connection for the aggregated code database (eagerly loaded)."""+ if _code_sqlite_conn is None:+ raise RuntimeError(+ "Code SQLite database not found. Ensure code_index.sqlite is present in CODE_DB_PATH."+ )+ return _code_sqlite_conn+++# =================== DOCUMENTATION QUERY TOOLS (READ-ONLY) ===================+++def query_docs_db(sql: str) -> list[dict]:+ """+ Execute a SQL query against the documentation database.+ The database is READ-ONLY.++ Database Schema:++ Table: pages+ - id INTEGER PRIMARY KEY AUTOINCREMENT+ - url TEXT NOT NULL UNIQUE -- Full URL of the documentation page+ - title TEXT NOT NULL -- Page title+ - category TEXT NOT NULL -- Category (e.g., 'cua', 'cuabench', 'llms.txt')+ - content TEXT NOT NULL -- Plain text content (markdown stripped)++ Virtual Table: pages_fts (FTS5 full-text search)+ - content TEXT -- Full-text indexed content+ - url TEXT UNINDEXED+ - title TEXT UNINDEXED+ - category TEXT UNINDEXED++ Example queries:++ 1. List all pages: SELECT url, title, category FROM pages ORDER BY category, title++ 2. Full-text search with snippets:+ SELECT p.url, p.title, snippet(pages_fts, 0, '>>>', '<<<', '...', 64) as snippet+ FROM pages_fts JOIN pages p ON pages_fts.rowid = p.id+ WHERE pages_fts MATCH 'agent loop' ORDER BY rank LIMIT 10++ 3. Get page content: SELECT url, title, content FROM pages WHERE url LIKE '%quickstart%'++ Args:+ sql: SQL query to execute++ Returns:+ List of dictionaries, one per row, with column names as keys+ """+ start_time = time.perf_counter()+ status = "success"+ try:+ conn = get_sqlite_conn()+ cursor = conn.cursor()+ cursor.execute(sql)+ return [dict(row) for row in cursor.fetchall()]+ except Exception:+ status = "error"+ raise+ finally:+ record_request("query_docs_db", time.perf_counter() - start_time, status)+++def query_docs_vectors(+ query: str,+ limit: int = 10,+ where: Optional[str] = None,+ select: Optional[list[str]] = None,+) -> list[dict]:+ """+ Execute a vector similarity search against the documentation LanceDB (read-only).++ Schema:+ - text TEXT -- The document chunk text+ - vector VECTOR -- Embedding vector (all-MiniLM-L6-v2, 384 dimensions)+ - url TEXT -- Source URL+ - title TEXT -- Document title+ - category TEXT -- Category (e.g., 'cua', 'cuabench')+ - chunk_index INT -- Index of chunk within document++ Args:+ query: Natural language query to embed and search for+ limit: Maximum number of results (default: 10, max: 100)+ where: Optional SQL-like filter (e.g., "category = 'cua'")+ select: Optional list of columns to return (default: all except vector)++ Returns:+ List of matching documents with similarity scores (_distance field)+ """+ start_time = time.perf_counter()+ status = "success"+ try:+ limit = min(max(1, limit), 100)+ table = get_lance_table()++ search = table.search(query).limit(limit)++ if where:+ search = search.where(where)+ if select:+ search = search.select(select)++ results = search.to_list()++ formatted = []+ for r in results:+ result = {}+ for key, value in r.items():+ if key == "vector":+ continue+ result[key] = value+ formatted.append(result)++ return formatted+ except Exception:+ status = "error"+ raise+ finally:+ record_request("query_docs_vectors", time.perf_counter() - start_time, status)+++# =================== CODE QUERY TOOLS (READ-ONLY) ===================+++def query_code_db(sql: str) -> list[dict]:+ """+ Execute a SQL query against the code search database.+ The database is READ-ONLY.++ Database Schema:++ Table: code_files+ - id INTEGER PRIMARY KEY AUTOINCREMENT+ - component TEXT NOT NULL -- Component name (e.g., "agent", "computer")+ - version TEXT NOT NULL -- Version string (e.g., "0.7.3")+ - file_path TEXT NOT NULL -- Path to file+ - content TEXT NOT NULL -- Full source code content+ - language TEXT NOT NULL -- Programming language+ - UNIQUE(component, version, file_path)++ Virtual Table: code_files_fts (FTS5 full-text search)+ - content TEXT -- Full-text indexed content+ - component TEXT UNINDEXED+ - version TEXT UNINDEXED+ - file_path TEXT UNINDEXED++ Example queries:++ 1. List components: SELECT component, COUNT(DISTINCT version) as version_count+ FROM code_files GROUP BY component ORDER BY component++ 2. List versions: SELECT DISTINCT version FROM code_files+ WHERE component = 'agent' ORDER BY version DESC++ 3. Full-text search:+ SELECT f.component, f.version, f.file_path,+ snippet(code_files_fts, 0, '>>>', '<<<', '...', 64) as snippet+ FROM code_files_fts JOIN code_files f ON code_files_fts.rowid = f.id+ WHERE code_files_fts MATCH 'ComputerAgent' ORDER BY rank LIMIT 10++ 4. Get file content: SELECT content, language FROM code_files+ WHERE component = 'agent' AND version = '0.7.3' AND file_path = 'agent/core.py'++ Args:+ sql: SQL query to execute++ Returns:+ List of dictionaries, one per row, with column names as keys+ """+ start_time = time.perf_counter()+ status = "success"+ try:+ conn = get_code_sqlite_conn()+ cursor = conn.cursor()+ cursor.execute(sql)+ return [dict(row) for row in cursor.fetchall()]+ except Exception:+ status = "error"+ raise+ finally:+ record_request("query_code_db", time.perf_counter() - start_time, status)+++def query_code_vectors(+ query: str,+ limit: int = 10,+ where: Optional[str] = None,+ select: Optional[list[str]] = None,+ component: Optional[str] = None,+) -> list[dict]:+ """+ Execute a vector similarity search against the code LanceDB (read-only).++ Schema:+ - text TEXT -- The source code content+ - vector VECTOR -- Embedding vector (all-MiniLM-L6-v2, 384 dimensions)+ - component TEXT -- Component name (e.g., "agent", "computer")+ - version TEXT -- Version string (e.g., "0.7.3")+ - file_path TEXT -- Path to file within the component+ - language TEXT -- Programming language++ Args:+ query: Natural language query to embed and search for+ limit: Maximum number of results (default: 10, max: 100)+ where: Optional SQL-like filter (e.g., "version = '0.7.3'")+ select: Optional list of columns to return (default: all except vector)+ component: Optional component to filter by (if not specified, searches all)++ Returns:+ List of matching code files with similarity scores (_distance field)+ """+ start_time = time.perf_counter()+ status = "success"+ try:+ limit = min(max(1, limit), 100)+ table = get_code_lance_table()++ search = table.search(query).limit(limit)++ # Build where clause, adding component filter if specified+ where_clauses = []+ if component:+ where_clauses.append(f"component = '{component}'")+ if where:+ where_clauses.append(where)++ if where_clauses:+ search = search.where(" AND ".join(where_clauses))+ if select:+ search = search.select(select)++ results = search.to_list()++ formatted = []+ for r in results:+ result = {}+ for key, value in r.items():+ if key == "vector":+ continue+ result[key] = value+ formatted.append(result)++ return formatted+ except Exception:+ status = "error"+ raise+ finally:+ record_request("query_code_vectors", time.perf_counter() - start_time, status)+++# Create the ASGI app+app = mcp.http_app(+ transport="sse",+ middleware=[+ Middleware(+ CORSMiddleware,+ allow_origins=["*"],+ allow_credentials=True,+ allow_methods=["*"],+ allow_headers=["*"],+ )+ ],+)++if __name__ == "__main__":+ import uvicorn++ port = int(os.environ.get("PORT", "8000"))+ host = os.environ.get("HOST", "0.0.0.0")++ print(f"Starting MCP server on {host}:{port}")+ uvicorn.run(app, host=host, port=port)diff --git a/docs/scripts/docs-mcp-server/pyproject.toml b/docs/scripts/docs-mcp-server/pyproject.tomlnew file mode 100644index 0000000000..3277d934be--- /dev/null+++ b/docs/scripts/docs-mcp-server/pyproject.toml@@ -0,0 +1,30 @@+[project]+name = "docs-mcp-server"+description = "MCP Server for CUA Documentation and Code Search"+version = "0.1.0"+requires-python = ">=3.12,<3.14"+authors = [+ {name = "TryCua", email = "[email protected]"}+]+dependencies = [+ "fastmcp>=2.14.0",+ "lancedb>=0.4.0",+ "sentence-transformers>=2.2.0",+ "pyarrow>=14.0.1",+ "pydantic>=2.0.0",+ "pandas>=2.0.0",+ "markdown-it-py>=3.0.0",+ "opentelemetry-api>=1.20.0",+ "opentelemetry-sdk>=1.20.0",+ "opentelemetry-exporter-otlp-proto-http>=1.20.0",+ "uvicorn>=0.23.0",+]++[project.scripts]+docs-mcp-server = "main:app"++[tool.uv]+dev-dependencies = [+ "black>=23.9.1",+ "ruff>=0.0.292",+]diff --git a/docs/scripts/modal_app.py b/docs/scripts/modal_app.pyindex cf524a49ab..4a1ffc9540 100644--- a/docs/scripts/modal_app.py+++ b/docs/scripts/modal_app.py@@ -1,9 +1,12 @@"""-Modal app for CUA documentation crawling and MCP server+Modal app for CUA documentation crawling and database generationThis app provides:1. Scheduled daily crawling of cua.ai/docs stored in a Modal volume-2. MCP server that serves documentation search over the crawled data+2. Database generation (LanceDB vectors + SQLite FTS) for the MCP server++The MCP server that queries these databases runs as a separate containerized+service (see docs/scripts/docs-mcp-server/).Usage:modal deploy docs/scripts/modal_app.py@@ -14,7 +17,6 @@ import jsonimport reimport sqlite3from pathlib import Path-from typing import Optionalimport modalfrom markdown_it import MarkdownIt@@ -29,10 +31,6 @@ code_volume = modal.Volume.from_name("cua-code-index", create_if_missing=True)# GitHub token secret for cloninggithub_secret = modal.Secret.from_name("github-secret", required_keys=["GITHUB_TOKEN"])-# OpenTelemetry endpoint (no auth required)-OTEL_ENDPOINT = "https://otel.cua.ai"-OTEL_SERVICE_NAME = "cua-docs-mcp"-# Define the container image with all dependenciesimage = (modal.Image.debian_slim(python_version="3.12")@@ -43,16 +41,10 @@ image = ("lancedb>=0.4.0","sentence-transformers>=2.2.0","pyarrow>=14.0.1",- "fastapi>=0.100.0",- "fastmcp>=2.14.0","pydantic>=2.0.0","pandas>=2.0.0","markdown-it-py>=3.0.0","markitdown>=0.0.1",- # OpenTelemetry for metrics and tracing- "opentelemetry-api>=1.20.0",- "opentelemetry-sdk>=1.20.0",- "opentelemetry-exporter-otlp-proto-http>=1.20.0",).run_commands("playwright install --with-deps chromium"))@@ -1494,478 +1486,6 @@ async def scheduled_code_index():}-# =============================================================================-# MCP Server-# =============================================================================--- image=image,- volumes={VOLUME_PATH: docs_volume, CODE_VOLUME_PATH: code_volume},- cpu=1.0,- memory=2048,- min_containers=1, # Keep one container warm to avoid cold start latency-)[email protected](max_inputs=10)[email protected]_app(custom_domains=["docs-mcp.cua.ai"])-def web():- """ASGI web endpoint for the MCP server"""- import time-- import lancedb- from fastmcp import FastMCP- from lancedb.embeddings import get_registry- from starlette.middleware.cors import CORSMiddleware-- # Initialize OpenTelemetry for metrics and tracing- _tracer = None- _meter = None- _request_counter = None- _request_duration = None-- try:- from opentelemetry import metrics, trace- from opentelemetry.exporter.otlp.proto.http.metric_exporter import OTLPMetricExporter- from opentelemetry.exporter.otlp.proto.http.trace_exporter import OTLPSpanExporter- from opentelemetry.sdk.metrics import MeterProvider- from opentelemetry.sdk.metrics.export import PeriodicExportingMetricReader- from opentelemetry.sdk.resources import Resource- from opentelemetry.sdk.trace import TracerProvider- from opentelemetry.sdk.trace.export import BatchSpanProcessor-- resource = Resource.create({- "service.name": OTEL_SERVICE_NAME,- "service.version": "1.0.0",- })-- # Set up tracing- trace_exporter = OTLPSpanExporter(endpoint=f"{OTEL_ENDPOINT}/v1/traces")- tracer_provider = TracerProvider(resource=resource)- tracer_provider.add_span_processor(BatchSpanProcessor(trace_exporter))- trace.set_tracer_provider(tracer_provider)- _tracer = trace.get_tracer(OTEL_SERVICE_NAME)-- # Set up metrics- metric_exporter = OTLPMetricExporter(endpoint=f"{OTEL_ENDPOINT}/v1/metrics")- metric_reader = PeriodicExportingMetricReader(metric_exporter, export_interval_millis=60000)- meter_provider = MeterProvider(resource=resource, metric_readers=[metric_reader])- metrics.set_meter_provider(meter_provider)- _meter = metrics.get_meter(OTEL_SERVICE_NAME)-- # Create metrics instruments- _request_counter = _meter.create_counter(- name="mcp_requests_total",- description="Total number of MCP tool requests",- unit="1",- )- _request_duration = _meter.create_histogram(- name="mcp_request_duration_seconds",- description="Duration of MCP tool requests in seconds",- unit="s",- )-- print(f"OpenTelemetry initialized with endpoint: {OTEL_ENDPOINT}")- except ImportError as e:- print(f"OpenTelemetry packages not available: {e}")- except Exception as e:- print(f"Failed to initialize OpenTelemetry: {e}")-- def record_request(tool_name: str, duration: float, status: str = "success"):- """Record metrics for a tool request."""- if _request_counter is not None:- _request_counter.add(1, {"tool": tool_name, "status": status})- if _request_duration is not None:- _request_duration.record(duration, {"tool": tool_name, "status": status})-- # Initialize the MCP server- mcp = FastMCP(- name="CUA Docs & Code",- instructions="""CUA Documentation and Code Server - provides direct read-only query access to Computer Use Agent (CUA) documentation and versioned source code.--=== AVAILABLE TOOLS ===--Documentation:-- query_docs_db: Execute SQL queries against the documentation SQLite database-- query_docs_vectors: Execute vector similarity searches against the documentation LanceDB--Code:-- query_code_db: Execute SQL queries against the code search SQLite database-- query_code_vectors: Execute vector similarity searches against the code LanceDB--All tools are READ-ONLY. Only SELECT queries are allowed for SQL databases.--=== DOCUMENTATION DATABASE ===--The documentation database contains crawled pages from cua.ai/docs covering:-- CUA SDK: Python library for building computer-use agents-- CUA Bench: Benchmarking framework for evaluating computer-use agents-- Agent Loop: Core execution loop for autonomous agent operation-- Sandboxes: Docker and cloud VM environments for safe agent execution-- Computer interfaces: Screen, mouse, keyboard, and bash interaction APIs--=== CODE DATABASE ===--The code database contains versioned source code indexed across all git tags.-Components include: agent, computer, mcp-server, som, etc.--=== WORKFLOW EXAMPLES ===--1. Find documentation about a topic:- - Use query_docs_vectors with a natural language query for semantic search- - Use query_docs_db with FTS5 MATCH for keyword search--2. Explore code across versions:- - List components: SELECT component, COUNT(DISTINCT version) FROM code_files GROUP BY component- - Search code: Use query_code_db with FTS5 on code_files_fts- - Get file content: SELECT content FROM code_files WHERE component='agent' AND version='0.7.3' AND file_path='...'--3. Semantic code search:- - Use query_code_vectors with natural language queries like "screenshot capture implementation"--IMPORTANT: Always cite sources - URLs for docs, component@version:path for code.""",- )-- # Initialize embedding model - load eagerly to avoid cold start on first search- print("Initializing embedding model...")- model = get_registry().get("sentence-transformers").create(name="all-MiniLM-L6-v2")-- # Eagerly initialize database connections at startup to reduce first-request latency- print("Initializing database connections...")-- # Docs LanceDB- _docs_lance_db = None- _docs_lance_table = None- db_path = Path(DB_PATH)- if db_path.exists():- try:- _docs_lance_db = lancedb.connect(db_path)- _docs_lance_table = _docs_lance_db.open_table("docs")- print(f" Docs LanceDB loaded from {db_path}")- except Exception as e:- print(f" Warning: Could not load docs LanceDB: {e}")-- # Docs SQLite- _docs_sqlite_conn = None- sqlite_path = Path(DB_PATH) / "docs.sqlite"- if sqlite_path.exists():- try:- _docs_sqlite_conn = sqlite3.connect(f"file:{sqlite_path}?mode=ro", uri=True)- _docs_sqlite_conn.row_factory = sqlite3.Row- print(f" Docs SQLite loaded from {sqlite_path}")- except Exception as e:- print(f" Warning: Could not load docs SQLite: {e}")-- # Code LanceDB- _code_lance_db = None- _code_lance_table = None- code_lance_path = Path(CODE_DB_PATH) / "code_index.lancedb"- if code_lance_path.exists():- try:- _code_lance_db = lancedb.connect(code_lance_path)- _code_lance_table = _code_lance_db.open_table("code")- print(f" Code LanceDB loaded from {code_lance_path}")- except Exception as e:- print(f" Warning: Could not load code LanceDB: {e}")-- # Code SQLite- _code_sqlite_conn = None- code_sqlite_path = Path(CODE_DB_PATH) / "code_index.sqlite"- if code_sqlite_path.exists():- try:- _code_sqlite_conn = sqlite3.connect(f"file:{code_sqlite_path}?mode=ro", uri=True)- _code_sqlite_conn.row_factory = sqlite3.Row- print(f" Code SQLite loaded from {code_sqlite_path}")- except Exception as e:- print(f" Warning: Could not load code SQLite: {e}")-- print("Database initialization complete.")-- def get_lance_table():- """Get LanceDB connection for docs (eagerly loaded)"""- if _docs_lance_table is None:- raise RuntimeError("Database not found. Run crawl and generation functions first.")- return _docs_lance_table-- def get_sqlite_conn():- """Get read-only SQLite connection for docs (eagerly loaded)"""- if _docs_sqlite_conn is None:- raise RuntimeError("SQLite database not found.")- return _docs_sqlite_conn-- def get_code_lance_table():- """Get LanceDB connection for the aggregated code database (eagerly loaded)."""- if _code_lance_table is None:- raise RuntimeError(- "Code LanceDB not found. Run generate_code_index_parallel and aggregate_code_databases first."- )- return _code_lance_table-- def get_code_sqlite_conn():- """Get read-only SQLite connection for the aggregated code database (eagerly loaded)."""- if _code_sqlite_conn is None:- raise RuntimeError(- "Code SQLite database not found. Run generate_code_index_parallel and aggregate_code_databases first."- )- return _code_sqlite_conn-- # =================== DOCUMENTATION QUERY TOOLS (READ-ONLY) ===================-- @mcp.tool()- def query_docs_db(sql: str) -> list[dict]:- """- Execute a SQL query against the documentation database.- The database is READ-ONLY.-- Database Schema:-- Table: pages- - id INTEGER PRIMARY KEY AUTOINCREMENT- - url TEXT NOT NULL UNIQUE -- Full URL of the documentation page- - title TEXT NOT NULL -- Page title- - category TEXT NOT NULL -- Category (e.g., 'cua', 'cuabench', 'llms.txt')- - content TEXT NOT NULL -- Plain text content (markdown stripped)-- Virtual Table: pages_fts (FTS5 full-text search)- - content TEXT -- Full-text indexed content- - url TEXT UNINDEXED- - title TEXT UNINDEXED- - category TEXT UNINDEXED-- Example queries:-- 1. List all pages: SELECT url, title, category FROM pages ORDER BY category, title-- 2. Full-text search with snippets:- SELECT p.url, p.title, snippet(pages_fts, 0, '>>>', '<<<', '...', 64) as snippet- FROM pages_fts JOIN pages p ON pages_fts.rowid = p.id- WHERE pages_fts MATCH 'agent loop' ORDER BY rank LIMIT 10-- 3. Get page content: SELECT url, title, content FROM pages WHERE url LIKE '%quickstart%'-- Args:- sql: SQL query to execute-- Returns:- List of dictionaries, one per row, with column names as keys- """- start_time = time.perf_counter()- status = "success"- try:- conn = get_sqlite_conn()- cursor = conn.cursor()- cursor.execute(sql)- return [dict(row) for row in cursor.fetchall()]- except Exception as e:- status = "error"- raise- finally:- record_request("query_docs_db", time.perf_counter() - start_time, status)-- @mcp.tool()- def query_docs_vectors(- query: str,- limit: int = 10,- where: Optional[str] = None,- select: Optional[list[str]] = None,- ) -> list[dict]:- """- Execute a vector similarity search against the documentation LanceDB (read-only).-- Schema:- - text TEXT -- The document chunk text- - vector VECTOR -- Embedding vector (all-MiniLM-L6-v2, 384 dimensions)- - url TEXT -- Source URL- - title TEXT -- Document title- - category TEXT -- Category (e.g., 'cua', 'cuabench')- - chunk_index INT -- Index of chunk within document-- Args:- query: Natural language query to embed and search for- limit: Maximum number of results (default: 10, max: 100)- where: Optional SQL-like filter (e.g., "category = 'cua'")- select: Optional list of columns to return (default: all except vector)-- Returns:- List of matching documents with similarity scores (_distance field)- """- start_time = time.perf_counter()- status = "success"- try:- limit = min(max(1, limit), 100)- table = get_lance_table()-- search = table.search(query).limit(limit)-- if where:- search = search.where(where)- if select:- search = search.select(select)-- results = search.to_list()-- formatted = []- for r in results:- result = {}- for key, value in r.items():- if key == "vector":- continue- result[key] = value- formatted.append(result)-- return formatted- except Exception as e:- status = "error"- raise- finally:- record_request("query_docs_vectors", time.perf_counter() - start_time, status)-- # =================== CODE QUERY TOOLS (READ-ONLY) ===================-- @mcp.tool()- def query_code_db(sql: str) -> list[dict]:- """- Execute a SQL query against the code search database.- The database is READ-ONLY.-- Database Schema:-- Table: code_files- - id INTEGER PRIMARY KEY AUTOINCREMENT- - component TEXT NOT NULL -- Component name (e.g., "agent", "computer")- - version TEXT NOT NULL -- Version string (e.g., "0.7.3")- - file_path TEXT NOT NULL -- Path to file- - content TEXT NOT NULL -- Full source code content- - language TEXT NOT NULL -- Programming language- - UNIQUE(component, version, file_path)-- Virtual Table: code_files_fts (FTS5 full-text search)- - content TEXT -- Full-text indexed content- - component TEXT UNINDEXED- - version TEXT UNINDEXED- - file_path TEXT UNINDEXED-- Example queries:-- 1. List components: SELECT component, COUNT(DISTINCT version) as version_count- FROM code_files GROUP BY component ORDER BY component-- 2. List versions: SELECT DISTINCT version FROM code_files- WHERE component = 'agent' ORDER BY version DESC-- 3. Full-text search:- SELECT f.component, f.version, f.file_path,- snippet(code_files_fts, 0, '>>>', '<<<', '...', 64) as snippet- FROM code_files_fts JOIN code_files f ON code_files_fts.rowid = f.id- WHERE code_files_fts MATCH 'ComputerAgent' ORDER BY rank LIMIT 10-- 4. Get file content: SELECT content, language FROM code_files- WHERE component = 'agent' AND version = '0.7.3' AND file_path = 'agent/core.py'-- Args:- sql: SQL query to execute-- Returns:- List of dictionaries, one per row, with column names as keys- """- start_time = time.perf_counter()- status = "success"- try:- conn = get_code_sqlite_conn()- cursor = conn.cursor()- cursor.execute(sql)- return [dict(row) for row in cursor.fetchall()]- except Exception as e:- status = "error"- raise- finally:- record_request("query_code_db", time.perf_counter() - start_time, status)-- @mcp.tool()- def query_code_vectors(- query: str,- limit: int = 10,- where: Optional[str] = None,- select: Optional[list[str]] = None,- component: Optional[str] = None,- ) -> list[dict]:- """- Execute a vector similarity search against the code LanceDB (read-only).-- Schema:- - text TEXT -- The source code content- - vector VECTOR -- Embedding vector (all-MiniLM-L6-v2, 384 dimensions)- - component TEXT -- Component name (e.g., "agent", "computer")- - version TEXT -- Version string (e.g., "0.7.3")- - file_path TEXT -- Path to file within the component- - language TEXT -- Programming language-- Args:- query: Natural language query to embed and search for- limit: Maximum number of results (default: 10, max: 100)- where: Optional SQL-like filter (e.g., "version = '0.7.3'")- select: Optional list of columns to return (default: all except vector)- component: Optional component to filter by (if not specified, searches all)-- Returns:- List of matching code files with similarity scores (_distance field)- """- start_time = time.perf_counter()- status = "success"- try:- limit = min(max(1, limit), 100)- table = get_code_lance_table()-- search = table.search(query).limit(limit)-- # Build where clause, adding component filter if specified- where_clauses = []- if component:- where_clauses.append(f"component = '{component}'")- if where:- where_clauses.append(where)-- if where_clauses:- search = search.where(" AND ".join(where_clauses))- if select:- search = search.select(select)-- results = search.to_list()-- formatted = []- for r in results:- result = {}- for key, value in r.items():- if key == "vector":- continue- result[key] = value- formatted.append(result)-- return formatted- except Exception as e:- status = "error"- raise- finally:- record_request("query_code_vectors", time.perf_counter() - start_time, status)-- # Create SSE app directly - endpoints at /sse (GET) and /messages (POST)- from starlette.middleware import Middleware-- mcp_app = mcp.http_app(- transport="sse",- middleware=[- Middleware(- CORSMiddleware,- allow_origins=["*"],- allow_credentials=True,- allow_methods=["*"],- allow_headers=["*"],- )- ],- )-- return mcp_app--# =============================================================================# Local testing functions# =============================================================================