PlayFab MCP Server

这是什么？🤔

此服务器是一种中间件，使大型语言模型（如Claude和VS Code）能够直接与PlayFab服务交互。作为安全高效的翻译器，它连接您的AI助手与各种PlayFab功能，例如项目搜索、分段查询、玩家资料查找、库存管理和PlayFab ID转换。

快速示例

您："显示最新的10个项目。"
Claude：*调用PlayFab的search_items API并以纯文本形式返回结果*

它是如何工作的？🛠️

该服务器利用模型上下文协议（MCP）在AI模型和PlayFab服务之间建立通用接口。尽管MCP旨在支持任何AI模型，但它目前仅作为开发者预览版提供。

按照以下步骤开始使用：

1. 设置您的项目。
2. 将您的项目详细信息添加到您的LLM客户端配置中。
3. 开始自然地与PlayFab数据进行交互！

它能做什么？📊

目录与搜索

• 使用PlayFab的search_items API搜索项目。
• 目录管理（经济v2）：
  • 使用create_draft_item API创建新的草稿项目。
  • 使用update_draft_item API更新现有草稿项目。
  • 使用delete_item API从目录中删除项目。
  • 使用publish_draft_item API发布草稿项目使其可用。
  • 使用get_item API获取详细的项目信息。

玩家管理

• 获取全面的分段信息。
• 查询指定分段内的玩家资料。
• 使用get_title_player_account_id_from_playfab_id API将PlayFab ID转换为标题玩家账户ID。
• 使用get_user_account_info API获取详细的用户账户信息。

库存管理

• 获取操作：
  • 使用get_inventory_items API检索当前库存项目。
  • 使用get_inventory_collection_ids API获取库存集合ID。
• 添加/移除操作：
  • 使用add_inventory_items API向库存添加项目。
  • 使用delete_inventory_items API从库存中删除项目。
  • 使用subtract_inventory_items API减去特定数量。
• 修改操作：
  • 使用update_inventory_items API更新项目属性。

经济v2管理

• 使用execute_inventory_operations API执行批量库存操作。
• 注意：在经济v2中，虚拟货币作为库存项目进行管理。

用户账户管理

• 使用ban_users API通过ID、IP或MAC地址封禁玩家。
• 使用revoke_all_bans_for_user API完全解除玩家的封禁。

玩家数据管理

• 使用get_user_data API检索玩家自定义数据。
• 使用update_user_data API更新玩家自定义数据。

标题配置管理

• 使用set_title_data API设置全局标题数据。
• 使用get_title_data API检索标题数据。
• 使用set_title_internal_data API设置仅供服务器使用的内部数据。
• 使用get_title_internal内部数据API检索内部数据。

快速入门🚀

通过Smithery安装

要通过Smithery自动安装PlayFab MCP Server用于Claude Desktop：

npx -y @smithery/cli install @akiojin/playfab-mcp-server --client claude

先决条件

• Node.js 18或更高版本。
• 有效的PlayFab账户（通过PlayFab游戏管理器获得您的标题ID和开发者密钥）。
• 支持的LLM客户端，如Claude Desktop。

设置您的项目

从PlayFab游戏管理器获取您的PlayFab标题ID和开发者密钥，然后在项目根目录中创建一个.env文件，内容如下（替换占位符为您实际的凭证）：

PLAYFAB_TITLE_ID=
PLAYFAB_DEV_SECRET_KEY=

安装与设置

1. 安装依赖项

   在项目根目录中运行以下命令以安装所有必要的依赖项：

   npm install
   

2. 构建项目

   通过执行以下命令编译项目：

   npm run build
   

3. 启动服务器

   通过执行以下命令启动服务器：

   npm start
   

4. 确认消息

   启动后，您应该看到以下消息：

   PlayFab Server正在stdio上运行
   

开发设置

代码质量工具

• ESLint：为TypeScript配置了推荐规则以确保代码一致性
• Prettier：根据项目特定设置自动格式化代码
• TypeScript：启用严格模式以增强类型安全性
• Jest：配置了TypeScript的测试框架

可用脚本

# 构建项目
npm run build

# 开发模式，带文件监视
npm run watch

# TypeScript类型检查
npm run typecheck

# 运行ESLint
npm run lint

# 运行ESLint并修复问题
npm run lint:fix

# 使用Prettier格式化代码
npm run format

# 检查代码格式
npm run format:check

# 运行测试
npm test

# 在监视模式下运行测试
npm run test:watch

# 运行带有覆盖率的测试
npm run test:coverage

TypeScript配置

该项目使用TypeScript并启用了严格模式，确保：

• 严格的空值检查
• 不允许隐式any类型
• 严格的函数类型
• 始终启用严格模式

测试

测试使用Jest编写，可以在__tests__目录或扩展名为.test.ts的文件中找到。在提交更改前运行测试以确保代码质量。

使用Cursor运行

要使用PlayFab MCP服务器与Cursor一起运行，请遵循以下步骤：

1. 如果尚未安装，请安装Cursor Desktop。
2. 在一个空文件夹中打开一个新的Cursor实例。
3. 将此存储库中的mcp.json文件复制到您的文件夹，并根据您的环境更新值。
4. 启动Cursor；PlayFab MCP Server应出现在工具列表中。
5. 例如，尝试提示“显示最新的10个项目”以验证服务器是否正确处理您的查询。

将您的项目详细信息添加到Claude Desktop的配置文件中

打开Claude Desktop并导航至文件→设置→开发者→编辑配置。然后，将claude_desktop_config文件的内容替换为以下片段：

{
  "mcpServers": {
    "playfab": {
      "command": "npx",
      "args": [
        "-y",
        "@akiojin/playfab-mcp-server"
      ],
      "env": {
        "PLAYFAB_TITLE_ID": "您的PlayFab标题ID",
        "PLAYFAB_DEV_SECRET_KEY": "您的PlayFab开发者密钥"
      }
    }
  }
}

完成这些步骤后，您已成功配置PlayFab MCP服务器以与您的LLM客户端配合使用，从而实现与PlayFab服务的无缝交互。

贡献

提交消息约定

此项目遵循常规提交以实现自动化版本控制和发布。

提交消息格式

<类型>(<范围>)：<主题>

<正文>

<页脚>

类型

• feat：新功能（触发次要版本升级）
• fix：错误修复（触发补丁版本升级）
• docs：仅文档更改
• style：不影响代码意义的更改
• refactor：既不修复错误也不添加功能的代码更改
• perf：提高性能的代码更改
• test：添加缺失的测试或纠正现有测试
• chore：对构建过程或辅助工具的更改

版本升级规则

• 主要版本：当提交消息包含页脚中的BREAKING CHANGE或类型/范围后的!
  • 示例：feat!: 移除废弃的API端点
  • 示例：feat: 新API\n\nBREAKING CHANGE: 移除了旧端点
• 次要版本：当提交类型为feat
  • 示例：feat: 添加新的PlayFab API集成
• 补丁版本：当提交类型为fix
  • 示例：fix: 更正API调用中的错误处理

发布流程

1. 更新版本和变更日志

# 分析提交并更新CHANGELOG.md
# 然后根据更改提升版本：
npm version patch  # 或minor/major

2. 推送更改和标签

# 推送版本提交
git push origin main

# 推送由npm version创建的版本标签
git push origin --tags

3. 自动发布与发布

当推送v*标签时，release-and-publish.yml工作流会自动：

• 创建带有发布说明的GitHub发布
• 将包发布到npm
• 附加发布资产

存储库先决条件

• 存储库设置中必须设置NPM_TOKEN秘密以进行npm发布
• 必须设置DEPENDABOT_PAT秘密以自动批准Dependabot PR：
  1. 创建具有repo和workflow权限的个人访问令牌（PAT）
  2. 转到设置→Secrets和变量→Actions
  3. 添加一个名为DEPENDABOT_PAT的新秘密，其值为您的PAT
• 配置分支保护规则以使自动合并生效：
  1. 转到设置→分支
  2. 为主分支添加规则
  3. 启用“合并前需要拉取请求”
  4. 启用“合并前需要状态检查通过”
  5. 添加所需的状态检查：build (18.x)，build (20.x)，build (22.x)

脚本参考

脚本	描述
npm start	启动MCP服务器
npm run build	将TypeScript编译为JavaScript
npm run watch	开发模式下的监视构建
npm run typecheck	运行TypeScript类型检查
npm run lint	运行ESLint检查
npm run lint:fix	自动修复ESLint问题
npm run format	使用Prettier格式化代码
npm run format:check	检查代码格式
npm test	运行所有测试
npm run test:watch	在监视模式下运行测试
npm run test:coverage	生成测试覆盖率报告

安全

我们重视安全。如果您在此项目中发现安全漏洞，请遵循以下步骤：

报告安全漏洞

1. 不要为安全漏洞创建公共GitHub问题
2. 相反，请通过GitHub的私人漏洞报告来报告安全问题：
   • 转到此存储库的安全选项卡
   • 单击报告漏洞
   • 提供关于漏洞的详细信息

我们需要什么

• 漏洞描述
• 复现问题的步骤
• 潜在影响
• 任何建议的修复措施（可选）

我们的承诺

• 我们将在48小时内确认收到您的报告
• 我们将定期更新我们的进度
• 我们将承认您的发现（除非您希望保持匿名）

安全最佳实践

使用此服务器时：

1. 永远不要提交凭据：始终使用环境变量存储敏感数据
2. 保持依赖项更新：定期运行npm audit并更新包
3. 使用最小权限：仅授予所需的最低权限
4. 定期轮换密钥：定期更改您的PlayFab开发者密钥

支持

获取帮助

如果您遇到任何问题或有关于使用PlayFab MCP Server的问题，以下是获取支持的最佳方式：

1. GitHub问题：对于错误报告和功能请求，请创建一个问题
2. 讨论：对于一般问题和社区支持，请使用GitHub讨论
3. 文档：查看README和代码注释以获取使用示例

在创建问题之前

请通过搜索现有问题来检查您的问题是否已被报告。如果找到类似问题，您可以添加额外的信息作为评论。

我们支持什么

• 安装和设置问题
• 可复现步骤的错误报告
• 功能请求和建议
• 文档改进

我们不支持什么

• 一般的PlayFab API问题（请参阅PlayFab文档）
• 第三方工具或服务的问题
• 定制实现请求

许可证

本项目根据MIT许可证授权 - 查看LICENSE文件以获取详细信息。