Pdf Generator Api

PDF Generator API — MCP 服务

适用于 PDF Generator API 的模型上下文协议（MCP）服务，根据 OpenAPI v4 规范生成。

概览

此服务支持 stdio 和 HTTP 两种传输方式：

• Stdio 模式（默认）：用于本地 MCP 客户端集成（Claude Desktop、Claude Code、Cline 等）
• HTTP 模式：用于生产部署、市场平台和多个客户端

快速开始

本地开发（Stdio 模式）

安装并构建：

npm install
npm run build

MCP 客户端配置示例：

{
  "mcpServers": {
    "pdf-generator-api": {
      "command": "node",
      "args": ["/path/to/mcp-server/build/index.js"],
      "env": {
        "API_BASE_URL": "https://us1.pdfgeneratorapi.com/api/v4",
        "BEARER_TOKEN_JWT": "your-jwt-token-here"
      }
    }
  }
}

注意：将 /path/to/mcp-server 替换为实际路径，并将 your-jwt-token-here 替换为你的 PDF Generator API JWT 令牌（请参阅下文的 JWT 令牌生成）。

常见配置位置：

• Claude Desktop：Settings > Developer > Edit Config
• Claude Code（CLI）：~/.claude/mcp_config.json
• Cline/Roo-Codeium：.vscode/mcp_config.json
• Continue：~/.continue/config.json

远程 MCP 服务（Streamable HTTP）

如果你部署了 MCP 服务（例如 https://mcp.example.com），无需在本地运行任何程序，即可直接从 MCP 客户端连接。

Claude Code（~/.claude/mcp_config.json）：

{
  "mcpServers": {
    "pdf-generator-api": {
      "type": "streamable-http",
      "url": "https://mcp.pdfgeneratorapi.com/mcp",
      "headers": {
        "Authorization": "Bearer your-jwt-token-here"
      }
    }
  }
}

Claude Desktop（claude_desktop_config.json）：

Claude Desktop 不直接支持 streamable-http。请使用 mcp-remote 作为桥接：

{
  "mcpServers": {
    "pdf-generator-api": {
      "command": "npx",
      "args": [
        "mcp-remote",
        "https://mcp.pdfgeneratorapi.com/mcp",
        "--header",
        "Authorization: Bearer your-jwt-token-here"
      ]
    }
  }
}

注意：对于远程服务，请使用较长有效期的 JWT 令牌（例如 --expiresIn 30d），以避免会话中途过期。请参阅 JWT 令牌生成了解如何创建令牌。更新配置后，重启 MCP 客户端。

生产部署（HTTP 模式）

本地运行：

npm install
npm run start:http
# Server runs on http://localhost:3000
# MCP endpoint: http://localhost:3000/mcp
# Health check: http://localhost:3000/health

Docker：

docker compose -f deploy/docker-compose.yml up -d
# MCP endpoint: http://localhost:3001/mcp

身份验证

Stdio 模式：在 MCP 客户端配置中，通过 BEARER_TOKEN_JWT 环境变量传入 JWT 令牌。

HTTP 模式：在每个请求的 Authorization 标头中传入 JWT 令牌：

curl -X POST http://localhost:3000/mcp \
  -H "Content-Type: application/json" \
  -H "Accept: application/json, text/event-stream" \
  -H "Authorization: Bearer your-jwt-token-here" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize",...}'

JWT 令牌生成

你需要使用 JWT 令牌向 PDF Generator API 进行身份验证。请从 PDF Generator API 控制面板的 Account Settings > API Integration 中获取凭据。

你需要以下三个值：

• Workspace ID（iss 声明）——数字形式的工作区标识符
• Workspace Identifier（sub 声明）——工作区邮箱或唯一密钥
• Secret Key ——JWT 的签名密钥（请妥善保密）

参阅：https://docs.pdfgeneratorapi.com/v4#section/Authentication/Creating-a-JWT

Node.js

const jwt = require('jsonwebtoken');

const token = jwt.sign(
  {
    iss: 'YOUR_WORKSPACE_ID',       // e.g. "12345"
    sub: 'YOUR_WORKSPACE_IDENTIFIER' // e.g. "[email protected]"
  },
  'YOUR_SECRET_KEY',
  {
    algorithm: 'HS256',
    expiresIn: '24h'  // Token lifetime — see notes below
  }
);

console.log(token);

快速单行命令（npx）

npx jsonwebtoken-cli -- sign \
  '{"iss":"YOUR_WORKSPACE_ID","sub":"YOUR_WORKSPACE_IDENTIFIER"}' \
  'YOUR_SECRET_KEY' \
  --algorithm HS256 \
  --expiresIn 24h

令牌过期时间（TTL）

请根据使用场景选择合适的 TTL：

使用场景	建议的 TTL	原因
本地 MCP（stdio）	24h 或更长	MCP 会话可能持续很长时间；可避免会话中途过期
生产环境（HTTP）	1h	较短有效期的令牌可降低泄露风险
CI/CD 或脚本	5m – 15m	将自动化任务的暴露时间窗口降至最低

PDF Generator API 会在每次请求时验证令牌。如果令牌在会话中途过期，后续 API 调用将返回 401 Unauthorized — 请生成新令牌并重启 MCP 客户端。

安全最佳实践

• 切勿将令牌或密钥提交到版本控制系统
• 使用环境变量或密钥管理器来存储 BEARER_TOKEN_JWT
• 定期在 PDF Generator API 控制面板中轮换密钥
• 对于 HTTP 模式，在生产环境中使用 HTTPS，以保护传输中的令牌

参阅：PDF Generator API 身份验证文档

环境变量

变量	模式	默认值	描述
API_BASE_URL	Both	https://us1.pdfgeneratorapi.com/api/v4	PDF Generator API 基础 URL
BEARER_TOKEN_JWT	Stdio	—	用于身份验证的 JWT 令牌
PORT	HTTP	3000	服务端口
LOG_LEVEL	Both	info	日志级别（debug、info、warn、error）
SESSION_TTL_MINUTES	HTTP	30	会话空闲超时时长（分钟）
CORS_ORIGIN	HTTP	*（所有来源）	以逗号分隔的允许来源

在仓库根目录中创建 .env 文件：

cp .env.example .env

重新生成

OpenAPI 规范变更后，重新生成：

# Place the updated spec at docs/apiv4.json, then:
./scripts/generate-mcp.sh

# Or specify a custom input:
./scripts/generate-mcp.sh --input /path/to/apiv4.json

注意： 重新生成后，可能需要重新应用自定义补丁。

测试

npm run build
npm test

手动测试 stdio 模式：

BEARER_TOKEN_JWT="your-token" echo '{"jsonrpc":"2.0","id":1,"method":"tools/list"}' | npm run start:stdio

测试 HTTP 模式：

npm run start:http
curl http://localhost:3000/health

资源

• MCP 文档
• PDF Generator API 文档
• OpenAPI MCP Generator