OSVauco/docs/PLATFORM_MAP.md

OSVx Platform Map

Project ID: 357036551735
Primary region: us-central1
Secondary region: europe-west1 (static site)
Owner: OSVauco / Vauco
Last updated: 2026-09-01

This document describes the Cloud Run–based platform that powers the OSVx MCP connector and related services. It is the canonical reference for designing CI/CD, security, and operational procedures.

1. Overview

The platform consists of:

• A production MCP backend for the OSVx Perplexity connector
• A staging/dev MCP service for pre-production testing
• An internal worker/API service used by the MCP backend
• A public static website (separate product)
• One legacy service marked for cleanup

All services run on Cloud Run with container images pinned by digest.

2. Services

2.1. MCP Backend (Production)

• Current name: opax-mcp
• Planned name: osvx-mcp-prod
• Region: us-central1
• URL: https://opax-mcp-357036551735.us-central1.run.app/
• Image: .../opax-mcp@sha256:8adbd3f7...
• Last deployed: 2026-09-01
• Environment: prod
• Role: Live OSVx MCP backend
• Health check: GET /health → 200 OK

  {"status":"ok","service":"opax-mcp","version":"3.5.0","ollama":"http://34.13.238.133:11434"}
  

• Auth: Bearer token via MCP_SECRET
• Traffic: 100% to current revision
• Notes:
  • Serves the OSVx connector in Perplexity.
  • Exposes MCP methods including daily_ops_report.
  • Version in code: 3.5.0 (matches /health).
• Dependencies:
  • Internal worker: osvauco-agent (via OSVAUCO_AGENT_URL)
  • Ollama endpoint (for model access)

2.2. MCP Backend (Staging / Dev)

• Current name: osvx-mcp-dev
• Planned name: osvx-mcp-staging
• Region: us-central1
• URL: https://osvx-mcp-dev-…run.app/
• Image: .../opax-mcp@sha256:7b6a5c4b...
• Last deployed: 2026-08-20
• Environment: dev / staging
• Role: Pre-production MCP service
• Health check: GET /health → 200 OK

  {"status":"ok","service":"opax-mcp","version":"3.4.0", ...}
  

• Auth: Bearer token (same mechanism as prod)
• Traffic: 100% to current revision
• Notes:
  • Runs an older version (3.4.0).
  • Intended for testing new MCP releases before promoting to prod.
• Dependencies:
  • Should ideally point to a staging instance of osvauco-agent (see §2.3).
  • Currently may share prod agent depending on env config.

2.3. Internal Worker / API

• Name: osvauco-agent
• Region: us-central1
• URL: Internal only (no public URL)
• Image: .../osvauco-agent@sha256:1a2b3c4d...
• Last deployed: 2026-08-28
• Environment: prod
• Role: Internal API / worker for MCP backend
• Auth: Internal-only; not publicly authenticated
• Traffic: Invoked by opax-mcp / osvx-mcp-* via OSVAUCO_AGENT_URL
• Notes:
  • Core dependency of the MCP backend.
  • Currently only a prod instance exists.
• Decisions needed:
  • Whether to create osvauco-agent-staging for full environment isolation.
  • Whether staging MCP should:
    1. Share prod agent (simpler, less isolated), or
    2. Use a dedicated staging agent (cleaner isolation, more moving parts).

2.4. Public Website

• Name: vauco-site
• Region: europe-west1
• URL: https://vauco-site-…run.app/
• Image: .../web-static@sha256:e3b0c442...
• Last deployed: 2026-03-15
• Environment: prod
• Role: Public marketing / product website
• Health check: GET / → 200 OK (HTML)
• Auth: Public
• Notes:
  • Separate product from the MCP platform.
  • Should have its own CI/CD pipeline.
  • No direct dependency on MCP services.

2.5. Legacy / Cleanup Candidate

• Name: opax-billing-test
• Region: us-central1
• URL: No active URL (0% traffic)
• Image: .../opax-billing@sha256:f1e2d3c4...
• Last deployed: 2025-11-05
• Environment: test
• Role: Experimental billing service (no longer used)
• Notes:
  • No traffic allocated.
  • Not updated in >9 months.
  • Label: env=test.
• Action: Marked for deletion after final confirmation.

3. Environments

Environment	MCP Service	Agent Service	Purpose
prod	opax-mcp	osvauco-agent	Live OSVx backend for Perplexity
staging	osvx-mcp-dev	(shared or dedicated)	Pre-production testing of MCP
test	(none active)	(none active)	Legacy/experimental (billing test)

Decisions:

1. Adopt naming:
   • osvx-mcp-prod (currently opax-mcp)
   • osvx-mcp-staging (currently osvx-mcp-dev)
2. Decide agent strategy for staging:
   • Option A (simple): staging MCP shares prod osvauco-agent.
   • Option B (isolated): create osvauco-agent-staging and wire staging MCP to it.

4. Dependencies

4.1. Service-to-service

• opax-mcp → osvauco-agent
  • Via environment variable OSVAUCO_AGENT_URL.
• osvx-mcp-dev → osvauco-agent (or future osvauco-agent-staging).

4.2. External dependencies

• Ollama endpoint
  • Used by MCP for model access.
  • Currently: http://34.13.238.133:11434 (from /health output).
• GCP services
  • Secret Manager (MCP_SECRET for Bearer token).
  • Cloud Build (for future CI/CD).
  • Artifact Registry (container images).

4.3. Missing dependencies (known issues)

• gcloud CLI in MCP container
  • trigger_build tool in opax-mcp/server.py calls gcloud via subprocess.
  • Dockerfile does not install google-cloud-sdk.
  • Result: any use of trigger_build on prod/staging will fail with “gcloud not found”.
  • Fix: Add google-cloud-sdk installation to the Dockerfile before enabling this tool.

5. Deployment Model

5.1. Image strategy

• All services use pinned image digests (@sha256:...).
• CI/CD must:
  1. Build images with a commit-SHA label, e.g. gcb-commit-sha=<COMMIT_SHA>.
  2. Deploy using the exact image digest produced by the build.

5.2. Environment promotion flow (target)

• For the MCP platform:
  1. On push to main / feature branch:
     • Build opax-mcp image with commit-SHA label.
     • Deploy to osvx-mcp-staging (osvx-mcp-dev).
  2. On manual approval or version tag:
     • Promote the same image to osvx-mcp-prod (opax-mcp).
• For the website:
  • Separate pipeline:
    • Build web-static image.
    • Deploy to vauco-site.
• For the agent:
  • Similar pattern if/when a staging agent is introduced.

5.3. Configuration gaps to address

• No commit-SHA in images
  • Images currently lack labels linking them to Git commits.
  • CI/CD should add gcb-commit-sha label during build.
• Inconsistent naming
  • Prod MCP: opax-mcp
  • Dev MCP: osvx-mcp-dev
  • Target: osvx-mcp-prod + osvx-mcp-staging.

6. Security & Access (high level)

• MCP services (opax-mcp, osvx-mcp-dev)
  • Require Bearer token (MCP_SECRET) for MCP calls.
  • Should restrict invocations to:
    • Perplexity’s connector infrastructure
    • Trusted service accounts (if calling from other GCP services).
• Agent (osvauco-agent)
  • Internal-only; no public ingress.
  • Should allow calls only from MCP service accounts.
• Website (vauco-site)
  • Public read access.
  • No privileged operations.

7. Operational Notes

• Health checks
  • MCP: GET /health on each MCP service.
  • Agent: define a simple /health if not already present.
  • Site: GET / as basic availability check.
• Logging
  • All services use Cloud Logging via Cloud Run.
  • Key logs to monitor:
    • MCP tool calls (tools/call), especially daily_ops_report and trigger_build.
    • Agent API errors.
• Incident focus
  • If OSVx connector misbehaves:
    1. Check opax-mcp logs and revision.
    2. Verify /health version matches expected deployment.
    3. Confirm MCP_SECRET and connector URL.

8. Action Items

1. Cleanup
   • Confirm opax-billing-test is unused.
   • Delete opax-billing-test service.
2. Naming alignment
   • Decide final names:
     • osvx-mcp-prod vs keeping opax-mcp.
     • osvx-mcp-staging vs keeping osvx-mcp-dev.
   • Optionally rename services in GCP to match.
3. Agent environment strategy
   • Decide: shared prod agent vs dedicated staging agent.
   • Document the decision here and implement if needed.
4. Image labeling
   • Update Cloud Build config / Dockerfile for opax-mcp to include gcb-commit-sha.
5. gcloud dependency
   • Add google-cloud-sdk to the MCP Dockerfile before enabling trigger_build.
6. CI/CD design
   • Use this document as the basis for:
     • Build pipelines per service.
     • Promotion rules (staging → prod).
     • Environment-specific configs.

9. Future Extensions (optional)

• Per-developer ephemeral environments (short-lived Cloud Run revisions).
• Separate osvx-mcp-sandbox for integration tests in CI.
• Centralized config service or Secret Manager–driven config for env-specific URLs.

This document is the source of truth for the OSVx platform architecture. Update it whenever services, environments, or deployment patterns change.

---

10. CI/CD Setup

This section describes the continuous integration and deployment architecture for the OSVx MCP platform.

10.1. Source of Truth

• Primary Git repository:
  Self-hosted Gitea: http://34.59.131.162:3000/chris/osvauco.git
• Primary branch for MCP:
  feat/osvx-mcp-full-catalog

All development and code review happens in Gitea. No other Git host is used as a primary source.

10.2. Mirror to Cloud Source Repositories

Cloud Build cannot directly trigger on Gitea pushes, so the repo is mirrored to Cloud Source Repositories (CSR) as a read-only CI/CD mirror.

• CSR project: 357036551735
• CSR repo name: osvauco
• CSR repo URL:
  https://source.developers.google.com/p/357036551735/r/osvauco

Mirror configuration (on the VM):

cd ~/OSVauco
git remote add csr https://source.developers.google.com/p/357036551735/r/osvauco
git push csr feat/osvx-mcp-full-catalog:feat/osvx-mcp-full-catalog

Mirroring is automated via either:

• A post-receive hook on the Gitea server that pushes feat/osvx-mcp-full-catalog to csr, or
• A cron job on the VM that periodically runs:

  git push --quiet csr feat/osvx-mcp-full-catalog:feat/osvx-mcp-full-catalog
  

CSR is read-only from the CI/CD perspective; it exists only to trigger Cloud Build.

10.3. Cloud Build Trigger (Staging)

A Cloud Build trigger watches the CSR repo and runs the MCP pipeline on every push to the CI branch.

• Trigger name: osvx-mcp-staging-trigger
• Trigger type: Cloud Source Repositories
• Project: 357036551735
• Region: us-central1
• Repo: projects/357036551735/repos/osvauco
• Branch pattern: ^feat/osvx-mcp-full-catalog$
• Build config: opax-mcp/cloudbuild.yaml
• Substitutions:
  • _REGION=us-central1
  • _REPOSITORY=osvx-images
  • _ENV=staging

Creation command (reference):

PROJECT=357036551735
REGION=us-central1
REPO=osvx-images
BRANCH=feat/osvx-mcp-full-catalog

gcloud builds triggers create cloud-source-repositories   --project="$PROJECT"   --name="osvx-mcp-staging-trigger"   --region="$REGION"   --repo="projects/$PROJECT/repos/osvauco"   --branch-pattern="^${BRANCH}$"   --build-config="opax-mcp/cloudbuild.yaml"   --substitutions=_REGION=${REGION},_REPOSITORY=${REPO},_ENV=staging   --included-files="opax-mcp/**"   --description="Deploy OSVx MCP to staging on push to ${BRANCH}"

Behavior:

• On every push to feat/osvx-mcp-full-catalog in Gitea (mirrored to CSR):
  • Cloud Build runs opax-mcp/cloudbuild.yaml with _ENV=staging.
  • The built image is deployed to osvx-mcp-staging.

10.4. Production Deployment (Manual Promotion)

Production deployments are intentionally manual to provide an explicit promotion gate.

Options:

1. Local script (recommended):

   cd ~/OSVauco
   ./deploy-mcp.sh prod
   

   This builds the current commit and deploys to osvx-mcp-prod.

2. One-off Cloud Build:

   PROJECT=357036551735
   REGION=us-central1
   REPO=osvx-images
   
   gcloud builds submit .       --project="$PROJECT"       --config=opax-mcp/cloudbuild.yaml       --substitutions=_REGION=${REGION},_REPOSITORY=${REPO},_ENV=prod
   

No automatic prod trigger is configured.

10.5. Artifact Registry

• Repo name: osvx-images
• Location: us-central1
• Format: Docker

Images are tagged with the short commit SHA:

• us-central1-docker.pkg.dev/357036551735/osvx-images/opax-mcp:<SHORT_SHA>

Each image includes labels:

• gcb-commit-sha=<SHORT_SHA>
• env=staging or env=prod

10.6. Operational Notes

• Build logs and history:
  GCP Console → Cloud Build → History
• Trigger configuration:
  GCP Console → Cloud Build → Triggers → osvx-mcp-staging-trigger
• To temporarily disable CI:
  Disable or delete osvx-mcp-staging-trigger in the Cloud Build console.
• To change the CI branch:
  Update the trigger’s branch pattern and the mirror configuration.