get_reporting_chain_down

Instructions

Implementation Reference

• humaans_mcp/server.py:195-218 (handler)

  The core handler function for the 'get_reporting_chain_down' tool. It fetches all people, builds a subtree of reports under the given person recursively using the 'directReports' field, up to max_depth levels. Decorated with @mcp.tool() to register as an MCP tool.

  @mcp.tool()
  async def get_reporting_chain_down(person_id: str, max_depth: int = 5) -> dict[str, Any]:
      """Build the subtree of reports under the given person, up to max_depth levels. Uses a single fetch of all people then walks `directReports` locally."""
      by_id, _, custom_by_person = await _people_index()
      root = by_id.get(person_id)
      if root is None:
          raise ValueError(f"Person {person_id} not found")
  
      def build(node: dict[str, Any], depth: int) -> dict[str, Any]:
          summary = _person_summary(node, custom_by_person.get(node.get("id") or ""))
          child_ids = node.get("directReports") or []
          if depth >= max_depth:
              summary["reports"] = (
                  f"<{len(child_ids)} more, increase max_depth to expand>"
                  if child_ids
                  else []
              )
              return summary
          summary["reports"] = [
              build(by_id[cid], depth + 1) for cid in child_ids if cid in by_id
          ]
          return summary
  
      return build(root, 0)

• humaans_mcp/server.py:195-195 (registration)

  Registration of the tool via the @mcp.tool() decorator on line 195, which registers get_reporting_chain_down with the FastMCP server instance.

  @mcp.tool()

• humaans_mcp/server.py:151-160 (helper)

  Helper function _person_summary used by the handler to produce a summary dict for each person node in the tree.

  def _person_summary(p: dict[str, Any], custom: dict[str, Any] | None = None) -> dict[str, Any]:
      return {
          **(custom or {}),
          "id": p.get("id"),
          "firstName": p.get("firstName"),
          "lastName": p.get("lastName"),
          "jobTitle": p.get("jobTitle"),
          "email": p.get("email"),
          "contractType": p.get("contractType"),
      }

• humaans_mcp/server.py:127-148 (helper)

  Helper function _people_index used by the handler to fetch and index all people by ID along with custom field data.

  async def _people_index() -> tuple[dict[str, dict[str, Any]], dict[str, str], dict[str, dict[str, Any]]]:
      """Return (by_id, parent_of, custom_by_person). parent_of maps a report's id to their manager's id; custom_by_person maps personId to {fieldName: value}."""
      all_people = await client().list_all("/people")
      by_id = {p["id"]: p for p in all_people if "id" in p}
      parent_of: dict[str, str] = {}
      for p in all_people:
          mgr_id = p.get("id")
          for child_id in p.get("directReports") or []:
              parent_of[child_id] = mgr_id
  
      names = await _custom_field_names()
      all_values = await client().list_all("/custom-values")
      values_by_person: dict[str, list[dict[str, Any]]] = {}
      for v in all_values:
          pid = v.get("personId")
          if pid:
              values_by_person.setdefault(pid, []).append(v)
      custom_by_person = {
          pid: _resolve_custom(vs, names) for pid, vs in values_by_person.items()
      }
  
      return by_id, parent_of, custom_by_person

• humaans_mcp/server.py:7-7 (registration)

  The FastMCP server instance used for registration. The @mcp.tool() decorator registers tools on this instance.

  mcp = FastMCP("humaans")