flowchart TB
    LLM([LLM / Claude])

    subgraph KNOW["Knowledge — 250 diag-tech MCPs"]
        DIAG["diag-postgres / diag-hbase / diag-kafka / ... / diag-cloudflare"]
    end

    subgraph META["Reasoning Layer"]
        EX["srefix-explorer<br/>fallback plan + dependency graph"]
    end

    subgraph DISCOVERY["srefix-discovery — 33 adapters across 5 layers (coverage varies by deployment)"]
        D_BASIC["opscloud4 / kubernetes / zookeeper"]
        D_CLOUD["aws / gcp / azure / digitalocean"]
        D_CHINA["aliyun / tencentcloud / huaweicloud / jdcloud / volcengine"]
        D_PAAS["vercel / flyio / railway / heroku"]
        D_REG["consul / eureka / nacos / backstage"]
        D_DIRECT["redis-cluster / mongo / cassandra / es-direct / etcd"]
        D_SAAS["SaaS 14: cloudflare / datadog / sentry / snowflake / planetscale / auth0 / okta / netlify / pagerduty / opsgenie / github-actions / gitlab-ci / newrelic / splunk"]
        D_RUN["nomad / rancher / helm / zabbix / nagios / openfaas / knative"]
        D_VIRT["virtual: meta-agents + local-tools + abstract concepts"]
    end

    subgraph EXEC["Telemetry + Execution"]
        PROM["srefix-prom<br/>PromQL"]
        LOKI["srefix-loki<br/>LogQL"]
        ES["srefix-es<br/>ES/OpenSearch"]
        JH["srefix-jumphost<br/>SSH via bastion"]
    end

    LLM --> DIAG
    LLM --> EX
    LLM --> DISCOVERY
    LLM --> EXEC
    EX -.suggested calls.-> EXEC
    DIAG -.extract_diagnostic_queries.-> EXEC

flowchart LR
    subgraph BASIC["Basic 3"]
        OPSCLOUD4["OPSCLOUD4_BASE_URL +<br/>OPSCLOUD4_TOKEN"]
        K8S["K8S_DISCOVERY_ENABLED=1"]
        ZK["ZK_QUORUMS"]
    end

    subgraph CLOUD_W["Western cloud"]
        AWS["AWS_DISCOVERY_REGIONS"]
        GCP["GCP_PROJECTS"]
        AZ["AZURE_SUBSCRIPTION_IDS"]
        DO["DIGITALOCEAN_TOKEN"]
    end

    subgraph CLOUD_CN["China cloud"]
        ALI["ALIBABA_CLOUD_ACCESS_KEY_ID"]
        TC["TENCENTCLOUD_SECRET_ID"]
        HW["HUAWEICLOUD_ACCESS_KEY"]
        JD["JDCLOUD_ACCESS_KEY"]
        VOLC["VOLCENGINE_ACCESS_KEY"]
    end

    subgraph PAAS["PaaS"]
        VC["VERCEL_TOKEN"]
        FLY["FLY_API_TOKEN"]
        RW["RAILWAY_TOKEN"]
        HK["HEROKU_API_TOKEN"]
    end

    subgraph REG["Service registries"]
        CON["CONSUL_URL"]
        EUR["EUREKA_URL"]
        NAC["NACOS_URL"]
        BS["BACKSTAGE_URL"]
    end

    subgraph DIRECT["Self-as-registry"]
        RC["REDIS_CLUSTERS"]
        MGO["MONGODB_CLUSTERS"]
        CAS["CASSANDRA_CLUSTERS"]
        ESD["ES_DISCOVERY_ENDPOINTS"]
        ETD["ETCD_CLUSTERS"]
    end

    subgraph SAAS["SaaS — 14 adapters"]
        CF["CLOUDFLARE_API_TOKEN"]
        DD["DD_API_KEY + DD_APP_KEY"]
        SE["SENTRY_AUTH_TOKEN + SENTRY_ORG"]
        SF["SNOWFLAKE_ACCOUNT/USER/PASSWORD"]
        PS["PLANETSCALE_TOKEN + ORG"]
        AU["AUTH0_DOMAIN + AUTH0_MGMT_TOKEN"]
        OK["OKTA_DOMAIN + OKTA_API_TOKEN"]
        NL["NETLIFY_TOKEN"]
        PD["PAGERDUTY_TOKEN"]
        OG["OPSGENIE_API_KEY"]
        GH["GITHUB_TOKEN + GITHUB_ORG"]
        GL["GITLAB_TOKEN"]
        NR["NEW_RELIC_API_KEY"]
        SP["SPLUNK_URL + SPLUNK_TOKEN"]
    end

    subgraph RUN["Orchestrator + monitoring servers"]
        NM["NOMAD_ADDR"]
        RN["RANCHER_URL + RANCHER_TOKEN"]
        HE["HELM_DISCOVERY_ENABLED=1"]
        ZB["ZABBIX_URL + ZABBIX_API_TOKEN"]
        NG["NAGIOS_URL"]
        OF["OPENFAAS_URL"]
        KN["KNATIVE_DISCOVERY_ENABLED=1"]
    end

    subgraph VIRT["Always-on virtual"]
        VRT["(no env required — covers 32 meta + tools + abstract)"]
    end

Service=hbase                  ← matches diag-hbase.md (tech short-name)
ClusterName=hbase-prod-us-east ← members with same value form one cluster
Role=master | regionserver     ← optional; surfaced as Host.role

from srefix_discovery_mcp.adapters.aws_extended import build_aws_ec2_classified

instances = ec2.describe_instances()['Reservations'][...]['Instances']  # raw boto3
clusters = build_aws_ec2_classified(instances, region='us-east-1', account='123')
# → 1 hbase cluster (3 nodes, roles preserved) + 1 kafka cluster + N untagged

# 1. Install the verifier (small — no telemetry deps)
cd srefix-diagnosis/verify-mcp
pip install -e .

# 2. Run the audit on the whole agents/ corpus
srefix-verify-corpus srefix-diagnosis/agents

# Or just one tech
srefix-verify-corpus --tech vitess srefix-diagnosis/agents

Manuals scanned: 250
  with whitelist:      3  (nginx, prometheus, vitess)
  without whitelist: 247  (not yet covered)

In covered manuals: 58 metric references
  matched whitelist (likely real): 16
  flagged (likely hallucinated):   42

── Flagged metrics by manual ──
  [vitess]  19 flagged
    × vtgate_queries_error  ×6  L155,242,278,426,429,…
    × vtgate_queries_processed_total  ×4  L167,1252,1271,1326
    ...

# 1. Auto-draft (read-only Claude run against the Vitess manual + source)
srefix-fix propose vitess
# → fix_maps/vitess.draft.yaml

# 2. Review (drop unsure entries, add confirmed_by)
$EDITOR fix_maps/vitess.draft.yaml
mv fix_maps/vitess.draft.yaml fix_maps/vitess.yaml
git add fix_maps/vitess.yaml

# 3. Dry-run, then real apply
srefix-fix apply fix_maps/vitess.yaml --dry-run
srefix-fix apply fix_maps/vitess.yaml

# 4. Inspect + commit
git diff agents/vitess-agent.md
git commit -am "fix(vitess): apply confirmed metric-name corrections"

{
  "mcpServers": {
    "srefix-verify": { "command": "srefix-verify" }
  }
}

cd srefix-diagnosis/mcp

# See what's available
python3 generate.py --list-all
python3 generate.py --list-all | grep -i sql

# Pick one of three filter modes:

# (a) explicit list
python3 generate.py --techs postgres redis kafka hbase k8s

# (b) from a file (recommended — you can git-commit the file)
cat > my_stack.txt <<'EOF'
postgres
redis
kafka
hbase
k8s
prometheus
nginx
istio
EOF
python3 generate.py --from-file my_stack.txt

# (c) regex
python3 generate.py --regex 'postgres|mysql|redis|kafka'

# Then install — only the selected commands appear on PATH
pip install -e .

which srefix-diag-postgres   # should print a path
srefix-diag-postgres --help  # MCP servers don't have --help; if it starts and waits on stdio, it works

python3 generate.py     # no filter = all 250
pip install -e .

cd srefix-diagnosis/discovery-mcp
pip install -e ".[all]"   # includes kubernetes + kazoo extras
# Or pick one:
#   pip install -e ".[kubernetes]"
#   pip install -e ".[zookeeper]"
#   pip install -e .             # opscloud4-only

# opscloud4 (any one of: REST CMDB)
export OPSCLOUD4_BASE_URL=https://opscloud.your-corp.com
export OPSCLOUD4_TOKEN=<x-token>

# kubernetes (uses ambient kubeconfig)
export K8S_DISCOVERY_ENABLED=1
export K8S_CONTEXTS=prod-east,prod-west       # optional

# zookeeper (HBase / Kafka legacy / Solr)
export ZK_QUORUMS="zk-prod-east=zk1:2181,zk2:2181,zk3:2181;zk-prod-west=zkw1:2181"
export ZK_WATCHES=hbase,kafka,solr            # optional, default = all

export DISCOVERY_CACHE_TTL=300                # optional, default 300s

cd srefix-diagnosis/prometheus-mcp
pip install -e .

export PROMETHEUS_URL=http://prometheus.prod:9090
# Optional auth:
#   PROMETHEUS_TOKEN=<bearer>
#   PROMETHEUS_USERNAME=... PROMETHEUS_PASSWORD=...
#   PROMETHEUS_VERIFY_TLS=0   (skip TLS verify)
#   PROMETHEUS_TIMEOUT=30

cd srefix-diagnosis/loki-mcp
pip install -e .

export LOKI_URL=http://loki.prod:3100
# Optional:
#   LOKI_TOKEN=<bearer>           or LOKI_USERNAME / LOKI_PASSWORD
#   LOKI_ORG_ID=<tenant>          (multi-tenant Loki)
#   LOKI_TIMEOUT=30
#   LOKI_VERIFY_TLS=0

cd srefix-diagnosis/es-mcp
pip install -e .

export ES_URL=https://es.prod:9200
# Auth (one of):
#   ES_API_KEY=<id:secret base64>
#   ES_USERNAME=... ES_PASSWORD=...
# Optional:
#   ES_VERIFY_TLS=0
#   ES_TIMEOUT=30

cd srefix-diagnosis/jumphost-mcp
pip install -e .

mkdir -p ~/.config/srefix

# Inventory — which hosts exist + their tags
cat > ~/.config/srefix/inventory.yaml <<'EOF'
hosts:
  pg-prod-1:
    tags: {env: prod, tech: postgres, role: primary}
  pg-prod-2:
    tags: {env: prod, tech: postgres, role: replica}
  hbase-rs-001:
    tags: {env: prod, tech: hbase, role: regionserver}
EOF

# Presets — read-only commands the LLM is allowed to invoke
cat > ~/.config/srefix/presets.yaml <<'EOF'
postgres:
  pg-replication-status:
    description: Replication status from primary
    command: 'psql -At -c "SELECT pid, state, sent_lsn FROM pg_stat_replication"'
    allowed_roles: [primary]
    timeout: 10
  pg-table-size:
    description: Size of one table
    command: 'psql -At -c "SELECT pg_total_relation_size(''{table_name}'')"'
    allowed_roles: [primary, replica]
    allowed_args: [table_name]
    timeout: 10
EOF

Host bastion
  HostName bastion.your-corp.com
  User you

Host pg-prod-*
  ProxyJump bastion
  User postgres

export JUMPHOST_INVENTORY=~/.config/srefix/inventory.yaml
export JUMPHOST_PRESETS=~/.config/srefix/presets.yaml
export JUMPHOST_MODE=preset_only       # default; safest
# Other modes:
#   JUMPHOST_MODE=filtered_arbitrary    # `run` enabled, denylist applied
#   JUMPHOST_MODE=unrestricted          # `run` enabled, no filter (use with external approval)
export JUMPHOST_DRY_RUN=1              # never actually exec; great for testing
export JUMPHOST_DEFAULT_TIMEOUT=30

cd srefix-diagnosis/explorer-mcp
pip install -e .

{
  "mcpServers": {
    "discovery": {
      "command": "srefix-discovery",
      "env": {
        "OPSCLOUD4_BASE_URL": "https://opscloud.your-corp.com",
        "OPSCLOUD4_TOKEN":    "...",
        "K8S_DISCOVERY_ENABLED": "1",
        "ZK_QUORUMS": "zk-prod-east=zk1:2181,zk2:2181,zk3:2181"
      }
    },
    "prom":     { "command": "srefix-prom",  "env": { "PROMETHEUS_URL": "..." } },
    "loki":     { "command": "srefix-loki",  "env": { "LOKI_URL": "..." } },
    "es":       { "command": "srefix-es",    "env": { "ES_URL": "...", "ES_API_KEY": "..." } },
    "jumphost": {
      "command": "srefix-jumphost",
      "env": {
        "JUMPHOST_INVENTORY": "/Users/you/.config/srefix/inventory.yaml",
        "JUMPHOST_PRESETS":   "/Users/you/.config/srefix/presets.yaml",
        "JUMPHOST_MODE":      "preset_only",
        "JUMPHOST_DRY_RUN":   "1"
      }
    },
    "diag-postgres": { "command": "srefix-diag-postgres" },
    "diag-hbase":    { "command": "srefix-diag-hbase" },
    "diag-redis":    { "command": "srefix-diag-redis" },
    "diag-kafka":    { "command": "srefix-diag-kafka" },
    "diag-k8s":      { "command": "srefix-diag-k8s" }
  }
}

cd mcp
python3 filter_config.py postgres redis kafka hbase k8s > ~/my_diag_subset.json
# then merge ~/my_diag_subset.json["mcpServers"] into your Claude config

Observation: "PostgreSQL replica 复制延迟 > 5min"
  │
  ├─ discovery.list_hosts(tech="postgres", role="primary")
  │       → ["pg-prod-1"]
  ├─ diag-postgres.diagnose("replication lag spiking")
  │       → case "ReplicationLagCritical" + Symptoms / Diagnosis / Root Cause Tree / Thresholds
  ├─ diag-postgres.extract_diagnostic_queries("ReplicationLagCritical")
  │       → [4 structured queries: 3 psql + 1 shell, each with suggested_mcp]
  │
  ├─ prom.range_query("pg_replication_lag_seconds{...}", "-30m", "now")
  ├─ jumphost.run_safe(host="pg-prod-1", tech="postgres",
  │                    preset_name="pg-replication-status")
  ├─ loki.query_range('{app="postgres"} |= "wal"', "-30m", "now")
  ├─ es.search("logs-postgres-*", query='level:ERROR AND host:"pg-prod-1"')
  │
  └─ Claude correlates evidence + manual → diagnosis + suggested fixes

# Each command should be on PATH:
which srefix-discovery srefix-prom srefix-loki srefix-es srefix-jumphost
which srefix-diag-postgres   # plus whichever diag-* you generated

# Smoke-test one MCP server (will hang on stdin — that's normal; Ctrl-C to exit):
srefix-diag-postgres

# Full inspection via the MCP CLI inspector:
npx @modelcontextprotocol/inspector srefix-diag-postgres