Invoice Studio

Markdown invoice templates with an MCP server for interactive editing (Claude Desktop / Cursor / Windsurf) and a headless generate pipeline for monthly PDF runs.

Agents: see AGENTS.md for the edit → generate → preview workflow. Registry → PDF → fork: USER-JOURNEY.md.

How it works

Phase 1 — Interactive studio: an AI client connects to the MCP server over stdio. You ask it to tweak the template or styles, regenerate, and inspect the preview PNG until the layout looks right.

Phase 2 — Monthly execution: update src/data/invoice-input.json (or inject it from CI), then run npm run generate to produce output/invoice.pdf and output/preview.png.

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

Setup

npm install
npm run build:mcp

Chrome or Chromium is required for PDF/PNG rendering. The generate script finds common install paths (macOS / Linux / Windows). If needed:

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

Generate an invoice (headless)

1. Edit monthly fields in src/data/invoice-input.json (amounts, dates, line items, etc.).
2. Optionally adjust layout in src/templates/invoice.md or src/styles/invoice.css.
3. Run:

npm run generate

Artifacts land in output/.

Use the MCP to edit and generate

1. Build and point your client at the server

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

Cursor (recommended): this repo includes .cursor/mcp.json. Open the project folder in Cursor, then reload MCP / the window. It uses ${workspaceFolder}/dist/index.js so the path is always the repo root.

If you configure MCP manually in Cursor Settings, use the absolute path to dist/index.js (relative dist/index.js alone resolves under your home directory and fails):

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

Claude Desktop — in claude_desktop_config.json (absolute paths required):

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

The server locates the repo from its own script path, so tools always read/write this project even if the client’s cwd is wrong.

Public MCP Registry

Registry name: io.github.vijayst/invoice-studio (npm: @vijayst/invoice-studio). After publish, search the official MCP Registry.

Clients that install from the registry typically run:

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

npx runs a copy of this repo (sample data included). You can generate output/invoice.pdf in that copy, then fork this repo and export the template into the clone.

Full walkthrough: USER-JOURNEY.md.

2. Interactive edit loop

Ask the model something like:

Read src/templates/invoice.md and tighten the payment section. Regenerate and show me the preview.

Typical tool sequence:

| Tool | Purpose | |------|---------| | read_template_file | Read src/templates/invoice.md or src/styles/invoice.css | | write_template_file | Write updated template/CSS | | run_generate_build | Runs npm run generate → PDF + output/preview.png | | get_invoice_preview | Returns the preview PNG for visual review | | get_git_status | Check what changed before committing | | get_workspace_root | Show the npx or clone directory this server is using | | export_studio_to_repo | Copy template/CSS/data from this workspace into a cloned fork |

Repeat edit → generate → preview until satisfied, then commit.

3. Scripts reference

| Script | Command | |--------|---------| | Build MCP | npm run build:mcp | | Start MCP (stdio) | npm run start:mcp | | Generate PDF/PNG | npm run generate |

Project layout

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