Invoice Studio

Invoice Studio

带有 MCP 服务的发票模板，可进行交互式编辑（Claude Desktop / Cursor / Windsurf），并提供三种无头生成流水线，用于每月生成 PDF。

Agent：编辑 → 生成 → 预览工作流请参阅 AGENTS.md。注册表 → PDF → fork：USER-JOURNEY.md。

工作原理

**阶段 1 — 交互式工作室：**AI 客户端通过 stdio 连接到 MCP 服务。你可以让它调整模板或样式、重新生成，并检查预览 PNG，直到布局符合预期。

**阶段 2 — 每月执行：**从下方三条生成命令中选择一条。默认流水线会更新 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 文件。

原始 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）。

原始 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 Settings 中手动配置 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，然后 fork 此仓库，并将模板导出到克隆仓库中。

完整操作指南：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/数据复制到克隆的 fork

重复编辑 → 生成 → 预览，直到满意为止，然后提交。

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
原始 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