@agent2pdf/mcp-server 1.0.2 → 1.1.1

package/README.md

@@ -1,15 +1,18 @@
 # @agent2pdf/mcp-server
 
-Official MCP (Model Context Protocol) Server for Agent2PDF with auto-polling support.
+Official MCP (Model Context Protocol) stdio Server for Agent2PDF with auto-polling support.
 
 This MCP Server acts as a bridge between MCP clients (like Claude Desktop, Cursor) and the Agent2PDF async job API. It automatically handles job creation, polling, and returns a direct download URL when the PDF is ready, providing a "pseudo-synchronous" experience.
 
+> **Note:** Agent2PDF also provides an HTTP MCP endpoint (`POST https://api.agent2pdf.com/api/v1/mcp`) for agents that cannot run a local Node process. The HTTP endpoint returns `job_id` only — agents must poll manually. **This stdio server is recommended** for the best experience.
+
 ## Features
 
-- 🚀 **Auto-polling**: Automatically polls job status until completion
+- 🚀 **Auto-polling**: `generate_pdf` automatically polls job status and returns `download_url` directly
 - 📦 **Zero-config**: Works out of the box with `npx`
-- 🔄 **Three tools**: `generate_pdf`, `list_available_templates`, `get_job_status`
+- 🔄 **Seven tools**: `generate_pdf`, `list_available_templates`, `get_job_status`, `get_branding`, `upload_logo`, `remove_logo`, `submit_feedback`
 - ⚡ **Fast**: Typical wait time: 5-30 seconds
+- 🔀 **Pseudo-synchronous**: No manual polling needed — just call `generate_pdf` and get the download URL
 
 ## Installation
 
@@ -27,6 +30,14 @@ npx @agent2pdf/mcp-server
 npm install -g @agent2pdf/mcp-server
 ```
 
+### Check version
+
+From a directory **outside** the repo (e.g. `/tmp`), you can confirm the installed version:
+
+```bash
+npx @agent2pdf/mcp-server --version
+```
+
 ## Configuration
 
 **Note:** The server connects to the **production** API (`https://api.agent2pdf.com/api/v1`) by default. To use the dev environment, set the `AGENT2PDF_API_BASE` environment variable.
@@ -109,7 +120,7 @@ Add to your Cursor settings (`.cursor/mcp.json` or similar):
 
 ### `generate_pdf`
 
-Generate a PDF from Markdown content. This tool automatically handles the async job process and returns a download URL when ready.
+Generate a PDF from Markdown content. This tool **automatically handles the async job process** (creates job → polls every 3s → returns download URL when ready). Typical wait: 5–30 seconds.
 
 **Arguments:**
 - `markdown` (required): The document body in Markdown format
@@ -117,6 +128,8 @@ Generate a PDF from Markdown content. This tool automatically handles the async
 - `title` (optional): Document title. Defaults to "Untitled"
 - `author` (optional): Author or company name
 - `template_id` (optional): Custom template ID if using a saved template
+- `use_logo` (optional): Whether to include the company logo in the PDF. Defaults to user settings (true if a logo is uploaded)
+- `heading_numbering` (optional): Heading numbering style. `none` (default), `1.1` (hierarchical, recommended for tech_spec), `1.` (flat, recommended for report), `1.1.1` (deep hierarchical). Manually numbered headings are auto-stripped.
 
 **Example:**
 ```
@@ -146,12 +159,79 @@ Check the status of an async PDF job. Useful for manual polling.
 Check job status for job_id "abc123"
 ```
 
+### `get_branding`
+
+Get current branding settings: company name, logo status, colors, font, and watermark. Use this to check whether a logo is already uploaded before generating a PDF.
+
+**Arguments:** None
+
+**Example:**
+```
+Show my current branding settings
+```
+
+### `upload_logo`
+
+Upload or replace the company logo used in PDF headers and cover pages. Provide either a public image URL or a base64-encoded image. PNG/JPG/SVG/WebP, max 2 MB. Min 128×128px, max 2048×2048px. Max aspect ratio 5:1. Recommended: horizontal logo ~600×200px, transparent PNG. The logo will appear on all future PDFs when `use_logo` is enabled (default).
+
+**Arguments:**
+- `logo_url` (optional): Public URL of the logo image to download and store
+- `logo_base64` (optional): Base64-encoded image, optionally as a data URI (e.g. `data:image/png;base64,...`)
+
+Provide exactly one of `logo_url` or `logo_base64`.
+
+**Example:**
+```
+Upload my company logo from URL "https://example.com/logo.png"
+```
+
+### `remove_logo`
+
+Remove the current company logo. PDFs generated after this will show the company name instead of a logo.
+
+**Arguments:** None
+
+**Example:**
+```
+Remove the current logo
+```
+
+### `submit_feedback`
+
+Submit feedback about Agent2PDF service. **Best practice: call this after every PDF generation session** to report quality, suggest improvements, or flag issues. Even a short note helps.
+
+**Arguments:**
+- `title` (required): Brief summary of your feedback
+- `category` (optional): `bug`, `feature_request`, `template_request`, `usability`, `general` (default)
+- `rating` (optional): 1–5 satisfaction rating
+- `body` (optional): Detailed description
+- `job_id` (optional): Related job ID if applicable
+- `template_type` (optional): Related template type if applicable
+
+**Example:**
+```
+Submit feedback: title "Great PDF quality", category "general", rating 5, body "The tech_spec template works perfectly for API docs."
+```
+
 ## How It Works
 
 1. **Job Creation**: When `generate_pdf` is called, the server creates an async job via `POST /api/v1/jobs`
 2. **Auto-polling**: The server polls `GET /api/v1/jobs/{job_id}` every 3 seconds
 3. **Completion**: When the job status is `completed`, it returns the download URL
-4. **Error Handling**: If the job fails or times out, it returns an error message
+4. **Error Handling**: If the job fails or times out (~2 min), it returns an error message
+5. **Branding**: `get_branding`, `upload_logo`, and `remove_logo` manage branding via `GET/POST/DELETE /api/v1/settings/logo`
+
+## stdio Server vs HTTP Endpoint
+
+| Aspect | This stdio Server | HTTP Endpoint (`/api/v1/mcp`) |
+|--------|-------------------|-------------------------------|
+| `generate_pdf` returns | `download_url` directly | `job_id` only (manual polling needed) |
+| Polling | Automatic (internal) | Agent calls `get_job_status` in a loop |
+| Requires local Node | Yes (npx or global install) | No |
+| MCP protocol | Full (@modelcontextprotocol/sdk) | Simplified (tools/list + tools/call only) |
+| Best for | Claude Desktop, Cursor, local agents | Cloud agents, serverless environments |
+
+For the HTTP endpoint, see: https://agent2pdf.com/docs/api.md
 
 ## Development
 

package/dist/index.js

@@ -1,15 +1,17 @@
 #!/usr/bin/env node
-import{Server as w}from"@modelcontextprotocol/sdk/server/index.js";import{StdioServerTransport as h}from"@modelcontextprotocol/sdk/server/stdio.js";import{CallToolRequestSchema as E,ListToolsRequestSchema as j}from"@modelcontextprotocol/sdk/types.js";import i,{AxiosError as $}from"axios";var p=process.env.AGENT2PDF_API_BASE||"https://api.agent2pdf.com/api/v1",A=parseInt(process.env.AGENT2PDF_POLLING_INTERVAL_MS||"3000",10),u=parseInt(process.env.AGENT2PDF_MAX_RETRIES||"40",10),g=process.env.AGENT2PDF_API_KEY;g||(console.error("[Agent2PDF] Error: AGENT2PDF_API_KEY environment variable is required."),process.exit(1));var P=()=>g,v=o=>{if(o instanceof $&&o.response?.data){let s=o.response.data;return`[${s.code}] ${s.message}${s.request_id?` (request_id: ${s.request_id})`:""}`}return o instanceof Error?o.message:String(o)},c=new w({name:"agent2pdf-mcp-server",version:"1.0.0"},{capabilities:{tools:{}}});c.setRequestHandler(j,async()=>({tools:[{name:"generate_pdf",description:"Generate a PDF from Markdown. This tool handles the async job process internally and returns a direct download URL when ready. Typical wait time: 5-30 seconds.",inputSchema:{type:"object",properties:{markdown:{type:"string",description:"The document body in Markdown format."},template_type:{type:"string",description:"Template type: general, tech_spec, invoice, report, resume, letter, meeting. Defaults to general.",enum:["general","tech_spec","invoice","report","resume","letter","meeting"]},title:{type:"string",description:"Document title. Defaults to 'Untitled'."},author:{type:"string",description:"Author or company name (optional)."},template_id:{type:"string",description:"Custom template ID if using a saved template (optional)."}},required:["markdown"]}},{name:"list_available_templates",description:"Get a list of available built-in PDF templates with descriptions and recommended use cases.",inputSchema:{type:"object",properties:{}}},{name:"get_job_status",description:"Check the status of an async PDF job. Use this if you want to manually poll a job.",inputSchema:{type:"object",properties:{job_id:{type:"string",description:"The job ID returned by generate_pdf or POST /api/v1/jobs."}},required:["job_id"]}}]}));c.setRequestHandler(E,async o=>{let s=P(),{name:a,arguments:r}=o.params;try{if(a==="list_available_templates")return{content:[{type:"text",text:`Available Templates:
+import{createRequire as w}from"module";import{Server as P}from"@modelcontextprotocol/sdk/server/index.js";import{StdioServerTransport as j}from"@modelcontextprotocol/sdk/server/stdio.js";import{CallToolRequestSchema as $,ListToolsRequestSchema as R}from"@modelcontextprotocol/sdk/types.js";import p,{AxiosError as v}from"axios";var E=w(import.meta.url),x=E("../package.json"),y=x.version;process.argv.includes("--version")&&(console.log(y),process.exit(0));var l=process.env.AGENT2PDF_API_BASE||"https://api.agent2pdf.com/api/v1",A=parseInt(process.env.AGENT2PDF_POLLING_INTERVAL_MS||"3000",10),u=parseInt(process.env.AGENT2PDF_MAX_RETRIES||"40",10),f=process.env.AGENT2PDF_API_KEY;f||(console.error("[Agent2PDF] Error: AGENT2PDF_API_KEY environment variable is required."),process.exit(1));var k=()=>f,D=a=>{if(a instanceof v&&a.response?.data){let s=a.response.data;return`[${s.code}] ${s.message}${s.request_id?` (request_id: ${s.request_id})`:""}`}return a instanceof Error?a.message:String(a)},g=new P({name:"agent2pdf-mcp-server",version:y},{capabilities:{tools:{}}});g.setRequestHandler(R,async()=>({tools:[{name:"generate_pdf",description:"Generate a PDF from Markdown. This tool handles the async job process internally and returns a direct download URL when ready. Typical wait time: 5-30 seconds.",inputSchema:{type:"object",properties:{markdown:{type:"string",description:"The document body in Markdown format."},template_type:{type:"string",description:"Template type: general, tech_spec, invoice, report, resume, letter, meeting. Defaults to general.",enum:["general","tech_spec","invoice","report","resume","letter","meeting"]},title:{type:"string",description:"Document title. Defaults to 'Untitled'."},author:{type:"string",description:"Author or company name (optional)."},template_id:{type:"string",description:"Custom template ID if using a saved template (optional)."},use_logo:{type:"boolean",description:"Whether to include the company logo in the PDF. Defaults to user settings (true if a logo is uploaded)."}},required:["markdown"]}},{name:"list_available_templates",description:"Get a list of available built-in PDF templates with descriptions and recommended use cases.",inputSchema:{type:"object",properties:{}}},{name:"get_job_status",description:"Check the status of an async PDF job. Use this if you want to manually poll a job.",inputSchema:{type:"object",properties:{job_id:{type:"string",description:"The job ID returned by generate_pdf or POST /api/v1/jobs."}},required:["job_id"]}},{name:"get_branding",description:"Get current branding settings: company name, logo status, colors, font, and watermark. Use this to check whether a logo is already uploaded before generating a PDF.",inputSchema:{type:"object",properties:{}}},{name:"upload_logo",description:"Upload or replace the company logo. Accepts PNG/JPG/SVG/WebP, max 2 MB, 128-2048px per side, max 5:1 aspect ratio. Recommended: horizontal PNG ~600x200px with transparent background. The logo appears in PDF headers and cover pages.",inputSchema:{type:"object",properties:{logo_url:{type:"string",description:"Public URL of the logo image to download and store."},logo_base64:{type:"string",description:"Base64-encoded image, optionally as a data URI (e.g. data:image/png;base64,...)."}}}},{name:"remove_logo",description:"Remove the current company logo. PDFs generated after this will show the company name instead of a logo.",inputSchema:{type:"object",properties:{}}},{name:"submit_feedback",description:"Submit feedback about Agent2PDF service \u2014 report bugs, request features or templates, or share your experience.",inputSchema:{type:"object",properties:{category:{type:"string",enum:["bug","feature_request","template_request","usability","general"],description:"Type of feedback."},rating:{type:"integer",minimum:1,maximum:5,description:"Optional 1-5 rating."},title:{type:"string",description:"Brief summary of your feedback."},body:{type:"string",description:"Detailed description."},job_id:{type:"string",description:"Related job ID if applicable."},template_type:{type:"string",description:"Related template type if applicable."}},required:["title"]}}]}));g.setRequestHandler($,async a=>{let s=k(),{name:i,arguments:n}=a.params;try{if(i==="list_available_templates")return{content:[{type:"text",text:`Available Templates:
 
-${(await i.get(`${p}/templates/manifest`)).data.templates.map(t=>`- **${t.id}** (${t.name}): ${t.description}`).join(`
-`)}`}]};if(a==="get_job_status"){let n=r.job_id,e=(await i.get(`${p}/jobs/${n}`,{headers:{"X-API-Key":s}})).data,t=`Job Status:
-- ID: ${e.job_id}
-- Status: ${e.status}`;return e.progress!==void 0&&(t+=`
-- Progress: ${e.progress}%`),e.download_url&&(t+=`
-- Download URL: ${e.download_url}`),e.expires_at&&(t+=`
-- Expires: ${e.expires_at}`),e.error_message&&(t+=`
-- Error: ${e.error_message}`),{content:[{type:"text",text:t}]}}if(a==="generate_pdf"){if(!r||typeof r!="object")throw new Error("Invalid arguments: args must be an object");if(!r.markdown||typeof r.markdown!="string"||r.markdown.trim().length===0)throw new Error("markdown is required and cannot be empty");let n=["general","tech_spec","invoice","report","resume","letter","meeting"];if(r.template_type&&typeof r.template_type=="string"&&!n.includes(r.template_type))throw new Error(`Invalid template_type: ${r.template_type}. Valid values: ${n.join(", ")}`);console.error("[Agent2PDF] Submitting job...");let e=(await i.post(`${p}/jobs`,r,{headers:{"X-API-Key":s,"Content-Type":"application/json"}})).data.job_id;console.error(`[Agent2PDF] Job started: ${e}. Polling for completion...`);for(let t=0;t<u;t++){t>0&&await new Promise(y=>setTimeout(y,A));let _=await i.get(`${p}/jobs/${e}`,{headers:{"X-API-Key":s}}),{status:l,download_url:m,error_message:b,progress:f}=_.data;if(console.error(`[Agent2PDF] Poll ${t+1}/${u}: status=${l}, progress=${f??"N/A"}`),l==="completed"&&m)return{content:[{type:"text",text:`PDF Generated Successfully!
+${(await p.get(`${l}/templates/manifest`)).data.templates.map(o=>`- **${o.id}** (${o.name}): ${o.description}`).join(`
+`)}`}]};if(i==="get_job_status"){let e=n.job_id,t=(await p.get(`${l}/jobs/${e}`,{headers:{"X-API-Key":s}})).data,o=`Job Status:
+- ID: ${t.job_id}
+- Status: ${t.status}`;return t.progress!==void 0&&(o+=`
+- Progress: ${t.progress}%`),t.download_url&&(o+=`
+- Download URL: ${t.download_url}`),t.expires_at&&(o+=`
+- Expires: ${t.expires_at}`),t.error_message&&(o+=`
+- Error: ${t.error_message}`),{content:[{type:"text",text:o}]}}if(i==="generate_pdf"){if(!n||typeof n!="object")throw new Error("Invalid arguments: args must be an object");if(!n.markdown||typeof n.markdown!="string"||n.markdown.trim().length===0)throw new Error("markdown is required and cannot be empty");let e=["general","tech_spec","invoice","report","resume","letter","meeting"];if(n.template_type&&typeof n.template_type=="string"&&!e.includes(n.template_type))throw new Error(`Invalid template_type: ${n.template_type}. Valid values: ${e.join(", ")}`);console.error("[Agent2PDF] Submitting job...");let t=(await p.post(`${l}/jobs`,n,{headers:{"X-API-Key":s,"Content-Type":"application/json"}})).data.job_id;console.error(`[Agent2PDF] Job started: ${t}. Polling for completion...`);for(let o=0;o<u;o++){o>0&&await new Promise(h=>setTimeout(h,A));let c=await p.get(`${l}/jobs/${t}`,{headers:{"X-API-Key":s}}),{status:d,download_url:m,error_message:_,progress:b}=c.data;if(console.error(`[Agent2PDF] Poll ${o+1}/${u}: status=${d}, progress=${b??"N/A"}`),d==="completed"&&m)return{content:[{type:"text",text:`PDF Generated Successfully!
 
 Download URL: ${m}
 
-(Note: Link expires in 1 hour)`}]};if(l==="failed")throw new Error(`Job failed: ${b||"Unknown error"}`)}throw new Error(`Timeout: PDF generation took longer than 2 minutes. Job ID: ${e}`)}throw new Error(`Unknown tool: ${a}`)}catch(n){return{content:[{type:"text",text:`Error: ${v(n)}`}],isError:!0}}});var T=new h;await c.connect(T);console.error("[Agent2PDF] MCP Server started.");
+(Note: Link expires in 1 hour)`}]};if(d==="failed")throw new Error(`Job failed: ${_||"Unknown error"}`)}throw new Error(`Timeout: PDF generation took longer than 2 minutes. Job ID: ${t}`)}if(i==="get_branding"){let r=(await p.get(`${l}/settings`,{headers:{"X-API-Key":s}})).data,t=r.logoUrl?`uploaded (${r.logoUrl})`:"not uploaded";return{content:[{type:"text",text:["Branding settings:",`- company_name: ${r.companyName}`,`- logo: ${t}`,`- primary_color: ${r.primaryColor}`,`- secondary_color: ${r.secondaryColor}`,`- font_family: ${r.fontFamily}`,`- watermark_text: ${r.watermarkText||"(none)"}`].join(`
+`)}]}}if(i==="upload_logo"){let e=n?.logo_url,r=n?.logo_base64;if(!e&&!r)throw new Error("Provide either 'logo_url' or 'logo_base64'.");if(e&&r)throw new Error("Provide only one of 'logo_url' or 'logo_base64', not both.");let t={};return e&&(t.logo_url=e),r&&(t.logo_base64=r),{content:[{type:"text",text:["Logo uploaded successfully.",`- logo_url: ${(await p.post(`${l}/settings/logo`,t,{headers:{"X-API-Key":s,"Content-Type":"application/json"}})).data.logoUrl}`,"","The logo will appear on future PDFs. Use generate_pdf with use_logo=true (default) to include it."].join(`
+`)}]}}if(i==="remove_logo")return await p.delete(`${l}/settings/logo`,{headers:{"X-API-Key":s}}),{content:[{type:"text",text:"Logo removed successfully. PDFs will now show the company name instead of a logo."}]};if(i==="submit_feedback"){let e=n,r=typeof e?.title=="string"?e.title.trim():"";if(!r)throw new Error("title is required for submit_feedback.");let t=typeof e?.category=="string"&&["bug","feature_request","template_request","usability","general"].includes(e.category)?e.category:"general",o=typeof e?.rating=="number"&&e.rating>=1&&e.rating<=5?e.rating:void 0,c={category:t,title:r,body:typeof e?.body=="string"?e.body:void 0,job_id:typeof e?.job_id=="string"?e.job_id:void 0,template_type:typeof e?.template_type=="string"?e.template_type:void 0};return o!==void 0&&(c.rating=o),{content:[{type:"text",text:`Feedback submitted successfully. feedback_id: ${(await p.post(`${l}/feedback`,c,{headers:{"X-API-Key":s,"Content-Type":"application/json"}})).data.feedback_id}`}]}}throw new Error(`Unknown tool: ${i}`)}catch(e){return{content:[{type:"text",text:`Error: ${D(e)}`}],isError:!0}}});var T=new j;await g.connect(T);console.error("[Agent2PDF] MCP Server started.");

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agent2pdf/mcp-server",
-  "version": "1.0.2",
+  "version": "1.1.1",
   "description": "Official MCP Server for Agent2PDF with auto-polling support",
   "type": "module",
   "bin": {
@@ -16,7 +16,8 @@
     "build": "tsup",
     "dev": "tsup --watch",
     "test": "node test-mcp-server.js",
-    "prepublishOnly": "npm run build"
+    "prepublishOnly": "npm run build",
+    "test:full": "./scripts/full-e2e-test.sh"
   },
   "keywords": [
     "mcp",