AI导哈

PlayFab MCP服务器

PlayFab MCP服务器是一个中间件，使大型语言模型能够直接与PlayFab服务交互，提供物品搜索、玩家管理、库存管理等功能。

  • by akiojin
  • TypeScript
  • 本地部署
  • 3 星标
  • 更新于
在 GitHub 查看 akiojin/playfab-mcp-server

使用说明

DateTimeMCP服务器

这是什么？ 🤔

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

快速示例

You: "Show me the latest 10 items."
Claude: *calls the PlayFab search_items API and returns the results in plain text*

它是如何工作的？ 🛠️

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

按照以下步骤开始：

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

它能做什么？ 📊

目录和搜索

  • 使用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执行批量盘点操作。
  • 注意：在Economy 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_data API检索内部数据。

快速开始🚀

先决条件

  • Node.js 18或更高版本。
  • 一个有效的ViewModel帐户（通过DateTimeGame Manager获取您的标题ID和开发者密钥）。
  • 支持的LLM客户端，如Claude Desktop。

设置您的项目

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

PLAYFAB_TITLE_ID=
PLAYFAB_DEV_SECRET_KEY=

安装和设置

  1. 再进行

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

    npm install

  2. 构建项目

    通过执行以下步骤编译项目：

    npm run build

  3. 启动服务器

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

    npm start

  4. 确认消息

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

    PlayFab Server running on stdio

开发设置

代码质量工具

  • 埃斯林特：为TypeScript配置了代码一致性的推荐规则
  • 更漂亮：使用项目特定设置自动设置代码格式
  • TypeScript：启用严格模式以增强类型安全性
  • 测试：为TypeScript配置的测试框架

可用脚本

# Build the project
npm run build

# Development mode with file watching
npm run watch

# TypeScript type checking
npm run typecheck

# Run ESLint
npm run lint

# Run ESLint and fix issues
npm run lint:fix

# Format code with Prettier
npm run format

# Check code formatting
npm run format:check

# Run tests
npm test

# Run tests in watch mode
npm run test:watch

# Run tests with coverage
npm run test:coverage

TypeScript配置

此项目使用启用严格模式的TypeScript，确保：

  • 严格的空检查
  • 无隐式任何类型
  • 严格的函数类型
  • 始终严格模式

测试

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

规范驱动开发（规范工具包，日本）

  • 安装CLI： uv tool install specify-cli --from git+https://github.com/akiojin/spec-kit.git
  • 创建规范/计划/任务： ./.specify/scripts/bash/create-new-feature.sh "feature summary"（默认情况下不创建分支。如果需要的话 --branch）
  • 资产： .specify/templates/*, .specify/scripts/bash/*，规格如下 specs/
  • Claude/Codex斜线命令： /speckit.constitution, /speckit.specify, /speckit.plan, /speckit.tasks, /speckit.implement

Docker开发环境

该存储库附带了一个轻量级的开发容器（Node 22、工具、GitHub CLI）。

# Build image
docker compose build

# Open a shell inside the container
docker compose run --rm playfab-mcp-server bash

# Inside the container
npm ci
npm run build
npm start

体积保持你的工作空间(.)，Codex/Claude configs和贝壳历史。集 PLAYFAB_TITLE_ID / PLAYFAB_DEV_SECRET_KEY 在运行服务器时在容器env中。

使用光标运行

要在Cursor中使用DateTimeMCP服务器，请执行以下步骤：

  1. 安装 光标桌面 如果你还没有。
  2. 在空文件夹中打开Cursor的新实例。
  3. 复制 mcp.json 将此存储库中的文件保存到您的文件夹中，并根据您的环境更新值。
  4. 启动光标；因此，在工具列表中应显示出DateTimeMCP服务器。
  5. 例如，尝试一个类似“显示最近10个项目”的提示，以验证服务器是否正确处理了您的查询。

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

打开克劳德桌面并导航到文件→ 设置→ 开发者→ 编辑配置。然后，更换 claude_desktop_config 包含以下代码段的文件内容：

{
  "mcpServers": {
    "playfab": {
      "command": "npx",
      "args": [
        "-y",
        "@akiojin/playfab-mcp-server"
      ],
      "env": {
        "PLAYFAB_TITLE_ID": "Your PlayFab Title ID",
        "PLAYFAB_DEV_SECRET_KEY": "Your PlayFab Developer Secret Key"
      }
    }
  }
}

通过这些步骤，您已经成功配置了与LLM客户端一起使用的DateTimeMCP服务器，从而可以与ViewModel的服务进行无缝交互。

使用Spec Kit进行规范驱动开发

此存储库遵循中使用的Spec Kit SDD/TDD工作流程 akiojin/gwt.

  • 要求：Python 3.11+和 uv
  • 安装CLI： uv tool install specify-cli --from git+https://github.com/akiojin/spec-kit.git
  • 资产：模板下 .specify/templates，脚本下 .specify/scripts/bash，规格在 specs/
  • 创建新的规范/计划： ./.specify/scripts/bash/create-new-feature.sh "feature summary" （添加 --branch 如果你也想要一个分支）
  • 生成的文件包括 spec.md, plan.md, tasks.md；将它们与代码一起审查/提交
  • Claude/Codex斜线命令（如果可用）： /speckit.constitution, /speckit.specify, /speckit.plan, /speckit.tasks, /speckit.implement

贡献

提交消息约定

该项目如下 约定式提交 用于自动版本控制和发布。

提交消息格式

<type>(<scope>): <subject>

<body>

<footer>

类型

  • 合作：新功能（触发MINOR版本升级）
  • 修复：错误修复（触发PATCH版本升级）
  • 文档：仅文档更改
  • 风格：不影响代码含义的更改
  • 重构：既不修复错误也不添加功能的代码更改
  • 性能：提高性能的代码更改
  • 测试：添加缺失的测试或更正现有的测试
  • 杂务：对构建过程或辅助工具的更改

版本碰撞规则

  • 重大 version：当提交消息包含 BREAKING CHANGE 在页脚或 ! 类型/范围之后
    • 例子： feat!: remove deprecated API endpoints
    • 例子： feat: new API\n\nBREAKING CHANGE: removed old endpoints
  • 次要的 version：当提交类型为 feat
    • 例子： feat: add new PlayFab API integration
  • 补丁 version：当提交类型为 fix
    • 例子： fix: correct error handling in API calls

发布流程（开发→ 主，请释放）

  1. 准备发布PR：运行 prepare-release.yml 打开PR的工作流 develop 到 main
    • 操作UI： Prepare Release → 使用ref运行 develop
    • CLI： gh workflow run prepare-release.yml --ref develop
    • 如果PR来自 develop 已存在，将重新使用；PR从打开 develop 可以通过工作流自动合并。
  2. 发布自动化：何时 main 被更新， release.yml 运行release please（manifest）以更新版本 CHANGELOG.md，并创建GitHub Release/标签。
  3. 发布：标签推送 v* 触发器 publish.yml 运行测试、构建、类型检查和 npm publish --access public.

所需机密：

  • PERSONAL_ACCESS_TOKEN （可选；由以下人员使用 prepare-release/release 如果提供，则回退到 GITHUB_TOKEN)
  • NPM_TOKEN （为 publish.yml)

分支保护：保持保护打开 main；合并前，发布PR应满足所需的检查。

脚本参考

脚本 描述
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. 定期旋转按键：定期更改DateTimeDeveloper密钥

支持

获取帮助

如果您遇到任何问题或对使用DateTimeMCP服务器有疑问，以下是获得支持的最佳方法：

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

创建问题之前

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

我们支持什么

  • 安装和设置问题
  • 带有可重复步骤的Bug报告
  • 功能请求和建议
  • 文档改进

我们不支持什么

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

许可证

此项目根据MIT许可证获得许可-请参阅 许可证 文件以获取详细信息。

相关 MCP