关于 PlayerOS
PlayerOS SDK 是面向游戏运营商的 PlayerOS API 提供的 TypeScript/JavaScript SDK 与 CLI。它涵盖玩家数据、营销活动、合规、隐私和 Webhook 操作，并提供供 AI Agent 使用的 MCP 服务。
主要功能
- 01管理玩家记录
- 02发送邮件与短信活动
- 03检查合规并记录同意
- 04导出或删除隐私数据
- 05管理 Webhook 与 API 密钥
- 06提供 JSON 输出的 CLI
适用场景
- 01查询或更新玩家资料
- 02执行营销活动并使用幂等键
- 03处理同意记录和隐私请求
- 04通过 CLI 将 API 结果传入其他命令
MCP 相关
PlayerOS API 在 `https://api.playeros.ai/api/mcp` 提供 MCP 服务，包含 25 个工具和可发现资源，供 AI Agent 使用。
配置
远程服务无需本地安装。选择你使用的客户端，复制配置或使用一键安装。
https://api.playeros.ai/api/mcpclaude mcp add --transport http playeros-sdk https://api.playeros.ai/api/mcp{"mcpServers":{"playeros-sdk":{"type":"http","url":"https://api.playeros.ai/api/mcp"}}}在 Cursor 中打开{"servers":{"playeros-sdk":{"type":"http","url":"https://api.playeros.ai/api/mcp"}}}在 VS Code 中打开{"mcpServers":{"playeros-sdk":{"type":"http","url":"https://api.playeros.ai/api/mcp"}}}{"mcpServers":{"playeros-sdk":{"serverUrl":"https://api.playeros.ai/api/mcp"}}}命令在终端中运行；JSON 粘贴到对应客户端的 MCP 配置后重启。需要授权的服务会在首次连接时提示登录。
工具
25| 参数 | 类型 | 必填 | 说明 |
|---|---|---|---|
| limit | integer | 否 | 最大行数（既定値 25、最大 200）。 |
| status | string | 否 | 精确的状态筛选，例如 'active'。 |
| email_contains | string | 否 | 不区分大小写的电子邮件子字符串。 |
| order | string | 否 | 排序子句，例如 'created_at.desc'。 |
详细介绍
PlayerOS SDK
面向 PlayerOS API 的官方 TypeScript/JavaScript SDK 和 CLI —— 这是面向游戏运营商的赌场营销平台（统一玩家数据库、多渠道营销活动、旅程自动化，以及 TCPA/CCPA/GDPR 合规）。
- 文档： https://playeros.ai/api-docs · Markdown
- OpenAPI 3.1： https://playeros.ai/openapi.json
- MCP 服务（面向 AI Agent）： https://api.playeros.ai/api/mcp · 清单
- 身份验证指南： https://playeros.ai/auth.md
零运行时依赖。Node 18+（使用内置的 fetch）。
安装
npm install @playeros/sdk
身份验证
在 Settings → API & MCP
(https://playeros.ai/dashboard/mcp) 中创建属性范围的 API 密钥（pk_…）。密钥包含 read 和/或 write 权限范围，并绑定到一个属性。将其作为 X-Api-Key 发送（SDK 会为你完成此操作）。
快速入门
import { PlayerOS } from "@playeros/sdk";
const playeros = new PlayerOS({ apiKey: process.env.PLAYEROS_API_KEY! });
// List players
const { data: players, totalCount } = await playeros.players.list({ limit: 50, q: "gold" });
// Create a player (gaming-native fields)
await playeros.players.create({ email: "[email protected]", tier: "Gold", adt: 250, coin_in: 18000 });
// Send a campaign — pass an idempotencyKey so retries never double-send
await playeros.campaigns.sendEmail(
{ campaignId: "…", propertyId: "…" },
{ idempotencyKey: crypto.randomUUID() }
);
资源
| 分组 | 方法 |
|---|---|
players | list、get、create、update、delete、validateBatch |
validationJobs | get（轮询异步批处理作业） |
campaigns | sendEmail、sendSms（两者均接受 { idempotencyKey }） |
compliance | check、recordConsent |
privacy | exportData、deleteData（CCPA / GDPR） |
webhooks | list、create |
apiKeys | create、list、revoke（管理员；需要 dashboard JWT） |
每次调用都会返回 { data, status, requestId, totalCount?, rateLimit, idempotencyReplayed? }。
错误
非 2xx 响应会抛出 PlayerOSError，其中包含稳定的 .code，可用于分支处理：
import { PlayerOSError } from "@playeros/sdk";
try {
await playeros.players.create({ /* … */ });
} catch (e) {
if (e instanceof PlayerOSError) {
if (e.code === "insufficient_scope") { /* use a write-scoped key */ }
if (e.status === 429) await sleep((e.retryAfter ?? 1) * 1000); // then retry
console.error(e.status, e.code, e.requestId);
}
}
遵循 rateLimit（X-RateLimit-*）提示，并在收到 429 时退避。
CLI
此软件包提供 playeros 命令：
export PLAYEROS_API_KEY=pk_live_…
playeros players list --limit 25
playeros players get <id>
playeros players create --data '{"email":"[email protected]","tier":"Gold"}'
playeros campaigns send <campaignId> --property <propertyId> --idempotency-key $(uuidgen)
playeros compliance check --data '{"propertyId":"…","playerId":"…","channel":"sms"}'
playeros --help
输出为 stdout 上的 JSON，可通过管道传给 jq。无需安装即可一次性运行：npx @playeros/sdk --help。
面向 AI Agent
请参阅 AGENTS.md。PlayerOS 还提供了一个 模型上下文协议
服务，地址为 https://api.playeros.ai/api/mcp，包含 25 个工具和可发现资源。
许可证
MIT © PlayerOS
评论
一个开放协议，规定了 AI 应用如何以统一方式连接外部工具与数据源。客户端负责与模型对话，MCP 服务负责提供工具、资源和提示模板，两者通过标准消息通信，同一个服务可以被不同客户端复用。