InvoiceFlow

InvoiceFlow はフリーランサー向けの請求書アプリです。クライアントを管理し、ブランドに合わせた請求書や見積書を作成し、公開決済リンクを共有して、Stripe Connect で支払いを受け取り、支払い期限を過ぎた場合のリマインダーを自動化できます。

MCP サーバー（エージェント向け）

InvoiceFlow には依存関係のないModel Context Protocol サーバーが付属しているため、Claude Desktop、Cursor、その他の MCP ホスト上のエージェントは、 REST ドキュメントを読まずに請求書を作成し、支払い可能な Stripe リンクを取得できます。

{
  "mcpServers": {
    "invoiceflow": {
      "command": "node",
      "args": ["/abs/path/invoiceflow-mcp.mjs"],
      "env": { "INVOICEFLOW_API_KEY": "ifk_..." }
    }
  }
}

サーバーは https://invoiceflow-ten-azure.vercel.app/sdk/invoiceflow-mcp.mjs からダウンロードできます。

ツール： whoami、create_client、list_clients、create_invoice、 list_invoices、get_invoice、share_invoice。

あえて機能を省いています。 メール送信、削除、返金、支払いを行うツールはありません。 請求書の作成はデータを追加する操作であり、人が取り消せます。一方、再試行のたびに顧客へ メールを送るエージェントが行った操作は取り消せません。金額は unitPrice という名前の 整数のセント単位で指定します。整数以外は丸めず、説明を添えて拒否します。25.5 が 何の説明もなく 25 セントを意味してしまうことは、実際の顧客に影響を及ぼしかねない 重大な不具合だからです。

アカウント不要で、自分で動作を確認できます：

curl -sO https://invoiceflow-ten-azure.vercel.app/sdk/invoiceflow-mcp.mjs
curl -sO https://invoiceflow-ten-azure.vercel.app/sdk/invoiceflow-client.mjs
curl -sO https://invoiceflow-ten-azure.vercel.app/sdk/test-mcp.mjs
node test-mcp.mjs     # 14 passed, 0 failed — no key, no network

---

技術スタック

• Node.js 22 と pnpm 10.34.9（package.json の packageManager）
• Next.js 15 App Router、React 18、TypeScript、Tailwind CSS、Framer Motion
• Google OAuth と JWT セッションを使用する NextAuth v5
• Prisma 5 と PostgreSQL 16。ローカルでは Docker Compose、デプロイでは Neon を使用
• Stripe Connect Express と Checkout、Resend、React Email
• Vitest による単体テストと PostgreSQL 統合テスト、ESLint、GitHub Actions

実装済みのワークフロー

領域	動作
クライアントと請求書	所有者ごとの管理、明細、割合による税金、下書きの編集、ステータス変更の制御
請求書の送信	「保存して送信」ではメールエンドポイントを呼び出します。メールが受理されると固定の公開リンクを使用し、送信に失敗した場合は保存済みの下書きを1件だけ保持します。明示的な再送も可能です
公開請求書	ブランドに合わせた表示、保存済みのメモと正確な税額内訳を含む、読みやすい複数ページのPDFエクスポート、推測されにくい共有トークン、noindex メタデータ
オンライン決済	税込み合計金額、オープン中のCheckoutセッションの再利用、署名付きWebhookによる照合
リマインダー	送信済みおよび期限超過の請求書に対する、段階的なメールリマインダー
定期請求書	スケジュール済みの下書き生成とスケジュール更新を、1つのデータベーストランザクションで実行
見積書	見積書の作成と管理、見積書から請求書への変換は1回のみ可能
レポートとエクスポート	売上、未払い残高、経過期間別の未払い額、クライアントレポート、CSVエクスポート
事業者プロフィール	名前、住所、ロゴ、アクセントカラー、請求書番号のプレフィックス

すべてのアカウントで14日間の無料トライアルを利用できます。トライアル終了後のInvoiceFlow Proは、Stripe Checkoutを通じて月額9米ドルです。カードの変更と解約はStripeの請求ポータルで行えます。トライアル終了後、請求書の作成と送信には有効なサブスクリプションが必要ですが、既存のレコード、PDF、エクスポート、クライアントの支払いは引き続き利用できます。請求書の支払いは各ユーザー自身のStripeアカウントに送金され、InvoiceFlowのサブスクリプションとは別です。決定事項はローンチ仕様書に記録されています。

インターフェースとデザインのガイドライン

公開サイト、Googleサインイン、ワークスペースでは、温かみのある白、濃いインク色、常緑色のビジュアルシステムを採用しています。インタラクティブな請求書のサンプル、コンパクトなテーブル、キーボードで操作しやすいモバイルナビゲーションも備えています。レポートでは通貨ごとに合計を分けて表示します。請求書や見積書の下書き内でクライアントを作成できます。

インターフェースを変更する前に、PRODUCT.mdとDESIGN.mdをお読みください。指定されたEmil Kowalski、Impeccable、Taste、frontend-designのスキルは、アップストリームのリビジョンとライセンス情報とともに、ローカルの.agents/skillsにインストールされています。デザインレビューには、レンダリングの確認結果と意図的に行ったトレードオフが記録されています。

ローカル開発

まずNode.js 22と、指定バージョンのpnpmをインストールしてください。既存のローカル設定は置き換えず、そのまま使用してください。

pnpm install --frozen-lockfile
test -e .env || cp .env.example .env
# Configure .env before continuing.
docker compose up -d --wait
pnpm run db:generate
pnpm run db:deploy
pnpm run dev

.env.exampleに記載されたローカルPostgreSQLのURLを、DATABASE_URLとDATABASE_URL_UNPOOLEDの両方に設定してください。AUTH_SECRETを生成し、Google OAuthの認証情報を追加して、NEXTAUTH_URLとNEXT_PUBLIC_APP_URLにはhttp://localhost:3000を使用してください。Google OAuthクライアントには、http://localhost:3000/api/auth/callback/googleを登録してください。

有効な認証情報を用意するまでは、StripeとResendの任意のキーは空欄のままにしてください。例の文字列はプレースホルダーです。設定されていない連携機能は利用不可のレスポンスを返します。Googleサインインと、送信・支払いの一連のワークフローをすべて利用するには、各サービスの実際の設定が必要です。

pnpm run db:deployは、コミット済みのマイグレーションを新しい開発用データベースに適用します。既存のデータベースがprisma db pushで作成されている場合は、マイグレーションを適用する前にベースライン手順に従ってください。本番環境のスキーマ変更をデプロイする際に、db pushやmigrate resetを使用しないでください。

Composeデータベースは永続化された名前付きボリュームを使用します。docker compose downを実行するとデータベースは停止しますが、そのボリュームは削除されません。

任意のデモデータ：

# Only against a disposable development database.
pnpm run db:seed

シード処理は、SEED_DEMO_EMAILで指定されたアカウント（デフォルトは[email protected]）と、その関連データを置き換えます。実在する顧客のアカウントや本番データベースを対象にしないでください。

PDF エクスポート

PDF のダウンロードでは、送信者と宛先のブロック、発行日／支払期日、通貨、ステータス、項目別の料金、税額、合計を分けた、寸法を調整した A4 レイアウトを使用します。長い記録は、表の見出しを繰り返して複数ページに分割されます。保存済みの請求書の「メモ」は「メモと支払い方法」の下に含まれます。支払いの詳細と請求期間はここに入力できます。PDF には保存済みの請求金額が反映され、支払いステータスやデータは変更されません。

合成 PDF の例を表示し、レイアウトのレビューも確認してください。データベースやプロバイダーにアクセスせずに、短・標準・長のレビュー用フィクスチャを生成します。

pnpm exec tsx scripts/preview-invoice-pdf.ts

設定

変数	用途
DATABASE_URL	Prisma の実行時 PostgreSQL 接続。デプロイでは Neon のプール済み URL を使用します
DATABASE_URL_UNPOOLED	Prisma のマイグレーション用の直接データベース接続
AUTH_SECRET	安定した非公開の NextAuth 署名／暗号化シークレット
AUTH_GOOGLE_ID, AUTH_GOOGLE_SECRET	Google Web OAuth クライアントの認証情報
NEXTAUTH_URL	正規の認証オリジン。本番環境では HTTPS を使用します
AUTH_TRUST_HOST	Vercel など、信頼できるデプロイプロキシの背後でのみ true に設定します
NEXT_PUBLIC_APP_URL	請求書、支払い、メールの URL に使用する正規の公開 HTTPS オリジン
STRIPE_SECRET_KEY	Connect と Checkout 用の Stripe プラットフォーム API キー
STRIPE_WEBHOOK_SECRET	このデプロイの連結アカウント用 webhook エンドポイントの署名シークレット
STRIPE_CONNECT_COUNTRY	新規作成アカウントでサポートされる Connect の国。既定値は US です
RESEND_API_KEY, RESEND_FROM_EMAIL	メール API キーと、認証済み Resend ドメインの送信者
FREELANCER_NOTIFY_EMAIL	請求書の所有者にメールアドレスがない場合に限り使用するフォールバック
CRON_SECRET	請求書の定期生成とリマインダー用のスケジュール済み処理に使用する Bearer シークレット
SEED_DEMO_EMAIL	破壊的なデモ用シード処理の対象となる使い捨てアカウント

NEXT_PUBLIC_STRIPE_PUBLISHABLE_KEY は設定例で予約されています。現在のホスト型 Checkout リダイレクトでは、ブラウザー向けの Stripe SDK は使用しません。INNGEST_* 変数も使用されていません。

シークレットは、Git の追跡対象外となっているローカル環境ファイル、またはホスティングプロバイダーの安全な設定に保管してください。プレビュー環境と本番環境のデプロイでは、別々のデータベースとサービスキーを使用してください。

検証

pnpm test
pnpm run lint
NEXT_PUBLIC_APP_URL=https://invoiceflow.example.test pnpm run build
pnpm run typecheck
# After building, against the disposable local test DB:
pnpm run test:browser
pnpm audit --prod --audit-level high

これらのローカルブラウザーチェックでは、ビルドに上記の HTTPS テストオリジンを使用します。Vercel のリリースでは、実際に設定された本番オリジンを使用します。Next.js はビルド時に NEXT_PUBLIC_APP_URL を埋め込みます。

ビルドでは Prisma Client を生成し、すべてのルートをコンパイルして、本番アプリケーションを生成します。本番の Vercel ビルドでは、ガード付きリリースステップでデータベースの検証とマイグレーションを先に実行します。ローカルビルドとプレビュービルドでは、明示的なデータベースの準備が必要です。設定済みの next/font ローダーには、Google Fonts へのアクセスが必要です。Prisma のダウンロードでは、TLS とチェックサム検証を維持してください。

統合テストでは、invoiceflow_test という名前の別の使い捨てローカルデータベースを使用します。次のコマンドを一度だけ実行して作成します。

docker compose exec -T db createdb -U postgres invoiceflow_test

続いて、次を実行します。

export DATABASE_URL='postgresql://postgres:postgres@localhost:5432/invoiceflow_test?schema=public'
export DATABASE_URL_UNPOOLED="$DATABASE_URL"
pnpm run db:deploy
pnpm run test:integration

これらのエクスポートは、開発サーバーとは別のシェルで実行してください。テストスイートは、リモートデータベースとその他のデータベース名を拒否します。実際の PostgreSQL トランザクションと署名済み Stripe フィクスチャを使用し、外部への Stripe／Resend リクエストはモックします。請求書の合計、公開リンク、Checkout の再利用、webhook の検証と再試行、並行処理での番号付け／変換、定期処理のトランザクションロールバックを対象とします。実際の OAuth、支払い、メールの認証情報が機能することを確認するものではありません。

GitHub Actions は、PostgreSQL 16 と Node.js 22 を使用して、ロックファイルに基づくインストール、Prisma の生成、マイグレーション、lint、単体／統合テスト、本番ビルド、Chromium のブラウザーワークフロー、型チェック、本番依存関係の監査を実行します。

デプロイ

マイグレーションの処理、サービス設定、スケジュール済みジョブ、必須のテストモードでのリリーススモークテストについては、Vercel と Neon のリリースガイドを参照してください。ローカルチェックに合格しても、デプロイ済みアプリケーションの検証とは別です。

スケジュール実行ジョブ

どちらのジョブも GET を使用し、Authorization: Bearer <CRON_SECRET> が必要です。

• /api/cron/generate-recurring は、期限が到来した下書き請求書を作成し、スケジュールを更新します。
• /api/cron/chase-invoices は、期限が到来したリマインダーを送信します。

vercel.json では、生成ジョブを毎日 00:00 UTC、リマインダーを毎日 09:00 UTC に実行するようスケジュールしています。CRON_SECRET が設定されている場合、Vercel はベアラーヘッダーを送信します。より大規模なワークロードを有効にする前に、プランのスケジュール実行と関数実行時間の上限を確認してください。

現在の製品上の制限

• Online Checkout は、小数点以下 2 桁の通貨と、検証済みの金額上限内の正の合計金額に対応しています。税金を含む請求書合計を 1 件分請求し、内訳は公開請求書に表示されます。
• ダッシュボードとレポートには、選択した通貨の金額合計が表示されます。通貨換算や、外国為替を統合した合計金額には対応していません。最近の請求書には、それぞれの通貨が表示されます。
• 公開決済の IP スロットリングはメモリ内で実行されるため、Vercel インスタンス間ではベストエフォートです。より大規模なデプロイには、分散レートリミッターが必要です。
• 現在、決済確認メールは請求書の所有者に送信されます。顧客向けの領収書を別途送信するワークフローには対応していません。
• 定期実行ジョブは下書きを作成しますが、自動送信や、保存済み決済手段への請求は行いません。
• 返金、一部入金、および請求書単位の会計機能には、別途製品開発が必要です。InvoiceFlow Pro のプランは月額プラン 1 種類のみで、年額プラン、クーポン、チームシートはありません。

アーキテクチャ

                           ┌─────────────────────────────┐
                           │      Client / Browser       │
                           └──────────────┬──────────────┘
                                          │
                                          ▼
                         ┌─────────────────────────────────┐
                         │   Next.js Middleware (Auth)     │
                         └──────────────┬──────────────────┘
                                        │
        ┌───────────────────────────────┼───────────────────────────────┐
        ▼                               ▼                               ▼
 ┌──────────────┐             ┌──────────────────┐            ┌──────────────────┐
 │ Landing Page │             │ Dashboard (App)  │            │  Public Invoice  │
 │     `/`      │             │  `/(dashboard)`  │            │   `/i/[token]`   │
 └──────────────┘             └─────────┬────────┘            └────────┬─────────┘
                                        │                              │
                                        ▼                              ▼
                         ┌─────────────────────────────────────────────────┐
                         │               API Routes & Crons                │
                         │   • /api/invoices        • /api/estimates       │
                         │   • /api/clients         • /api/cron/*          │
                         │   • /api/i/[token]/pay   • /api/webhooks/stripe │
                         └──────────────────────┬──────────────────────────┘
                                                │
         ┌──────────────────────────────────────┼──────────────────────────────────────┐
         ▼                                      ▼                                      ▼
┌──────────────────┐                  ┌──────────────────┐                   ┌──────────────────┐
│  Neon Postgres   │                  │  Stripe Connect  │                   │      Resend      │
│  (Prisma Engine) │                  │ (Checkout & Web) │                   │  (React Emails)  │
└──────────────────┘                  └──────────────────┘                   └──────────────────┘

---

構成

prisma/             Schema, migrations and disposable demo seed
src/app/            Marketing, authenticated app, public invoices and API routes
src/lib/            Billing, auth, money, reporting, validation and integrations
src/emails/         React Email templates
src/components/     UI, reports and marketing components
integration/        PostgreSQL-backed billing regression tests
.github/workflows/  CI

ブラウザーワークフローテスト

DATABASE_URL と DATABASE_URL_UNPOOLED が、使い捨てのローカル invoiceflow_test データベースを参照するように設定したうえで、pnpm run build の後に pnpm run test:browser を実行してください。システムに Chromium がない場合は、 pnpm exec playwright install chromium でインストールしてください。ブラウザーテストは、 ポート 3100 で本番サーバーを起動し、分離されたテストアカウントとローカルで署名した セッションを使用して、実際のページ、API リクエスト、データベースへの書き込みをテストします。 デザインチェックでは、公開請求書、請求書・見積書の詳細、キーボード操作、動きを抑える設定、 モバイルでのサインアウトなど、13 のルートをデスクトップ（1440px）、タブレット（768px）、 スマートフォン（390px）の幅で検証します。PDF ブラウザーテストでは、「PDF をダウンロード」 ボタンもテストし、エクスポートされた値と注記を解析して、別アカウントからのダウンロードや 未認証でのダウンロードを拒否します。Google OAuth の完了や、実際のメール・決済の送信は 行いません。プロバイダーの HTTP レスポンスには、テストサーバーにのみ読み込まれる 保護されたローカルフィクスチャを使用します。これらのフィクスチャは、実際の Resend／Stripe SDK リクエストをテストすると同時に、フィクスチャに一致しない外部リクエストをブロックします。 ブラウザーチェックでは、「保存して送信」、プロバイダーによる拒否と再試行、明示的な再送信、 既存の発行済み請求書、Stripe の準備状況の再照合、および Checkout へのリダイレクトを検証します。 本番環境の設定と、メールの受理と受信トレイへの配信の違いについては、 配信と決済のチェックを参照してください。