kintai-plus-mcp 0.0.0-stage → 0.1.2

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 atzzCokeK
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,240 @@
-# Temporary Holding Version
+# kintai-plus-mcp
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+> **非公式** の MCP サーバーです。株式会社マネーフォワードとは関係がなく、同社による確認・保証は受けていません。
+> 「マネーフォワード クラウド勤怠Plus」「AKASHI」などの名称・商標は、それぞれの権利者に帰属します。
+
+[マネーフォワード クラウド勤怠Plus](https://biz.moneyforward.com/attendance-plus/)（旧 AKASHI）の公開 API を、Claude などの AI アシスタントから使えるようにする [Model Context Protocol](https://modelcontextprotocol.io) サーバーです。
+
+「出勤して」「今月の残業はどれくらい？」「昨日の工数を設計 2 時間・実装 5 時間で入れて」のように話しかけるだけで、打刻・勤務実績の確認・工数入力ができます。
+
+- 手元の PC で動くローカルの stdio サーバーです（トークンを第三者のサーバーに預けません）
+- トークンは OS のキーチェーンに保存し、有効期限が近づくと自動で再発行します（環境変数で渡したトークンは、明示しない限り保存も再発行もしません）
+- 打刻の位置情報・IP アドレスは、既定では AI に渡しません
+
+公開 API の仕様（公式）: [マネーフォワード クラウド勤怠Plus 公開API 仕様](https://akashi.zendesk.com/hc/ja/articles/115000475854)
+
+> v0.1 は開発中です。主要な応答の形は実環境で確認済みです。まだ未確認の点は [docs/api-notes.md](./docs/api-notes.md) の「未確認事項」にあります。
+
+## できること
+
+| ツール | 内容 |
+|---|---|
+| `get_my_profile` | 自分の従業員情報と権限 |
+| `get_today_status` | 今日の状況（未出勤／勤務中／休憩中／退勤済み）と、ここまでの勤務時間 |
+| `punch` 【書き込み】 | 打刻（出勤・退勤・直行・直帰・休憩入・休憩戻、テレワーク） |
+| `get_stamps` | 打刻履歴（長い期間は自動で分割） |
+| `get_working_records` | 勤務実績（労働区分・時刻・実働・休憩。31 日ごとに自動で分割） |
+| `summarize_working_hours` | 実働合計・出勤日数・休日出勤日数・法定時間外の目安（月ごとの内訳つき） |
+| `get_alerts` | アラート（打刻忘れ、遅刻、36協定 など） |
+| `check_attendance_issues` | 打刻漏れチェック（退勤・出勤・休憩戻の打刻忘れ、12 時間超の日、勤務間インターバル 11 時間未満、休日出勤）。勤務実績にその時刻がある日は打刻漏れにしない。休憩が不明な経過時間は、12 時間超を情報にとどめる |
+| `list_projects` / `list_tasks` / `get_my_projects` | プロジェクトとタスク |
+| `get_manhours` | 工数（プロジェクト名・タスク名つき） |
+| `save_manhours` 【書き込み】 / `delete_manhours` 【書き込み】 | 工数の登録・更新・削除 |
+
+管理者（企業管理者・一般管理者）には、次のツールも表示されます。一般の従業員には表示されません。
+
+| ツール | 内容 |
+|---|---|
+| `list_staff` | 管理下の従業員の一覧（ID・氏名・社員番号・所属のみ） |
+| `get_team_stamps` | 管理下の従業員の 1 日分の打刻と状況 |
+| `get_working_statuses` | 勤務処理（欠勤・出張など） |
+| `get_project_members` | プロジェクトのメンバー |
+| `find_overtime_risks` | 残業リスク検出（今月の法定時間外の目安と月末の着地予測。既定のしきい値は 45 時間） |
+
+### 定型プロンプト
+
+対応しているクライアントでは、メニューから次のプロンプトを呼び出せます（使うツールが公開されているときだけ表示）。
+
+| プロンプト | 内容 |
+|---|---|
+| `end_of_day` | 退勤前チェック（今日の勤務と工数を確認し、入力漏れを埋めてから退勤を打刻） |
+| `log_manhours` | 工数を入力する（日付と、やったことを渡せる） |
+| `monthly_review` | 月の振り返り（勤務時間・残業の目安・打刻漏れ・アラート） |
+| `team_status` | 管理者向け: チームの今日の状況と残業リスク |
+
+## 必要なもの
+
+- Node.js 22 以上
+- クラウド勤怠Plus の API トークン（下の「API トークンの発行」）
+
+## セットアップ
+
+### 1. API トークンの発行
+
+**管理者が行うこと**（一度だけ）: 従業員設定 > 対象の従業員の「変更」 > 利用機能設定 で、「公開API利用可否」を「利用する」にします。
+
+**本人が行うこと**: マイページ > APIトークン で発行します。トークンの有効期限は 1 ヶ月と 1 日です。`login` で登録したトークンは、登録時と、期限が近づいたときに再発行します。
+
+> `login` で登録するトークンは、このツール専用にしてください。再発行すると、それまで使っていたトークンは使えなくなります。環境変数で渡すだけの場合は、既定では再発行しません（下の「環境変数でトークンを渡す」）。
+
+### 2. ログイン
+
+```sh
+npx kintai-plus-mcp login
+```
+
+次の 3 つを聞かれます。
+
+- **ログイン企業ID**
+- **接続先**: ログイン後のブラウザの URL のドメイン（`atnd.ak4.jp` または `atnd-awj.ak4.jp`）
+- **APIトークン**（入力は表示されません）
+
+疎通を確認してから保存します。状態の確認と削除は次のとおりです。
+
+```sh
+npx kintai-plus-mcp status   # 保存先・有効期限・権限（トークンは表示しません）
+npx kintai-plus-mcp logout   # 保存した認証情報を削除
+```
+
+### 3. AI クライアントへの登録
+
+<details open>
+<summary>Claude Desktop</summary>
+
+`claude_desktop_config.json` に追加します。
+
+```json
+{
+  "mcpServers": {
+    "kintai-plus": {
+      "command": "npx",
+      "args": ["-y", "kintai-plus-mcp"]
+    }
+  }
+}
+```
+</details>
+
+<details>
+<summary>Claude Code</summary>
+
+```sh
+claude mcp add kintai-plus -- npx -y kintai-plus-mcp
+```
+</details>
+
+<details>
+<summary>Cursor</summary>
+
+`~/.cursor/mcp.json`（またはプロジェクトの `.cursor/mcp.json`）:
+
+```json
+{
+  "mcpServers": {
+    "kintai-plus": {
+      "command": "npx",
+      "args": ["-y", "kintai-plus-mcp"]
+    }
+  }
+}
+```
+</details>
+
+<details>
+<summary>VS Code（GitHub Copilot）</summary>
+
+`.vscode/mcp.json`:
+
+```json
+{
+  "servers": {
+    "kintai-plus": {
+      "type": "stdio",
+      "command": "npx",
+      "args": ["-y", "kintai-plus-mcp"]
+    }
+  }
+}
+```
+</details>
+
+<details>
+<summary>Codex CLI</summary>
+
+`~/.codex/config.toml`:
+
+```toml
+[mcp_servers.kintai-plus]
+command = "npx"
+args = ["-y", "kintai-plus-mcp"]
+```
+</details>
+
+## 設定（環境変数）
+
+| 変数 | 既定 | 内容 |
+|---|---|---|
+| `KINTAI_PLUS_READ_ONLY` | `false` | `true` で書き込みツール（打刻・工数）を出さない |
+| `KINTAI_PLUS_CONFIRM_WRITES` | `false` | `true` で書き込みの前に確認ダイアログを出す（Elicitation に対応したクライアントのみ。未対応のクライアントでは書き込みが失敗します）。旧名の `CONFIRM_WRITES` も当面は読みます |
+| `KINTAI_PLUS_INCLUDE_LOCATION` | `false` | `true` で打刻の位置情報・IP を返す |
+| `KINTAI_PLUS_REFRESH_DAYS` | `15` | 有効期限の残りがこの日数を切ったら再発行する（1〜30） |
+| `KINTAI_PLUS_AUTO_REFRESH` | `true` | `false` で自動の再発行を止める |
+| `KINTAI_PLUS_PERSIST_ENV_TOKEN` | `false` | `true` で、環境変数のトークンを保存し、期限が不明なら再発行する。環境変数の値は使えなくなることがある |
+| `KINTAI_PLUS_CREDENTIAL_STORE` | `auto` | 保存先: `auto`（キーチェーン → ファイル）/ `keychain` / `file` |
+| `KINTAI_PLUS_CREDENTIALS_FILE` | `~/.config/kintai-plus-mcp/credentials.json` | ファイル保存のパス（指定するとファイル保存になる） |
+| `KINTAI_PLUS_LOG_LEVEL` | `info` | `debug` / `info` / `warn` / `error` / `silent`（ログは stderr のみ） |
+| `KINTAI_PLUS_MIN_INTERVAL_MS` | `300` | API リクエストの最小間隔（ミリ秒） |
+
+### 環境変数でトークンを渡す（ボットなど）
+
+`login` が使えないときは、環境変数だけで起動できます。**既定では保存せず、再発行 API も呼びません。**
+
+```sh
+KINTAI_PLUS_TOKEN=... KINTAI_PLUS_COMPANY_ID=... KINTAI_PLUS_HOST=atnd.ak4.jp npx kintai-plus-mcp
+```
+
+再発行 API は、渡したトークンを無効にして新しいトークンを返します。環境変数の値を自動で再発行すると、その値を共有している他のプロセスが突然使えなくなります。このサーバーは、明示しない限りそれをしません。
+
+自動更新（期限が近づいたら再発行して保存）が必要なときは、このサーバー専用のトークンを `npx kintai-plus-mcp login` で登録してください。キーチェーンが使えない環境では、本人だけが読み書きできるファイル（パーミッション 600）に保存します。
+
+環境変数のトークンを保存して再発行する動作は、`KINTAI_PLUS_PERSIST_ENV_TOKEN=true` を付けたときだけです。有効にすると、環境変数に書いたトークンは使えなくなることがあります。保存先にすでに認証情報があるときは、環境変数より保存先を優先します。
+
+## 制約
+
+- **申請（残業・休暇・打刻修正など）とスケジュールには対応していません**（公開 API にないため）
+- **打刻はサーバーに届いた時刻で記録され、API からは修正・削除できません。** 間違えた場合は Web 画面から申請してください。このため、その日の打刻と矛盾する打刻（出勤済みなのに出勤、など）は実行しません。どうしても必要なときは AI に「強制して」と伝えてください（`force`）
+- 残業時間は API にないため、「法定時間外の目安」（労働日・所定休日は 1 日 8 時間超、法定休日は全時間）として計算します。週 40 時間・変形労働時間制・フレックスは考慮しません。正式な値は勤怠Plus や給与計算で確認してください
+- API の制約（勤務実績は 31 日、打刻は 6 ヶ月・1000 件、従業員一覧は 20 人/ページ、複数従業員の打刻は 1 日・50 人）は、サーバー側で分割・ページ送りします。1 回の呼び出しで取得できる期間には上限があります
+- タイムゾーンは日本時間（Asia/Tokyo）固定です
+- 人事マスタの書き込み（従業員の登録・削除、権限、異動など）は扱いません
+
+## セキュリティとプライバシー
+
+- トークンは OS のキーチェーン（macOS キーチェーン、Windows 資格情報マネージャー、Linux の Secret Service）に保存します。Linux で Secret Service がない場合は、再起動で消えるカーネルのキーリングではなく、ファイル（600）に保存します
+- トークンは URL に載る API 仕様のため、ログ・エラーメッセージから必ず取り除きます
+- 打刻の位置情報・IP は既定で AI に渡しません。従業員情報も ID・氏名・社員番号・所属に絞ります（メールアドレスは渡しません）
+- `logout` は手元の認証情報を削除するだけです。トークン自体を無効にするには、マイページで操作してください
+
+## 開発
+
+```sh
+pnpm install
+pnpm test        # Vitest（モックと架空のフィクスチャのみ）
+pnpm lint        # Biome
+pnpm typecheck
+pnpm build       # tsdown
+pnpm e2e         # 実環境を叩く手動 E2E（読み取りのみ。手元でだけ実行）
+```
+
+設計の決定事項は [docs/design.md](./docs/design.md)、背景は [docs/adr/](./docs/adr/) にあります。
+
+## ライセンス
+
+[MIT](./LICENSE)
+
+---
+
+## English
+
+**Unofficial** MCP server for the public API of "Money Forward Cloud Kintai Plus" (formerly AKASHI), a Japanese attendance management service.
+This project is not affiliated with, endorsed by, or sponsored by Money Forward, Inc. All trademarks belong to their respective owners.
+
+- Punch in/out, check today's status, view punch history, working records, alerts, and man-hours, and record man-hours
+- Admin tools (staff list, team punches, working statuses, project members) are shown only to admins
+- Runs locally over stdio: `npx kintai-plus-mcp`. Register your token first with `npx kintai-plus-mcp login`
+- The token is stored in the OS keychain (or a 600-permission file) and reissued automatically before it expires. A token passed only via `KINTAI_PLUS_TOKEN` is not stored or reissued unless `KINTAI_PLUS_PERSIST_ENV_TOKEN=true` (reissue invalidates the previous token)
+- Location and IP address of punches are not sent to the AI by default
+- Not supported: requests (申請) and schedules, because the public API does not provide them. Punches are recorded at the time the server receives them and cannot be edited via the API
+- Requires Node.js 22+ and an API token issued from your Kintai Plus "My Page" (an admin must enable "公開API利用可否" for you)
+- Official API reference (Japanese): https://akashi.zendesk.com/hc/ja/articles/115000475854
+- License: MIT