Skip to content

Commit 76c7e64

Browse files
jakexkimjakexkim
committed
docs: enterprise-quality README
1 parent 0287c51 commit 76c7e64

1 file changed

Lines changed: 162 additions & 0 deletions

File tree

‎README.md‎

Lines changed: 162 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,162 @@
1+
# @paperjsx/mcp-server
2+
3+
AI agents can reason about documents — structure a report, draft a contract, calculate an invoice — but they cannot produce the actual files. This MCP server gives Claude, Cursor, and any MCP-compatible agent the ability to generate presentations, reports, invoices, and contracts as real `.pptx`, `.docx`, and `.pdf` files.
4+
5+
[![npm](https://img.shields.io/npm/v/@paperjsx/mcp-server)](https://www.npmjs.com/package/@paperjsx/mcp-server)
6+
[![CI](https://github.com/paperjsx/mcp-server/actions/workflows/ci.yml/badge.svg)](https://github.com/paperjsx/mcp-server/actions/workflows/ci.yml)
7+
8+
## Install
9+
10+
```bash
11+
npm install -g @paperjsx/mcp-server
12+
```
13+
14+
Or run directly:
15+
16+
```bash
17+
npx @paperjsx/mcp-server
18+
```
19+
20+
## Quick Start — Claude Desktop
21+
22+
Add to `~/Library/Application Support/Claude/claude_desktop_config.json`:
23+
24+
```json
25+
{
26+
"mcpServers": {
27+
"paperjsx": {
28+
"command": "npx",
29+
"args": ["-y", "@paperjsx/mcp-server"],
30+
"env": {
31+
"PAPERJSX_API_KEY": "your-api-key"
32+
}
33+
}
34+
}
35+
}
36+
```
37+
38+
Restart Claude Desktop. Ask it to generate a presentation, invoice, or report.
39+
40+
### DOCX-Only Mode (No API Key)
41+
42+
The three DOCX tools (`generate_report_docx`, `generate_contract_docx`, `generate_invoice_docx`) render locally and do not require an API key. To use only these tools, omit the `env` block:
43+
44+
```json
45+
{
46+
"mcpServers": {
47+
"paperjsx": {
48+
"command": "npx",
49+
"args": ["-y", "@paperjsx/mcp-server"]
50+
}
51+
}
52+
}
53+
```
54+
55+
## Quick Start — Cursor
56+
57+
Add to Cursor's MCP settings (`.cursor/mcp.json`):
58+
59+
```json
60+
{
61+
"mcpServers": {
62+
"paperjsx": {
63+
"command": "npx",
64+
"args": ["-y", "@paperjsx/mcp-server"],
65+
"env": {
66+
"PAPERJSX_API_KEY": "your-api-key"
67+
}
68+
}
69+
}
70+
}
71+
```
72+
73+
## Tools
74+
75+
| Tool | Output | API Key | Description |
76+
| --- | --- | --- | --- |
77+
| `generate_presentation` | PPTX or PDF | Yes | Multi-slide presentations with 8 slide types: title, content, chart, two-column, quote, image, comparison, stats |
78+
| `generate_report` | PDF | Yes | Markdown-to-PDF reports with cover page, table of contents, headers/footers, and page numbers |
79+
| `generate_invoice` | PDF | Yes | Professional invoices with tax calculation, multi-currency, and regional compliance (EU, India, Brazil) |
80+
| `generate_chart` | PDF | Yes | Data visualization PDFs with line, bar, pie, and area charts |
81+
| `generate_report_docx` | DOCX | No | Structured reports with sections, bullet points, themes, and table of contents |
82+
| `generate_contract_docx` | DOCX | No | Legal contracts with parties, numbered clauses, recitals, and signature blocks |
83+
| `generate_invoice_docx` | DOCX | No | Itemized invoices with tax, shipping, and payment terms |
84+
| `list_templates` | Text | No | Browse all available document templates with schemas and examples |
85+
| `list_components` | Text | No | List available React components for custom templates |
86+
| `render_template` | Varies | Yes | Render a custom template by ID with data |
87+
88+
### Local vs Cloud
89+
90+
**Local rendering (no network, no API key):** `generate_report_docx`, `generate_contract_docx`, `generate_invoice_docx`. These use the built-in DOCX engine. Files never leave your machine.
91+
92+
**Cloud rendering (requires API key):** `generate_presentation`, `generate_report`, `generate_invoice`, `generate_chart`, `render_template`. These call the PaperJSX cloud API for PPTX and PDF generation.
93+
94+
## Environment Variables
95+
96+
| Variable | Required | Default | Description |
97+
| --- | --- | --- | --- |
98+
| `PAPERJSX_API_KEY` | For cloud tools | — | API key from [paperjsx.com](https://paperjsx.com) |
99+
| `PAPERJSX_API_URL` | No | `https://api.paperjsx.com` | API base URL (for self-hosted deployments) |
100+
| `PAPERJSX_OUTPUT_DIR` | No | `~/PaperJSX-Output` | Directory where generated files are saved |
101+
102+
## What Agents Can Do
103+
104+
### Generate a Word Report
105+
106+
> "Write a Q4 performance report as a Word document with sections for revenue, customers, and product updates."
107+
108+
The agent calls `generate_report_docx` with structured sections. Output: a `.docx` file with headings, bullet points, and optional table of contents.
109+
110+
### Create an Invoice
111+
112+
> "Generate an invoice for 3 months of enterprise software at $4,000/month plus $600 support. Tax rate 8.875%. Send to TechCorp Ltd in New York."
113+
114+
The agent calls `generate_invoice` with line items, sender/recipient details, and tax rate. Output: a print-ready PDF with automatic calculations.
115+
116+
### Build a Presentation
117+
118+
> "Make a 5-slide pitch deck: title slide, problem statement, solution, market size with a bar chart, and team slide."
119+
120+
The agent calls `generate_presentation` with slide types and content. Output: a `.pptx` file with editable charts that opens in PowerPoint.
121+
122+
### Draft a Contract
123+
124+
> "Draft a consulting agreement between Acme Corp and Smith Consulting for 6 months at $15,000/month."
125+
126+
The agent calls `generate_contract_docx` with parties, clauses, and signature blocks. Output: a `.docx` with formal legal formatting.
127+
128+
## Presentation Slide Types
129+
130+
The `generate_presentation` tool supports 8 slide layouts:
131+
132+
| Slide Type | Content | Layout |
133+
| --- | --- | --- |
134+
| `title` | Title + subtitle + optional background image | Centered, large type |
135+
| `content` | Heading + bullet points + optional image | Text with optional left/right image |
136+
| `chart` | Heading + chart data + caption | Full-width chart |
137+
| `two_column` | Heading + left/right content | Side-by-side columns |
138+
| `quote` | Quote text + attribution | Centered, large type |
139+
| `image` | Heading + image + caption | Full-bleed image |
140+
| `comparison` | Heading + labeled items | Comparison grid |
141+
| `stats` | Heading + metrics with trends | KPI cards |
142+
143+
Presentation themes: `corporate`, `modern`, `minimal`, `dark`, `gradient`. Aspect ratios: `16:9`, `4:3`.
144+
145+
## Artifact Management
146+
147+
Generated files are saved to `~/PaperJSX-Output/` (or `PAPERJSX_OUTPUT_DIR`) with timestamp prefixes. Files older than 24 hours are automatically cleaned up on server startup.
148+
149+
## Limitations
150+
151+
- Node.js >= 18 required.
152+
- PDF and PPTX tools require network access to the PaperJSX cloud API.
153+
- The output directory must be writable by the process.
154+
- Generated files are saved locally — the MCP server does not retain files on any remote server.
155+
156+
## Documentation
157+
158+
[paperjsx.com/docs/mcp](https://paperjsx.com/docs/mcp)
159+
160+
## License
161+
162+
MIT

0 commit comments

Comments
 (0)