# AIエージェント連携・MCPサーバー運用仕様書

本ドキュメントは、**AI画像販売森山会**における売上集計・費用（経費）控除・利益分配（森山40% / 永瀬40% / 長尾20%）および Lark Base 連携用自作 MCP サーバー (`moriyama-lark-mcp`) の完全仕様書です。

---

## 1. システム全体構成図

```mermaid
graph TD
    A[ユーザー / 他のAIエージェント] -->|指示・データ入力| B[自作MCPサーバー moriyama-lark-mcp]
    B -->|手数料・経費控除・4:4:2計算| C[分配計算ロジック]
    C -->|lark-cli 連携| D[Lark Base: CjekbYmeEagRmjselTOj7QhCpDc]
    B -->|同期・表示| E[Cloudflare Pages ダッシュボード]
```

---

## 2. 費用・経費の計算仕様

### ■ 算定フォーミュラ
$$\text{総売上} = \text{FANZA売上} + \text{DLsite売上} + (\text{Patreon USD売上} \times \text{為替レート})$$

$$\text{手数料合計} = (\text{FANZA売上} \times r_{\text{fanza}}) + (\text{DLsite売上} \times r_{\text{dlsite}}) + (\text{Patreon JPY売上} \times r_{\text{patreon}})$$

$$\text{トータル純利益} = \text{総売上} - \text{手数料合計} - \text{諸経費・費用}$$

### ■ 分配額算出（1円未満端数調整ルール）
- **永瀬 氏 (40%)**: $\lfloor \text{トータル純利益} \times 0.40 \rfloor$
- **長尾 氏 (20%)**: $\lfloor \text{トータル純利益} \times 0.20 \rfloor$
- **森山 氏 (40% + 端数余り)**: $\text{トータル純利益} - (\text{永瀬分配額} + \text{長尾分配額})$

---

## 3. MCP サーバー仕様 (`mcp-server/index.js`)

### ■ 起動方法
```bash
node ./mcp-server/index.js
```

### ■ 提供ツール（Tool Schema）

#### 1. `record_sales_and_distribution`
* **機能**: 売上、為替レート、経費を入力し、利益分配額を自動計算して Lark Base へ保存します。
* **パラメータ**:
  * `year_month` (string, 必須): 例 `"2026-08"`
  * `fanza_sales` (number, 必須): 円
  * `dlsite_sales` (number, 必須): 円
  * `patreon_usd` (number, 必須): USD $
  * `fx_rate` (number, 必須): 例 `154.0`
  * `fanza_fee_rate` (number, 任意): 既定 `32` (%)
  * `dlsite_fee_rate` (number, 任意): 既定 `22` (%)
  * `patreon_fee_rate` (number, 任意): 既定 `12` (%)
  * `expenses` (number, 任意): 諸経費・費用合計 (円)
  * `expenses_detail` (string, 任意): 経費内訳 (例: `"生成AI API: 8,000円, サーバー代: 3,000円"`)
  * `notes` (string, 任意): メモ

#### 2. `get_sales_history`
* **機能**: 過去の売上、経費、純利益、分配履歴を Lark Base から一覧取得します。
* **パラメータ**: `limit` (number, 既定 20)

#### 3. `calculate_distribution_preview`
* **機能**: 保存せずにシミュレーション計算結果のみを返します。

---

## 4. Lark Base フィールド構造 (`tblFJzOhtsuC6q6Z`)

| フィールド名 | データ型 | 説明 |
| :--- | :--- | :--- |
| **タイトル** | text | レコード件名 (例: `【2026-08月度】売上集計・利益分配確定データ`) |
| **対象年月** | text | YYYY-MM 形式 |
| **総売上** | number | 全プラットフォーム合計 (円) |
| **手数料合計** | number | プラットフォーム手数料合計 (円) |
| **諸経費_費用** | number | サーバー代・プロンプト生成AIコスト・素材代・広告費等 |
| **経費内訳** | text | 経費の品目・金額メモ |
| **トータル純利益** | number | 総売上 − 手数料 − 諸経費 |
| **森山分配額_40%** | number | 森山氏受領額 (40% + 端数) |
| **永瀬分配額_40%** | number | 永瀬氏受領額 (40%) |
| **長尾分配額_20%** | number | 長尾氏受領額 (20%) |
| **ダッシュボードURL** | text | デプロイ先Webサイトリンク |
| **備考・運用メモ** | text | 売上内訳・為替レート等の記録 |

---

## 5. 他のAIエージェントへの注意事項
- **直接のBaseデータ削除・改変の禁止**: 蓄積された確定データを上書きする場合は、必ず承認を得ること。
- **端数処理の統一**: 端数調整は必ず森山氏の分配額にまとめること。
- **デプロイの自動化**:Web UI（`index.html`）を修正した際は、`CLOUDFLARE_ACCOUNT_ID=9fc0bee463e4bca6a6e0c0b58b6d530a npx wrangler pages deploy . --project-name=moriyama-kai-sales-dashboard` を実行して即座にデプロイを更新すること。