Cirrus Solar MCP Deployment Package

Portable deployment package for the Cirrus Solar Salesforce hosted MCP demo agent. The agent is built with Google ADK, serves through FastAPI, deploys to Cloud Run, reads demo operational data from BigQuery, invokes Salesforce hosted MCP prompt-template retrieval for diagnostics, and can create Salesforce WorkOrder records when a replacement workflow is needed.

This repository is sanitized for reuse in another Salesforce org and Google Cloud project. It intentionally contains no org-specific credentials, tokens, keys, project IDs, Salesforce org aliases, generated Salesforce record IDs, or local virtual environment files.

What Is Included

• app/: ADK agent, FastAPI app, Salesforce MCP client, OAuth helper logic, BigQuery tools, telemetry setup, and local mock/offline data.
• deployment/terraform/single-project/: optional single-project GCP infrastructure for Cloud Run service identity, APIs, telemetry storage, and BigQuery analytics resources.
• salesforce-dx/: Salesforce DX metadata and Knowledge article seed content for target org setup.
• scripts/: setup and smoke-test helpers for Salesforce hosted MCP, PKCE OAuth, BigQuery demo data, and deployed trigger testing.
• tests/: unit and integration tests plus ADK evaluation scaffolding.
• Dockerfile, pyproject.toml, uv.lock, and agents-cli-manifest.yaml: deploy/runtime metadata.

What Is Intentionally Excluded

• .env, .venv, caches, .terraform, local ADK state, and local CLI state.
• Salesforce generated record ID maps such as knowledge_draft_ids.csv.
• Generated Knowledge import/update CSVs containing target-org record IDs.
• Any refresh tokens, bearer tokens, client secrets, service account keys, or concrete environment-specific values.

Prerequisites

• Python 3.11 through 3.13.
• uv: https://docs.astral.sh/uv/getting-started/installation/
• Google Agents CLI:

uv tool install google-agents-cli
uvx google-agents-cli setup

• Google Cloud SDK authenticated to the target project.
• Salesforce CLI authenticated to the target Salesforce org.
• Terraform, only if you plan to provision the optional infrastructure under deployment/terraform/single-project.

Local Setup

Install dependencies:

agents-cli install

Create a local environment file from the template:

cp .env.example .env

Run the deterministic offline smoke test:

DEMO_OFFLINE_MODE=true agents-cli run "Triage signal SIG-FATAL-MINV-0001"

Start the local playground:

agents-cli playground

Run tests:

uv run pytest tests/unit tests/integration

Environment Variables

Use .env.example as the authoritative list of runtime configuration values. Do not commit .env or any file that contains real tokens or secrets.

For deployed environments, prefer Google Secret Manager for sensitive values:

• SALESFORCE_OAUTH_REFRESH_TOKEN
• SALESFORCE_OAUTH_CLIENT_SECRET, only if your Salesforce External Client App requires one.
• SALESFORCE_MCP_BEARER_TOKEN, only if you use bearer-token mode.

Non-sensitive deployment variables can be passed with agents-cli deploy --update-env-vars or configured in your deployment system.

Salesforce Target Org Setup

Hosted MCP Documentation Notes

Official Salesforce documentation:

• Salesforce Hosted MCP Servers overview
• Create an External Client App

Key points from the Hosted MCP docs that matter for this deployment:

• Hosted MCP Servers let MCP-compatible AI clients connect to Salesforce data, automation, Prompt Builder templates, SObject operations, Apex/Flow/custom tools, and product integrations through Salesforce governance and sharing.
• Hosted MCP is intended for per-user OAuth access, so actions should respect each authorized user's Salesforce permissions, field-level security, and sharing rules.
• Salesforce requires an External Client App for MCP clients. Connected Apps are not supported for hosted MCP access.
• External Client Apps can take up to 30 minutes to become operational after creation.
• Scratch org setup is different: Salesforce notes that External Client Apps cannot be created directly in scratch orgs through Setup UI. Create the app in a Dev Hub org, package it, and install it into the target scratch org.
• Required OAuth scopes for this project are mcp_api and refresh_token.
• Recommended External Client App security controls include limiting access to authorized users with a permission set, using client secrets only where they can be safely stored server-side, considering IP restrictions for stable server-side clients, enabling refresh-token rotation, shortening refresh-token validity, and enabling single logout when immediate revocation is required.

1. Authenticate to the target Salesforce org:

sf org login web --alias "<target-org-alias>"

2. Confirm Salesforce Knowledge is enabled in the target org.

3. Deploy the Knowledge metadata and seed articles:

cd salesforce-dx
SALESFORCE_ORG_ALIAS="<target-org-alias>" \
KNOWLEDGE_RECORD_TYPE_ID="<target-knowledge-record-type-id>" \
./scripts/deploy_and_import_knowledge.sh
cd ..

The KNOWLEDGE_RECORD_TYPE_ID value must come from the target org. The script builds salesforce-dx/data/knowledge_articles_kav_import.csv locally at deploy time so no source-controlled CSV carries a record type from another org.

4. Create a Salesforce External Client App for hosted MCP access. Follow SALESFORCE_MCP_AUTH.md.

5. Generate a refresh token with the local PKCE helper:

uv run python scripts/salesforce_oauth_pkce.py \
  --client-id "<external-client-app-consumer-key>" \
  --login-url "https://<target-my-domain>.my.salesforce.com"

6. Discover hosted MCP tool names:

SALESFORCE_OAUTH_CLIENT_ID="<external-client-app-consumer-key>" \
SALESFORCE_OAUTH_REFRESH_TOKEN="<refresh-token-from-pkce-flow>" \
SALESFORCE_LOGIN_URL="https://<target-my-domain>.my.salesforce.com" \
uv run python scripts/test_salesforce_mcp.py

Update these placeholders if the discovered names differ:

• SALESFORCE_PROMPT_TEMPLATE_NAME
• SALESFORCE_MCP_PROMPT_TOOL
• SALESFORCE_MCP_RECORD_TOOL
• SALESFORCE_WORK_ORDER_OBJECT

BigQuery Demo Data

Authenticate to Google Cloud:

gcloud auth login
gcloud auth application-default login
gcloud config set project "<target-gcp-project-id>"

Load the demo datasets:

GCP_PROJECT_ID="<target-gcp-project-id>" \
GCP_REGION="<target-region>" \
uv run python scripts/setup_bigquery_demo.py

By default the agent expects:

• BQ_PANEL_TELEMETRY_DATASET=panel_telemetry
• BQ_PARTS_MASTER_DATASET=parts_master

Override these variables if you load data into different datasets.

Optional Terraform Infrastructure

Review and edit the placeholder values in:

deployment/terraform/single-project/vars/env.tfvars

Then provision:

cd deployment/terraform/single-project
terraform init
terraform plan -var-file=vars/env.tfvars
terraform apply -var-file=vars/env.tfvars
cd ../../..

The Terraform creates an application service account and telemetry-related resources. Review IAM roles before applying in production.

Cloud Run Deployment

Deploy with agents-cli after Salesforce, BigQuery, and secrets are ready:

agents-cli deploy \
  --project "<target-gcp-project-id>" \
  --region "<target-region>" \
  --service-account "<app-service-account-email>" \
  --secrets "SALESFORCE_OAUTH_REFRESH_TOKEN=<secret-id>" \
  --update-env-vars "DEMO_OFFLINE_MODE=false,GCP_PROJECT_ID=<target-gcp-project-id>,GCP_REGION=<target-region>,SALESFORCE_LOGIN_URL=https://<target-my-domain>.my.salesforce.com,SALESFORCE_OAUTH_CLIENT_ID=<external-client-app-consumer-key>,SALESFORCE_MCP_AUTH_MODE=oauth,SALESFORCE_MCP_PROMPT_SERVER_URL=https://api.salesforce.com/platform/mcp/v1/custom/prompttemplates,SALESFORCE_MCP_RECORD_SERVER_URL=https://api.salesforce.com/platform/mcp/v1/platform/sobject-all,SALESFORCE_PROMPT_TEMPLATE_NAME=<target-prompt-template-name>,SALESFORCE_MCP_RECORD_TOOL=<target-record-tool-name>,SALESFORCE_WORK_ORDER_OBJECT=WorkOrder"

If your External Client App requires a client secret, store it in Secret Manager and add it to the --secrets argument:

--secrets "SALESFORCE_OAUTH_REFRESH_TOKEN=<refresh-token-secret-id>,SALESFORCE_OAUTH_CLIENT_SECRET=<client-secret-id>"

Post-Deployment Validation

Run a deployed trigger smoke test:

CLOUD_RUN_URL="<deployed-cloud-run-url>" \
uv run python scripts/run_demo_trigger.py

Ask the deployed agent to triage:

Triage signal SIG-FATAL-MINV-0001

Expected flow:

1. Read fault signal details.
2. Read panel details.
3. Invoke Salesforce hosted MCP prompt-template diagnosis.
4. Check BigQuery part inventory.
5. Plan a resolution action.
6. Create a Salesforce WorkOrder only when replacement is required.

GitHub Actions

.github/workflows/deploy-cloud-run.yml is a placeholder CI/CD workflow. It is safe to commit because it contains no credentials. Before enabling it:

• Configure Google Workload Identity Federation.
• Add repository variables such as GCP_PROJECT_ID, GCP_REGION, and GCP_SERVICE_ACCOUNT_EMAIL.
• Add Salesforce non-secret configuration as repository variables.
• Store sensitive Salesforce values in Google Secret Manager, not GitHub.

Security Notes

• Never commit .env, service account JSON files, OAuth refresh tokens, bearer tokens, generated access tokens, or Salesforce client secrets.
• Use target-org placeholders in docs and scripts until deployment time.
• Keep Salesforce record IDs out of source control; generate import/update CSVs per target org.
• Review Terraform IAM roles before use in regulated or production environments.

Useful Commands

agents-cli install
agents-cli run "Triage signal SIG-FATAL-MINV-0001"
agents-cli playground
uv run pytest tests/unit tests/integration
agents-cli deploy --help