feat: MCP server + HF Docker Space config for AgentSpot

mcp_server.py exposes the demo-build pipeline as MCP tools (ping,
build_demo_from_brief). Thin adapter over the existing controller;
streamable-HTTP with a pure-ASGI bearer gate + unauthenticated health
route. Dockerfile/README target an HF Docker Space (deploy branch only).

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

Dockerfile

@@ -1,39 +1,29 @@
-# ThoughtSpot Demo Builder - Docker Deployment
-# Use this for Railway.app, Render.com, or self-hosted deployment
-
-FROM python:3.10-slim
-
-# Set working directory
+# Dockerfile — DemoPrep MCP Space (Hugging Face Docker Space)
+#
+# Runs the MCP server (mcp_server.py) over streamable-HTTP on port 7860.
+# This is a SEPARATE Space from the Gradio app: same codebase, different
+# entrypoint. Business logic stays in one place (demoprep_app/) — this Space
+# just runs the MCP adapter instead of the Gradio UI.
+#
+# Required secrets: set in Space Settings -> Repository Secrets (see the
+# mcp_server.py module docstring for the full list).
+FROM python:3.11-slim
+
+RUN useradd -m -u 1000 user
 WORKDIR /app
 
-# Install system dependencies
-RUN apt-get update && apt-get install -y \
-    git \
-    curl \
-    && rm -rf /var/lib/apt/lists/*
-
-# Copy requirements first for better caching
-COPY requirements.txt .
+RUN apt-get update && apt-get install -y git curl && rm -rf /var/lib/apt/lists/*
 
-# Install Python dependencies
+COPY --chown=user requirements.txt .
 RUN pip install --no-cache-dir -r requirements.txt
 
-# Copy application code
-COPY . .
+COPY --chown=user . .
 
-# Create necessary directories
-RUN mkdir -p results demo_logs
+USER user
+ENV MCP_TRANSPORT=http \
+    MCP_HTTP_PORT=7860 \
+    HOME=/home/user
 
-# Set environment variables for Gradio
-ENV GRADIO_SERVER_NAME="0.0.0.0"
-ENV GRADIO_SERVER_PORT="7860"
-
-# Expose the Gradio port
 EXPOSE 7860
 
-# Health check
-HEALTHCHECK --interval=30s --timeout=10s --start-period=5s --retries=3 \
-    CMD curl -f http://localhost:7860/ || exit 1
-
-# Run the application
-CMD ["python", "app.py"]
+CMD ["python", "mcp_server.py"]

README.md

@@ -1,170 +1,41 @@
 ---
-title: ThoughtSpot Demo Builder
-emoji: 🚀
+title: DemoPrep MCP
+emoji: 🔌
 colorFrom: blue
-colorTo: purple
-sdk: gradio
-sdk_version: "4.44.1"
-app_file: app.py
+colorTo: green
+sdk: docker
+app_port: 7860
 pinned: false
 license: mit
-python_version: "3.11"
 ---
 
-# Demo Wire - AI-Powered Demo Builder
+# DemoPrep MCP Server
 
-A powerful Gradio-based application that automatically generates and deploys complete demo environments for ThoughtSpot, including Snowflake schemas, data population, and semantic model creation.
+An MCP (Model Context Protocol) server that exposes DemoPrep's demo-build pipeline
+as tools an external agent (ThoughtSpot **AgentSpot**) can call — building a full
+demo (Snowflake schema → ThoughtSpot model → liveboard) from a prospect **brief**,
+with no human clicking through the Gradio UI.
 
-> **Deployed on Hugging Face Spaces**: This app can be deployed to HF Spaces for easy access. See [DEPLOYMENT.md](DEPLOYMENT.md) for setup instructions.
+- **Transport:** streamable-HTTP at `/mcp`, gated by `Authorization: Bearer <MCP_ACCESS_TOKEN>`.
+- **Health:** unauthenticated `GET /` returns `{"status":"ok"}`.
+- **Tools:** `ping` (connectivity check) and `build_demo_from_brief` (full build).
 
-## 🚀 Features
+This Space shares the DemoPrep codebase with the app Space but runs the MCP
+entrypoint (`mcp_server.py`) instead of the Gradio app — the business logic lives
+in one place (`demoprep_app/` + the controller). Builds run for minutes, so the
+tool is meant to be driven job-style (fire, then check back).
 
-- **AI-Powered Research**: Automatically researches companies and industries using LLM
-- **Schema Generation**: Creates optimized Snowflake DDL based on business context
-- **Data Population**: Generates realistic demo data with strategic outliers
-- **ThoughtSpot Integration**: Deploys connections, tables, and semantic models
-- **Interactive UI**: Clean, intuitive Gradio interface with real-time progress updates
+## Required secrets
 
-## 🛠️ Tech Stack
+Set these in **Settings → Repository Secrets** (nothing sensitive is committed):
 
-- **Frontend**: Gradio (Python web UI)
-- **Backend**: Python 3.12+
-- **Database**: Snowflake
-- **Analytics**: ThoughtSpot
-- **AI**: OpenAI GPT models
-- **Data Generation**: Faker library
+| Secret | Purpose |
+|--------|---------|
+| `SUPABASE_URL`, `SUPABASE_ANON_KEY` | bootstrap → pulls Snowflake + LLM keys from admin settings |
+| `OPENAI_API_KEY` | LLM key (env-only) |
+| `TS_ENV_1_LABEL`, `TS_ENV_1_URL`, `TS_ENV_1_KEY_VAR` | the target ThoughtSpot environment |
+| `MCP_OWNER_EMAIL` | TS user that owns created objects (trusted-auth) |
+| `MCP_TS_ENV_LABEL` | which TS env label to deploy into |
+| `MCP_ACCESS_TOKEN` | shared bearer secret the calling agent presents |
 
-## 📋 Prerequisites
-
-- Python 3.12+
-- Snowflake account with appropriate permissions
-- ThoughtSpot Cloud account
-- OpenAI API key
-
-## 🚀 Quick Start
-
-1. **Clone the repository**
-   ```bash
-   git clone https://github.com/yourusername/demo-wire.git
-   cd demo-wire
-   ```
-
-2. **Set up virtual environment**
-   ```bash
-   python -m venv demo_wire
-   source demo_wire/bin/activate  # On Windows: demo_wire\Scripts\activate
-   ```
-
-3. **Install dependencies**
-   ```bash
-   pip install -r requirements.txt
-   ```
-
-4. **Configure environment variables**
-   ```bash
-   cp .env.example .env
-   # Edit .env with your credentials
-   ```
-
-5. **Run the application**
-   ```bash
-   python demo_prep.py
-   ```
-
-6. **Open your browser**
-   Navigate to `http://localhost:7860`
-
-## ⚙️ Configuration
-
-Create a `.env` file with the following variables:
-
-```env
-# OpenAI
-OPENAI_API_KEY=your_openai_api_key
-
-# Snowflake
-SNOWFLAKE_USER=your_username
-SNOWFLAKE_PASSWORD=your_password
-SNOWFLAKE_ACCOUNT=your_account
-SNOWFLAKE_WAREHOUSE=your_warehouse
-SNOWFLAKE_DATABASE=your_database
-SNOWFLAKE_SCHEMA=your_schema
-
-# ThoughtSpot
-THOUGHTSPOT_URL=your_thoughtspot_url
-THOUGHTSPOT_USERNAME=your_username
-THOUGHTSPOT_PASSWORD=your_password
-
-# Slack deployment notifications (optional, outbound-only)
-SLACK_BOT_TOKEN=xoxb-your_bot_token
-SLACK_DEPLOYMENT_CHANNEL_ID=C0123456789
-```
-
-Slack notifications use the Slack Web API to post deployment status messages from
-DemoPrep into one approved channel. This path is outbound-only: no Socket Mode,
-event subscriptions, slash commands, or public Slack request URL are required.
-The Slack app only needs the `chat:write` bot scope, and the bot must be invited
-to the target channel.
-
-## 🎯 Usage
-
-1. **Enter Company Information**: Company name, URL, and industry
-2. **Start Research**: AI analyzes the company and industry
-3. **Create DDL**: Generate optimized Snowflake schema
-4. **Generate Data**: Create realistic demo data with outliers
-5. **Deploy**: Deploy to Snowflake and ThoughtSpot
-
-## 📁 Project Structure
-
-```
-demo-wire/
-├── demo_prep.py              # Main Gradio application
-├── schema_utils.py           # Schema parsing and generation utilities
-├── thoughtspot_deployer.py   # ThoughtSpot deployment logic
-├── snowflake_auth.py         # Snowflake authentication
-├── demo_personas.py          # Demo persona configurations
-├── prompts.py                # LLM prompt templates
-├── requirements.txt          # Python dependencies
-├── docs/                     # Documentation
-├── tests/                    # Test files
-└── results/                  # Generated demo results
-```
-
-## 🧪 Testing
-
-Run the test suite:
-
-```bash
-python -m pytest tests/
-```
-
-## 🤝 Contributing
-
-1. Fork the repository
-2. Create a feature branch (`git checkout -b feature/amazing-feature`)
-3. Commit your changes (`git commit -m 'Add amazing feature'`)
-4. Push to the branch (`git push origin feature/amazing-feature`)
-5. Open a Pull Request
-
-## 📄 License
-
-This project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.
-
-## 🙏 Acknowledgments
-
-- ThoughtSpot for the analytics platform
-- Snowflake for the data warehouse
-- OpenAI for the AI capabilities
-- Gradio for the web interface
-
-## 📚 Development Notes
-
-Development notes and sprint planning are stored in `dev_notes/` (not committed to version control).
-
-## 📞 Support
-
-For support, email support@demo-wire.com or create an issue in this repository.
-
----
-
-**Built with ❤️ for the ThoughtSpot community**
+`MCP_TRANSPORT=http` and `MCP_HTTP_PORT=7860` are baked into the Dockerfile.

mcp_server.py

@@ -0,0 +1,318 @@
+"""
+mcp_server.py — Demo Wire MCP server (v1)
+
+Exposes DemoPrep's demo-build pipeline as an MCP tool so an external agent
+(AgentSpot / Spotter Assistant) can build a full ThoughtSpot demo from a prospect
+*brief* without a human clicking through the Gradio UI.
+
+This is a THIN ADAPTER. It does not reimplement any business logic — it drives the
+exact same `ChatDemoInterface` controller the Gradio app uses, headlessly, skipping
+the research phase by injecting the brief as the research output. All build logic
+stays in one place (see docs/SINGLE_PIPELINE.md and CLAUDE.md).
+
+v1 scope (simplest thing that works):
+  * ONE blocking tool — build_demo_from_brief(...) runs the whole pipeline
+    (blueprint -> dataset -> DDL -> Snowflake -> TS model -> liveboard) and returns
+    the resulting IDs when done.
+  * Everything is fixed/server-side; per-call config (env, model, sharing) is a
+    later version.
+  * Builds run for minutes. If the caller's connection times out, the build still
+    finishes server-side and DemoPrep's Slack notification delivers the liveboard
+    URL. (Async / job-backed delivery is the planned next step.)
+
+Server-side config (env vars — fail loud if a required one is missing):
+  MCP_OWNER_EMAIL    (required)  TS user that owns created objects (trusted-auth)
+  MCP_TS_ENV_LABEL   (required)  which TS_ENV_<n>_LABEL from .env to deploy into
+  MCP_TRANSPORT      "stdio" (default, local dev) | "http" (HF Space)
+  MCP_HTTP_PORT      http port (default 7860)
+  MCP_ACCESS_TOKEN   (required in http mode)  shared bearer secret gating the endpoint
+
+Local smoke test (needs the project venv with requirements installed):
+    MCP_OWNER_EMAIL=you@thoughtspot.com MCP_TS_ENV_LABEL=SE python mcp_server.py
+Then point an MCP client (e.g. `mcp dev mcp_server.py` / MCP Inspector) at stdio.
+"""
+
+from __future__ import annotations
+
+import os
+import sys
+import time
+import types
+import uuid
+import threading
+
+# --- env bootstrap: order matters --------------------------------------------
+# .env first so MCP_* / TS_ENV_* / Supabase creds are available.
+from dotenv import load_dotenv
+load_dotenv()
+
+# Fixed owner identity for v1 (per-user "everyone as themselves" is a later
+# version). No silent fallback — user identity is required (see CLAUDE.md).
+_OWNER_EMAIL = (os.getenv("MCP_OWNER_EMAIL") or "").strip()
+if not _OWNER_EMAIL:
+    raise RuntimeError(
+        "MCP_OWNER_EMAIL is required — the ThoughtSpot user that owns created objects."
+    )
+# The controller resolves the acting user from these when there's no login cookie.
+os.environ.setdefault("DEMOPREP_NO_AUTH", "true")
+os.environ.setdefault("DEMOPREP_DEV_USER_EMAIL", _OWNER_EMAIL)
+
+_TS_ENV_LABEL = (os.getenv("MCP_TS_ENV_LABEL") or "").strip()
+if not _TS_ENV_LABEL:
+    raise RuntimeError(
+        "MCP_TS_ENV_LABEL is required — which TS_ENV_<n>_LABEL from .env to deploy into."
+    )
+
+# Snowflake creds + SNOWFLAKE_DATABASE from Supabase admin settings -> os.environ.
+# Must run once at startup; the deploy path reads these via get_admin_setting/env.
+from supabase_client import inject_admin_settings_to_env
+inject_admin_settings_to_env()
+
+# Heavy imports (pull gradio etc.) — safe headless. DEMOPREP_NO_AUTH is set above,
+# which must happen BEFORE importing chat_interface.
+from chat_interface import ChatDemoInterface, get_ts_env_url, get_ts_env_auth_key
+from demo_builder_class import DemoBuilder
+from demo_personas import parse_use_case, get_use_case_config
+from llm_config import DEFAULT_LLM_MODEL
+
+# Resolve the fixed ThoughtSpot environment once (light — reads .env only).
+_TS_URL = get_ts_env_url(_TS_ENV_LABEL)
+_TS_AUTH_KEY = get_ts_env_auth_key(_TS_ENV_LABEL)
+if not _TS_URL or not _TS_AUTH_KEY:
+    raise RuntimeError(
+        f"ThoughtSpot environment '{_TS_ENV_LABEL}' not found or incomplete in .env "
+        f"(need TS_ENV_<n>_LABEL={_TS_ENV_LABEL} with matching _URL and _KEY_VAR)."
+    )
+
+from mcp.server.fastmcp import FastMCP
+
+# Serialize-first: one build at a time. Protects the process-global os.environ
+# writes (Snowflake account) that inject_admin_settings_to_env performs, and
+# matches the decision to lift real concurrency later.
+_build_lock = threading.Lock()
+
+mcp = FastMCP("demoprep")
+
+
+@mcp.tool()
+def ping() -> dict:
+    """Health / connectivity check — returns server identity + config, no side effects.
+
+    Use this to confirm a client (e.g. AgentSpot) can reach and invoke the server
+    without triggering a full build.
+    """
+    return {
+        "ok": True,
+        "server": "demoprep-mcp v1",
+        "ts_environment": _TS_ENV_LABEL,
+        "ts_url": _TS_URL,
+        "owner_email": _OWNER_EMAIL,
+        "tools": ["ping", "build_demo_from_brief"],
+    }
+
+
+def _run_build(brief: str, company_name: str, use_case: str, company_url: str) -> dict:
+    """Drive the controller headlessly. Mirrors tests/newvision_sample_runner.py but
+    injects `brief` in place of the research phase. Returns a structured dict and
+    never raises to the caller — failures come back as status 'failed' / 'partial'."""
+    run_id = uuid.uuid4().hex[:12]
+    started = time.time()
+
+    def result(status: str, dc: dict | None = None, schema: str | None = None,
+               error: str | None = None) -> dict:
+        dc = dc or {}
+        return {
+            "run_id": run_id,
+            "status": status,                       # success | partial | failed
+            "schema": dc.get("schema") or schema or "",
+            "model_guid": dc.get("model_guid", ""),
+            "liveboard_guid": dc.get("liveboard_guid", ""),
+            "model_url": dc.get("model_url", ""),
+            "liveboard_url": dc.get("liveboard_url", ""),
+            "ts_environment": _TS_ENV_LABEL,
+            "owner_email": _OWNER_EMAIL,
+            "warnings": dc.get("warnings", []),
+            "errors": ([error] if error else dc.get("errors", [])),
+            "elapsed_seconds": round(time.time() - started, 1),
+        }
+
+    controller = None
+    try:
+        # (i) controller
+        controller = ChatDemoInterface(user_email=_OWNER_EMAIL)
+
+        # (ii) settings: model + fixed TS env (exact key names per the wiring trace)
+        controller.settings["model"] = controller.settings.get("model") or DEFAULT_LLM_MODEL
+        controller.settings["thoughtspot_url"] = _TS_URL
+        controller.settings["thoughtspot_trusted_auth_key"] = _TS_AUTH_KEY
+
+        # vertical / function / use_case_config exactly as the runner does
+        controller.vertical, controller.function = parse_use_case(use_case or "")
+        controller.use_case_config = get_use_case_config(
+            controller.vertical or "Generic", controller.function or "Generic"
+        )
+
+        # (iii) demo_builder with the BRIEF injected in place of research.
+        db = DemoBuilder(use_case=use_case, company_url=company_url)
+        db.company_analysis_results = brief          # component field
+        db.combined_research_results = brief         # <-- the field build_demo actually reads
+        db.company_summary = brief                   # <-- liveboard Spotter story reads this (Gotcha 2)
+        # Force the exact display name — extract_company_name() otherwise parses the
+        # domain from company_url. Minimal shim standing in for a scraped website.
+        db.website_data = types.SimpleNamespace(
+            title=company_name, url=company_url, text="", css_links=[], logo_candidates=[]
+        )
+        controller.demo_builder = db
+        controller.generic_use_case_context = ""
+
+        # (iv) DDL — returns a (response, ddl) tuple; NOT a generator.
+        resp, ddl_text = controller.run_ddl_creation()
+        if not ddl_text or "CREATE TABLE" not in ddl_text.upper():
+            return result("failed", error=f"DDL generation failed: {str(resp)[:500]}")
+
+        # (v) Snowflake load, then ThoughtSpot. Both are generators — draining them
+        # IS what runs the work. Decoupled from validation_mode: drain the Snowflake
+        # generator, read the schema it set, then run the TS deploy ourselves.
+        for _ in controller.run_deployment_streaming():
+            pass
+        schema = getattr(controller, "_deployed_schema_name", None)
+        if not schema:
+            return result(
+                "failed",
+                schema=getattr(controller, "_last_schema_name", None),
+                error="Snowflake load did not complete (no deployed schema).",
+            )
+
+        for _ in controller._run_thoughtspot_deployment(schema, company_name, use_case):
+            pass
+
+        # (vi) structured result from the completion record.
+        dc = getattr(controller, "deployment_completion", None)
+        if not dc:
+            # deploy_all raised before the completion record was written — surface
+            # partial success: the Snowflake schema exists even if TS didn't finish.
+            return result(
+                "partial", schema=schema,
+                error="ThoughtSpot deploy did not complete; Snowflake schema exists.",
+            )
+        return result("success" if dc.get("success") else "partial", dc=dc, schema=schema)
+
+    except Exception as e:  # never leak a raw exception to the MCP caller
+        schema = getattr(controller, "_deployed_schema_name", None) if controller else None
+        return result(
+            "partial" if schema else "failed",
+            schema=schema,
+            error=f"{type(e).__name__}: {e}",
+        )
+
+
+@mcp.tool()
+def build_demo_from_brief(
+    brief: str,
+    company_name: str,
+    use_case: str,
+    company_url: str = "",
+) -> dict:
+    """Build a complete ThoughtSpot demo from a prospect brief.
+
+    Skips DemoPrep's own research: the `brief` IS the research context. Runs the
+    full pipeline (dataset -> DDL -> Snowflake -> model -> liveboard) and returns
+    the resulting IDs. BLOCKS until the build finishes (several minutes); if your
+    connection times out, the build still completes server-side.
+
+    Args:
+        brief: Prospect narrative — pain points, what they're evaluating, industry
+               context, goals. Becomes the research context the demo is built from.
+        company_name: Display name for the demo (e.g. "Acme Corporation").
+        use_case: The analytics story / use case (e.g. "Retail Sales").
+        company_url: Optional company URL (used for context/branding; not scraped).
+
+    Returns:
+        dict: status (success|partial|failed|busy), schema, model_guid,
+        liveboard_guid, model_url, liveboard_url, ts_environment, owner_email,
+        warnings, errors, run_id, elapsed_seconds.
+    """
+    if not brief or not brief.strip():
+        return {"status": "failed", "errors": ["brief is required"]}
+    if not (company_name or "").strip() or not (use_case or "").strip():
+        return {"status": "failed", "errors": ["company_name and use_case are required"]}
+
+    # Serialize-first: reject overlapping builds rather than corrupting shared env.
+    if not _build_lock.acquire(blocking=False):
+        return {
+            "status": "busy",
+            "errors": ["A build is already running (v1 runs one at a time). Retry shortly."],
+        }
+    try:
+        return _run_build(
+            brief.strip(), company_name.strip(), use_case.strip(), (company_url or "").strip()
+        )
+    finally:
+        _build_lock.release()
+
+
+def _run_http(token: str) -> None:
+    """Serve over streamable HTTP behind a shared-bearer gate.
+
+    The auth check is a PURE-ASGI wrapper, NOT Starlette's BaseHTTPMiddleware —
+    the latter buffers responses and breaks the streamable-HTTP SSE stream. This
+    checks the bearer on every HTTP request and otherwise passes the raw ASGI
+    through untouched.
+    """
+    import uvicorn
+
+    inner = mcp.streamable_http_app()  # verified accessor on mcp 1.28.1
+
+    class _BearerGate:
+        def __init__(self, app):
+            self.app = app
+
+        async def __call__(self, scope, receive, send):
+            if scope.get("type") == "http":
+                path = scope.get("path", "")
+                if path in ("/", "/health"):
+                    # Unauthenticated liveness check so the HF Space reports healthy.
+                    # The MCP protocol itself lives at /mcp behind the bearer gate.
+                    await send({
+                        "type": "http.response.start",
+                        "status": 200,
+                        "headers": [(b"content-type", b"application/json")],
+                    })
+                    await send({"type": "http.response.body",
+                                "body": b'{"status":"ok","service":"demoprep-mcp"}'})
+                    return
+                headers = dict(scope.get("headers") or [])
+                if headers.get(b"authorization", b"").decode() != f"Bearer {token}":
+                    await send({
+                        "type": "http.response.start",
+                        "status": 401,
+                        "headers": [(b"content-type", b"application/json")],
+                    })
+                    await send({"type": "http.response.body", "body": b'{"error":"unauthorized"}'})
+                    return
+            await self.app(scope, receive, send)
+
+    uvicorn.run(_BearerGate(inner), host="0.0.0.0", port=int(os.getenv("MCP_HTTP_PORT", "7860")))
+
+
+def main() -> None:
+    transport = (os.getenv("MCP_TRANSPORT") or "stdio").strip().lower()
+    print(
+        f"[mcp_server] ready — ts_env='{_TS_ENV_LABEL}' url={_TS_URL} "
+        f"owner={_OWNER_EMAIL} transport={transport}",
+        file=sys.stderr, flush=True,
+    )
+
+    if transport in ("stdio", ""):
+        mcp.run(transport="stdio")
+    elif transport in ("http", "streamable-http", "streamable_http"):
+        token = (os.getenv("MCP_ACCESS_TOKEN") or "").strip()
+        if not token:  # public endpoint must be gated
+            raise RuntimeError("MCP_ACCESS_TOKEN is required in http mode (public endpoint).")
+        _run_http(token)
+    else:
+        raise RuntimeError(f"Unknown MCP_TRANSPORT: {transport!r} (use 'stdio' or 'http').")
+
+
+if __name__ == "__main__":
+    main()