Quickstart

Audience: Engineers setting up the Case Automation MCP Server for the first time.
Time to complete: ~10 minutes.
What you will accomplish: Install dependencies, start backing services, run the full test suite, and start both the MCP server and sidecar locally.

Python version requirement

The project requires Python 3.12+. Do not use bare python3 -m pytest — the system Python may be 3.11. Always run commands through uv.

Prerequisites

Tool	Version	Install
Python	3.12+	python.org (opens in a new tab)
`uv`	latest	`curl -LsSf https://astral.sh/uv/install.sh \| sh`
PostgreSQL	16	Docker or local
Redis	7	Docker or local

Step 1 — Clone and install

Terminal

git clone https://github.com/pt-act/Case_Automation_MCP.git\ncd Case_Automation_MCP\nuv sync --extra dev

Troubleshooting: If `uv` is not found, install it first: `curl -LsSf https://astral.sh/uv/install.sh | sh`

Expected result: uv resolves Python 3.12+, installs all project dependencies including dev extras, and creates a virtual environment at .venv/.

Step 2 — Environment variables

Terminal

cp .env.example .env

Edit .env and fill in at minimum:

# Required
CAM_DATABASE_URL=postgresql+asyncpg://cam:cam_test_pw@localhost:5432/cam_test
CAM_REDIS_URL=redis://localhost:6379/0
CAM_ENCRYPTION_KEK=AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA=   # base64 32-byte key
 
# Optional — defaults shown
CAM_SECRET_BACKEND=env
CAM_LOG_LEVEL=INFO
CAM_RESIDENCY_REGION=us-east-1
CAM_OTEL_EXPORTER_ENDPOINT=           # OpenTelemetry collector (optional)
CAM_FEATURE_FLAGS='{"intake":false,"status_update":false,"document_gen":false,"document_routing":false,"qc":false}'  # All feature flags in one JSON blob
CAM_EXTRACTION_ALLOW_EXTERNAL_INFERENCE=false

Never commit real keys

.env is already in .gitignore. The CI workflow uses a zero-filled test KEK. Production must use a real 256-bit key from your secret store.

Step 3 — Start backing services

If you have Docker:

Terminal

docker compose up -d postgres redis

Troubleshooting: If Docker is unavailable, install PostgreSQL 16 and Redis 7 locally and adjust the URLs in `.env`.

Expected result: docker ps shows postgres:16 and redis:7 containers running.

Step 4 — Database migrations

Terminal

uv run alembic upgrade head

Troubleshooting: `Can't locate revision` means the migration directory is out of sync. Run `uv run alembic current` to check.

Expected result: Alembic applies all migrations and reports head.

Step 5 — Run the test suite

Terminal

uv run pytest -q

Expected result: 424 passed, 1 skipped in ~3.5 seconds. The 1 skipped test is intentional (test_reminder_fires_exactly_once — no armed reminders in that edge scenario).

If you see AttributeError: 'PrintLogger', your conftest.py may be outdated. Pull the latest main branch.

Step 6 — Start the servers

MCP server (stdio mode for local agents)

Terminal

uv run python -m cam.mcp_server

Troubleshooting: If the module is not found, ensure you ran `uv sync --extra dev` from the project root.

Sidecar (webhooks + approval UI)

Terminal

uv run uvicorn cam.sidecar.main:app --port 8001 --reload

Expected result:

Sidecar health endpoint returns {"status":"ok"} at http://localhost:8001/health
Webhook ingestion endpoint is ready at POST /webhooks/{connector}
Approval endpoints are ready at GET /approvals/{token} and POST /approvals/{token}

Verification checklist

uv sync completes without errorsIn progress
PostgreSQL and Redis containers are runningIn progress
Alembic migrations reach headIn progress
424 tests pass (1 skipped)In progress
Sidecar health endpoint returns okIn progress

Common issues

Symptom	Cause	Fix
`RuntimeError: Intake services not configured`	`configure_services()` not called	Ensure you are running `cam.sidecar.main` which bootstraps all services
`KeyError: workflow 'intake' not registered`	`register_intake_workflow()` not called	Same — use the official entry point
`requires-python >=3.12` error	Wrong interpreter	Always use `uv run …`
Tests fail on `PrintLogger`	Outdated conftest	Pull latest main; `_reset_global_singletons` fixture handles this

What next?

Architecture — Understand the system layout and data flow
Capabilities — Explore every tool, service, and workflow
Client Intake Workflow — Run your first end-to-end workflow

Last updated: 2026-06-01