freee

freee Attendance

Prefer the installed freee MCP tools for business operations. Use the companion CLI only for local interactive authentication setup, diagnostics when MCP cannot start, or source development. Both entry points call the same FreeeService. Select one backend before any business operation and keep it for the whole process or command. FREEE_BACKEND=api|playwright is authoritative; unset or auto selects API when API configuration exists and Playwright otherwise. Never fall back to another backend or switch from MCP to CLI after an operation error. Never assume that Claude Code was started from the source repository.

Choose the workflow

1. If MCP tools are available, call freee_backend_status; otherwise run CLI backend status. An explicit .env or process FREEE_BACKEND wins over credential detection. If it is auto, API configuration present means api; absent means playwright. Use the selected execution surface for the rest of that operation.
2. In the API branch, use only API-backed commands. Cross-employee operations require the API role to allow them; attendance_manager is known not to support API team status.
3. In the Playwright branch, use the corresponding MCP clock, monthly, personal-application, team, and approval tools. freee_monthly_status reads an explicitly requested personal work month or the month currently selected in freee; freee_personal_applications_list and freee_personal_application_detail read the employee-side 申請 workflow; freee_team_status returns the management view's visible members, closing application state, attendance issues, and work totals. freee_approvals_list and freee_approval_detail read the general manager-side 承認 workflow. Use the dedicated freee_monthly_approvals_list and freee_monthly_approval_review for another employee's 月次勤怠締め; the monthly list exposes the application's explicit paymentPeriod and its freee-mapped work period, and the review binds both months plus the exact application, one visible member, monthly summary, daily attendance table, alerts, and automatic checks. Never directly run the legacy project or ad-hoc browser actions.
4. For API setup, run auth configure only after explicit approval. Prefer system, which stores Client Secret and Tokens in the System Keyring. In an installed plugin or agent package, use its resolved CLI path and persistent data directory; never invent a repository-relative command.
5. For Playwright first-time setup, call freee_auth_status and show the exact setupCommand returned with WEB_CREDENTIALS_UNAVAILABLE. Instruct the user to run it directly in a local interactive terminal. The CLI hides username, password, and confirmation input, stores them in System Keychain, and returns no credential value. Never run it through a non-interactive Agent shell or accept credentials in chat. Use browser credentials-status only in a source-development checkout.
6. For a real punch, call freee_clock_prepare_action, match the returned action and identity to the exact instruction or active scoped business policy, retain its fingerprint, and call freee_clock_commit_action with unchanged values and confirm: true. If the user's instruction already precisely authorized execution, do not pause merely because prepare completed later. With CLI-only hosts, use the equivalent status plus dedicated clock ... --confirm command.
7. For a personal monthly attendance submission or withdrawal, call freee_monthly_status first. Include period when the user named a work month; Playwright selects that month through freee's official payment-month navigator and verifies the resulting work month before reading. Omit it only when the user intends the currently selected month. Evaluate every returned calendar warning against the exact instruction or policy. A non-empty warning not expressly covered by that authorization stops the item; do not infer safety from a separate department summary. Use freee_monthly_prepare_action, validate the preview and fingerprint on the user's behalf, then call freee_monthly_commit_action with confirm: true when it remains authorized. A known MONTHLY_PREVIEW_CHANGED result means no write occurred and may be reprepared under the same authorization.
8. For the current employee's leave or work-time correction, call freee_personal_application_options first, including the date for leave. Use the exact returned leave label. If the selected leave form exposes a time range, provide the exact leave_start and leave_end; never accept or submit default 00:00 values. To request deletion of registered work time for one or more authorized dates, use one sequential create flow per date with kind=work-time-correction and work_time_action=delete, omit every clock and break field, and require each preview to show that exact date and action. This selects only 勤務時間を削除; it creates a 勤務時間修正 application and does not directly delete a raw work record. Never substitute an API whole-day delete, a partial label, or list position. Read existing applications with freee_personal_applications_list or freee_personal_application_detail. Use the matching personal-application prepare tool, evaluate the full preview against the exact instruction or active policy, retain the fingerprint, and commit with unchanged values and confirm: true without another prompt when it remains in scope. A deletion commit must be verified as one new same-date 勤務時間修正 whose content is exactly 勤務時間を削除; if freee does not expose that exact result, treat it as unknown and never retry. A cancellation commit creates a new cancellation application that may still require manager approval; only approve it when the authorized final outcome expressly includes that follow-up. Overtime is unavailable until the options tool reports it as both available and supported; never bypass company configuration.
9. For a 月次勤怠締め application requiring manager action, call freee_monthly_approvals_list, then freee_monthly_approval_review for the exact No. Treat text such as 2026年09月の支払分 as a payment month, never as the work month. The dedicated workflow derives the work month from freee's displayed payment-month/work-month relationship, verifies that exact pair on both the attendance monitor and employee attendance page, and fails closed with MONTHLY_APPROVAL_PERIOD_MAPPING_UNCONFIRMED when the application payment month or page relationship is missing, inconsistent, or ambiguous. Never substitute a fixed one-month offset. Evaluate the applicant, paymentPeriod, work period, monthly summary, every daily row, alerts, and automatic checks against the exact instruction or active scoped business policy. Use the dedicated prepare and commit tools and retain the fingerprint on the user's behalf. For other employee applications, use the general approval list, detail, prepare, and commit tools. Before approving a 休暇, every pending approval page must be checked for a pending 勤務時間修正 with the exact same applicant and target date. Process every authorized matching 勤務時間修正 first, then reread and prepare the 休暇 approval again; never bypass LEAVE_APPROVAL_BLOCKED_BY_WORK_TIME_CORRECTION, and fail closed on LEAVE_APPROVAL_DEPENDENCY_UNCONFIRMED. The commit repeats this check and reopens the exact target before any click. This dependency rule does not block returning a 休暇 or processing the 勤務時間修正 itself. Before summarizing or preparing a pending 勤務時間修正, read its detail and present workTimeChange.before and workTimeChange.after; each null time means freee displayed 未入力. If workTimeChange is null, state that a reliable comparison is unavailable and do not infer one from flattened list content; it still blocks a same-applicant, same-date 休暇 approval while pending. All lists are paginated; read every pending page for each complete scan.
10. For any other request or CLI syntax, check references/commands.md. Do not improvise an API, MCP, or browser workflow that lacks a dedicated tool or command.