MCP Reference

timeclock_list

Get Time Clocks

Beschreibung

Reads TimeClock entries (check-in / check-out records). One row per work/pause session, or a full sick/vacation day.

Admin / employer see every member's entries (and may filter by user_id); regular members see only their own and can't pass a foreign user_id.

checkin_out is the real field name (not checkout_at).
duration_seconds is null on open entries (is_open: true) so sums stay safely additive without filtering.
created_on is a local-time date — may differ from checkin_at.to_date for late-night sessions.
Full-day sick/vacation still use 00:00–23:59 pair, category: "work".
comment == "auto closed" flags nightly auto-close sweeps.
Sorted checkin_at DESC, capped at 500 rows.

Zugriff

Zugriffsprofil: gated. Module: timeclock. Die Freigabe im Profil ersetzt keine Account-, Workspace- oder Rollenberechtigung.

Parameter

Name	Typ	Pflicht	Beschreibung
`account_id`	string	Ja	Account prefix ID (e.g., acct_abc123).
`user_id`	string	Nein	User prefix ID (user_…) or @handle / handle (e.g., 'sam' or '@sam'). Admin/employer only for foreign users.
`start_date`	string	Nein	Inclusive lower bound on created_on (YYYY-MM-DD). Use alone for a single day.
`end_date`	string	Nein	Inclusive upper bound on created_on. Defaults to start_date when only start_date is given — pair them for a range.

Eingabeschema

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "properties": {
    "account_id": {
      "type": "string",
      "description": "Account prefix ID (e.g., acct_abc123)."
    },
    "user_id": {
      "type": "string",
      "description": "User prefix ID (user_…) or @handle / handle (e.g., 'sam' or '@sam'). Admin/employer only for foreign users."
    },
    "start_date": {
      "type": "string",
      "format": "date",
      "description": "Inclusive lower bound on created_on (YYYY-MM-DD). Use alone for a single day."
    },
    "end_date": {
      "type": "string",
      "format": "date",
      "description": "Inclusive upper bound on created_on. Defaults to start_date when only start_date is given — pair them for a range."
    }
  },
  "required": [
    "account_id"
  ],
  "type": "object"
}

Ausgabeschema

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "properties": {
    "time_clocks": {
      "type": "array",
      "items": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "description": "TimeClock prefix ID (clk_…)."
          },
          "user": {
            "type": "object",
            "properties": {
              "id": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "handle": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "name": {
                "type": "string"
              }
            }
          },
          "created_on": {
            "type": "string",
            "format": "date",
            "description": "Calendar day the entry belongs to (local-time assigned at check-in; may differ from checkin_at.to_date for late-night sessions)."
          },
          "checkin_at": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time"
          },
          "checkin_out": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time",
            "description": "Null when entry is still open. Field name is intentional — not a typo for checkout_at."
          },
          "is_open": {
            "type": "boolean",
            "description": "True iff checkin_out is null."
          },
          "category": {
            "type": "string",
            "enum": [
              "work",
              "pause"
            ]
          },
          "work_location_type": {
            "type": [
              "string",
              "null"
            ],
            "enum": [
              null,
              "remote",
              "on_site"
            ]
          },
          "sick_day": {
            "type": "boolean"
          },
          "vacation_day": {
            "type": "boolean"
          },
          "comment": {
            "type": [
              "string",
              "null"
            ],
            "description": "AUTO_CHECKOUT_COMMENT='auto closed' marks entries closed by the nightly sweep."
          },
          "duration_seconds": {
            "type": [
              "integer",
              "null"
            ],
            "description": "Null on open entries to keep sums safely additive."
          }
        },
        "required": [
          "id",
          "user",
          "created_on",
          "is_open",
          "category",
          "sick_day",
          "vacation_day"
        ]
      }
    }
  },
  "required": [
    "time_clocks"
  ],
  "type": "object"
}