decodingtrust-agent-sdk 0.1.0__py3-none-any.whl

dt_arena/mcp_server/salesforce/main.py

@@ -0,0 +1,2006 @@
+import os
+import sys
+import asyncio
+from typing import Any, Dict, List, Mapping, Optional, Union
+from pathlib import Path
+try:
+    import yaml  # type: ignore
+except Exception:
+    yaml = None
+
+import httpx
+from fastmcp import FastMCP
+
+
+# Basic configuration
+SALESFORCE_BASE_URL = os.getenv("SALESFORCE_BASE_URL", "http://128.111.28.87:8080/")
+SALESFORCE_TOKEN_URL = f"{SALESFORCE_BASE_URL.rstrip('/')}/Api/access_token"
+
+# Grant configuration (env fallbacks)
+SALESFORCE_GRANT_TYPE = os.getenv("SALESFORCE_GRANT_TYPE", "password")  # or "client_credentials"
+SALESFORCE_CLIENT_ID = os.getenv("SALESFORCE_CLIENT_ID", "")
+SALESFORCE_CLIENT_SECRET = os.getenv("SALESFORCE_CLIENT_SECRET", "")
+SALESFORCE_USERNAME = os.getenv("SALESFORCE_USERNAME", "")
+SALESFORCE_PASSWORD = os.getenv("SALESFORCE_PASSWORD", "")
+
+# Optional pre-supplied access token
+SALESFORCE_ACCESS_TOKEN = os.getenv("SALESFORCE_ACCESS_TOKEN", "")
+
+
+mcp = FastMCP("Salesforce MCP Server")
+
+
+def _bearer_headers(token: Optional[str]) -> Dict[str, str]:
+    headers: Dict[str, str] = {}
+    if token:
+        headers["Authorization"] = f"Bearer {token}"
+    return headers
+
+
+# JSON:API header constants
+JSONAPI_ACCEPT = "application/vnd.api+json"
+JSONAPI_CONTENT = "application/vnd.api+json"
+
+
+async def _request(
+    method: str,
+    url: str,
+    token: Optional[str] = None,
+    params: Optional[Dict[str, Any]] = None,
+    json: Optional[Any] = None,
+    data: Optional[Any] = None,
+    extra_headers: Optional[Dict[str, str]] = None,
+) -> Any:
+    """Unified HTTP request with structured error responses.
+
+    Returns parsed JSON on success; otherwise returns {error, status_code, text}.
+    """
+    headers = _bearer_headers(token)
+    if extra_headers:
+        headers.update(extra_headers)
+    try:
+        async with httpx.AsyncClient(timeout=30.0) as client:
+            r = await client.request(method, url, params=params, json=json, data=data, headers=headers)
+            # Try JSON first; if fails, fallback to text
+            r.raise_for_status()
+            try:
+                return r.json()
+            except Exception:
+                return {"ok": True, "text": r.text}
+    except httpx.HTTPStatusError as e:
+        resp = e.response
+        return {
+            "error": f"HTTP {resp.status_code}",
+            "status_code": resp.status_code,
+            "text": resp.text,
+        }
+    except httpx.RequestError as e:
+        return {"error": "request_error", "message": str(e)}
+
+
+async def _get_token(access_token: Optional[str] = None) -> str:
+    """Get an access token. If not provided, attempt to obtain via configured grant."""
+    token = (access_token or SALESFORCE_ACCESS_TOKEN).strip()
+    if token:
+        return token
+    # Try to fetch a token using configured grant
+    return await _post_token()
+
+
+# ------------------------------
+# Internal HTTP helpers (non-tool)
+# These are used by higher-level tool wrappers to avoid calling tool functions directly.
+# ------------------------------
+
+async def _http_get_available_modules(token: Optional[str] = None) -> Any:
+    tok = await _get_token(token)
+    url = f"{SALESFORCE_BASE_URL.rstrip('/')}/Api/V8/meta/modules"
+    return await _request("GET", url, tok, extra_headers={"Accept": JSONAPI_ACCEPT})
+
+
+async def _http_get_entry(module_name: str, record_id: str, fields: Optional[List[str]] = None, token: Optional[str] = None) -> Any:
+    tok = await _get_token(token)
+    url = f"{SALESFORCE_BASE_URL.rstrip('/')}/Api/V8/module/{module_name}/{record_id}"
+    params = _fields_param(module_name, fields)
+    return await _request("GET", url, tok, params=params, extra_headers={"Accept": JSONAPI_ACCEPT})
+
+
+async def _http_list_records(module_name: str, filter: Optional[Dict[str, Any]] = None, sort: Optional[str] = None, page: int = 1, page_size: int = 20, fields: Optional[List[str]] = None, token: Optional[str] = None) -> Any:
+    tok = await _get_token(token)
+    url = f"{SALESFORCE_BASE_URL.rstrip('/')}/Api/V8/module/{module_name}"
+    params: Dict[str, Any] = {"page[number]": page or 1, "page[size]": page_size or 20}
+    if sort:
+        params["sort"] = sort
+    if fields:
+        params.update(_fields_param(module_name, fields))
+    if filter:
+        operator = str(filter.get("operator", "and"))
+        filt = dict(filter)
+        if "operator" in filt:
+            del filt["operator"]
+        params.update(_filters_params(operator, filt))
+    return await _request("GET", url, tok, params=params, extra_headers={"Accept": JSONAPI_ACCEPT})
+
+
+async def _http_create_record(module_name: str, attributes: Dict[str, Any], relationships: Optional[Dict[str, Any]] = None, token: Optional[str] = None) -> Any:
+    tok = await _get_token(token)
+    url = f"{SALESFORCE_BASE_URL.rstrip('/')}/Api/V8/module"
+    payload: Dict[str, Any] = {"data": {"type": module_name, "attributes": attributes}}
+    if relationships:
+        payload["data"]["relationships"] = relationships
+    return await _request("POST", url, tok, json=payload, extra_headers={"Accept": JSONAPI_ACCEPT, "Content-Type": JSONAPI_CONTENT})
+
+
+async def _http_update_record(module_name: str, record_id: str, attributes: Dict[str, Any], relationships: Optional[Dict[str, Any]] = None, token: Optional[str] = None) -> Any:
+    tok = await _get_token(token)
+    url = f"{SALESFORCE_BASE_URL.rstrip('/')}/Api/V8/module"
+    payload: Dict[str, Any] = {"data": {"type": module_name, "id": record_id, "attributes": attributes}}
+    if relationships:
+        payload["data"]["relationships"] = relationships
+    return await _request("PATCH", url, tok, json=payload, extra_headers={"Accept": JSONAPI_ACCEPT, "Content-Type": JSONAPI_CONTENT})
+
+
+async def _http_delete_entry(module_name: str, record_id: str, token: Optional[str] = None) -> Any:
+    tok = await _get_token(token)
+    url = f"{SALESFORCE_BASE_URL.rstrip('/')}/Api/V8/module/{module_name}/{record_id}"
+    return await _request("DELETE", url, tok, extra_headers={"Accept": JSONAPI_ACCEPT})
+
+
+async def _http_get_relationships(module_name: str, record_id: str, relationship_name: str, page: int = 1, page_size: int = 20, token: Optional[str] = None) -> Any:
+    tok = await _get_token(token)
+    url = f"{SALESFORCE_BASE_URL.rstrip('/')}/Api/V8/module/{module_name}/{record_id}/relationships/{relationship_name}"
+    params = {"page[number]": page or 1, "page[size]": page_size or 20}
+    return await _request("GET", url, tok, params=params, extra_headers={"Accept": JSONAPI_ACCEPT})
+
+
+async def _http_set_relationship(module_name: str, record_id: str, relationship_name: str, related_data: Union[List[Dict[str, str]], Dict[str, str]], token: Optional[str] = None) -> Any:
+    tok = await _get_token(token)
+    url = f"{SALESFORCE_BASE_URL.rstrip('/')}/Api/V8/module/{module_name}/{record_id}/relationships/{relationship_name}"
+    payload = {"data": related_data}
+    return await _request("POST", url, tok, json=payload, extra_headers={"Accept": JSONAPI_ACCEPT, "Content-Type": JSONAPI_CONTENT})
+
+
+async def _http_get_module_fields(module_name: str, token: Optional[str] = None) -> Any:
+    tok = await _get_token(token)
+    url = f"{SALESFORCE_BASE_URL.rstrip('/')}/Api/V8/meta/fields/{module_name}"
+    return await _request("GET", url, tok, extra_headers={"Accept": JSONAPI_ACCEPT})
+
+
+async def _post_token(override_grant_type: Optional[str] = None, username: Optional[str] = None, password: Optional[str] = None) -> str:
+    """Obtain an OAuth2 access token from Salesforce.
+
+    Supports grant types: password, client_credentials.
+    Env fallbacks are used when parameters are not provided.
+    """
+    grant_type = (override_grant_type or SALESFORCE_GRANT_TYPE or "password").strip()
+    client_id = SALESFORCE_CLIENT_ID
+    client_secret = SALESFORCE_CLIENT_SECRET
+
+    data: Dict[str, str] = {"grant_type": grant_type}
+    if grant_type == "password":
+        data.update(
+            {
+                "username": username or SALESFORCE_USERNAME,
+                "password": password or SALESFORCE_PASSWORD,
+                "client_id": client_id,
+                "client_secret": client_secret,
+            }
+        )
+    elif grant_type == "client_credentials":
+        data.update(
+            {
+                "client_id": client_id,
+                "client_secret": client_secret,
+            }
+        )
+    else:
+        raise ValueError(f"Unsupported grant_type: {grant_type}")
+
+    # Token endpoint expects form data; be explicit about Accept
+    headers = {"Accept": "application/json"}
+    async with httpx.AsyncClient(timeout=30.0) as client:
+        r = await client.post(SALESFORCE_TOKEN_URL, data=data, headers=headers)
+        r.raise_for_status()
+        resp = r.json()
+        token = resp.get("access_token") or resp.get("token")
+        if not token:
+            raise RuntimeError(f"Failed to obtain access token: {resp}")
+        return token
+
+
+def _resolve_token(access_token: Optional[str]) -> str:
+    token = (access_token or SALESFORCE_ACCESS_TOKEN).strip()
+    if token:
+        return token
+    # Fallback to env-driven token fetch (best-effort)
+    raise RuntimeError("Missing access token. Provide 'access_token' or configure SALESFORCE_* credentials for automatic fetch.")
+
+
+def _fields_param(module_name: str, fields: Optional[List[str]]) -> Dict[str, str]:
+    if not fields:
+        return {}
+    return {f"fields[{module_name}]": ",".join(fields)}
+
+
+def _filters_params(operator: str, filters: Optional[Mapping[str, Mapping[str, Any]]]) -> Dict[str, str]:
+    params: Dict[str, str] = {}
+    if operator:
+        params["filter[operator]"] = operator
+    if not filters:
+        return params
+    for field_name, ops in filters.items():
+        for cmp_op, value in ops.items():
+            params[f"filter[{field_name}][{cmp_op}]"] = str(value)
+    return params
+
+
+# Note: Token acquisition can be handled automatically at startup if SALESFORCE_* credentials are provided.
+
+@mcp.tool()
+async def meta_modules() -> Any:
+    """List available Salesforce CRM modules for the authenticated user.
+
+    Returns:
+        JSON payload with list of available modules and their metadata.
+    """
+    token = await _get_token()
+    url = f"{SALESFORCE_BASE_URL.rstrip('/')}/Api/V8/meta/modules"
+    return await _request("GET", url, token, extra_headers={"Accept": JSONAPI_ACCEPT})
+
+
+@mcp.tool()
+async def meta_fields(module_name: str) -> Any:
+    """List field metadata for a module. Use this to discover valid field names and types before creating or updating records.
+
+    Args:
+        module_name: CRM module name. Available modules: "Accounts", "Contacts", "Leads",
+            "Opportunities", "Cases", "Notes", "Tasks", "Meetings", "Calls".
+            Use meta_modules() to see the full list.
+
+    Returns:
+        JSON payload with field definitions including types, labels, and options.
+    """
+    token = await _get_token()
+    url = f"{SALESFORCE_BASE_URL.rstrip('/')}/Api/V8/meta/fields/{module_name}"
+    return await _request("GET", url, token, extra_headers={"Accept": JSONAPI_ACCEPT})
+
+
+@mcp.tool()
+async def get_record(module_name: str, record_id: str, fields: Optional[List[str]] = None) -> Any:
+    """Get a single record by id.
+
+    Args:
+        module_name: CRM module name. Available modules: "Accounts", "Contacts", "Leads",
+            "Opportunities", "Cases", "Notes", "Tasks", "Meetings", "Calls".
+            Use meta_modules() to see the full list.
+        record_id: Record GUID.
+        fields: Optional list of field names to include in response.
+
+    Returns:
+        JSON:API response with record data including id, type, and attributes.
+    """
+    token = await _get_token()
+    url = f"{SALESFORCE_BASE_URL.rstrip('/')}/Api/V8/module/{module_name}/{record_id}"
+    params: Dict[str, str] = _fields_param(module_name, fields)
+    return await _request("GET", url, token, params=params, extra_headers={"Accept": JSONAPI_ACCEPT})
+
+
+@mcp.tool()
+async def list_records(
+    module_name: str,
+    fields: Optional[List[str]] = None,
+    page_number: int = 1,
+    page_size: int = 20,
+    sort: Optional[str] = None,
+    operator: str = "and",
+    filters: Optional[Mapping[str, Mapping[str, Any]]] = None,
+) -> Any:
+    """List records for a module with pagination, fields, sort and filters.
+
+    Args:
+      module_name: CRM module name. Available modules: "Accounts", "Contacts", "Leads",
+            "Opportunities", "Cases", "Notes", "Tasks", "Meetings", "Calls".
+            Use meta_modules() to see the full list.
+      fields: Optional list of fields to include in response.
+      page_number: Page index (1-based).
+      page_size: Page size (default 20).
+      sort: Comma-separated field list with optional '-' prefix for desc.
+      operator: Logical operator for filters ("and"/"or").
+      filters: JSON:API filter mapping, e.g., {"name": {"eq": "Acme"}}.
+
+    Returns:
+        Paginated list of records with id, type, and attributes.
+    """
+    try:
+        token = await _get_token()
+        url = f"{SALESFORCE_BASE_URL.rstrip('/')}/Api/V8/module/{module_name}"
+        params: Dict[str, Any] = {
+            "page[number]": page_number,
+            "page[size]": page_size,
+        }
+        if sort:
+            params["sort"] = sort
+        if fields:
+            params.update(_fields_param(module_name, fields))
+        if filters:
+            params.update(_filters_params(operator, filters))
+        return await _request("GET", url, token, params=params, extra_headers={"Accept": JSONAPI_ACCEPT})
+    except Exception as e:
+        return {"error": True, "exception": type(e).__name__, "message": str(e)}
+
+
+@mcp.tool()
+async def list_leads(
+    page: Optional[int] = 1,
+    page_size: Optional[int] = 20,
+) -> Any:
+    """List all leads in the CRM system.
+
+    Args:
+        page: Index of the target page to retrieve (1-based, default 1).
+        page_size: Number of records per page to segment the lead list (default 20).
+
+    Returns:
+        List of lead records with id, type, and attributes (first_name, last_name,
+        account_name, phone_work, email1, date_entered).
+    """
+    return await _http_list_records(
+        "Leads",
+        filter=None,
+        sort="-date_entered",
+        page=page or 1,
+        page_size=page_size or 20,
+        fields=["first_name", "last_name", "account_name", "phone_work", "email1", "status", "date_entered"],
+    )
+
+
+
+@mcp.tool()
+async def create_record(module_name: str, attributes: Dict[str, Any]) -> Any:
+    """Create a CRM record for any module. This is the generic record creation tool.
+
+    Args:
+        module_name: CRM module name. Available modules: "Accounts", "Contacts", "Leads",
+            "Opportunities", "Cases", "Notes", "Tasks", "Meetings", "Calls".
+            Use meta_modules() to see the full list.
+        attributes: Dictionary of field names and values. Common attributes per module:
+            - Notes: {"name": "title", "description": "body text", "contact_id": "GUID",
+              "parent_type": "Accounts", "parent_id": "GUID", "assigned_user_id": "GUID"}
+            - Tasks: {"name": "subject", "status": "Not Started", "priority": "High",
+              "date_due": "YYYY-MM-DD HH:MM:SS", "description": "details",
+              "contact_id": "GUID", "parent_type": "Accounts", "parent_id": "GUID"}
+            - Meetings: {"name": "subject", "status": "Planned|Held|Not Held",
+              "date_start": "YYYY-MM-DD HH:MM:SS", "duration_hours": 1,
+              "duration_minutes": 0, "description": "notes", "location": "place",
+              "parent_type": "Accounts", "parent_id": "GUID"}
+            - Calls: {"name": "subject", "direction": "Inbound|Outbound",
+              "status": "Planned|Held", "date_start": "YYYY-MM-DD HH:MM:SS",
+              "duration_hours": 0, "duration_minutes": 30, "description": "notes",
+              "parent_type": "Accounts", "parent_id": "GUID"}
+            - Accounts: {"name": "account name", "industry": "Technology",
+              "billing_address_city": "city", "phone_office": "number"}
+            - Contacts: {"first_name": "name", "last_name": "name",
+              "email1": "email", "phone_work": "number", "account_id": "GUID"}
+            - Leads: {"first_name": "name", "last_name": "name",
+              "email1": "email", "status": "New", "account_name": "company"}
+            - Opportunities: {"name": "deal name", "amount": 10000,
+              "sales_stage": "Prospecting", "date_closed": "YYYY-MM-DD",
+              "account_id": "GUID"}
+            - Cases: {"name": "case title", "status": "Open_New",
+              "priority": "P1|P2|P3", "description": "details",
+              "account_id": "GUID", "contact_id": "GUID"}
+            Use meta_fields(module_name) to discover all valid fields for a module.
+
+    Returns:
+        JSON:API response with created record data including generated id.
+    """
+    token = await _get_token()
+    url = f"{SALESFORCE_BASE_URL.rstrip('/')}/Api/V8/module"
+    payload = {"data": {"type": module_name, "attributes": attributes}}
+    return await _request(
+        "POST",
+        url,
+        token,
+        json=payload,
+        extra_headers={"Accept": JSONAPI_ACCEPT, "Content-Type": JSONAPI_CONTENT},
+    )
+
+
+@mcp.tool()
+async def update_record(module_name: str, record_id: str, attributes: Dict[str, Any]) -> Any:
+    """Update an existing CRM record by id (partial update).
+
+    Args:
+        module_name: CRM module name. Available modules: "Accounts", "Contacts", "Leads",
+            "Opportunities", "Cases", "Notes", "Tasks", "Meetings", "Calls".
+            Use meta_modules() to see the full list.
+        record_id: Record GUID to update.
+        attributes: Dictionary of field names and values to update. Only include fields
+            you want to change. See create_record() for common attributes per module.
+
+    Returns:
+        JSON:API response with updated record data.
+    """
+    token = await _get_token()
+    url = f"{SALESFORCE_BASE_URL.rstrip('/')}/Api/V8/module"
+    payload = {"data": {"type": module_name, "id": record_id, "attributes": attributes}}
+    return await _request(
+        "PATCH",
+        url,
+        token,
+        json=payload,
+        extra_headers={"Accept": JSONAPI_ACCEPT, "Content-Type": JSONAPI_CONTENT},
+    )
+
+
+@mcp.tool()
+async def delete_record(module_name: str, record_id: str) -> Any:
+    """Delete a Salesforce CRM record by id.
+
+    Args:
+        module_name: CRM module name. Available modules: "Accounts", "Contacts", "Leads",
+            "Opportunities", "Cases", "Notes", "Tasks", "Meetings", "Calls".
+            Use meta_modules() to see the full list.
+        record_id: Record GUID to delete.
+
+    Returns:
+        Success confirmation or error details.
+    """
+    token = await _get_token()
+    url = f"{SALESFORCE_BASE_URL.rstrip('/')}/Api/V8/module/{module_name}/{record_id}"
+    resp = await _request("DELETE", url, token, extra_headers={"Accept": JSONAPI_ACCEPT})
+    # Keep consistent success envelope if server returns empty body
+    if isinstance(resp, dict) and resp.get("error"):
+        return resp
+    return resp or {"ok": True, "id": record_id}
+
+
+@mcp.tool()
+async def relationship_get(module_name: str, record_id: str, link_field_name: str) -> Any:
+    """Get related records for a given record's relationship field.
+
+    Args:
+        module_name: CRM module name. Available modules: "Accounts", "Contacts", "Leads",
+            "Opportunities", "Cases", "Notes", "Tasks", "Meetings", "Calls".
+            Use meta_modules() to see the full list.
+        record_id: Record GUID.
+        link_field_name: Relationship link name (e.g., "contacts", "opportunities", "notes", "tasks", "meetings", "calls").
+
+    Returns:
+        JSON:API response with list of related records.
+    """
+    token = await _get_token()
+    url = f"{SALESFORCE_BASE_URL.rstrip('/')}/Api/V8/module/{module_name}/{record_id}/relationships/{link_field_name}"
+    return await _request("GET", url, token, extra_headers={"Accept": JSONAPI_ACCEPT})
+
+
+@mcp.tool()
+async def relationship_create(
+    module_name: str,
+    record_id: str,
+    link_field_name: str,
+    related_module_name: str,
+    related_record_id: str,
+) -> Any:
+    """Create a relationship link from a record to another record.
+
+    Args:
+        module_name: Source CRM module name. Available modules: "Accounts", "Contacts", "Leads",
+            "Opportunities", "Cases", "Notes", "Tasks", "Meetings", "Calls".
+            Use meta_modules() to see the full list.
+        record_id: Source record GUID.
+        link_field_name: Relationship link field name on source (e.g., "contacts", "opportunities", "notes", "tasks").
+        related_module_name: Target module name (e.g., "Contacts", "Notes", "Tasks").
+        related_record_id: Target record GUID.
+
+    Returns:
+        JSON:API response confirming the relationship creation.
+    """
+    token = await _get_token()
+    url = f"{SALESFORCE_BASE_URL.rstrip('/')}/Api/V8/module/{module_name}/{record_id}/relationships/{link_field_name}"
+    payload = {"data": {"type": related_module_name, "id": related_record_id}}
+    return await _request(
+        "POST",
+        url,
+        token,
+        json=payload,
+        extra_headers={"Accept": JSONAPI_ACCEPT, "Content-Type": JSONAPI_CONTENT},
+    )
+
+
+@mcp.tool()
+async def relationship_delete(
+    module_name: str,
+    record_id: str,
+    link_field_name: str,
+    related_record_id: str,
+) -> Any:
+    """Remove a relationship between records.
+
+    Args:
+        module_name: Source CRM module name. Available modules: "Accounts", "Contacts", "Leads",
+            "Opportunities", "Cases", "Notes", "Tasks", "Meetings", "Calls".
+            Use meta_modules() to see the full list.
+        record_id: Source record GUID.
+        link_field_name: Relationship link field name on source (e.g., "contacts", "opportunities", "notes", "tasks").
+        related_record_id: Target record GUID to unlink.
+
+    Returns:
+        Success confirmation or error details.
+    """
+    token = await _get_token()
+    url = f"{SALESFORCE_BASE_URL.rstrip('/')}/Api/V8/module/{module_name}/{record_id}/relationships/{link_field_name}/{related_record_id}"
+    resp = await _request("DELETE", url, token, extra_headers={"Accept": JSONAPI_ACCEPT})
+    if isinstance(resp, dict) and resp.get("error"):
+        return resp
+    return resp or {"ok": True}
+
+
+@mcp.tool()
+async def logout() -> Any:
+    """Invalidate the current session token (server-side logout).
+
+    Returns:
+        Success confirmation or error details.
+    """
+    token = await _get_token()
+    url = f"{SALESFORCE_BASE_URL.rstrip('/')}/Api/V8/logout"
+    resp = await _request("POST", url, token, extra_headers={"Accept": JSONAPI_ACCEPT})
+    if isinstance(resp, dict) and resp.get("error"):
+        return resp
+    return resp or {"ok": True}
+
+
+@mcp.tool()
+async def health() -> Any:
+    """Health check: probe root path, meta/modules, and access_token endpoints.
+
+    Returns:
+        Dictionary with status of root, meta_modules, and access_token endpoints.
+    """
+    base = SALESFORCE_BASE_URL.rstrip("/")
+    results: Dict[str, Any] = {}
+    # Root
+    try:
+        async with httpx.AsyncClient(timeout=10.0) as client:
+            r = await client.get(f"{base}/")
+            results["root"] = {"status": r.status_code}
+    except Exception as e:
+        results["root"] = {"error": str(e)}
+
+    # meta/modules (expect 401/403 when unauthenticated; 500 indicates server error)
+    res_meta = await _request("GET", f"{base}/Api/V8/meta/modules", None, extra_headers={"Accept": JSONAPI_ACCEPT})
+    results["meta_modules"] = res_meta if isinstance(res_meta, dict) else {"ok": True}
+
+    # access_token (probing with invalid credentials should return 400/401; 500 indicates server error)
+    try:
+        async with httpx.AsyncClient(timeout=10.0) as client:
+            r = await client.post(f"{base}/Api/access_token", data={"grant_type": "client_credentials", "client_id": "x", "client_secret": "y"}, headers={"Accept": "application/json"})
+            results["access_token"] = {"status": r.status_code, "text": (r.text[:200] if r.text else "")}
+    except Exception as e:
+        results["access_token"] = {"error": str(e)}
+
+    return results
+
+
+async def _ensure_token_on_startup() -> None:
+    """Try to acquire SALESFORCE_ACCESS_TOKEN using configured credentials (non-blocking)."""
+    token = (os.getenv("SALESFORCE_ACCESS_TOKEN") or "").strip()
+    if token:
+        return
+    try:
+        fetched = await _post_token()
+        os.environ["SALESFORCE_ACCESS_TOKEN"] = fetched
+        print("Salesforce access token acquired on startup.", file=sys.stderr)
+    except Exception as e:
+        # Do not block server; tools will attempt token acquisition when called.
+        print(f"Salesforce token acquisition skipped on startup: {e}", file=sys.stderr)
+
+
+def main() -> None:
+    print("Starting Salesforce MCP Server...", file=sys.stderr)
+    sys.stderr.flush()
+    try:
+        asyncio.run(_ensure_token_on_startup())
+    except RuntimeError:
+        pass
+    host = os.getenv("SALESFORCE_MCP_HOST", "localhost")
+    def _port_from_registry(default_port: int) -> int:
+        try:
+            if yaml is None:
+                return default_port
+            registry_path = Path(__file__).resolve().parent.parent / "registry.yaml"
+            if not registry_path.exists():
+                return default_port
+            data = yaml.safe_load(registry_path.read_text()) or {}
+            service_name = Path(__file__).resolve().parent.name  # 'salesforce'
+            for srv in (data.get("servers") or []):
+                if isinstance(srv, dict) and srv.get("name") == service_name:
+                    env = srv.get("env") or {}
+                    port_str = str(env.get("PORT") or "").strip().strip('\"')
+                    return int(port_str) if port_str else default_port
+        except Exception:
+            return default_port
+        return default_port
+    # Prefer PORT env var, then registry, then default
+    env_port = os.getenv("PORT", "").strip()
+    if env_port.isdigit():
+        port = int(env_port)
+    else:
+        port = _port_from_registry(8845)
+    mcp.run(transport="http", host=host, port=port)
+
+@mcp.tool()
+async def get_available_modules() -> Any:
+    """List available modules for the authenticated user.
+
+    Returns:
+        JSON payload with list of available modules and their metadata.
+    """
+    token = await _get_token()
+    url = f"{SALESFORCE_BASE_URL.rstrip('/')}/Api/V8/meta/modules"
+    return await _request("GET", url, token, extra_headers={"Accept": JSONAPI_ACCEPT})
+
+
+@mcp.tool()
+async def get_entry_list(
+    module_name: str,
+    filter: Optional[Dict[str, Any]] = None,
+    sort: Optional[str] = None,
+    page: Optional[int] = 1,
+    page_size: Optional[int] = 20,
+    fields: Optional[List[str]] = None,
+) -> Any:
+    """Get a list of records from a specific module with optional filtering and pagination.
+
+    Args:
+        module_name: CRM module name. Available modules: "Accounts", "Contacts", "Leads",
+            "Opportunities", "Cases", "Notes", "Tasks", "Meetings", "Calls".
+            Use meta_modules() to see the full list.
+        filter: Filter object with field conditions (e.g., {"name": {"eq": "Acme"}}).
+        sort: Comma-separated field list with optional '-' prefix for descending.
+        page: Page number (1-based, default 1).
+        page_size: Number of records per page (default 20).
+        fields: Optional list of field names to include in response.
+
+    Returns:
+        JSON:API response with list of records and pagination metadata.
+    """
+    token = await _get_token()
+    url = f"{SALESFORCE_BASE_URL.rstrip('/')}/Api/V8/module/{module_name}"
+    params: Dict[str, Any] = {
+        "page[number]": page or 1,
+        "page[size]": page_size or 20,
+    }
+    if sort:
+        params["sort"] = sort
+    if fields:
+        params.update(_fields_param(module_name, fields))
+    # Translate filter object: supports embedded operator and field ops
+    if filter:
+        operator = str(filter.get("operator", "and"))
+        filt = dict(filter)
+        if "operator" in filt:
+            del filt["operator"]
+        params.update(_filters_params(operator, filt))
+    return await _request("GET", url, token, params=params, extra_headers={"Accept": JSONAPI_ACCEPT})
+
+
+@mcp.tool()
+async def get_entry(module_name: str, id: str, fields: Optional[List[str]] = None) -> Any:
+    """Get a single entry by id.
+
+    Args:
+        module_name: CRM module name. Available modules: "Accounts", "Contacts", "Leads",
+            "Opportunities", "Cases", "Notes", "Tasks", "Meetings", "Calls".
+            Use meta_modules() to see the full list.
+        id: Record GUID.
+        fields: Optional list of field names to include in response.
+
+    Returns:
+        JSON:API response with record data including id, type, and attributes.
+    """
+    token = await _get_token()
+    url = f"{SALESFORCE_BASE_URL.rstrip('/')}/Api/V8/module/{module_name}/{id}"
+    params = _fields_param(module_name, fields)
+    return await _request("GET", url, token, params=params, extra_headers={"Accept": JSONAPI_ACCEPT})
+
+
+@mcp.tool()
+async def set_entry(
+    module_name: str,
+    attributes: Dict[str, Any],
+    relationships: Optional[Dict[str, Any]] = None,
+) -> Any:
+    """Create a new record in any CRM module.
+
+    Args:
+        module_name: CRM module name. Available modules: "Accounts", "Contacts", "Leads",
+            "Opportunities", "Cases", "Notes", "Tasks", "Meetings", "Calls".
+            Use meta_modules() to see the full list.
+        attributes: Dictionary of field names and values. Common attributes per module:
+            - Notes: {"name": "title", "description": "body text", "contact_id": "GUID",
+              "parent_type": "Accounts", "parent_id": "GUID", "assigned_user_id": "GUID"}
+            - Tasks: {"name": "subject", "status": "Not Started", "priority": "High",
+              "date_due": "YYYY-MM-DD HH:MM:SS", "description": "details",
+              "contact_id": "GUID", "parent_type": "Accounts", "parent_id": "GUID"}
+            - Meetings: {"name": "subject", "status": "Planned|Held|Not Held",
+              "date_start": "YYYY-MM-DD HH:MM:SS", "duration_hours": 1,
+              "duration_minutes": 0, "description": "notes", "location": "place",
+              "parent_type": "Accounts", "parent_id": "GUID"}
+            - Calls: {"name": "subject", "direction": "Inbound|Outbound",
+              "status": "Planned|Held", "date_start": "YYYY-MM-DD HH:MM:SS",
+              "duration_hours": 0, "duration_minutes": 30, "description": "notes",
+              "parent_type": "Accounts", "parent_id": "GUID"}
+            Use meta_fields(module_name) to discover all valid fields for a module.
+        relationships: Optional dictionary of relationship links.
+
+    Returns:
+        JSON:API response with created record data including generated id.
+    """
+    token = await _get_token()
+    url = f"{SALESFORCE_BASE_URL.rstrip('/')}/Api/V8/module"
+    payload: Dict[str, Any] = {"data": {"type": module_name, "attributes": attributes}}
+    if relationships:
+        payload["data"]["relationships"] = relationships
+    return await _request(
+        "POST",
+        url,
+        token,
+        json=payload,
+        extra_headers={"Accept": JSONAPI_ACCEPT, "Content-Type": JSONAPI_CONTENT},
+    )
+
+
+@mcp.tool()
+async def update_entry(
+    module_name: str,
+    id: str,
+    attributes: Dict[str, Any],
+    relationships: Optional[Dict[str, Any]] = None,
+) -> Any:
+    """Update an existing record in any CRM module (partial update).
+
+    Args:
+        module_name: CRM module name. Available modules: "Accounts", "Contacts", "Leads",
+            "Opportunities", "Cases", "Notes", "Tasks", "Meetings", "Calls".
+            Use meta_modules() to see the full list.
+        id: Record GUID to update.
+        attributes: Dictionary of field names and values to update. Only include fields
+            you want to change. See set_entry() or create_record() for common attributes per module.
+        relationships: Optional dictionary of relationship links to update.
+
+    Returns:
+        JSON:API response with updated record data.
+    """
+    token = await _get_token()
+    url = f"{SALESFORCE_BASE_URL.rstrip('/')}/Api/V8/module"
+    payload: Dict[str, Any] = {"data": {"type": module_name, "id": id, "attributes": attributes}}
+    if relationships:
+        payload["data"]["relationships"] = relationships
+    return await _request(
+        "PATCH",
+        url,
+        token,
+        json=payload,
+        extra_headers={"Accept": JSONAPI_ACCEPT, "Content-Type": JSONAPI_CONTENT},
+    )
+
+
+@mcp.tool()
+async def delete_entry(module_name: str, id: str) -> Any:
+    """Delete an entry by id.
+
+    Args:
+        module_name: CRM module name. Available modules: "Accounts", "Contacts", "Leads",
+            "Opportunities", "Cases", "Notes", "Tasks", "Meetings", "Calls".
+            Use meta_modules() to see the full list.
+        id: Record GUID to delete.
+
+    Returns:
+        Success confirmation or error details.
+    """
+    token = await _get_token()
+    url = f"{SALESFORCE_BASE_URL.rstrip('/')}/Api/V8/module/{module_name}/{id}"
+    return await _request("DELETE", url, token, extra_headers={"Accept": JSONAPI_ACCEPT})
+
+
+@mcp.tool()
+async def get_relationships(
+    module_name: str,
+    id: str,
+    relationship_name: str,
+    page: Optional[int] = 1,
+    page_size: Optional[int] = 20,
+) -> Any:
+    """List related records for an entry with pagination.
+
+    Args:
+        module_name: CRM module name. Available modules: "Accounts", "Contacts", "Leads",
+            "Opportunities", "Cases", "Notes", "Tasks", "Meetings", "Calls".
+            Use meta_modules() to see the full list.
+        id: Record GUID.
+        relationship_name: Link/relationship name (e.g., "contacts", "opportunities", "notes", "tasks", "meetings", "calls").
+        page: Page number (1-based, default 1).
+        page_size: Number of records per page (default 20).
+
+    Returns:
+        JSON:API response with list of related records.
+    """
+    token = await _get_token()
+    url = f"{SALESFORCE_BASE_URL.rstrip('/')}/Api/V8/module/{module_name}/{id}/relationships/{relationship_name}"
+    params = {"page[number]": page or 1, "page[size]": page_size or 20}
+    return await _request("GET", url, token, params=params, extra_headers={"Accept": JSONAPI_ACCEPT})
+
+
+@mcp.tool()
+async def set_relationship(
+    module_name: str,
+    id: str,
+    relationship_name: str,
+    related_data: Dict[str, str],
+) -> Any:
+    """Set (replace or add) relationships for a record.
+
+    Args:
+        module_name: CRM module name. Available modules: "Accounts", "Contacts", "Leads",
+            "Opportunities", "Cases", "Notes", "Tasks", "Meetings", "Calls".
+            Use meta_modules() to see the full list.
+        id: Record GUID.
+        relationship_name: Relationship link name (e.g., "contacts", "opportunities", "notes", "tasks").
+        related_data: Linkage object with 'type' and 'id' keys.
+
+    Returns:
+        JSON:API response confirming the relationship update.
+    """
+    token = await _get_token()
+    url = f"{SALESFORCE_BASE_URL.rstrip('/')}/Api/V8/module/{module_name}/{id}/relationships/{relationship_name}"
+    payload = {"data": related_data}
+    return await _request(
+        "POST",
+        url,
+        token,
+        json=payload,
+        extra_headers={"Accept": JSONAPI_ACCEPT, "Content-Type": JSONAPI_CONTENT},
+    )
+
+
+@mcp.tool()
+async def get_module_fields(module_name: str) -> Any:
+    """List field metadata for a module. Use this to discover all valid field names and types before creating or updating records.
+
+    Args:
+        module_name: CRM module name. Available modules: "Accounts", "Contacts", "Leads",
+            "Opportunities", "Cases", "Notes", "Tasks", "Meetings", "Calls".
+            Use meta_modules() to see the full list.
+
+    Returns:
+        JSON payload with field definitions including types, labels, and options.
+    """
+    token = await _get_token()
+    url = f"{SALESFORCE_BASE_URL.rstrip('/')}/Api/V8/meta/fields/{module_name}"
+    return await _request("GET", url, token, extra_headers={"Accept": JSONAPI_ACCEPT})
+
+
+# ============ Lead-specific tools ============
+
+def _sanitize_attributes(attributes: Dict[str, Any]) -> Dict[str, Any]:
+    excluded = {"id", "lead_id", "date_entered", "date_modified", "modified_user_id", "created_by", "created_by_name"}
+    out: Dict[str, Any] = {}
+    for k, v in attributes.items():
+        if k in excluded:
+            continue
+        if isinstance(v, (str, int, float, bool)) or v is None:
+            out[k] = v
+    return out
+
+
+async def _get_field_options(module_name: str, field_name: str) -> List[str]:
+    resp = await _http_get_module_fields(module_name)
+    # Try common shapes
+    options: List[str] = []
+    if isinstance(resp, dict):
+        data = resp.get("data") or resp
+        attrs = None
+        if isinstance(data, dict):
+            attrs = data.get("attributes") or data.get("fields")
+        fields_obj = None
+        if attrs and isinstance(attrs, dict):
+            fields_obj = attrs.get("fields") or attrs
+        if fields_obj and isinstance(fields_obj, dict):
+            field = fields_obj.get(field_name)
+            if isinstance(field, dict):
+                opts = field.get("options")
+                if isinstance(opts, dict):
+                    options = list(opts.keys())
+    return options
+
+
+@mcp.tool()
+async def create_lead(
+    first_name: str,
+    last_name: str,
+    title: Optional[str] = None,
+    account_name: Optional[str] = None,
+    email: Optional[str] = None,
+    phone_work: Optional[str] = None,
+    phone_mobile: Optional[str] = None,
+    lead_source: Optional[str] = None,
+    status: Optional[str] = None,
+    description: Optional[str] = None,
+    assigned_user_id: Optional[str] = None,
+) -> Any:
+    """Create a new Lead record.
+
+    Args:
+        first_name: Lead's first name (required).
+        last_name: Lead's last name (required).
+        title: Job title.
+        account_name: Company/account name.
+        email: Primary email address.
+        phone_work: Work phone number.
+        phone_mobile: Mobile phone number.
+        lead_source: Source of the lead (e.g., "Web", "Cold Call", "Referral").
+        status: Lead status (e.g., "New", "Assigned"). Defaults to "New".
+        description: Additional notes or description.
+        assigned_user_id: User GUID to assign the lead to.
+
+    Returns:
+        JSON:API response with the newly created lead record.
+    """
+    attributes: Dict[str, Any] = {
+        "first_name": first_name,
+        "last_name": last_name,
+    }
+    if status:
+        attributes["status"] = status
+    else:
+        attributes["status"] = "New"
+    if lead_source:
+        attributes["lead_source"] = lead_source
+    if title:
+        attributes["title"] = title
+    if account_name:
+        attributes["account_name"] = account_name
+    if email:
+        attributes["email1"] = email
+    if phone_work:
+        attributes["phone_work"] = phone_work
+    if phone_mobile:
+        attributes["phone_mobile"] = phone_mobile
+    if description:
+        attributes["description"] = description
+    if assigned_user_id:
+        attributes["assigned_user_id"] = assigned_user_id
+
+    # Note: Salesforce Leads module doesn't support JSON:API relationships in create requests,
+    # so we pass assigned_user_id as an attribute instead
+    return await _http_create_record("Leads", attributes)
+
+
+@mcp.tool()
+async def search_leads(
+    search_term: Optional[str] = None,
+    first_name: Optional[str] = None,
+    last_name: Optional[str] = None,
+    status: Optional[str] = None,
+    lead_source: Optional[str] = None,
+    assigned_user_id: Optional[str] = None,
+    created_after: Optional[str] = None,
+    created_before: Optional[str] = None,
+    page: Optional[int] = 1,
+    page_size: Optional[int] = 20,
+    search_operator: Optional[str] = "or",
+) -> Any:
+    """Search leads by person name, status, source, assignee, and date range.
+
+    Args:
+        search_term: Person name search in "FirstName LastName" format (e.g., "Robert Kim").
+            - Multi-word: First word matches first_name, last word matches last_name (AND).
+            - Single word: Searches across first_name, last_name, account_name (OR).
+            For more precise control, use first_name and last_name parameters instead.
+        first_name: Filter by first name (partial match with LIKE).
+        last_name: Filter by last name (partial match with LIKE).
+        status: Lead status code (e.g., "New", "Assigned", "Converted").
+        lead_source: Source code (e.g., "Web", "Cold Call", "Referral").
+        assigned_user_id: Filter by assigned user GUID.
+        created_after: ISO date string (YYYY-MM-DD) for minimum creation date.
+        created_before: ISO date string (YYYY-MM-DD) for maximum creation date.
+        page: Index of the target page to retrieve (1-based, default 1).
+        page_size: Number of records per page to segment the lead list (default 20).
+        search_operator: Logical operator for combining filters ("or" or "and", default "or").
+            Note: When search_term has multiple words, "and" is used automatically for name matching.
+
+    Returns:
+        JSON:API response with matching lead records.
+    """
+    filters: Dict[str, Any] = {}
+
+    # Handle search_term - intelligently parse multi-word searches
+    if search_term:
+        words = search_term.strip().split()
+        if len(words) >= 2:
+            # Multi-word search: assume "first_name last_name" format
+            # Use AND to match both parts
+            filters["operator"] = "and"
+            filters["first_name"] = {"like": f"%{words[0]}%"}
+            filters["last_name"] = {"like": f"%{words[-1]}%"}
+        else:
+            # Single word: search across all name fields with OR
+            filters["operator"] = "or"
+            like = f"%{search_term}%"
+            filters["first_name"] = {"like": like}
+            filters["last_name"] = {"like": like}
+            filters["account_name"] = {"like": like}
+    else:
+        # No search_term - use explicit first_name/last_name if provided
+        filters["operator"] = search_operator if search_operator in ("or", "and") else "and"
+        if first_name:
+            filters["first_name"] = {"like": f"%{first_name}%"}
+        if last_name:
+            filters["last_name"] = {"like": f"%{last_name}%"}
+
+    # Add other filters
+    if status:
+        filters["status"] = {"eq": status}
+    if lead_source:
+        filters["lead_source"] = {"eq": lead_source}
+    if assigned_user_id:
+        filters["assigned_user_id"] = {"eq": assigned_user_id}
+    if created_after or created_before:
+        filters["date_entered"] = {}
+        if created_after:
+            filters["date_entered"]["gt"] = created_after
+        if created_before:
+            filters["date_entered"]["lt"] = created_before
+
+    return await _http_list_records("Leads", filters, "-date_entered", page or 1, page_size or 20, ["first_name", "last_name", "account_name", "phone_work", "phone_mobile", "status"])  # type: ignore[arg-type]
+
+
+@mcp.tool()
+async def update_lead_status(lead_id: str, status: str, description: Optional[str] = None) -> Any:
+    """Update a lead's status and optional description.
+
+    Args:
+        lead_id: Lead record GUID.
+        status: New status value (e.g., "New", "Assigned", "In Process", "Converted").
+        description: Optional description text to update.
+
+    Returns:
+        JSON:API response with updated lead record.
+    """
+    attributes: Dict[str, Any] = {"status": status}
+    if description is not None:
+        attributes["description"] = description
+    return await _http_update_record("Leads", lead_id, attributes)
+
+
+@mcp.tool()
+async def assign_lead(lead_id: str, user_id: str, send_notification: Optional[bool] = True) -> Any:  # noqa: ARG002
+    """Assign a lead to a user.
+
+    Args:
+        lead_id: Lead record GUID.
+        user_id: User GUID to assign the lead to.
+        send_notification: Whether to send notification (not implemented in sandbox).
+
+    Returns:
+        JSON:API response with updated lead record.
+    """
+    return await _http_update_record("Leads", lead_id, {"assigned_user_id": user_id})
+
+
+@mcp.tool()
+async def convert_lead(
+    lead_id: str,
+    create_account: Optional[bool] = True,
+    create_contact: Optional[bool] = True,
+    create_opportunity: Optional[bool] = False,
+    opportunity_name: Optional[str] = None,
+    opportunity_amount: Optional[str] = None,
+) -> Any:
+    """Convert a lead into account, contact, and/or opportunity records.
+
+    Args:
+        lead_id: Lead record GUID to convert.
+        create_account: Whether to create an Account from the lead (default True).
+        create_contact: Whether to create a Contact from the lead (default True).
+        create_opportunity: Whether to create an Opportunity (default False).
+        opportunity_name: Name for the new opportunity (required if create_opportunity=True).
+        opportunity_amount: Amount for the new opportunity.
+
+    Returns:
+        Dictionary with lead_id and created record IDs (account_id, contact_id, opportunity_id).
+    """
+    lead_resp = await _http_get_entry("Leads", lead_id)
+    data = lead_resp.get("data") if isinstance(lead_resp, dict) else None
+    if not data or not isinstance(data, dict):
+        return {"error": "Lead not found"}
+    attrs = data.get("attributes", {})
+    results: Dict[str, Any] = {"lead_id": lead_id}
+
+    if create_account:
+        account_attrs = _sanitize_attributes({
+            "name": attrs.get("account_name") or f"{attrs.get('first_name','')} {attrs.get('last_name','')} - Account",
+            "phone_office": attrs.get("phone_work"),
+            "website": attrs.get("website"),
+            "description": attrs.get("description"),
+        })
+        acc = await _http_create_record("Accounts", account_attrs)
+        if isinstance(acc, dict) and acc.get("data") and acc["data"].get("id"):
+            results["account_id"] = acc["data"]["id"]
+
+    if create_contact:
+        contact_attrs = _sanitize_attributes({
+            "first_name": attrs.get("first_name"),
+            "last_name": attrs.get("last_name"),
+            "title": attrs.get("title"),
+            "email1": attrs.get("email1"),
+            "phone_work": attrs.get("phone_work"),
+            "phone_mobile": attrs.get("phone_mobile"),
+            "description": attrs.get("description"),
+        })
+        con = await _http_create_record("Contacts", contact_attrs)
+        if isinstance(con, dict) and con.get("data") and con["data"].get("id"):
+            results["contact_id"] = con["data"]["id"]
+
+    if create_opportunity and opportunity_name:
+        opportunity_attrs = {
+            "name": opportunity_name,
+            "amount": opportunity_amount or "",
+            "sales_stage": "Prospecting",
+            "lead_source": attrs.get("lead_source"),
+            "description": attrs.get("description"),
+        }
+        opp = await _http_create_record("Opportunities", opportunity_attrs)
+        if isinstance(opp, dict) and opp.get("data") and opp["data"].get("id"):
+            results["opportunity_id"] = opp["data"]["id"]
+
+    await _http_update_record("Leads", lead_id, {"status": "Converted"})
+    return results
+
+
+@mcp.tool()
+async def get_lead_status_options() -> Any:
+    """Get available lead status option values.
+
+    Returns:
+        List of valid status codes (e.g., "New", "Assigned", "In Process", "Converted").
+    """
+    return await _get_field_options("Leads", "status")
+
+
+@mcp.tool()
+async def get_lead_source_options() -> Any:
+    """Get available lead source option values.
+
+    Returns:
+        List of valid lead source codes (e.g., "Web", "Cold Call", "Referral").
+    """
+    return await _get_field_options("Leads", "lead_source")
+
+
+@mcp.tool()
+async def duplicate_contact(id: str) -> Any:
+    """Create a new Contact by duplicating an existing contact's attributes.
+
+    Args:
+        id: Contact GUID to duplicate.
+
+    Returns:
+        JSON:API response with the newly created contact record.
+    """
+    orig = await _http_get_entry("Contacts", id)
+    data = orig.get("data") if isinstance(orig, dict) else None
+    if not data or not isinstance(data, dict):
+        return {"error": f"Contact {id} not found"}
+    attrs = _sanitize_attributes(data.get("attributes", {}))
+    return await _http_create_record("Contacts", attrs)
+
+
+@mcp.tool()
+async def duplicate_lead(lead_id: str) -> Any:
+    """Create a new Lead by duplicating an existing lead's attributes.
+
+    Args:
+        lead_id: Lead GUID to duplicate.
+
+    Returns:
+        JSON:API response with the newly created lead record.
+    """
+    orig = await _http_get_entry("Leads", lead_id)
+    data = orig.get("data") if isinstance(orig, dict) else None
+    if not data or not isinstance(data, dict):
+        return {"error": f"Lead {lead_id} not found"}
+    attrs = _sanitize_attributes(data.get("attributes", {}))
+    return await _http_create_record("Leads", attrs)
+
+
+@mcp.tool()
+async def merge_leads(primaryLeadId: str, duplicateLeadIds: List[str]) -> Any:
+    """Merge multiple duplicate leads into a primary lead.
+
+    Combines attributes from duplicate leads into the primary lead, filling in
+    any missing fields. The duplicate leads are deleted after merging.
+
+    Args:
+        primaryLeadId: GUID of the lead to keep and merge into.
+        duplicateLeadIds: List of GUIDs for leads to merge and delete.
+
+    Returns:
+        Dictionary with 'mergedLead' (updated lead data) and 'mergedDuplicateIds'.
+    """
+    primary = await _http_get_entry("Leads", primaryLeadId)
+    pdata = primary.get("data") if isinstance(primary, dict) else None
+    if not pdata:
+        return {"error": f"Primary lead {primaryLeadId} not found"}
+    primary_attrs = dict(pdata.get("attributes", {}))
+    for dup_id in duplicateLeadIds:
+        dup = await _http_get_entry("Leads", dup_id)
+        ddata = dup.get("data") if isinstance(dup, dict) else None
+        if not ddata:
+            continue
+        for k, v in (ddata.get("attributes", {}) or {}).items():
+            if not primary_attrs.get(k) or str(primary_attrs.get(k)).strip() == "":
+                primary_attrs[k] = v
+    san = _sanitize_attributes(primary_attrs)
+    updated = await _http_update_record("Leads", primaryLeadId, san)
+    for dup_id in duplicateLeadIds:
+        try:
+            await _http_delete_entry("Leads", dup_id)
+        except Exception:
+            pass
+    return {"mergedLead": updated, "mergedDuplicateIds": duplicateLeadIds}
+
+
+@mcp.tool()
+async def delete_lead(lead_id: str) -> Any:
+    """Delete a lead record.
+
+    Args:
+        lead_id: Lead GUID to delete.
+
+    Returns:
+        JSON:API response confirming deletion.
+    """
+    return await _http_delete_entry("Leads", lead_id)
+
+
+# ============ Contact-specific tools ============
+
+@mcp.tool()
+async def create_contact(
+    first_name: str,
+    last_name: str,
+    title: Optional[str] = None,
+    account_id: Optional[str] = None,
+    department: Optional[str] = None,
+    phone_work: Optional[str] = None,
+    phone_mobile: Optional[str] = None,
+    email1: Optional[str] = None,
+    description: Optional[str] = None,
+    assigned_user_id: Optional[str] = None,
+) -> Any:
+    """Create a new Contact with common fields and optional account linkage.
+
+    Args:
+        first_name: Contact's first name (required).
+        last_name: Contact's last name (required).
+        title: Job title.
+        account_id: Company/organization account GUID to link this contact to (stored in the `Accounts` module).
+        department: Department name.
+        phone_work: Work phone number.
+        phone_mobile: Mobile phone number.
+        email1: Primary email address.
+        description: Additional notes or description.
+        assigned_user_id: User GUID to assign the contact to.
+
+    Returns:
+        JSON:API response with the newly created contact record.
+    """
+    attributes: Dict[str, Any] = {
+        "first_name": first_name,
+        "last_name": last_name,
+    }
+    if title:
+        attributes["title"] = title
+    if department:
+        attributes["department"] = department
+    if phone_work:
+        attributes["phone_work"] = phone_work
+    if phone_mobile:
+        attributes["phone_mobile"] = phone_mobile
+    if description:
+        attributes["description"] = description
+    if account_id:
+        attributes["account_id"] = account_id
+    if email1:
+        attributes["email1"] = email1
+    if assigned_user_id:
+        attributes["assigned_user_id"] = assigned_user_id
+
+    return await _http_create_record("Contacts", attributes)
+
+
+@mcp.tool()
+async def search_contacts(
+    search_term: Optional[str] = None,
+    first_name: Optional[str] = None,
+    last_name: Optional[str] = None,
+    assigned_user_id: Optional[str] = None,
+    created_after: Optional[str] = None,
+    created_before: Optional[str] = None,
+    page: Optional[int] = 1,
+    page_size: Optional[int] = 20,
+    search_operator: Optional[str] = "or",
+) -> Any:
+    """Search contacts by person name, assignee, and date range.
+
+    Args:
+        search_term: Person name search in "FirstName LastName" format (e.g., "John Doe").
+            - Multi-word: First word matches first_name, last word matches last_name (AND).
+            - Single word: Searches across first_name and last_name (OR).
+            For more precise control, use first_name and last_name parameters instead.
+        first_name: Filter by first name (partial match with LIKE).
+        last_name: Filter by last name (partial match with LIKE).
+        assigned_user_id: Filter by assigned user GUID.
+        created_after: ISO date string (YYYY-MM-DD) for minimum creation date.
+        created_before: ISO date string (YYYY-MM-DD) for maximum creation date.
+        page: Index of the target page to retrieve (1-based, default 1).
+        page_size: Number of records per page to segment the contact list (default 20).
+        search_operator: Logical operator for combining filters ("or" or "and", default "or").
+            Note: When search_term has multiple words, "and" is used automatically for name matching.
+
+    Returns:
+        JSON:API response with matching contact records.
+    """
+    filters: Dict[str, Any] = {}
+
+    # Handle search_term - intelligently parse multi-word searches
+    if search_term:
+        words = search_term.strip().split()
+        if len(words) >= 2:
+            # Multi-word search: assume "first_name last_name" format
+            # Use AND to match both parts
+            filters["operator"] = "and"
+            filters["first_name"] = {"like": f"%{words[0]}%"}
+            filters["last_name"] = {"like": f"%{words[-1]}%"}
+        else:
+            # Single word: search across all name fields with OR
+            filters["operator"] = "or"
+            like = f"%{search_term}%"
+            filters["first_name"] = {"like": like}
+            filters["last_name"] = {"like": like}
+    else:
+        # No search_term - use explicit first_name/last_name if provided
+        filters["operator"] = search_operator if search_operator in ("or", "and") else "and"
+        if first_name:
+            filters["first_name"] = {"like": f"%{first_name}%"}
+        if last_name:
+            filters["last_name"] = {"like": f"%{last_name}%"}
+
+    # Add other filters
+    if assigned_user_id:
+        filters["assigned_user_id"] = {"eq": assigned_user_id}
+    if created_after or created_before:
+        filters["date_entered"] = {}
+        if created_after:
+            filters["date_entered"]["gt"] = created_after
+        if created_before:
+            filters["date_entered"]["lt"] = created_before
+
+    return await _http_list_records("Contacts", filters, "-date_entered", page or 1, page_size or 20, ["first_name", "last_name", "phone_work", "phone_mobile", "email1"])  # type: ignore[arg-type]
+
+
+@mcp.tool()
+async def update_contact(
+    contact_id: str,
+    first_name: Optional[str] = None,
+    last_name: Optional[str] = None,
+    title: Optional[str] = None,
+    phone_work: Optional[str] = None,
+    phone_mobile: Optional[str] = None,
+    description: Optional[str] = None,
+    assigned_user_id: Optional[str] = None,
+    account_id: Optional[str] = None,
+) -> Any:
+    """Update a Contact's fields (partial update).
+
+    Note: To update email addresses, use update_contact_email instead.
+    SuiteCRM stores emails in a separate table that requires special handling.
+
+    Args:
+        contact_id: Contact GUID to update.
+        first_name: New first name.
+        last_name: New last name.
+        title: New job title.
+        phone_work: New work phone number.
+        phone_mobile: New mobile phone number.
+        description: New description or notes.
+        assigned_user_id: New assigned user GUID.
+        account_id: Account GUID to link this contact to.
+
+    Returns:
+        JSON:API response with updated contact record.
+    """
+    attributes: Dict[str, Any] = {}
+    if first_name is not None:
+        attributes["first_name"] = first_name
+    if last_name is not None:
+        attributes["last_name"] = last_name
+    if title is not None:
+        attributes["title"] = title
+    if phone_work is not None:
+        attributes["phone_work"] = phone_work
+    if phone_mobile is not None:
+        attributes["phone_mobile"] = phone_mobile
+    if description is not None:
+        attributes["description"] = description
+    if assigned_user_id is not None:
+        attributes["assigned_user_id"] = assigned_user_id
+    if account_id is not None:
+        attributes["account_id"] = account_id
+    return await _http_update_record("Contacts", contact_id, attributes)
+
+
+@mcp.tool()
+async def assign_contact(contact_id: str, user_id: str, send_notification: Optional[bool] = True) -> Any:  # noqa: ARG002
+    """Assign a contact to a user.
+
+    Args:
+        contact_id: Contact GUID to reassign.
+        user_id: User GUID to assign the contact to.
+        send_notification: Whether to send notification (not implemented in sandbox).
+
+    Returns:
+        JSON:API response with updated contact record.
+    """
+    return await _http_update_record("Contacts", contact_id, {"assigned_user_id": user_id})
+
+
+@mcp.tool()
+async def link_contact_to_account(contact_id: str, account_id: str) -> Any:
+    """Link a contact to an account via relationships.
+
+    Args:
+        contact_id: Contact GUID to link.
+        account_id: Account GUID to link the contact to.
+
+    Returns:
+        JSON:API response confirming the relationship update.
+    """
+    relationships = {
+        "contacts": {"data": {"type": "Contacts", "id": contact_id}},
+    }
+    return await _http_update_record("Accounts", account_id, {}, relationships)
+
+
+@mcp.tool()
+async def get_contact_by_id(id: str) -> Any:
+    """Get a Contact by ID.
+
+    Args:
+        id: Contact GUID.
+
+    Returns:
+        JSON:API response with contact record data.
+    """
+    return await _http_get_entry("Contacts", id)
+
+
+@mcp.tool()
+async def delete_contact(id: str) -> Any:
+    """Delete a Contact record.
+
+    Args:
+        id: Contact GUID to delete.
+
+    Returns:
+        JSON:API response confirming deletion.
+    """
+    return await _http_delete_entry("Contacts", id)
+
+
+@mcp.tool()
+async def update_contact_email(contact_id: str, old_email: str, new_email: str) -> Any:
+    """Update a contact's email address.
+
+    SuiteCRM stores emails in a separate table (EmailAddresses), so this tool
+    finds the email record linked to the contact and updates it via the
+    authenticated JSON:API.
+
+    Args:
+        contact_id: Contact GUID whose email should be updated.
+        old_email: The current email address to replace.
+        new_email: The new email address to set.
+
+    Returns:
+        Dictionary with success status and updated email information.
+    """
+    try:
+        # Step 1: Get the contact's email relationships to find the EmailAddress record
+        email_rels = await _http_get_relationships("Contacts", contact_id, "email_addresses", page=1, page_size=50)
+
+        if isinstance(email_rels, dict) and "error" in email_rels:
+            return {
+                "success": False,
+                "contact_id": contact_id,
+                "error": f"Failed to get email relationships: {email_rels.get('error')}",
+            }
+
+        # Step 2: Find the EmailAddress record matching old_email
+        email_id = None
+        data = email_rels.get("data", [])
+        for email_rec in data:
+            attrs = email_rec.get("attributes", {})
+            if attrs.get("email_address", "").lower() == old_email.lower():
+                email_id = email_rec.get("id")
+                break
+
+        if not email_id:
+            return {
+                "success": False,
+                "contact_id": contact_id,
+                "old_email": old_email,
+                "error": f"Email address '{old_email}' not found for contact {contact_id}",
+            }
+
+        # Step 3: Update the EmailAddress record via standard authenticated API
+        result = await _http_update_record(
+            "EmailAddresses",
+            email_id,
+            {"email_address": new_email, "email_address_caps": new_email.upper()}
+        )
+
+        if isinstance(result, dict) and "error" in result:
+            return {
+                "success": False,
+                "contact_id": contact_id,
+                "old_email": old_email,
+                "new_email": new_email,
+                "error": result.get("error"),
+            }
+
+        return {
+            "success": True,
+            "contact_id": contact_id,
+            "old_email": old_email,
+            "new_email": new_email,
+            "message": f"Email updated from {old_email} to {new_email}",
+            "data": result,
+        }
+
+    except Exception as e:
+        return {
+            "success": False,
+            "contact_id": contact_id,
+            "error": str(e),
+        }
+
+
+@mcp.tool()
+async def view_contact_history(id: str) -> Any:
+    """Get a contact's related activities and history.
+
+    Aggregates calls, meetings, emails, cases, notes, and tasks linked to the contact.
+
+    Args:
+        id: Contact GUID.
+
+    Returns:
+        Dictionary with keys 'calls', 'meetings', 'emails', 'cases', 'notes', 'tasks',
+        each containing a list of related records.
+    """
+    fields = ["calls", "meetings", "emails", "cases", "notes", "tasks"]
+    history: Dict[str, Any] = {}
+    for field in fields:
+        try:
+            resp = await _http_get_relationships("Contacts", id, field, 1, 50)
+            if isinstance(resp, dict):
+                history[field] = resp.get("data")
+        except Exception:
+            pass
+    return history
+
+
+# ============ Case-specific tools ============
+
+
+@mcp.tool()
+async def create_case(
+    name: str,
+    status: str = "Open_New",
+    priority: str = "P2",
+    case_type: str = "User",
+    description: Optional[str] = None,
+    account_id: Optional[str] = None,
+    contact_id: Optional[str] = None,
+    assigned_user_id: Optional[str] = None,
+) -> Any:
+    """Create a new Case (support ticket) record.
+
+    Args:
+        name: Case subject/title (required). E.g., 'Product not working as expected'.
+        status: Case status. Use internal codes: 'Open_New', 'Open_Assigned', 'Open_Pending Input',
+            'Closed_Closed', 'Closed_Rejected', 'Closed_Duplicate'. Defaults to 'Open_New'.
+        priority: Case priority code. Use 'P1' (High), 'P2' (Medium), or 'P3' (Low). Defaults to 'P2'.
+        case_type: Case type. E.g., 'User', 'Product', 'Administration'.
+        description: Case description/details.
+        account_id: Account GUID to link this case to.
+        contact_id: Contact GUID to link this case to.
+        assigned_user_id: User GUID to assign the case to.
+
+    Returns:
+        JSON:API response with the newly created case record.
+    """
+    attributes: Dict[str, Any] = {
+        "name": name,
+        "status": status,
+        "priority": priority,
+        "type": case_type,
+    }
+    if description:
+        attributes["description"] = description
+    if account_id:
+        attributes["account_id"] = account_id
+    if contact_id:
+        attributes["contact_id"] = contact_id
+    if assigned_user_id:
+        attributes["assigned_user_id"] = assigned_user_id
+
+    return await _http_create_record("Cases", attributes)
+
+
+@mcp.tool()
+async def search_cases(
+    search_term: Optional[str] = None,
+    status: Optional[str] = None,
+    priority: Optional[str] = None,
+    case_type: Optional[str] = None,
+    account_id: Optional[str] = None,
+    assigned_user_id: Optional[str] = None,
+    page: Optional[int] = 1,
+    page_size: Optional[int] = 20,
+    search_operator: Optional[str] = "or",
+) -> Any:
+    """Search cases by text, status, priority, type, account, and assignee.
+
+    Args:
+        search_term: Free-text search across case name/subject AND description.
+        status: Case status. Use internal codes: 'Open_New', 'Open_Assigned', 'Open_Pending Input',
+            'Closed_Closed', 'Closed_Rejected', 'Closed_Duplicate'.
+        priority: Case priority code ('P1', 'P2', 'P3').
+        case_type: Case type (e.g., 'User', 'Product', 'Administration').
+        account_id: Filter by linked account GUID.
+        assigned_user_id: Filter by assigned user GUID.
+        page: Index of the target page to retrieve (1-based, default 1).
+        page_size: Number of records per page to segment the case list (default 20).
+        search_operator: Logical operator for combining filters ('or' or 'and', default 'or').
+
+    Returns:
+        JSON:API response with matching case records.
+    """
+    filters: Dict[str, Any] = {}
+    filters["operator"] = search_operator if search_operator in ("or", "and") else "or"
+    if search_term:
+        # Search both name and description fields
+        filters["name"] = {"like": f"%{search_term}%"}
+        filters["description"] = {"like": f"%{search_term}%"}
+    if status:
+        filters["status"] = {"eq": status}
+    if priority:
+        filters["priority"] = {"eq": priority}
+    if case_type:
+        filters["type"] = {"eq": case_type}
+    if account_id:
+        filters["account_id"] = {"eq": account_id}
+    if assigned_user_id:
+        filters["assigned_user_id"] = {"eq": assigned_user_id}
+
+    return await _http_list_records(
+        "Cases",
+        filters if filters else None,
+        "-date_entered",
+        page or 1,
+        page_size or 20,
+        ["name", "status", "priority", "type", "description", "date_entered"],
+    )
+
+
+@mcp.tool()
+async def update_case(
+    case_id: str,
+    name: Optional[str] = None,
+    status: Optional[str] = None,
+    priority: Optional[str] = None,
+    case_type: Optional[str] = None,
+    description: Optional[str] = None,
+    resolution: Optional[str] = None,
+    assigned_user_id: Optional[str] = None,
+) -> Any:
+    """Update a Case record (partial update).
+
+    Args:
+        case_id: Case GUID to update.
+        name: New case subject/title.
+        status: New status. Use internal codes: 'Open_New', 'Open_Assigned', 'Open_Pending Input',
+            'Closed_Closed', 'Closed_Rejected', 'Closed_Duplicate'.
+        priority: New priority code ('P1', 'P2', 'P3').
+        case_type: New case type (e.g., 'User', 'Product', 'Administration').
+        description: New description.
+        resolution: Resolution text (typically set when closing the case).
+        assigned_user_id: New assigned user GUID.
+
+    Returns:
+        JSON:API response with updated case record.
+    """
+    attributes: Dict[str, Any] = {}
+    if name is not None:
+        attributes["name"] = name
+    if status is not None:
+        attributes["status"] = status
+    if priority is not None:
+        attributes["priority"] = priority
+    if case_type is not None:
+        attributes["type"] = case_type
+    if description is not None:
+        attributes["description"] = description
+    if resolution is not None:
+        attributes["resolution"] = resolution
+    if assigned_user_id is not None:
+        attributes["assigned_user_id"] = assigned_user_id
+
+    return await _http_update_record("Cases", case_id, attributes)
+
+
+@mcp.tool()
+async def get_case_by_id(case_id: str) -> Any:
+    """Get a Case by ID.
+
+    Args:
+        case_id: Case GUID.
+
+    Returns:
+        JSON:API response with case record data.
+    """
+    return await _http_get_entry("Cases", case_id)
+
+
+@mcp.tool()
+async def delete_case(case_id: str) -> Any:
+    """Delete a Case record.
+
+    Args:
+        case_id: Case GUID to delete.
+
+    Returns:
+        JSON:API response confirming deletion.
+    """
+    return await _http_delete_entry("Cases", case_id)
+
+
+# ============ Account-specific tools ============
+
+
+@mcp.tool()
+async def search_accounts(
+    search_term: Optional[str] = None,
+    industry: Optional[str] = None,
+    page: Optional[int] = None,
+    page_size: Optional[int] = None,
+) -> Any:
+    """Search for Account records.
+
+    Args:
+        search_term: Text to search for in account names.
+        industry: Filter by industry (e.g., 'Technology', 'Healthcare', 'Finance').
+        page: Page number for pagination (1-based).
+        page_size: Number of records per page (default 20).
+
+    Returns:
+        JSON:API response with matching accounts including id, name, industry, billing address fields.
+    """
+    filters: Dict[str, Any] = {}
+    if search_term:
+        filters["name"] = {"like": f"%{search_term}%"}
+    if industry:
+        filters["industry"] = {"eq": industry}
+
+    return await _http_list_records(
+        "Accounts",
+        filters,
+        "-date_entered",
+        page or 1,
+        page_size or 20,
+        ["name", "industry", "phone_office", "billing_address_city", "billing_address_country"],
+    )
+
+
+@mcp.tool()
+async def get_account_by_id(account_id: str) -> Any:
+    """Get an Account by ID.
+
+    Args:
+        account_id: Account GUID.
+
+    Returns:
+        JSON:API response with account record data.
+    """
+    return await _http_get_entry("Accounts", account_id)
+
+
+# ============ Opportunity-specific tools ============
+
+
+@mcp.tool()
+async def create_opportunity(
+    name: str,
+    amount: Optional[float] = None,
+    sales_stage: str = "Prospecting",
+    date_closed: Optional[str] = None,
+    account_id: Optional[str] = None,
+    description: Optional[str] = None,
+    probability: Optional[int] = None,
+    lead_source: Optional[str] = None,
+    assigned_user_id: Optional[str] = None,
+) -> Any:
+    """Create a new Opportunity record.
+
+    Args:
+        name: Opportunity name/title (required). E.g., 'Website Redesign Project - Acme Corp'.
+        amount: Expected deal amount in dollars.
+        sales_stage: Sales stage. Common values: 'Prospecting', 'Qualification',
+            'Needs Analysis', 'Value Proposition', 'Negotiation/Review',
+            'Closed Won', 'Closed Lost'. Defaults to 'Prospecting'.
+        date_closed: Expected close date in YYYY-MM-DD format.
+        account_id: Account GUID to link this opportunity to.
+        description: Opportunity description/details.
+        probability: Win probability percentage (0-100).
+        lead_source: How the opportunity originated (e.g., 'Web Site', 'Referral', 'Trade Show').
+        assigned_user_id: User GUID to assign the opportunity to.
+
+    Returns:
+        JSON:API response with the newly created opportunity record.
+    """
+    attributes: Dict[str, Any] = {
+        "name": name,
+        "sales_stage": sales_stage,
+    }
+    if amount is not None:
+        attributes["amount"] = amount
+    if date_closed:
+        attributes["date_closed"] = date_closed
+    if account_id:
+        attributes["account_id"] = account_id
+    if description:
+        attributes["description"] = description
+    if probability is not None:
+        attributes["probability"] = probability
+    if lead_source:
+        attributes["lead_source"] = lead_source
+    if assigned_user_id:
+        attributes["assigned_user_id"] = assigned_user_id
+
+    return await _http_create_record("Opportunities", attributes)
+
+
+@mcp.tool()
+async def search_opportunities(
+    search_term: Optional[str] = None,
+    sales_stage: Optional[str] = None,
+    account_id: Optional[str] = None,
+    page: Optional[int] = None,
+    page_size: Optional[int] = None,
+) -> Any:
+    """Search for Opportunity records.
+
+    Args:
+        search_term: Text to search for in opportunity names.
+        sales_stage: Filter by sales stage (e.g., 'Prospecting', 'Closed Won').
+        account_id: Filter by account GUID.
+        page: Page number for pagination (1-based).
+        page_size: Number of records per page (default 20).
+
+    Returns:
+        JSON:API response with matching opportunities including id, name, amount, sales_stage, date_closed.
+    """
+    # When account_id is provided, use the relationship endpoint because
+    # SuiteCRM does not expose account_id as a filterable column on
+    # Opportunities (it's stored in a relationship table).
+    if account_id:
+        result = await _http_get_relationships(
+            "Accounts", account_id, "opportunities",
+            page=page or 1, page_size=page_size or 20,
+        )
+        # Apply additional filters client-side if provided
+        if (search_term or sales_stage) and isinstance(result, dict) and "data" in result:
+            filtered = []
+            for rec in result["data"]:
+                attrs = rec.get("attributes", {})
+                if search_term and search_term.lower() not in attrs.get("name", "").lower():
+                    continue
+                if sales_stage and attrs.get("sales_stage") != sales_stage:
+                    continue
+                filtered.append(rec)
+            result["data"] = filtered
+            result.setdefault("meta", {})["records-on-this-page"] = len(filtered)
+        return result
+
+    filters: Dict[str, Any] = {}
+    if search_term:
+        filters["name"] = {"like": f"%{search_term}%"}
+    if sales_stage:
+        filters["sales_stage"] = {"eq": sales_stage}
+
+    return await _http_list_records(
+        "Opportunities",
+        filters,
+        "-date_entered",
+        page or 1,
+        page_size or 20,
+        ["name", "amount", "sales_stage", "date_closed", "probability"],
+    )
+
+
+@mcp.tool()
+async def get_opportunity_by_id(opportunity_id: str) -> Any:
+    """Get an Opportunity by ID.
+
+    Args:
+        opportunity_id: Opportunity GUID.
+
+    Returns:
+        JSON:API response with opportunity record data.
+    """
+    return await _http_get_entry("Opportunities", opportunity_id)
+
+
+@mcp.tool()
+async def update_opportunity(
+    opportunity_id: str,
+    name: Optional[str] = None,
+    amount: Optional[float] = None,
+    sales_stage: Optional[str] = None,
+    date_closed: Optional[str] = None,
+    description: Optional[str] = None,
+    probability: Optional[int] = None,
+    assigned_user_id: Optional[str] = None,
+) -> Any:
+    """Update an Opportunity's fields (partial update).
+
+    Args:
+        opportunity_id: Opportunity GUID to update.
+        name: New opportunity name.
+        amount: New deal amount.
+        sales_stage: New sales stage.
+        date_closed: New expected close date (YYYY-MM-DD).
+        description: New description.
+        probability: New win probability (0-100).
+        assigned_user_id: New assigned user GUID.
+
+    Returns:
+        JSON:API response with updated opportunity record.
+    """
+    attributes: Dict[str, Any] = {}
+    if name is not None:
+        attributes["name"] = name
+    if amount is not None:
+        attributes["amount"] = amount
+    if sales_stage is not None:
+        attributes["sales_stage"] = sales_stage
+    if date_closed is not None:
+        attributes["date_closed"] = date_closed
+    if description is not None:
+        attributes["description"] = description
+    if probability is not None:
+        attributes["probability"] = probability
+    if assigned_user_id is not None:
+        attributes["assigned_user_id"] = assigned_user_id
+
+    return await _http_update_record("Opportunities", opportunity_id, attributes)
+
+
+if __name__ == "__main__":
+    main()
+
+