# smarthr-member-mcp-tools

SmartHR を **従業員として** 使っている人向けの MCP サーバーです。
自分の給与明細・賞与明細をまとめて取得し、年末調整で入力する「給与の収入金額（見込額）」を計算します。

- 管理者用の公式 API トークンは使いません。自分のアカウントでログインしたブラウザ（手元の Google Chrome）を Playwright で操作します。
- SmartHR 社の公式ツールではありません。画面構成が変わると動かなくなることがあります。
- 計算結果は見込額です。最終的な申告内容はご自身で確認してください。

## できること

| tool | 内容 |
| --- | --- |
| `list_payslips(year)` | 指定した年（支給日基準）の明細を取得し、勤怠・支給・控除・その他の項目を返す |
| `estimate_income(year?)` | 指定した年（省略時は今年）の給与の収入金額の見込額を返す |

`estimate_income` の計算方法:

- 給与の収入金額 = `課税対象額 + 社会保険合計`。立替精算や通勤手当などの非課税分を除くためです。これらの行がない明細では `支給 合計` を使います。
- 発行済みの明細は実額を使います。
- 最後の給与明細より後の月は、最新の給与明細の額で推計します（昇給を反映）。
- まだ支給されていない賞与は、前年同月の賞与の額で推計します。
- 推計分は `rows` の中で `estimated: true` になっています。賞与額の変更などが分かっている場合は、それをもとに補正してください。

## セットアップ

[uv](https://docs.astral.sh/uv/) と Google Chrome が必要です。

```sh
git clone https://github.com/tunagohan/smarthr-member-mcp-tools.git
cd smarthr-member-mcp-tools
uv sync
```

### Claude Code

```sh
claude mcp add smarthr-member \
  -e SMARTHR_URL=https://<your-tenant>.smarthr.jp \
  -- uv run --directory /path/to/smarthr-member-mcp-tools smarthr-member-mcp
```

### Claude Desktop など

```json
{
  "mcpServers": {
    "smarthr-member": {
      "command": "uv",
      "args": ["run", "--directory", "/path/to/smarthr-member-mcp-tools", "smarthr-member-mcp"],
      "env": { "SMARTHR_URL": "https://<your-tenant>.smarthr.jp" }
    }
  }
}
```

## 使い方

「今年の給与収入の見込額を出して」のように頼んでください。

初回やログインが切れているときは Chrome が開きます。5 分以内にログインすると、そのまま取得を続けます（SSO や 2 段階認証もそのまま使えます）。

## データの扱い

- ログイン状態は `~/.smarthr-member-mcp/profile` に保存されます（`SMARTHR_PROFILE_DIR` で変更可）。このリポジトリの中には保存されません。
- 取得した明細は MCP サーバーのメモリ上にだけ保持し、ファイルには書き出しません。
- 明細の内容は、MCP クライアント（AI アシスタント）に送られます。

## 画面構成が変わって動かなくなったとき

数字を伏せた状態で画面の構造を出力するスクリプトがあります。

```sh
SMARTHR_URL=https://<your-tenant>.smarthr.jp uv run smarthr-member-recon
```

出力先は `recon-output/recon.json` です（git の管理外）。氏名や会社名がページ本文に残るので、共有する前に中身を確認してください。

## 開発

```sh
uv run pytest
```

## License

MIT