lark-harness-freee-mcp

name	lark-harness-freee-mcp
description	Lark Harness から freee 公式MCPを安全に使うためのラッパースキル。請求書・見積書・取引・経費申請・試算表取得を、Larkの承認ゲート、監査ログ、Base同期、dry-run優先で実行する。

lark-harness-freee-mcp

開始前 MUST: Larkに書き込む場合は ../lark-shared/SKILL.md を読む。

このスキルは freee の公式 MCP サーバーを Lark Harness の業務実行層としてラップする。freee APIの再実装はしない。freee側の操作は公式 freee-mcp に委譲し、Lark Harness側では次の責務だけを持つ。

• 操作意図を Harness Envelope に正規化する
• freee書き込み前に preview / approval gate を置く
• 実行結果を Lark Base と Lark Drive 監査ログに残す
• 請求・会計・支払・送信などの外部アクションを明示承認なしで実行しない

Current Truth

• 推奨接続は freee 公式 Remote MCP: https://mcp.freee.co.jp/mcp
• freee 公式の Agent Skill は freee/freee-mcp releases の freee-api-skill.zip
• 2026-05-03時点で確認した最新 release は v0.26.0
• freee MCP はログインユーザーの権限範囲内で動く。Harness側でも Lark のユーザー権限・承認者・監査ログを別途管理する
• 請求書APIは service: "invoice" + path: "/invoices" を標準にする。会計APIの旧 /api/1/invoices を新規実装の第一候補にしない

Dependencies

• Skills: lark-shared, lark-base, lark-doc, lark-im, lark-approval, lark-workflow-invoice-issue, lark-workflow-bookkeeping-auto-ops
• Required bins: python3, lark-cli, larc
• Optional bins: npx, freee-mcp

Architecture

Lark Base / Lark Doc / Lark Approval
        |
        v
Lark Harness Finance Agent
        |
        v
lark-harness-freee-mcp
  - intent normalization
  - approval gate
  - audit envelope
  - result reconciliation
        |
        v
freee-mcp official server
        |
        v
freee API

Safety Gate

Gate	操作	実行条件
G0 read	freee_server_info, freee_auth_status, freee_list_companies, GET系	ユーザー意図が明確なら可。ただし機密データをチャットへ大量貼付しない
G1 preview	Lark上で下書きDoc、Baseレコード、Harness Envelope作成	デフォルト。freeeには書かない
G2 draft write	freeeに請求書・見積書・取引・経費申請の下書きを作成	対象会社、金額、税区分、取引先、承認者が envelope に固定済み。明示承認必須
G3 issue/send/payment	請求書正式発行、メール送信、支払、返金、削除、確定処理	直前レビューと明示承認必須。実行後は即監査ログ
G4 destructive	freeeデータ削除、認証クリア、トークン削除	原則禁止。必要時は別途明示確認

mode=live は --company-id を必須にする。write操作では --approved-by に加え、Lark Approvalの --approval-instance-id またはレビューDocの --approval-doc-url を必須にする。請求書・見積書は partner_id、billing_date、正の明細合計がない状態では live envelope を作らない。

live write で固定必須の項目:

• invoice.create_draft / quotation.create_draft: partner_id, billing_date, 正の lines[].quantity * unit_price, lines[].description, lines[].tax_rate
• deal.create_income / deal.create_expense: type (income / expense), issue_date, partner_id, details[].account_item_id, details[].tax_code, 正の details[].amount
• expense_application.create: title, issue_date, applicant_id, details[].description, details[].transaction_date, details[].account_item_id, details[].tax_code, 正の details[].amount

Secret Handling

以下のファイルは存在確認と権限確認だけに留め、内容を読まない・出力しない。

• ~/.config/freee-mcp/config.json
• ~/.config/freee-mcp/.miyabi-tokens.json
• ~/.config/freee-mcp/.miyabi-app-credentials.env
• .env 内の FREEE_*

Harness Envelope

すべての freee write 操作は先にこの envelope を作る。

{
  "schema": "lark-harness.freee.operation.v1",
  "operation_id": "FREEE-20260503-092500",
  "mode": "preview",
  "risk_level": "write",
  "freee": {
    "service": "invoice",
    "action": "invoice.create_draft",
    "path": "/invoices",
    "company_id": null
  },
  "request": {},
  "lark_context": {
    "source": "manual",
    "base_url": null,
    "doc_url": null,
    "audit_folder_token": null
  },
  "approval": {
    "required": true,
    "approved_by": null,
    "approved_at": null,
    "approval_instance_id": null,
    "approval_doc_url": null
  },
  "audit": {
    "created_by": "codex",
    "created_at": "2026-05-03T09:25:00+09:00",
    "external_action_performed": false
  }
}

操作別 Playbook

請求書下書き

1. Lark Base / Doc / 会話から請求情報を抽出
2. scripts/freee-harness-envelope.py invoice.create_draft --request <json> で preview envelope を生成
3. Lark Docに請求内容レビューを作る
4. Lark Approval またはユーザーの明示承認を取得
5. freee MCPで freee_api_post を使い、service: "invoice", path: "/invoices" に下書き作成
6. freee上のID/確認URLを Lark Base「請求管理」へ同期
7. Lark Driveへ監査ログを保存

取引登録

1. 事前に freee_list_companies とマスタ取得で company_id / account_item_id / tax_code / walletable_id を確認
2. 推測IDやハードコードIDを使わない
3. deal.create_income または deal.create_expense envelope を作る
4. 承認後に service: "accounting", path: "/api/1/deals" で作成

経費申請

1. 領収書OCRとLark Approvalを先に通す
2. expense_application.create envelope を作る
3. freeeプラン要件に注意する
4. 承認後に freee MCP へ委譲

試算表・月次チェック

1. GETのみで取得
2. 生データをチャットへ全量貼らず、Lark Drive監査フォルダに保存
3. lark-workflow-bookkeeping-auto-ops に渡して月次チェック

CLI

Envelope生成:

python3 <skill-root>/scripts/freee-harness-envelope.py \
  invoice.create_draft \
  --request <skill-root>/templates/invoice-draft-request.json \
  --source manual \
  --lark-base-url "https://miyabi-g-k.jp.larksuite.com/base/..." \
  --out /tmp/freee-harness-envelope.json

スキーマ検証相当の簡易チェック:

python3 <skill-root>/scripts/freee-harness-envelope.py \
  invoice.create_draft \
  --request <skill-root>/templates/invoice-draft-request.json \
  --check-only

live用Envelopeは承認エビデンス必須:

python3 <skill-root>/scripts/freee-harness-envelope.py \
  invoice.create_draft \
  --request /path/to/final-invoice-request.json \
  --mode live \
  --company-id 123456 \
  --approved-by shunsuke \
  --approval-doc-url "https://miyabi-g-k.jp.larksuite.com/docx/..."

Completion Definition

• freee Remote MCP または local MCP 接続モードを確認
• company_id を明示
• 操作内容を Harness Envelope に固定
• freee write / send / payment / delete は明示承認済み
• Lark Base / Lark Drive に監査ログを残す
• freee操作結果のID、URL、金額、相手先、実行者を記録

Non Goals

• freee APIの独自クライアントを新規実装しない
• 認証トークンを読む・保存・表示しない
• 税務判断をAIだけで確定しない
• 請求書送付、支払、返金、契約締結を承認なしで実行しない