Skip to main content
Glama
deenesjakoruzh
rakanalalami

Kamy

by rakanalalami
OverviewSchemaSourceRelated ServersDiscussionsAdmin
TypeScript
Remote

面向开发者的 PDF 生成 API。使用精美的默认设置发布发票、收据、合同和报告。

安装

# SDK — in your app
npm i @kamydev/sdk

# CLI — globally for scripts, CI, previews
npm i -g @kamydev/cli
import Kamy from "@kamydev/sdk";

const kamy = new Kamy({ apiKey: process.env.KAMY_API_KEY! });
const pdf = await kamy.render({
  template: "invoice",
  data: { invoiceNumber: "INV-001", total: 1500, currency: "USD" },
});
console.log(pdf.url); // signed URL, valid 1 hour

新增功能

日期

变更

2026年4月

GET /v1/renders 现在返回单次渲染成本 cost（以主要货币单位计）以及顶层 currency: "usd"。在插入时通过读取 users.plan 的 Postgres 触发器进行非规范化处理，因此成本反映了渲染发生时你的套餐。在 SDK 0.2.3 中作为 RenderSummary.cost / RendersListResult.currency 呈现。

2026年4月

SDK 现在提供由 OpenAPI 生成的类型 —— import type { paths, components } from "@kamydev/sdk/openapi"，用于获取从实时规范派生的完全类型化的请求/响应形状。同时也提供了原始的 openapi.json。

2026年4月

渲染时通过 Ajv 进行模板级 JSON Schema 验证（已启用格式）。此前仅检查 required —— 现在已实现完整的类型/格式/枚举/oneOf 强制执行。

2026年4月

options.encrypt —— AES-256 密码保护 + 权限标志（打印、复制、修改、注释、表单填充、辅助功能、组装）。

2026年4月

OpenAPI 3.0.3 规范现在涵盖所有 19 个 /v1/* 路由，并具有完整的请求/响应模式 —— https://kamy.dev/api/openapi.json

2026年4月

kamy push <file> CLI + client.pushTemplate() SDK + 幂等 PUT /v1/templates 更新插入。在每次提交时运行它以同步仓库中的模板。

2026年4月

options.validateOnly: true —— 对任何渲染进行试运行，以在不消耗配额的情况下验证有效负载。

2026年4月

`options.pdfA: "1b"

"2b"

"3b"` —— 通过嵌入式 sRGB ICC OutputIntent + XMP 实现尽力而为的 PDF/A 归档标记。

2026年4月

options.metadata（信息字典）+ options.watermark（pdf-lib 印章，不同于 theme.watermark）。

2026年4月

options.inlineImages + options.compressImages —— 服务器端图像加固，防止过期签名 URL 带来的问题。

每个版本的详细信息请参阅 CHANGELOG.md。

架构

Kamy 是一个包含以下内容的 Turborepo 单体仓库：

包

描述

apps/web

Next.js 15 应用 —— 落地页、仪表板、REST API

apps/mcp

Cloudflare Worker —— 用于 AI 编码代理的 MCP 服务器

apps/docs

Nextra 文档站点

packages/sdk

@kamydev/sdk —— 可发布的 TypeScript SDK

packages/templates

@kamy/templates —— PDF 模板 HTML/CSS + Zod 模式

packages/ui

@kamy/ui —— 共享的 shadcn/Radix UI 组件

packages/shared

@kamy/shared —— 类型、工具、可观测性、电子邮件

packages/tsconfig

@kamy/tsconfig —— 共享的 TypeScript 配置

先决条件

  • Node.js 22+

  • pnpm 10+

  • Supabase CLI (brew install supabase/tap/supabase)

  • Wrangler CLI (pnpm add -g wrangler) —— 用于 MCP 服务器

本地开发

# 1. Install dependencies
pnpm install

# 2. Copy env file and fill in values
cp .env.example apps/web/.env.local

# 3. Start local Supabase (requires Docker)
supabase start

# 4. Apply database migrations
supabase db reset

# 5. Generate TypeScript types from schema
supabase gen types typescript --local > packages/shared/src/types/database.ts

# 6. Start all apps in dev mode
pnpm dev

Web 应用运行在 https://kamy.dev

命令

pnpm dev          # Start all apps with Turbopack (hot reload)
pnpm build        # Production build all apps
pnpm typecheck    # TypeScript check across all packages
pnpm lint         # Biome lint + format check
pnpm lint:fix     # Biome auto-fix
pnpm test         # Run all tests (Vitest unit + Playwright E2E)
pnpm test:unit    # Vitest unit tests only
pnpm test:e2e     # Playwright E2E tests only
pnpm clean        # Remove all build artifacts

数据库

迁移文件位于 supabase/migrations/。它们按时间戳顺序应用。

# Reset and reseed local DB
supabase db reset

# Create a new migration
supabase migration new <name>

# Push to remote Supabase project
supabase db push

部署

  • Web 应用：合并到 main 分支时部署到 Vercel

  • MCP 服务器：通过 wrangler deploy 部署到 Cloudflare Workers

  • 数据库：托管在 Supabase Cloud 上

环境变量

请参阅 .env.example 获取所有必需变量及其描述。

技术栈

  • 框架：Next.js 15 (App Router, React Server Components, Turbopack)

  • 语言：TypeScript 5.7+ 严格模式

  • 数据库：Supabase (Postgres 16 + Auth + Storage)

  • 样式：Tailwind CSS v4 (Oxide 引擎)

  • 支付：Stripe (Meters API)

  • PDF 引擎：Browserless.io v2

  • 电子邮件：Resend + React Email

  • 可观测性：Sentry + PostHog + Axiom

  • 测试：Vitest + Playwright + MSW

开放插件

此仓库提供了一个 Open Plugins 分发包，以便 AI 编码代理（Cursor、Claude Code 以及任何其他兼容 Open-Plugins 的工具）可以将 Kamy 安装为单个插件，并获得现成的 PDF 流水线。

该插件在仓库根目录捆绑了四个组件：

路径

组件

用途

.plugin/plugin.json

清单

名称、版本、元数据、声明的组件

skills/kamy/SKILL.md

技能

教导代理何时以及如何渲染 PDF

rules/kamy-sdk.mdc

规则

@kamydev/sdk 和 REST API 的编码规范

agents/pdf-template-author.md

子代理

专门的模板设计代理（Handlebars + 打印 CSS）

.mcp.json

MCP 服务器

托管在 mcp.kamy.dev 的 MCP，暴露渲染工具

要在受支持的代理中安装插件，请将其指向此仓库 (https://github.com/rakanalalami/kamy) 并按照主机的插件安装流程操作。代理将自动读取清单并加载组件。

有关完整模式，请参阅 Open Plugins 规范。

This server cannot be deployed

Shareable, User-Owned Context BackendPeople, applications, and agents read, write, and coordinate together in one context lake. Reach it over MCP, a CLI, a Python SDK, or REST.fulcradynamics.comAd

Resources

Related MCP Connectors

Related MCP Servers

  • MCP PDF

    mcp-z
    A
    license
    A
    quality
    C
    maintenance
    Enables creative PDF generation with full design control including colors, shapes, emoji, and Unicode support. Supports everything from simple documents to artistic masterpieces using PDFKit's powerful API.
    5
    1,421 npm
    2
    MIT