Invoice Studio

Invoice Studio

インタラクティブな編集（Claude Desktop / Cursor / Windsurf）に対応した MCP サーバー付きの請求書テンプレートと、月次 PDF 出力のための 3 つのヘッドレス生成パイプラインです。

エージェント向け：編集 → 生成 → プレビューのワークフローについては、AGENTS.md を参照してください。レジストリ → PDF → フォークについては、USER-JOURNEY.md を参照してください。

動作の仕組み

フェーズ 1 — インタラクティブスタジオ： AI クライアントが stdio 経由で MCP サーバーに接続します。テンプレートやスタイルの調整、再生成、プレビュー PNG の確認を依頼し、レイアウトが整うまで繰り返します。

フェーズ 2 — 月次実行： 以下の 3 つの生成コマンドから 1 つを選びます。デフォルトのパイプラインでは、src/data/invoice-input.json を更新（または CI から注入）してから、npm run generate を実行し、output/invoice.pdf と output/preview.png を生成します。

Markdown + Handlebars（npm run generate）

src/templates/invoice.md   ← Markdown template ({{placeholders}} for data)
src/styles/invoice.css     ← Print styles
src/data/invoice-input.json
        │
        ▼  npm run generate
output/invoice.md          ← rendered markdown
output/invoice.html
output/invoice.pdf
output/preview.png         ← used by get_invoice_preview

Handlebars が src/data/invoice-input.json の内容を使って src/templates/invoice.md に値を埋め込みます。Marked がその Markdown を HTML に変換し、src/styles/invoice.css でスタイルを適用して、ヘッドレス Chrome が PDF とプレビューを書き出します。

Handlebars + Tailwind CDN（npm run generate:hbs）

src/templates/invoice.hbs  ← HTML template ({{placeholders}} + Tailwind classes)
src/data/invoice-input.json
        │
        ▼  npm run generate:hbs
output/invoice-hbs.html
output/invoice-hbs.pdf
output/preview-hbs.png

scripts/generate-invoice-hbs.js が同じ JSON を使って src/templates/invoice.hbs をコンパイルします。スタイルにはテンプレート内の Tailwind ユーティリティクラスを使用します。ページは https://cdn.jsdelivr.net/npm/@tailwindcss/browser@4 から Tailwind を読み込むため、このコマンドにはネットワークアクセスが必要です。このスクリプトは CSS ファイルをコンパイルしません。

Raw Markdown（npm run generate:raw）

src/templates/invoice-raw.md  ← Markdown with invoice values written in
src/styles/invoice.css
        │
        ▼  npm run generate:raw
output/invoice-raw.html
output/invoice-raw.pdf
output/preview-raw.png

src/templates/invoice-raw.md には請求書の本文（日時、金額、当事者、明細）が含まれています。scripts/generate-invoice-raw.js がこのファイルを Marked と src/styles/invoice.css で変換します。この方法では invoice-input.json を読み込まず、Handlebars も実行しません。月ごとの値を変更する場合は Markdown を編集してください。

セットアップ

npm install
npm run build:mcp

PDF/PNG のレンダリングには Chrome または Chromium が必要です。生成スクリプトは一般的なインストール先（macOS / Linux / Windows）を検索します。必要に応じて、次のようにします。

export CHROME_PATH="/Applications/Google Chrome.app/Contents/MacOS/Google Chrome"

請求書の生成（ヘッドレス）

Markdown + Handlebars

1. src/data/invoice-input.json の月次項目（金額、日付、明細など）を編集します。
2. 必要に応じて、src/templates/invoice.md または src/styles/invoice.css のレイアウトを調整します。
3. npm run generate を実行します。

Handlebars + Tailwind

1. 月ごとの値に合わせて src/data/invoice-input.json を編集します。
2. src/templates/invoice.hbs の Tailwind クラスを使ってレイアウトを調整します。
3. npm run generate:hbs を実行します（Chrome が Tailwind CDN を読み込めるよう、ネットワークが必要です）。

Raw Markdown

1. src/templates/invoice-raw.md の値を直接編集します。
2. 必要に応じて src/styles/invoice.css を調整します。
3. npm run generate:raw を実行します。

生成物は output/ に出力されます。

MCP を使った編集と生成

1. ビルドしてクライアントをサーバーに接続する

npm install
npm run build:mcp   # required — creates dist/index.js

Cursor（推奨）： このリポジトリには .cursor/mcp.json が含まれています。Cursor でプロジェクトフォルダーを開き、MCP / ウィンドウを再読み込みしてください。${workspaceFolder}/dist/index.js を使用するため、パスは常にリポジトリのルートを指します。

Cursor の設定で MCP を手動設定する場合は、dist/index.js の絶対パスを使用してください（相対パスの dist/index.js だけを指定すると、ホームディレクトリ内で解決され、失敗します）。

{
  "mcpServers": {
    "invoice-studio": {
      "command": "node",
      "args": ["/Users/YOU/Documents/invoice/dist/index.js"]
    }
  }
}

Claude Desktop — claude_desktop_config.json 内で設定します（絶対パスが必要です）。

{
  "mcpServers": {
    "invoice-studio": {
      "command": "node",
      "args": ["/Users/YOU/Documents/invoice/dist/index.js"]
    }
  }
}

サーバーは自身のスクリプトパスからリポジトリを特定するため、クライアントの cwd が間違っていても、ツールは常にこのプロジェクトのファイルを読み書きします。

パブリック MCP レジストリ

レジストリ名：io.github.vijayst/invoice-studio（npm：@vijayst/invoice-studio）。公開後は、公式 MCP レジストリで検索してください。

レジストリからインストールするクライアントでは、通常、次のコマンドを実行します。

{
  "mcpServers": {
    "invoice-studio": {
      "command": "npx",
      "args": ["-y", "@vijayst/invoice-studio"]
    }
  }
}

npx はこのリポジトリのコピー（サンプルデータを含む）を実行します。そのコピーで output/invoice.pdf を生成した後、このリポジトリをフォークし、テンプレートをクローンにエクスポートできます。

詳しい手順については、USER-JOURNEY.md を参照してください。

2. 対話型編集ループ

次のようにモデルに依頼します。

src/templates/invoice.md を読み、支払いに関するセクションを簡潔にしてください。再生成してプレビューを表示してください。

一般的なツールの実行順序：

ツール	目的
read_template_file	src/templates/invoice.md または src/styles/invoice.css を読み込む
write_template_file	更新したテンプレート／CSS を書き込む
run_generate_build	npm run generate を実行 → PDF と output/preview.png を生成
get_invoice_preview	目視確認用にプレビュー PNG を返す
get_git_status	コミット前に変更内容を確認する
get_workspace_root	このサーバーが使用している npx またはクローン先のディレクトリを表示する
export_studio_to_repo	このワークスペースのテンプレート／CSS／データをクローンしたフォークにコピーする

編集 → 生成 → プレビューを、満足するまで繰り返してからコミットします。

3. スクリプト一覧

スクリプト	コマンド
MCP をビルド	npm run build:mcp
MCP を起動（stdio）	npm run start:mcp
Markdown + Handlebars PDF	npm run generate
Handlebars + Tailwind CDN PDF	npm run generate:hbs
Raw Markdown PDF	npm run generate:raw

プロジェクトの構成

├── smithery.yaml
├── package.json
├── src/
│   ├── templates/invoice.md
│   ├── templates/invoice.hbs
│   ├── templates/invoice-raw.md
│   ├── styles/invoice.css
│   ├── data/invoice-input.json
│   └── mcp/index.ts
├── scripts/generate-invoice.js
├── scripts/generate-invoice-hbs.js
├── scripts/generate-invoice-raw.js
└── output/preview.png