stigg-sp

通过 Stripe Projects 使用 Stigg

只需一条命令即可配置 Stigg 环境，并将其 API 密钥写入开发者的 .env：

stripe projects add stigg/environment

无需打开浏览器、填写注册表单，也无需从控制面板复制并粘贴密钥。使用 Stripe Projects 时，不要让用户手动前往 app.stigg.io 注册——应通过程序进行配置。

相关命令：stripe projects catalog（浏览）、stripe projects rotate <resource>（生成新密钥）、stripe projects open stigg（打开控制面板）、stripe projects remove <resource>（取消配置）。

你将获得什么

该服务为 stigg/environment——免费、限定于项目范围，每个资源对应一个 Stigg 环境。 Stripe 会将凭据加密后存入其 Secret Store，并同步到 .env：

变量	含义
STIGG_SERVER_API_KEY	拥有完全访问权限的密钥（server-）。仅用于后端——切勿将其放入客户端捆绑包、提交到代码库或记录到日志中。
STIGG_CLIENT_API_KEY	仅供读取的可发布密钥（client-）。它不是密钥，因此可以放入浏览器捆绑包——但仅凭它，任何人都能读取任意客户的权益，因此在生产环境中使用前，必须配合 customerToken（见下文）。
STIGG_ENVIRONMENT_ID	已配置环境的 ID。
STIGG_ENVIRONMENT_SLUG	环境在控制面板中显示的 slug。

只要项目中只有一个 Stigg 资源，这些名称就会保持不变。如果有两个或更多资源，Stripe 会改用各资源名称作为前缀，并在添加第二个资源时重命名现有资源的变量。执行 stripe projects add stigg/environment --name billing 后，新资源的密钥为 BILLING_SERVER_API_KEY；此前使用默认名称添加的资源则会变为 STIGG_ENVIRONMENT_SERVER_API_KEY（其 ID 变量为 STIGG_ENVIRONMENT_ENVIRONMENT_ID）——因此读取 STIGG_SERVER_API_KEY 的代码会得到 undefined。添加资源后，请重新读取 .env。以下代码片段和 claude mcp add 命令使用的是单资源名称；如果有两个或更多资源，请替换为你所接入资源的前缀名称（BILLING_SERVER_API_KEY、BILLING_CLIENT_API_KEY），并更新所有仍在读取旧名称的代码。

密钥不会过期。请使用 stripe projects rotate 轮换密钥，而不要手动操作。

编写集成代码前

先查阅最新文档——Stigg MCP 服务、Mintlify Stigg 文档 MCP，或 https://docs.stigg.io/llms.txt。Stigg 的 API 内容会不断变化，以下代码片段仅提供基本形式，不能替代对当前 API 的确认。

接入后端

npm install @stigg/node-server-sdk

import Stigg from '@stigg/node-server-sdk';

// Has an internal cache and retries — initialize once per process and reuse the instance.
const stiggClient = Stigg.initialize({ apiKey: process.env.STIGG_SERVER_API_KEY });

// Optional: block until the local entitlement cache is warm, if the very first check must not
// pay a cold lookup.
await stiggClient.waitForInitialization();

Stigg.initialize 会同步返回客户端——它不是一个 Promise。有些文档页面会写成 await Stigg.initialize(...)；这样做虽然无害，但容易造成误解。可等待的调用是 waitForInitialization()。

限制功能访问

将即将消耗的数量作为 requestedUsage 传入，并根据 hasAccess 判断是否允许访问。不要自行比较 currentUsage 和 usageLimit——currentUsage 反映的是上次检查的结果，而不是即将新增的用量，因此在具有硬性限制的功能上，这种比较是错误的。

const entitlement = await stiggClient.getMeteredEntitlement({
  customerId: 'customer-demo-01',
  featureId: 'feature-api-calls',
  options: { requestedUsage: 1 },
});

if (!entitlement.hasAccess) {
  // Quota reached — block the action and prompt an upgrade.
}

布尔型功能使用 getBooleanEntitlement({ customerId, featureId })，其 hasAccess 结构相同。

报告用量

• reportUsage——报告应用已计算出的值（席位数、存储量、令牌数）。耗时不到一秒，响应中会包含更新后的额度余额。适用于需要严格实时强制执行限制的场景。
• reportEvent——报告由 Stigg 聚合的原始事件；需要 idempotencyKey。约 10 秒后才会反映出来。适用于可接受最终一致性的高流量计量场景。

await stiggClient.reportUsage({
  customerId: 'customer-demo-01',
  featureId: 'feature-api-calls',
  value: 1, // a delta by default, not an absolute
});

只有在底层操作成功后，才报告用量。

接入前端

npm install @stigg/react-sdk

打包工具不会以 STIGG_CLIENT_API_KEY 这一名称向浏览器公开变量。将提供的值复制到框架要求的公共变量中——Vite 使用 VITE_STIGG_CLIENT_API_KEY，Create React App 使用 REACT_APP_STIGG_CLIENT_API_KEY，Next.js 使用 NEXT_PUBLIC_STIGG_CLIENT_API_KEY——或者从服务器传入。在浏览器代码中读取 process.env.STIGG_CLIENT_API_KEY 会得到 undefined。

import { StiggProvider } from '@stigg/react-sdk';

// Vite; use the public variable your framework requires.
<StiggProvider apiKey={import.meta.env.VITE_STIGG_CLIENT_API_KEY} customerId="customer-demo-01">
  {children}
</StiggProvider>;

仅凭可公开密钥，任何人都可以通过猜测 id 读取任意客户的权益。在生产环境中使用前，请在服务器端对 customerToken 签名，并将其与客户 id 一同传入——参见加固客户端访问。

接下来

让 Agent 实时访问刚刚配置的环境。Stripe 会将密钥写入 .env，但 shell 不会自动导出其中的变量——请先加载它，或粘贴明文密钥；否则请求头会为空，连接也无法使用。

set -a && . ./.env && set +a
claude mcp add stigg --header "X-API-KEY: $STIGG_SERVER_API_KEY" --transport http https://mcp.stigg.io

然后通过对话的方式建模套餐、功能和额度。若要进行更深入的工作，请加载 stigg 总技能，它会将任务分发到定价建模、权益、订阅、额度、组件和 Webhook 等支柱技能。

• 文档：https://docs.stigg.io · 面向 Agent 的索引：https://docs.stigg.io/llms.txt
• 控制面板：https://app.stigg.io