Skip to content
Conduit

mcp server

Cybernetics

Google Cloud Rapid Agent Hackathon

strawberr0/Cyberneticscommunitylistedunreviewed
Use tool

Set up

Runs on your computer. Pick your agent and operating system.

Before you start

  • uv (`curl -LsSf https://astral.sh/uv/install.sh | sh`)
~/Library/Application Support/Claude/claude_desktop_config.json
{
  "mcpServers": {
    "cybernetics": {
      "command": "uvx",
      "args": [
        "cybernetics"
      ]
    }
  }
}

same format Cursor, GitHub Copilot CLI, Junie, JetBrains AI Assistant, Augment (Auggie CLI), Factory Droid, Kiro, Devin CLI +12

Values in angle brackets are placeholders. Restart Claude Desktop after editing its config.Claude Desktop docs

README

synced Oct 22, 2026

Quick Start (Docker Compose)

# 1. Configure (optional — defaults to PORT=4001, GEMINI_API_KEY empty)
cp .env.example.compose .env

# 2. Build & run
docker compose up --build

# 3. Open
open http://localhost:4001

The composer container serves both the built React frontend and the Go /api/* backend on the port set by $COMPOSER_PORT (default 4001). All ports are env-overridable — no values are hardcoded in the image.

Local dev (no Docker)

# Backend (Go) — defaults to :4001, override with PORT=...
go run ./cmd/composer

# Frontend (Vite) — defaults to :4000, proxies /api -> BACKEND_URL (default http://localhost:4001)
cd frontend && npm install && npm run dev

Classification: OPEN SOURCE
Authors: plasmaraygun, GoryGrey, royhodge812, sebuh-infsol (strawberryfield)
Version: 0.1.1
Status: Production-Ready

1. Executive Summary

Cybernetics is a composable Model Context Protocol (MCP) meta-broker designed for Google Cloud enterprise environments. It aggregates 56 third-party MCP servers into a unified, authenticated, auditable control plane and exposes composable agent templates that execute multi-phase autonomous workflows on top of that plane.

The project ships two surfaces:

  1. Cybernetics MCP broker — a single stdio-based MCP peer (cybernetics-mcp) that aggregates 56 adapters into one tool namespace. Drop it into Claude, Cursor, Codex, Antigravity, Devin, or Vims and you get every tool the broker advertises.
  2. Composer service — the Go HTTP + React UI in this repo. Generates Python agent code via Gemini, serves the public catalog at /api/templates, and is the operational dashboard.

See the Quick Start above for the composer; section 3 for the broker.

Key Differentiators

  • Zero Trust by default — every request authenticated, no anonymous endpoints beyond health probes
  • Defense in depth — circuit breakers, input sanitization, sentinel middleware, structured logging
  • Multi-tenant ready — per-adapter isolation, API-key scoping, audit trails
  • Operational hardening — non-root containers, Cloud IAM binding, Secret Manager injection, VPC-SC compatible

2. Architecture

┌───────────────────────────────────────────────────────────────────┐
│                    Google Cloud (VPC-SC)                          │
│  ┌─────────────┐    ┌─────────────┐    ┌─────────────────┐        │
│  │ Cloud Run   │◄──►│  Cloud SQL  │◄──►│ Secret Manager  │        │
│  │ (Broker)    │    │  (Postgres) │    │                 │        │
│  └──────┬──────┘    └─────────────┘    └─────────────────┘        │
│         │                                                         │
│  ┌──────┴─────────────────────────────────────────────────────┐   │
│  │                  Cybernetics Broker                        │   │
│  │  ┌──────────┐  ┌──────────┐  ┌──────────┐  ┌────────┐      │   │
│  │  │ Auth MW  │  │ Registry │  │Circuits  │  │Health  │      │   │
│  │  │ (Bearer) │  │ (Adapters│  │(CBs)     │  │Probes  │      │   │
│  │  └──────────┘  └──────────┘  └──────────┘  └────────┘      │   │
│  │  ┌───────────────────────────────────────────────────────┐ │   │
│  │  │            Agent Template Engine                      │ │   │
│  │  │  Sentinel  │  DeployAgent │ FinanceAgent │ InfraAgent │ │   │
│  │  └───────────────────────────────────────────────────────┘ │   │
│  └────────────────────────────────────────────────────────────┘   │
│         │                                                         │
│  ┌──────┴─────────────────────────────────────────────────┐       │
│  │                  MCP Adapter Layer                     │       │
│  │  Dynatrace  Elastic  Postgres  GitLab  Arize  Fivetran │       │
│  │  GitHub     Stripe   AWS       Vercel  Supabase        │       │
│  │  Cloudflare Browser (Playwright CDP)                   │       │
│  └────────────────────────────────────────────────────────┘       │
└───────────────────────────────────────────────────────────────────┘
         │
    ┌────┴──────────────────────────────────────┐
    │            Google ADK / Vertex AI         │
    │   (Agent orchestration, LLM-as-a-Judge)   │
    └───────────────────────────────────────────┘

Data Flow

  1. Request → Cloud Run → APIKeyAuth middleware validates Bearer token
  2. Routing → FastAPI dispatches to /mcp/invoke, /mcp/tools, or /mcp/sse
  3. Sentinel Pipeline → Auditor.before() logs call, Guard.before() blocks sensitive keys
  4. Registry → auto_discover() scans cybernetics/adapters/ and registers all concrete MCPAdapter subclasses dynamically; executes tool via circuit breaker
  5. Adapter → Async HTTP/SQL client calls downstream MCP server
  6. Response → Auditor.after() logs result, circuit breaker state updated

3. Cybernetics MCP Server — Usage Guide

Cybernetics is a first-class MCP server that exposes its adapters and agent templates as tools over the Model Context Protocol. Any MCP client (Antigravity, Claude Code, Cursor, Devin, Vims etc.) can connect to it.

3.1 What Is the Cybernetics MCP Server?

The Cybernetics MCP server is a single stdio-based MCP peer that aggregates all configured adapters into one unified tool namespace. Instead of installing 20 separate MCP servers, you install one:

{
  "mcpServers": {
    "cybernetics": {
      "command": "python",
      "args": ["-m", "cybernetics.mcp"],
      "env": {
        "BROKER_API_KEY": "your-broker-key",
        "POSTGRES_DSN": "postgresql+asyncpg://user:pass@localhost/sentinel"
      }
    }
  }
}

Once connected, your MCP client sees all tools from all enabled adapters as a flat list:

ToolWhat it does
dynatrace_get_problemsFetch active problems from Dynatrace
github_create_issueCreate a GitHub issue
slack_post_messagePost to a Slack channel
browser_screenshotTake a browser screenshot via CDP
sentinel_runExecute the full Sentinel agent workflow
deploy_trigger_pipelineTrigger a GitLab CI/CD pipeline

3.2 How It Works

┌─────────────┐      stdio       ┌──────────────────────────────────────────┐
│ AntiGravity │ ◄──────────────► │  Cybernetics MCP Server                  │
│   Desktop   │   JSON-RPC 2.0   │  ┌─────────────┐   ┌──────────────────┐  │
└─────────────┘                  │  │  Registry   │   │  Dynatrace       │  │
                                 │  │  (loads     │──►│  GitHub          │  │
                                 │  │  adapters)  │   │  Slack           │  │
                                 │  └─────────────┘   │  Browser...      │  │
                                 │                    └──────────────────┘  │
                                 └──────────────────────────────────────────┘

You do not configure each adapter individually. Adapters are loaded from the Cybernetics broker's registry based on the environment variables already set on the host.

3.3 Required Environment (Preset by Ops)

These are connection settings that your platform team configures once:

VariablePurposeExample
POSTGRES_DSNDatabase connectionpostgresql+asyncpg://...
DYNATRACE_BASE_URLDynatrace tenant URLhttps://xyz.live.dynatrace.com
ELASTIC_CLOUD_IDElastic Cloud deployment IDmy-deployment:ZXUta2...
GITLAB_URLGitLab instancehttps://gitlab.com
ARIZE_ENDPOINTArize Phoenix URLhttps://app.phoenix.arize.com
DATADOG_SITEDatadog regiondatadoghq.com
BROWSER_CDP_HOSTBrowser CDP hostlocalhost
BROWSER_CDP_PORTBrowser CDP port9222

3.4 Secret Keys (Injected per User / Team)

Set only the keys for the adapters you actually use. Adapters with no key required (browser, chrome, firefox, brave, docker, postgres) are omitted; they rely on preset connection settings from § 3.3.

Core

VariableAdapterWhere to get it
BROKER_API_KEYCybernetics brokerSelf-generated shared secret — openssl rand -hex 32. Set the same value on the broker process and in every MCP client config.
GEMINI_API_KEYComposer (Gemini)https://aistudio.google.com/apikey

Observability & Incident

VariableAdapterWhere to get it
DYNATRACE_API_TOKENDynatraceSettings → Access tokens
DATADOG_API_KEY / DATADOG_APP_KEYDatadogOrg Settings → API Keys / Application Keys
ELASTIC_API_KEYElasticStack Management → API Keys
PAGERDUTY_API_KEYPagerDutyProfile → User Settings → API Access
ARIZE_API_KEYArizeSettings → API Keys

Source Control & CI/CD

VariableAdapterWhere to get it
GITHUB_TOKENGitHubSettings → Developer settings → PAT (fine-grained)
GITLAB_TOKENGitLabUser Settings → Access Tokens
VERCEL_TOKENVercelAccount Settings → Tokens

Cloud Infrastructure

VariableAdapterWhere to get it
AWS_ACCESS_KEY_ID / AWS_SECRET_ACCESS_KEYAWSIAM → Users → Security credentials
CLOUDFLARE_API_TOKENCloudflareMy Profile → API Tokens (Custom or "Edit zone")
GOOGLE_SERVICE_ACCOUNT_KEYAll google-* adapters (25 services)GCP → IAM → Service Accounts → Keys → Create (JSON)

Productivity & Workspace

VariableAdapterWhere to get it
SLACK_BOT_TOKENSlackapi.slack.com/apps → OAuth & Permissions (xoxb-…)
NOTION_TOKENNotionhttps://www.notion.so/my-integrations
CONFLUENCE_API_TOKENConfluenceid.atlassian.com → Security → API tokens
JIRA_API_TOKENJiraid.atlassian.com → Security → API tokens
ASANA_TOKENAsanaProfile Settings → Apps → Manage Developer Apps → PAT
LINEAR_API_KEYLinearSettings → API
AIRTABLE_API_KEYAirtableairtable.com/create/tokens

Data & Databases

VariableAdapterWhere to get it
MONGODB_URIMongoDBAtlas → Database Access → connection string
REDIS_URLRedisredis://:<pass>@host:port/db
SUPABASE_KEYSupabaseProject Settings → API → service_role key
SNOWFLAKE_ACCOUNT / SNOWFLAKE_USER / SNOWFLAKE_PASSWORDSnowflakeAccount admin
FIVETRAN_API_KEY / FIVETRAN_API_SECRETFivetranAccount → API Config

Commerce & Finance

VariableAdapterWhere to get it
STRIPE_API_KEYStripeDevelopers → API Keys (use restricted keys in prod)
SHOPIFY_ACCESS_TOKEN / SHOPIFY_SHOP_DOMAINShopifyAdmin → Apps → Develop apps → Access token
QUICKBOOKS_ACCESS_TOKEN / QUICKBOOKS_COMPANY_IDQuickBooksIntuit Developer → My Apps → OAuth 2.0 Playground

Automation

VariableAdapterWhere to get it
N8N_API_KEYn8nSettings → API → Create API key

No-key adapters (preset config from § 3.3 only): airtable connection, brave, browser, chrome, docker, firefox, postgres.

3.5 Example: Using Cybernetics from Antigravity

Google Antigravity inherits VS Code's MCP wiring under the mcp.servers key.

Step 1: Install the broker:

pip install cybernetics-mcp

Step 2: Add to Antigravity's settings.json (Command Palette → Preferences: Open User Settings (JSON)):

{
  "mcp.servers": {
    "cybernetics": {
      "command": "cybernetics-mcp",
      "args": [],
      "env": {
        "BROKER_API_KEY": "$(openssl rand -hex 32)",
        "GEMINI_API_KEY": "<aistudio-key>",
        "POSTGRES_DSN": "postgresql+asyncpg://user:pass@localhost/cybernetics",
        "DYNATRACE_BASE_URL": "https://xyz.live.dynatrace.com",
        "DYNATRACE_API_TOKEN": "dt0c01.xxx"
      }
    }
  }
}

Step 3: Ask the agent to use it:

"Check Dynatrace for active problems on the api service, then post a summary to Slack #incidents."

The Antigravity agent will:

  1. Call tools/list and see dynatrace_get_problems + slack_post_message.
  2. Call dynatrace_get_problems with { "service": "api" }.
  3. Call slack_post_message with the results.

3.6 Other clients

The broker speaks vanilla MCP — same JSON schema in Claude Desktop / Claude Code (mcpServers), Cursor (.cursor/mcp.json), Codex CLI (~/.codex/config.toml, TOML), Devin (dashboard), and Vims (vims_mcp_add_server). The Composer UI's MCP Control Plane page renders copy-pasteable boilerplate for each.

3.7 Protocol Details

Implements MCP protocol 2024-11-05 over stdio (JSON-RPC 2.0):

MethodPurpose
initializeHandshake + capability exchange
tools/listDiscover all tools from all adapters
tools/callInvoke any tool by adapter_tool name

Tool names are namespaced: dynatrace_get_problems, github_create_issue, browser_screenshot, etc.

4. Adapter Catalog (56 Adapters)

Non-Google Adapters

AdapterProtocolAuthCircuitTools (complete)
airtableRESTBearerairtableairtable_list_bases, airtable_get_base, airtable_create_record
arizeRESTBearerarizearize_run_judge (Gemini), arize_log_eval
asanaRESTBearerasanaasana_list_projects, asana_get_task, asana_create_task
awsboto3IAM / keysawsaws_s3_list_buckets, aws_s3_list_objects, aws_ec2_describe_instances, aws_lambda_list_functions, aws_lambda_invoke, aws_cloudwatch_get_metrics
bravePlaywrightN/Abravebrave_navigate, brave_evaluate, brave_screenshot, brave_click, brave_type, brave_set_viewport, brave_pdf, brave_check_shields
browserWebSocket CDPN/Abrowserbrowser_navigate, browser_evaluate, browser_screenshot, browser_get_network_log, browser_get_console_log, browser_clear_cache
chromeWebSocket CDPN/Achromechrome_navigate, chrome_evaluate, chrome_screenshot, chrome_get_network, chrome_get_console, chrome_clear_cache, chrome_set_viewport, chrome_click, chrome_type, chrome_pdf
cloudflareRESTBearercloudflarecloudflare_list_zones, cloudflare_list_dns, cloudflare_create_dns, cloudflare_list_workers, cloudflare_deploy_worker
confluenceRESTApi-Tokenconfluenceconfluence_search_pages, confluence_get_page, confluence_create_page
datadogRESTDD-API-Keydatadogdatadog_query_metrics, datadog_list_monitors, datadog_get_monitor, datadog_mute_monitor, datadog_list_incidents, datadog_search_logs, datadog_post_event
dockerREST / socketN/Adockerdocker_list_containers, docker_run, docker_build, docker_logs
dynatraceRESTApi-Tokendynatracedynatrace_get_problems, dynatrace_get_traces, dynatrace_run_dql
elasticRESTApiKeyelasticelastic_search_incidents, elastic_search_runbooks, elastic_write_insight
fivetranRESTBasicfivetranfivetran_list_connectors, fivetran_get_connector_status, fivetran_sync_connector, fivetran_create_log_pipeline
firefoxPlaywrightN/Afirefoxfirefox_navigate, firefox_evaluate, firefox_screenshot, firefox_get_console, firefox_click, firefox_type, firefox_set_viewport, firefox_pdf
githubRESTtokengithubgithub_create_issue, github_get_issue, github_create_pr, github_list_repos, github_trigger_workflow, github_search_code
gitlabRESTPRIVATE-TOKENgitlabgitlab_create_issue, gitlab_create_mr, gitlab_get_file, gitlab_trigger_pipeline
jiraRESTApi-Tokenjirajira_create_issue, jira_search_issues, jira_get_sprint, jira_transition_issue
linearGraphQLBearerlinearlinear_create_issue, linear_list_issues, linear_update_issue, linear_get_teams, linear_search_issues, linear_create_comment
mongodbTCPURImongodbmongodb_find, mongodb_insert, mongodb_aggregate, mongodb_index
n8nRESTApi-Keyn8nn8n_list_workflows, n8n_trigger, n8n_get_execution
notionRESTBearernotionnotion_search, notion_get_page, notion_create_page, notion_query_database, notion_update_page, notion_get_database
pagerdutyRESTTokenpagerdutypagerduty_list_incidents, pagerduty_acknowledge, pagerduty_get_oncall
postgresTCPDSNpostgrespostgres_recall_pattern, postgres_store_pattern, postgres_log_incident, postgres_get_recent_incidents
quickbooksRESTOAuthquickbooksqb_list_customers, qb_get_customer, qb_create_invoice, qb_list_invoices, qb_get_report
redisTCPURIredisredis_get, redis_set, redis_publish, redis_stream_read
shopifyRESTAccess-Tokenshopifyshopify_list_products, shopify_get_order, shopify_create_draft, shopify_update_inventory
slackRESTBearerslackslack_post_message, slack_get_channel_history, slack_list_channels, slack_search_messages, slack_upload_file, slack_get_user_info
snowflakeJDBC/RESTKey-pairsnowflakesnowflake_query, snowflake_list_warehouses, snowflake_share
stripeRESTBearerstripestripe_create_customer, stripe_get_customer, stripe_create_charge, stripe_list_invoices, stripe_create_subscription
supabaseRESTapikeysupabasesupabase_select, supabase_insert, supabase_update, supabase_delete, supabase_rpc
vercelRESTBearervercelvercel_list_projects, vercel_get_deployment, vercel_list_deployments, vercel_add_env_var

Google MCP Hub (25 Servers)

AdapterSource
google-workspacegemini-cli-extensions/workspace
google-cloud-runGoogleCloudPlatform/cloud-run-mcp
google-gogo.dev/gopls/features/mcp
google-analyticsgoogleanalytics/google-analytics-mcp
google-mcp-toolboxgoogleapis/mcp-toolbox
google-cloud-storagegoogleapis/gcloud-mcp/packages/storage-mcp
google-genmediavertex-ai-creative-studio/mcp-genmedia
google-gkeGoogleCloudPlatform/gke-mcp
google-gcloudgoogleapis/gcloud-mcp/packages/gcloud-mcp
google-observabilitygoogleapis/gcloud-mcp/packages/observability-mcp
google-flutterdart-lang/ai/pkgs/dart_mcp_server
google-mapsGoogle Maps AI Code Assist
google-alloydbGoogle MCP Hub (remote)
google-bigtableGoogle MCP Hub (remote)
google-chronicleGoogle MCP Hub (remote)
google-cloud-resource-managerGoogle MCP Hub (remote)
google-cloud-sql-mysqlGoogle MCP Hub (remote)
google-cloud-sql-postgresGoogle MCP Hub (remote)
google-cloud-sql-sqlserverGoogle MCP Hub (remote)
google-compute-engineGoogle MCP Hub (remote)
google-developer-knowledgeGoogle MCP Hub (remote)
google-firebaseGoogle MCP Hub (remote)
google-firestoreGoogle MCP Hub (remote)
google-spannerGoogle MCP Hub (remote)

4.1 MCP Server Sources

AdapterOfficial MCP Server / Source
airtableAirtable MCP Server
arizeArize-ai/arize-tracing-assistant
asanaAsana MCP Server
awsawslabs/mcp
bravebrave/brave-search-mcp-server
confluence, jiraAtlassian MCP Server
browser / playwrightmicrosoft/playwright-mcp
chromeChromeDevTools/chrome-devtools-mcp
cloudflarecloudflare/mcp-server-cloudflare
datadogdatadog-labs/mcp-server
dynatracedynatrace-oss/dynatrace-mcp
elasticelastic/mcp-server-elasticsearch
fivetranfivetran/fivetran-mcp
firefoxmozilla/firefox-devtools-mcp
githubgithub/github-mcp-server
gitlabGitLab MCP Server
linearLinear MCP Docs
mongodbMongoDB MCP Server Docs
n8nn8n MCP Server
notionmakenotion/notion-mcp-server
pagerdutyPagerDuty/pagerduty-mcp-server
postgresprisma/mcp
quickbooksintuit/quickbooks-online-mcp-server
redisredis/mcp-redis
shopifyShopify MCP Storefront
slackSlack MCP Server
snowflakeSnowflake-Labs/mcp
stripemcp/com.stripe/mcp
supabaseSupabase MCP Guide
vercelvercel-labs/mcp-on-vercel

Google MCP Servers — see the Google MCP Hub table above for all 24 individual server sources.

5. Agent Templates

5.1 Sentinel — Self-Healing SRE

Adapters: dynatrace, elastic, postgres, gitlab, arize, fivetran
Phases:

  1. Detect — Fetch active problems from Dynatrace
  2. Investigate — Hybrid search incidents + runbooks in Elastic
  3. Reason — Recall pattern from Postgres; if unknown, generate diagnosis
  4. Act — Create GitLab issue with auto-labels
  5. Verify — Poll Dynatrace traces with exponential backoff until error rate < 1%
  6. Evaluate — Gemini LLM-as-a-Judge scores diagnosis/action quality
  7. Learn — Upsert pattern + log incident to Postgres; trigger Fivetran sync

5.2 DeployAgent — CI/CD Orchestrator

Adapters: github, vercel, aws, postgres
Phases:

  1. Validate — Verify latest commit on branch
  2. Build — Trigger GitHub Actions workflow
  3. Deploy — Vercel deployment + S3 artifact sync
  4. Verify — Smoke test deployed URL via httpx
  5. Learn — Log deployment outcome to Postgres

5.3 FinanceAgent — Payment Anomaly Detection

Adapters: stripe, supabase, postgres
Phases:

  1. Detect — Flag invoices > $1,000 or duplicate charges in 24h window
  2. Investigate — Pull customer tier/history from Supabase
  3. Reason — Tier-based decision: flag_for_review / partial_refund / notify
  4. Act — Execute Stripe refund or insert review ticket
  5. Learn — Store pattern + log incident

5.4 InfraAgent — Infrastructure Optimization

Adapters: dynatrace, cloudflare, aws, postgres
Phases:

  1. Detect — Dynatrace latency spikes on service
  2. Investigate — DNS records (Cloudflare) + EC2 instances (AWS)
  3. Reason — Under-provisioned? Deploy CF Worker cache? Scale EC2?
  4. Act — Deploy Worker script or scale compute
  5. Verify — Poll Dynatrace traces until error rate < 1%
  6. Learn — Store remediation pattern

5.5 SecurityAgent — Vulnerability & Secret Scanning

Adapters: github, slack, postgres, cloudflare, datadog
Phases:

  1. Scan — Dependency checks + secret detection in GitHub repos
  2. Assess — Severity scoring (critical/high/medium/low)
  3. Triage — Slack alerts for critical findings
  4. Remediate — Auto-fix low-severity, ticket rest
  5. Verify — Re-scan to confirm remediation
  6. Learn — Store scan patterns in Postgres

5.6 DataAgent — ETL Pipeline Orchestration

Adapters: postgres, supabase, fivetran, slack
Phases:

  1. Extract — Pull from Supabase tables
  2. Validate — Quality scoring (nulls, duplicates)
  3. Transform — Deduplicate, normalize
  4. Load — Upsert into Postgres destination
  5. Monitor — Slack notification on completion
  6. Learn — Store pipeline patterns

5.7 OpsAgent — General DevOps Orchestration

Adapters: datadog, slack, github, linear, postgres
Phases:

  1. Observe — Datadog metrics + system health checks
  2. Diagnose — Crash loop? Memory pressure? Latency spike?
  3. Act — Restart deployment, scale replicas, create Linear ticket
  4. Notify — Slack #ops-alerts with diagnosis + actions
  5. Learn — Store remediation patterns in Postgres

5.8 ContentAgent — Content Operations

Adapters: notion, linear, slack
Phases:

  1. Plan — Outline content from Linear roadmap
  2. Draft — Generate in Notion
  3. Review — Slack approval workflow
  4. Publish — Schedule via Notion API
  5. Distribute — Cross-post to channels
  6. Learn — Engagement analytics → content strategy

5.9 CommerceAgent — E-commerce Operations

Adapters: stripe, supabase, aws, slack
Phases:

  1. Catalog — Sync product data from Supabase
  2. Pricing — Dynamic pricing rules
  3. Checkout — Stripe payment flow monitoring
  4. Fulfillment — AWS Lambda order processing
  5. Reconcile — Daily Stripe payout audit
  6. Notify — Slack revenue digest

5.10 GoogleWorkspaceAgent — Workspace Automation

Adapters: google-workspace, slack
Phases:

  1. Monitor — Scan Gmail for priority threads
  2. Triage — Label & route via Drive docs
  3. Draft — Compose Calendar invites + replies
  4. Schedule — Auto-book meetings from email context
  5. Notify — Slack summary of day's actions
  6. Archive — Move resolved threads to Drive folder

5.11 AtlassianAgent — Engineering Project Management

Adapters: jira, confluence, github, slack
Phases:

  1. Backlog — Jira grooming from Confluence specs
  2. Sprint — Auto-assign from GitHub commit velocity
  3. Review — PR checklist from Jira acceptance criteria
  4. Deploy — GitHub Actions → Jira transition
  5. Retro — Confluence retro doc + Slack poll
  6. Learn — Sprint velocity trend analysis

5.12 BrowserQAAgent — Frontend QA Automation

Adapters: browser, chrome, firefox, slack
Phases:

  1. Scan — Crawl sitemap for changes
  2. Test — Playwright regression suite
  3. Screenshot — Visual diff across Chrome + Firefox
  4. Compare — Baseline vs current pixel match
  5. Report — Slack #qa-alerts with diff links
  6. Learn — Flaky test pattern detection

5.13 CRMAgent — Sales Operations

Adapters: airtable, google-workspace, slack
Phases:

  1. Lead — Ingest leads from Gmail signature capture
  2. Qualify — Airtable scoring + Drive proposal lookup
  3. Proposal — Generate quote from Drive template
  4. Close — Gmail follow-up sequence + Slack win channel
  5. Onboard — Drive welcome kit + Calendar kickoff
  6. Nurture — Airtable campaign enrollment

5.14 ShopifyAgent — Shopify Store Ops

Adapters: shopify, stripe, postgres, slack
Phases:

  1. Inventory — Shopify stock sync to Postgres
  2. Pricing — Dynamic margin rules
  3. Order — Shopify webhook → Stripe charge verify
  4. Fulfill — Shipping label + tracking update
  5. Refund — Stripe refund → Shopify order adjust
  6. Review — Slack daily P&L digest

5.15 DatabaseOpsAgent — Polyglot Database Ops

Adapters: mongodb, redis, postgres, datadog, slack
Phases:

  1. Monitor — Datadog slow query alerts
  2. Diagnose — Explain plan + index health across all DBs
  3. Migrate — Postgres → MongoDB schema mapping
  4. Optimise — Redis eviction + MongoDB index rebuild
  5. Backup — Cross-DB snapshot verification
  6. Learn — Query pattern + cache hit rate trends

5.16 SREObservabilityAgent — Full-Stack Observability

Adapters: dynatrace, elastic, datadog, pagerduty, slack
Phases:

  1. Detect — Dynatrace anomaly + Elastic error spike correlation
  2. Correlate — Datadog cross-service trace linking
  3. Escalate — PagerDuty severity + on-call routing
  4. Remediate — Auto-runbook execution
  5. Verify — Dynatrace/Elastic post-fix metrics
  6. Learn — Incident post-mortem → runbook update

5.17 InfrastructureAgent — IaC & Container Ops

Adapters: docker, gitlab, aws, cloudflare, slack
Phases:

  1. Plan — GitLab CI pipeline + drift detection
  2. Build — Docker image build + scan
  3. Test — GitLab plan against AWS staging
  4. Deploy — Cloudflare Worker + ECS rollout
  5. Monitor — AWS CloudWatch + CF analytics
  6. Learn — Cost + performance delta analysis

6. Production Deployment

For local development see the Quick Start (Docker Compose) at the top of this document — that's the canonical entry point for both the composer service and the broker.

6.1 GCP Production (Cloud Run)

Prerequisites:

  • GCP project with Cloud Run, Cloud SQL (Postgres 15+), Secret Manager enabled
  • Service account with roles/cloudsql.client, roles/secretmanager.secretAccessor
# 1. Create secrets
gcloud secrets create broker-api-key --data-file=<(openssl rand -hex 32)
gcloud secrets create gemini-api-key --data-file=<(echo -n YOUR_GEMINI_KEY)
gcloud secrets create postgres-dsn --data-file=<(echo -n "postgresql+asyncpg://user@/sentinel?host=/cloudsql/PROJECT:REGION:INSTANCE")

# 2. Build & deploy
gcloud builds submit --config cloudbuild.yaml

# 3. Verify
gcloud run services describe cybernetics-composer --region=us-central1
curl https://<URL>/healthz
curl https://<URL>/readyz

6.2 Cloud SQL Migration

# Apply schema
psql "host=/cloudsql/PROJECT:REGION:INSTANCE dbname=sentinel user=postgres" \
  -f migrations/001_init.sql

6.3 Hardening Checklist

The composer image already enforces the in-container half (distroless nonroot, read-only FS, cap_drop: ALL, cosign-signed, SBOM-attested). The deployment half is the operator's responsibility:

  • Cloud Run --no-allow-unauthenticated enforced (or OIDC via OIDC_ISSUER/OIDC_AUDIENCE)
  • Cloud Armor WAF + rate-limit policy in front of Cloud Run
  • VPC-SC perimeter restricts egress to approved APIs only
  • Cloud SQL private IP + IAM database authentication
  • Secret Manager rotation policy (90 days)
  • Cloud Audit Logs enabled for data_access, admin_activity
  • govulncheck + trivy fs gates pass in CI (.github/workflows/composer-security.yml)
  • Container scanning via Artifact Registry + Container Analysis

Full control mapping in docs/CONTROLS_NIST_800_53.md; threat model in docs/THREAT_MODEL.md.

7. Operations

7.1 Health & Readiness

# Liveness
curl https://<URL>/healthz

# Readiness (also verifies GEMINI_API_KEY presence)
curl https://<URL>/readyz

# Tool discovery
curl -H "Authorization: Bearer $API_KEY" https://<URL>/mcp/tools

# Circuit breaker status
curl -H "Authorization: Bearer $API_KEY" https://<URL>/mcp/circuits

# SSE health stream
curl -H "Authorization: Bearer $API_KEY" https://<URL>/mcp/sse

7.2 Structured Logging

Both surfaces emit JSON to stdout, captured by Cloud Logging.

Composer (Go, slog) — one line per HTTP request, correlation via X-Request-ID:

{
  "time": "2026-05-19T14:32:01Z",
  "level": "INFO",
  "msg": "http.request",
  "request_id": "3f8a1c2b9e0d",
  "method": "POST",
  "path": "/api/compose",
  "status": 200,
  "bytes": 4823,
  "duration": 612,
  "remote": "10.0.0.42"
}

Broker (Python) — one line per tool invocation, correlation via correlation_id:

{
  "timestamp": "2026-05-19T14:32:01Z",
  "level": "info",
  "event": "tool_executed",
  "adapter": "dynatrace",
  "tool": "dynatrace_get_problems",
  "latency_ms": 145,
  "session_id": "a1b2c3",
  "correlation_id": "req-xyz"
}

7.3 Runbook: Adapter Circuit Open

# 1. Diagnose
curl -H "Authorization: Bearer $API_KEY" https://<URL>/mcp/circuits
# → {"circuits": {"dynatrace": "OPEN"}}

# 2. Inspect Cloud Logging for failure reason
gcloud logging read "jsonPayload.breaker=dynatrace AND severity>=ERROR" --limit=10

# 3. Manual reset (if operator-verified)
# Restart Cloud Run revision to reset breaker state
gcloud run services update cybernetics-composer --region=us-central1

8. Testing

Composer (Go)

go vet ./...
go test -race -count=1 -coverprofile=cover.out ./...
go tool cover -func=cover.out | tail -1

# Static analysis & vulnerability gates (same as CI)
golangci-lint run                       # config: .golangci.yml
gosec -severity medium -confidence medium ./...
govulncheck ./...
trivy fs --severity CRITICAL,HIGH --ignore-unfixed .

Broker (Python)

pytest tests/ -v
pytest tests/ --cov=cybernetics --cov-fail-under=80
pip-audit --requirement requirements.txt
bandit -r cybernetics/

Container scan

gcloud artifacts docker images scan us-central1-docker.pkg.dev/PROJECT/cybernetics/composer:latest

CI runs the full composer gate on every push/PR — see .github/workflows/composer-security.yml.

9. Google ADK Integration

from cybernetics.adk.bridge import cybernetics_adk_agent
from google.adk.runners import Runner

runner = Runner(agent=cybernetics_adk_agent)
for event in runner.run("Deploy my-app to production"):
    print(event)

10. Agent Composer

The React + TypeScript UI and Go backend that generate Python agent code via Gemini, serve the public adapter catalog at /api/templates, and expose the operational dashboard. See the Quick Start at the top of this document for setup instructions — it is the canonical entry point.

Runtime config is fully env-driven; the composer-side env-var matrix is documented in AGENTS.md (project-wide AI-agent guide) and SECURITY.md (control posture).

Workflow:

  1. Pick Template — Choose from 18 agent templates (Sentinel, Deploy, Finance, Infra, Security, Data, Ops, Content, Commerce, Analytics, Google Workspace, Atlassian, Browser QA, CRM, Shopify, Database Ops, SRE Observability, Infrastructure)
  2. Select Adapters — Toggle any of the 56 MCP adapters
  3. Configure Keys — Enter API keys for selected adapters
  4. Compose — Gemini generates a custom Python agent class
  5. Deploy — One-click deploy to Google Cloud Run

API Endpoints:

EndpointMethodDescription
/api/templatesGETList all 18 templates + 56 adapters
/api/composePOSTGenerate agent code via Gemini
/api/deployPOSTReturn Cloud Run deployment command

Example compose request:

curl -X POST http://localhost:4001/api/compose \
  -H "Content-Type: application/json" \
  -d '{
    "template": "sentinel",
    "adapters": ["dynatrace", "slack", "datadog"],
    "env_vars": {"DYNATRACE_API_TOKEN": "xxx", "SLACK_BOT_TOKEN": "xoxb-xxx"},
    "prompt": "Add a custom phase that posts a daily digest to Slack"
  }'

11. Google ADK A2A, A2P & ERC-8004 Integration

Cybernetics agents implement Google's Agent-to-Agent (A2A) and Agent-to-Protocol (A2P) patterns for cross-agent interoperability.

11.1 A2A — Agent-to-Agent

Agents register capabilities in a shared A2ARegistry. Other agents can discover and invoke those capabilities dynamically.

from cybernetics.a2a.hooks import A2ACapability, get_a2a_registry

cap = A2ACapability(
    id="sentinel_detect",
    name="Sentinel Problem Detection",
    description="Fetch active Dynatrace problems for a service",
    input_schema={"service": {"type": "string"}},
    output_schema={"problems": {"type": "array"}},
)
get_a2a_registry().register_capability(cap)

11.2 A2P — Agent-to-Protocol

Agents can subscribe to or emit protocol events for decoupled coordination.

from cybernetics.a2a.hooks import A2PProtocol, get_a2a_registry

proto = A2PProtocol(
    id="incident_v1",
    name="Incident Stream",
    version="1.0",
    schema_uri="https://cybernetics.dev/schemas/incident.json",
    event_types=["detected", "resolved", "escalated"],
)
get_a2a_registry().register_protocol(proto)

11.3 ERC-8004 (8004.org)

ERC-8004 is an Ethereum standard for agent capability discovery and identity, authored by Google. Cybernetics implements the on-chain resolution contract via ERC8004Resolver.

from cybernetics.a2a.hooks import get_erc8004_resolver

resolver = get_erc8004_resolver()

# Query which capabilities are available
resolver.resolve(["sentinel_detect", "deploy_trigger"])
# → {"sentinel_detect": {"available": true, ...}, ...}

# Negotiate intersecting capabilities with a remote agent
resolver.negotiate([{"id": "sentinel_detect"}, {"id": "unknown_cap"}])
# → ["sentinel_detect"]

Reference: 8004.org

12. Extending Cybernetics

Cybernetics is designed to be easily extensible. Adapters placed in cybernetics/adapters/ are automatically discovered and registered at startup via auto_discover(). To add a new MCP adapter, follow these steps:

1. Create the Adapter Class

Create a new file in cybernetics/adapters/ (e.g., my_service.py). Inherit from MCPAdapter and implement the required methods:

from typing import Dict, Any
from cybernetics.adapters.base import MCPAdapter
from cybernetics.config.settings import settings

class MyServiceAdapter(MCPAdapter):
    name = "myservice"
    description = "Integration with MyService API"

    def __init__(self):
        super().__init__()
        self._api_key = settings.myservice_api_key
        # Initialize your client (e.g., httpx.AsyncClient)
        self._setup_tools()

    def _setup_tools(self):
        self.register_tool(
            "myservice_get_data",
            "Fetch data from MyService",
            {"id": {"type": "string"}},
            ["id"],
            self._get_data,
        )

    async def _get_data(self, id: str):
        # Implementation logic
        return {"id": id, "data": "..."}

    async def health(self) -> Dict[str, Any]:
        return {"status": "healthy"}

2. Add Configuration

Add any required environment variables to cybernetics/config/settings.py using Pydantic Field with an alias:

    # MyService
    myservice_api_key: str = Field("", alias="MYSERVICE_API_KEY")

3. Auto-Registration (No manual step needed)

Because auto_discover() scans cybernetics/adapters/ at startup, your adapter will be picked up automatically. No imports or manual registration required.

If your adapter lives outside the standard directory, register it explicitly:

from cybernetics.adapters.my_service import MyServiceAdapter
from cybernetics.registry.manager import register_adapter
register_adapter("myservice", MyServiceAdapter)

4. Verify

Run the integration tests and ensure your new adapter is listed in /mcp/tools.

13. Threat Model & Security Posture

Full STRIDE analysis lives in docs/THREAT_MODEL.md. Per-surface highlights:

Composer service (Go, cmd/composer/)

ThreatMitigationVerification
Anonymous API accessBearerAuth (constant-time) or OIDCAuth (RS256 JWT)internal/middleware/middleware_test.go, internal/oidc/oidc_test.go
CSRF / hostile originStrict CORS allowlist; no wildcard echoTestCORS_AllowlistOnly
Body-size DoSMaxBody (1 MiB default, env-tunable)TestMaxBody_Enforces413OnOversize
Per-IP request floodToken-bucket rate limiterTestRateLimiter_*
Panic stack-trace leakRecover middleware → generic 500TestRecover_TurnsPanicInto500
Container escapeDistroless nonroot, cap_drop: ALL, no-new-privileges, read-only FSDockerfile, docker-compose.yml
Supply-chain compromisestdlib-only Go, cosign keyless sign, CycloneDX SBOM attest, govulncheck + Trivy CI gates.github/workflows/composer-security.yml
Missing audit trailslog JSON with X-Request-ID correlation on every requestinternal/middleware/middleware.go

Broker service (Python, cybernetics/broker/)

ThreatMitigationVerification
Secret exfiltration from imageMulti-stage build; .env excluded; secrets via --set-secretsdocker inspect shows no Env secrets
Unauthorized broker access--no-allow-unauthenticated + Identity-Aware Proxy (IAP)gcloud run services describe
Timing attacks on API keyhmac.compare_digest + random delay on mismatchStatic analysis via bandit
DQL / SQL injectionRegex allow-list sanitization (_sanitize_dql) + parameterized queriesUnit test test_dql_sanitization
SSRF via adapter callbacksURL prefix validation, no redirects, httpx timeout capsRespx mock tests
ReDoS in regex filtersBounded regex (^...$), no .* backtrackingCode review
Credential leakage in logsGuard sentinel blocks keys named password, secret, tokentest_guard_blocks_sensitive
Async blocking I/OAll clients are httpx.AsyncClient, asyncpg, etc.pytest-asyncio coverage

Compliance Mapping

Full control-by-control coverage is in docs/CONTROLS_NIST_800_53.md (38 controls across 9 NIST 800-53 Rev 5 families, 66% fully implemented). Highlights:

  • NIST 800-53 Rev 5: AC-3, AU-2/3/10, CM-2/6/7/8, SC-5/7/8/13/17, SI-7/10/11 — all ✅. Full STRIDE analysis in docs/THREAT_MODEL.md.
  • FedRAMP Moderate: in-container controls covered; deployment controls (TLS, IdP, log storage) are operator-supplied via Cloud Run + Cloud SQL + Secret Manager.
  • SOC 2 Type II: structured JSON audit logs with X-Request-ID correlation, captured by Cloud Logging.

14. License & Attribution

Licensed under the GNU Affero General Public License v3.0 (AGPL-3.0). See LICENSE for the full text and NOTICE for third-party attributions.

Network use is distribution under the AGPL: anyone who interacts with this software over a network is entitled to receive the corresponding source.

Authors: plasmaraygun, GoryGrey, royhodge812, sebuh-infsol

For operational issues, contact the maintainers via GitHub Security Advisories. Do not open public issues for security-sensitive topics.

↑↓ navigate openesc close