Second Brain

simple-salesforce-metadata-api-tuples-not-dicts

2 min read

simple-salesforce-metadata-api-tuples-not-dicts

simple-salesforce Metadata API — All Methods Return Tuples

Every SfdcMetadataApi method returns tuples, never dicts. Code calling .get() on results will crash.

Method Signatures (verified from source)

  • deploy(zipfile, sandbox, **kwargs) → Tuple[str, str] (id, state). zipfile accepts file path or IO[bytes], NOT base64 strings. sandbox is required positional bool.
  • check_deploy_status(id) → Tuple[str, str, Mapping, Mapping] (state, state_detail, deployment_detail, unit_test_detail)
  • retrieve("", unpackaged={"Type": ["member"]}) → Tuple[str, str] (id, state). First arg is URL path segment.
  • check_retrieve_status(id) → Tuple[str, str, List[Dict]] (state, error_message, messages)
  • _read_deploy_zip(zipfile) — accepts IO[bytes] (has read+seek) or string (file path). Does its own base64 encoding internally.

Critical Gotchas

  • For base64 input from MCP tools: b64decode(base64_str) → io.BytesIO(bytes) → pass to deploy()
  • For sandbox flag: api_client.org_configs[alias]["type"] == "sandbox", map “sandbox” alias → “fullcopy”
  • For deploy zips: package.xml at root (no src/ prefix — that’s SFDX convention, not Metadata API)
  • asyncio.to_thread(func, *args, **kwargs) DOES support kwargs in Python 3.9+
  • Analytics REST API GET /analytics/reportTypes returns categories with nested reportTypes array — must flatten to get type keys

Audit Results (10-Apr-2026)

Full audit of 601-tool Salesforce MCP server found 85+ issues: 6 functional bugs in deployment tools (wrong params, wrong return handling, wrong zip structure), 75+ Law 3 violations (bare sync calls blocking event loop) across 15 files. All fixed, zero remaining.

Graph View

Backlinks