# mf-accounting-voucher-mcp

マネーフォワード クラウド会計の**公式MCPサーバーが未対応の機能を補完する**ローカルMCPサーバーです。REST API v3 を直接呼び出し、公式MCP（リモート）と併用します。

## 提供ツール

| ツール名 | 機能 | APIエンドポイント |
|---|---|---|
| `post_vouchers` | 証憑ファイル（PDF・画像）を仕訳に添付 | `POST /api/v3/vouchers` |
| `delete_voucher` | 証憑の添付解除 | `DELETE /api/v3/vouchers` |
| `delete_journal` | 仕訳の削除（**取り消し不可**） | `DELETE /api/v3/journals/{id}` |

> **注記**: 連携明細の「対象外」化は REST API に存在しないため提供しません。証憑ファイルのダウンロードも同様にAPI未対応です。公式MCPが提供済みの機能（`getJournals` 等）は再実装しません。

証憑ファイルのバイナリはLLMを経由しません。このサーバー（Nodeプロセス）がローカルのファイルパスを受け取り、読み込み・base64化してAPIへ送信します。

## セットアップ

### 1. アプリポータルでアプリを登録

マネーフォワードのアプリポータルでアプリを作成し、以下を設定します。

- **リダイレクトURI**: `http://127.0.0.1:53682/callback`
- **スコープ**:
  - `mfc/accounting/voucher.write`（証憑の登録、削除）
  - `mfc/accounting/journal.write`（仕訳の登録、更新、削除）

発行された **クライアントID / クライアントシークレット** を控えます。

### 2. インストールとビルド

```bash
pnpm install && pnpm run build
```

### 3. 環境変数の設定

```bash
export MF_CLIENT_ID="（クライアントID）"
export MF_CLIENT_SECRET="（クライアントシークレット）"
```

| 変数 | 既定値 | 用途 |
|---|---|---|
| `MF_CLIENT_ID` / `MF_CLIENT_SECRET` | なし（必須） | アプリポータルで発行 |
| `MF_REDIRECT_PORT` | `53682` | コールバック用ローカルポート |
| `MF_REDIRECT_URI` | `http://127.0.0.1:{PORT}/callback` | リダイレクトURI |
| `MF_TOKEN_PATH` | `~/.mf-accounting-voucher-mcp/tokens.json` | トークン保存先 |
| `MF_MAX_FILE_MB` | `20` | 1ファイルの上限（ローカル側の安全弁） |
| `MF_ALLOWED_EXT` | `.pdf,.jpg,.jpeg,.png` | 許可拡張子（カンマ区切りで上書き可） |

### 4. 初回認可

```bash
pnpm run auth
```

ブラウザが開くので、マネーフォワードにログインして認可します。トークンは `~/.mf-accounting-voucher-mcp/tokens.json`（mode 600）に保存され、以後は自動でリフレッシュされます。

## Claude Desktop / Cowork への登録

一度登録すれば、クライアントの起動時にMCPサーバーは**自動で立ち上がります**。日常的に手動起動する操作は不要です。

### 推奨: キーチェーン利用（シークレットを設定ファイルに書かない）

初回のみ、認証情報をmacOSキーチェーンに登録します:

```bash
security add-generic-password -s mf-accounting-voucher-mcp -a client_id -w '（クライアントID）' -U
security add-generic-password -s mf-accounting-voucher-mcp -a client_secret -w '（クライアントシークレット）' -U
```

`claude_desktop_config.json` の `mcpServers` には起動スクリプトを登録します（パスは実際のインストール先に置き換えてください）:

```json
{
  "mcpServers": {
    "mf-accounting-voucher-mcp": {
      "command": "/path/to/mf-accounting-voucher-mcp/scripts/mf-accounting-voucher-mcp.sh",
      "args": []
    }
  }
}
```

初回OAuth認可もスクリプト経由で実行できます（環境変数の設定不要）:

```bash
scripts/mf-accounting-voucher-mcp.sh auth
```

### 代替: 環境変数を設定ファイルに直接書く

```json
{
  "mcpServers": {
    "mf-accounting-voucher-mcp": {
      "command": "node",
      "args": ["/path/to/mf-accounting-voucher-mcp/dist/index.js"],
      "env": {
        "MF_CLIENT_ID": "（クライアントID）",
        "MF_CLIENT_SECRET": "（クライアントシークレット）"
      }
    }
  }
}
```

この方法はシークレットが設定ファイルに平文で残る点に注意してください。

## 使用例

```
「この領収書（/Users/xxx/Downloads/receipt.pdf）を仕訳 XXXX に添付して」
→ post_vouchers が呼ばれ、添付結果（voucher_file_ids）が返る

「仕訳 XXXX の証憑 a60cd25d-... の添付を解除して」
→ delete_voucher

「仕訳 XXXX を削除して」
→ delete_journal（実行前に仕訳内容の提示と明示的な確認が入る）
```

添付結果は公式MCPの `getJournalById` で対象仕訳を取得し、`voucher_file_ids` に反映されていることで検証できます。

## 注意

- MFのファイル種別・サイズ・枚数の正確な制限は公式仕様書 `/specs/vouchers` を参照してください（本サーバーの上限はローカル側の安全弁です）
- **事業者（オフィス）の切り替え**は `pnpm run auth` の再実行で行います
- `delete_journal` は取り消しできません。呼び出し側（LLM）はユーザーの明示的な確認を取ってから実行する設計です