# makeleaps-mcp

MakeLeapsの取引先、見積書、請求書をLLMから操作するための、非公式・ローカル実行専用MCPサーバーです。

HubSpotなど他サービスとの接続処理は含みません。LLMクライアントがHubSpot ConnectorとこのMCPサーバーを同時に利用し、必要な情報をツール間で受け渡す構成を想定しています。

> [!IMPORTANT]
> このプロジェクトはMakeLeaps株式会社による公式製品ではありません。MakeLeaps APIを利用した実装について、MakeLeapsは技術サポートを提供していません。

## 特徴

- stdioによるローカル実行のみ
- ホステッドサービス、リモートHTTP、テレメトリーなし
- MakeLeapsの認証情報と請求データを開発者側へ送信しない
- 金額を浮動小数点数ではなく`Decimal`として検証
- MakeLeapsのテンプレートに応じた税区分の検証
- ローカルSQLiteを用いた書き込み操作の二重実行防止
- 書類の送付機能は提供しない

## 利用者向け

### 提供ツール

| ツール | 内容 |
| --- | --- |
| `search_clients` | 取引先の一覧取得・検索 |
| `get_client` | 取引先とデフォルト連絡先の取得 |
| `create_organization_client` | 法人取引先の作成 |
| `list_document_templates` | 見積書・請求書テンプレートの取得 |
| `search_documents` | 見積書・請求書の検索 |
| `get_document` | 書類詳細の取得 |
| `create_quote` | 見積書の作成 |
| `create_invoice` | 請求書の作成 |

`create_quote`と`create_invoice`は書類をMakeLeapsへ保存しますが、取引先への送付は行いません。
HubSpotのDeal名など、書類の案件名は`project_name`で指定できます。

`create_organization_client`では法人名に加えて、法人のメールアドレス・電話番号・FAX番号・住所・適格請求書発行事業者登録番号と、任意の担当者を登録できます。住所を指定する場合は、MakeLeaps APIの仕様に従って`format`と2文字の国コード`country_name`が必須です。

書類には取引先向けの備考`message`とは別に、MakeLeaps内だけで使用する社内メモ`note`と発注番号`purchase_order_ids`を設定できます。`create_invoice`では請求対象期間も指定できます。

### 必要環境

- Python 3.12以上
- [uv](https://docs.astral.sh/uv/)
- MakeLeapsのAPI Client ID、Client Secret、Partner MID

MakeLeapsの管理画面からAPIキーを発行してください。APIは本番データへ接続され、サンドボックス環境は提供されていません。

### セットアップ

```powershell
git clone https://github.com/Swandive-Inc/makeleaps-mcp.git
cd makeleaps-mcp
uv sync --frozen
```

次の環境変数をMCPクライアントから渡します。

| 環境変数 | 必須 | 内容 |
| --- | --- | --- |
| `MAKELEAPS_CLIENT_ID` | はい | MakeLeaps API Client ID |
| `MAKELEAPS_CLIENT_SECRET` | はい | MakeLeaps API Client Secret |
| `MAKELEAPS_PARTNER_MID` | はい | MakeLeaps Partner MID |
| `MAKELEAPS_STATE_PATH` | いいえ | 冪等性管理用SQLiteファイルの保存先 |

`MAKELEAPS_STATE_PATH`を省略した場合は、OS標準のユーザーデータディレクトリへ保存します。認証トークンや書類本文はSQLiteへ保存しません。

MCPクライアントの設定例です。パスと認証情報を利用環境に合わせて変更してください。

```json
{
  "mcpServers": {
    "makeleaps": {
      "command": "uv",
      "args": [
        "--directory",
        "C:\\path\\to\\makeleaps-mcp",
        "run",
        "makeleaps-mcp"
      ],
      "env": {
        "MAKELEAPS_CLIENT_ID": "your-client-id",
        "MAKELEAPS_CLIENT_SECRET": "your-client-secret",
        "MAKELEAPS_PARTNER_MID": "your-partner-mid"
      }
    }
  }
}
```

秘密情報を`.env`やMCPクライアントの設定ファイルへ保存する場合は、ファイルのアクセス権とバックアップ先を確認してください。秘密情報をGitへコミットしないでください。

### LLMへの依頼例

```text
HubSpotのDeal 12345を取得し、会社と担当者をMakeLeapsで検索してください。
見積内容を提示して私の確認を取ったあと、MakeLeapsへ見積書を作成してください。
送付はしないでください。
```

### 利用上の注意

- HubSpotのIDを`external_id`へ保存する場合は、既存運用で同フィールドを使っていないか確認してください。すでに別システムとの対応付けに利用している場合は上書きしないでください。
- APIへの送信後に通信が切れた場合は、MakeLeaps上で作成結果を確認してください。

## 開発者向け

### 二重作成の防止

書き込みツールは`operation_key`を必須引数とし、呼び出し元と対象を識別できる安定した値を受け取ります。

```text
hubspot:deal:12345:quote:v1
```

同じキーと同じ入力を再実行すると、MakeLeaps APIを再度呼ばず、ローカルSQLiteに保存した結果を返します。同じキーを異なる入力で再利用した場合はエラーになります。

APIへの送信後に通信が切れた場合は、結果が確定できないため同じ操作を自動再実行しません。通信結果が不明なまま書類を二重作成することを防ぐためです。

### 開発

```powershell
uv sync --frozen
uv run ruff format --check .
uv run ruff check .
uv run pytest
```

テストはMakeLeaps APIをモックし、本番アカウントへ接続しません。

### セキュリティ

- MCPサーバーはstdioのみで動作し、待受ポートを開きません。
- APIアクセストークンはメモリ内でのみ保持し、期限切れ前に更新します。
- 顧客情報、書類内容、認証情報をログへ出力しません。
- 書類送付や削除のツールは実装していません。

### 参考資料

- [MakeLeaps APIドキュメント](https://app.makeleaps.com/api/docs/)
- [MakeLeaps公式MCPチュートリアル](https://developer.makeleaps.com/ja/api/tutorial/create-an-mcp-server-for-your-companys-invoices/)
- [Model Context Protocol](https://modelcontextprotocol.io/)

## ライセンス

[MIT License](LICENSE)