Second Brain

aws-mcp-v400-bible-v19110-upgrade-registry-dispatch-architec

3 min read

AWS MCP v4.0.0 / Bible v19.1.10 upgrade — registry-dispatch architecture surfaced

AWS MCP v4.0.0 / Bible v19.1.10 upgrade

Outcome

  • Repo: ARJ999/aws-god-agent-mcp-server PR #8 on upgrade/bible-v19.1.10-server-v4.0.0
  • Server: v3.1.0 → v4.0.0, Bible v18.1 → v19.1.10
  • 18 meta-tools / 3,006 internal tools (audit-verified) / 400+ services via CLI fallback
  • Pair status: DRAFT (cutover blocked at Phase 9 pending AJ approval)

Architectural surface — R50 DRAFT (Bible cascade candidate)

Registry-dispatch is a third architectural pattern for MCP servers, sibling to:

  • R45 (two-layer wrapper-impl arity) — two-layer FastMCP with separate api_client class
  • R49 (intra-class arity) — all-in-one-class self.(…) dispatch
  • R50 (registry-dispatch) — N meta-tools dispatching M internal tools (M >> N) via singleton registry, where dispatch is func(**params) lookup-by-name across module boundaries

Audit invariants for registry-dispatch (scripts/registry_dispatch_audit.py):

  1. No **kwargs in tool function signatures (Law 5)
  2. No positional-only parameters (R46 — kwargs-by-name)
  3. No *args in tool function signatures
  4. Walk tree.body only, NOT ast.walk — nested helpers (boto3 paginators) are legitimate, must not be flagged
  5. Meta-tools (@mcp.tool()-decorated) have zero **kwargs/*args
  6. Optional name-uniqueness across modules (Law 4)

This pattern generalizes to any MCP server using a registry to manage large internal tool surfaces (e.g., when tool count would blow context budget at registration time).

Reusable framework discoveries

  • CLI passthrough via shared helper (src/tools/_cli_helper.py): for vendor services where SDK lag exists (Q Apps, AppFabric, Cost Optimization Hub all GA 2024 with patchy boto3 coverage), cli_passthrough(namespace, operation, args) shells out to vendor CLI — forward-compatible with newest API surfaces. Generalizes beyond AWS to Snowflake/Salesforce/etc.
  • install_annotator + R33 + R41-R44: a single decorator wrap delivers outputSchema, ToolAnnotations, result-shape envelope, AND vendor-error-class unification (FEATURE_NOT_ENABLED, PERMISSION_DENIED, RATE_LIMITED, NOT_FOUND, GENERIC). Retro-fits onto v18.1-era codebases without per-tool source changes.
  • R48 composite tools for operator-intent: aws_lambda_deploy_full collapses 5+ AWS API calls (role + policy + function + alarm + tags) into one call with structured steps[] reporting. Same pattern: aws_ec2_launch_full, aws_s3_bucket_secure_create, aws_iam_role_for_service, aws_account_security_baseline.

Operational gotchas (concrete)

  • Pairing Contract internal_registry_count MUST match python3 scripts/registry_dispatch_audit.py output exactly, not hand-counted — drift is a Phase 5 cascade-check failure. Use inventory_verification_command field in contract.yaml to lock the source of truth.
  • paginate nested helper in 3 different boto3-using tools is NOT a Law 4 collision — it’s a legitimate paginator pattern. Audit script must walk tree.body only (module-level), not ast.walk (which descends into nested defs).
  • Secret scanner blocks AWS test fixtures that look like real keys (AKIA...). Use string concatenation at runtime to construct test-shaped sentinels, with explicit # test sentinel comments.
  • /opt/mcp-servers/aws-mcp/ is NOT a git clone — sync at cutover requires either fresh git clone (destructive) or careful overlay. Recommend converting to git clone post-cutover for v4.0.0+ to enable git pull upgrades.

Cutover prerequisites (Phase 9 — when AJ greenlights)

  1. Merge PR #8 to main
  2. Tag rollback: docker tag aws-mcp-aws-mcp:latest aws-mcp-aws-mcp:v3.1.0-pre-upgrade
  3. Sync /opt/mcp-servers/aws-mcp/ from main
  4. IMAGE_TAG=v4.0.0 docker compose up -d
  5. Run 17-check Phase 9 gate (skill §7 commands)
  6. Run R32 Census: scripts/tool_health_census.py --endpoint https://aws-mcp.arjtech.in/mcp
  7. If 17/17 + 0 TRUE_BUG: edit docs/pairing-contract.md flipping pair_status: DRAFT → SIGNED, rebuild + redeploy
  8. File Bible PR proposing R50 canonization

Bible upstream cascade owed

After SIGN: file PR against ARJ999/MCP-God-Agent-Development-Bible introducing 19_FRAMEWORK_REFINEMENTS_v19.1.12.md with R50 (registry-dispatch pattern), framework/scripts/registry_dispatch_audit.py, and Pair Architecture Matrix update in mcp-server-development skill.

Graph View

Backlinks