PlayFab MCP Server

Um servidor intermediário que permite que modelos de linguagem de grande escala interajam diretamente com os serviços PlayFab.

GitHub
3
Experimente este MCPPatrocinado

Documentação

Servidor MCP do PlayFab

O que é isso? 🤔

Este servidor é um middleware que permite que modelos de linguagem de grande porte (como Claude e VS Code) interajam diretamente com os serviços do PlayFab. Atuando como um tradutor seguro e eficiente, ele conecta seu assistente de IA a várias funcionalidades do PlayFab, como busca de itens, consultas de segmentos, consultas de perfis de jogadores, gerenciamento de inventário e conversão de IDs do PlayFab.

Exemplo Rápido

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

Como Funciona? 🛠️

Este servidor utiliza o Model Context Protocol (MCP) para estabelecer uma interface universal entre modelos de IA e os serviços do PlayFab. Embora o MCP seja projetado para suportar qualquer modelo de IA, ele está atualmente disponível como uma prévia para desenvolvedores.

Siga estes passos para começar:

  1. Configure seu projeto.
  2. Adicione os detalhes do seu projeto à configuração do seu cliente de LLM.
  3. Comece a interagir com os dados do PlayFab naturalmente!

O que Ele Pode Fazer? 📊

Catálogo e Busca

  • Busque itens usando a API search_items do PlayFab.
  • Gerenciamento de Catálogo (Economy v2):
    • Crie novos itens de rascunho com a API create_draft_item.
    • Atualize itens de rascunho existentes com a API update_draft_item.
    • Exclua itens do catálogo com a API delete_item.
    • Publique itens de rascunho para disponibilizá-los com a API publish_draft_item.
    • Obtenha informações detalhadas do item com a API get_item.

Gerenciamento de Jogadores

  • Recupere informações abrangentes de segmentos.
  • Consulte perfis de jogadores em segmentos específicos.
  • Converta um ID do PlayFab em um ID de Conta de Jogador do Título via API get_title_player_account_id_from_playfab_id.
  • Obtenha informações detalhadas da conta de usuário com a API get_user_account_info.

Gerenciamento de Inventário

  • Operações de Obtenção:
    • Recupere itens de inventário atuais com a API get_inventory_items.
    • Busque IDs de coleção de inventário usando a API get_inventory_collection_ids.
  • Operações de Adicionar/Remover:
    • Adicione itens ao inventário com a API add_inventory_items.
    • Exclua itens do inventário com a API delete_inventory_items.
    • Subtraia quantidades específicas com a API subtract_inventory_items.
  • Operações de Modificação:
    • Atualize propriedades de itens com a API update_inventory_items.

Administração do Economy v2

  • Execute operações de inventário em lote com a API execute_inventory_operations.
  • Nota: No Economy v2, moedas virtuais são gerenciadas como itens de inventário.

Administração de Contas de Usuário

  • Bane jogadores por ID, IP ou endereço MAC com a API ban_users.
  • Desbane jogadores completamente com a API revoke_all_bans_for_user.

Gerenciamento de Dados do Jogador

  • Recupere dados personalizados do jogador com a API get_user_data.
  • Atualize dados personalizados do jogador com a API update_user_data.

Gerenciamento de Configuração do Título

  • Defina dados globais do título com a API set_title_data.
  • Recupere dados do título com a API get_title_data.
  • Defina dados internos somente para servidor com a API set_title_internal_data.
  • Recupere dados internos com a API get_title_internal_data.

Início Rápido 🚀

Pré-requisitos

  • Node.js 18 ou superior.
  • Uma conta PlayFab válida (obtenha seu Title ID e Developer Secret Key via PlayFab Game Manager).
  • Um cliente de LLM compatível, como Claude Desktop.

Configure Seu Projeto

Obtenha seu Title ID e Developer Secret Key do PlayFab no PlayFab Game Manager e, em seguida, crie um arquivo .env na raiz do projeto com o seguinte conteúdo (substitua os espaços reservados pelas suas credenciais reais):

PLAYFAB_TITLE_ID=
PLAYFAB_DEV_SECRET_KEY=

Instalação e Configuração

  1. Instalar Dependências

    Na raiz do projeto, execute o seguinte comando para instalar todas as dependências necessárias:

    npm install

  2. Compilar o Projeto

    Compile o projeto executando:

    npm run build

  3. Iniciar o Servidor

    Inicie o servidor executando:

    npm start

  4. Mensagem de Confirmação

    Ao iniciar, você deve ver esta mensagem:

    PlayFab Server running on stdio

Configuração de Desenvolvimento

Ferramentas de Qualidade de Código

  • ESLint: Configurado para TypeScript com regras recomendadas para consistência de código
  • Prettier: Formatação automática de código com configurações específicas do projeto
  • TypeScript: Modo estrito habilitado para maior segurança de tipos
  • Jest: Framework de testes configurado para TypeScript

Scripts Disponíveis

# 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

Configuração do TypeScript

Este projeto usa TypeScript com modo estrito habilitado, garantindo:

  • Verificações estritas de nulos
  • Sem tipos any implícitos
  • Tipos de função estritos
  • Sempre em modo estrito

Testes

Os testes são escritos usando Jest e podem ser encontrados em diretórios __tests__ ou arquivos com extensão .test.ts. Execute os testes antes de confirmar alterações para garantir a qualidade do código.

Desenvolvimento Orientado por Especificações (Spec Kit, JP)

  • Instalar CLI: uv tool install specify-cli --from git+https://github.com/akiojin/spec-kit.git
  • Criar spec/plano/tarefas: ./.specify/scripts/bash/create-new-feature.sh "feature summary" (por padrão, não cria branch. Se necessário, use --branch)
  • Assets: .specify/templates/*, .specify/scripts/bash/*, specs em specs/
  • Comandos de barra do Claude/Codex: /speckit.constitution, /speckit.specify, /speckit.plan, /speckit.tasks, /speckit.implement

Ambiente de Desenvolvimento Docker

O repositório inclui um contêiner de desenvolvimento leve (Node 22, ferramentas, 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

Os volumes mantêm seu espaço de trabalho (.), configurações do Codex/Claude e histórico do shell. Defina PLAYFAB_TITLE_ID / PLAYFAB_DEV_SECRET_KEY no ambiente do contêiner ao executar o servidor.

Executando com Cursor

Para usar o servidor MCP do PlayFab com o Cursor, siga estes passos:

  1. Instale o Cursor Desktop se ainda não o fez.
  2. Abra uma nova instância do Cursor em uma pasta vazia.
  3. Copie o arquivo mcp.json deste repositório para sua pasta e atualize os valores de acordo com seu ambiente.
  4. Inicie o Cursor; o PlayFab MCP Server deve aparecer na lista de ferramentas.
  5. Por exemplo, tente um prompt como "Mostre-me os últimos 10 itens" para verificar se o servidor processa sua consulta corretamente.

Adicionando os Detalhes do Seu Projeto ao Arquivo de Configuração do Claude Desktop

Abra o Claude Desktop e navegue até File → Settings → Developer → Edit Config. Em seguida, substitua o conteúdo do arquivo claude_desktop_config pelo seguinte trecho:

{
  "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"
      }
    }
  }
}

Com esses passos, você configurou com sucesso o servidor MCP do PlayFab para uso com seu cliente de LLM, permitindo interação perfeita com os serviços do PlayFab.

Desenvolvimento Orientado por Especificações com Spec Kit

Este repositório segue o fluxo de trabalho SDD/TDD do Spec Kit usado em akiojin/gwt.

  • Requisitos: Python 3.11+ e uv
  • Instalar CLI: uv tool install specify-cli --from git+https://github.com/akiojin/spec-kit.git
  • Assets: modelos em .specify/templates, scripts em .specify/scripts/bash, specs em specs/
  • Criar uma nova spec/plano: ./.specify/scripts/bash/create-new-feature.sh "feature summary" (adicione --branch se também quiser um branch)
  • Arquivos gerados incluem spec.md, plan.md, tasks.md; mantenha-os revisados/confirmados junto com o código
  • Comandos de barra do Claude/Codex (se disponíveis): /speckit.constitution, /speckit.specify, /speckit.plan, /speckit.tasks, /speckit.implement

Contribuindo

Convenção de Mensagens de Commit

Este projeto segue Conventional Commits para versionamento e lançamento automatizados.

Formato da Mensagem de Commit

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

<body>

<footer>

Tipos

  • feat: Um novo recurso (aciona incremento de versão MINOR)
  • fix: Uma correção de bug (aciona incremento de versão PATCH)
  • docs: Apenas alterações de documentação
  • style: Alterações que não afetam o significado do código
  • refactor: Uma alteração de código que não corrige um bug nem adiciona um recurso
  • perf: Uma alteração de código que melhora o desempenho
  • test: Adicionar testes ausentes ou corrigir testes existentes
  • chore: Alterações no processo de build ou ferramentas auxiliares

Regras de Incremento de Versão

  • Versão MAJOR: Quando a mensagem de commit contém BREAKING CHANGE no rodapé ou ! após tipo/escopo
    • Exemplo: feat!: remove deprecated API endpoints
    • Exemplo: feat: new API\n\nBREAKING CHANGE: removed old endpoints
  • Versão MINOR: Quando o tipo de commit é feat
    • Exemplo: feat: add new PlayFab API integration
  • Versão PATCH: Quando o tipo de commit é fix
    • Exemplo: fix: correct error handling in API calls

Processo de Lançamento (develop → main, release-please)

  1. Preparar PR de lançamento: Execute o fluxo de trabalho prepare-release.yml para abrir um PR de develop para main
    • Interface de Ações: Prepare Release → execute com ref develop
    • CLI: gh workflow run prepare-release.yml --ref develop
    • Se um PR de develop já existir, ele será reutilizado; PRs abertos de develop podem ser mesclados automaticamente pelo fluxo de trabalho.
  2. Automação de lançamento: Quando main é atualizado, release.yml executa release-please (manifesto) para incrementar versões, atualizar CHANGELOG.md e criar o GitHub Release/tag.
  3. Publicar: O push da tag v* aciona publish.yml para executar testes, build, typecheck e npm publish --access public.

Segredos necessários:

  • PERSONAL_ACCESS_TOKEN (opcional; usado por prepare-release/release quando fornecido, com fallback para GITHUB_TOKEN)
  • NPM_TOKEN (para publish.yml)

Proteção de branch: mantenha as proteções em main; os PRs de lançamento devem atender às verificações necessárias antes da mesclagem.

Referência de Scripts

ScriptDescrição
npm startIniciar o servidor MCP
npm run buildCompilar TypeScript para JavaScript
npm run watchCompilar em modo de observação para desenvolvimento
npm run typecheckExecutar verificação de tipos do TypeScript
npm run lintExecutar verificações do ESLint
npm run lint:fixCorrigir problemas do ESLint automaticamente
npm run formatFormatar código com Prettier
npm run format:checkVerificar formatação do código
npm testExecutar todos os testes
npm run test:watchExecutar testes em modo de observação
npm run test:coverageGerar relatório de cobertura de testes

Segurança

Levamos a segurança a sério. Se você descobrir uma vulnerabilidade de segurança neste projeto, siga estes passos:

Reportando Vulnerabilidades de Segurança

  1. NÃO crie uma issue pública no GitHub para vulnerabilidades de segurança
  2. Em vez disso, reporte problemas de segurança via relatório privado de vulnerabilidades do GitHub:
    • Vá para a aba Security deste repositório
    • Clique em Report a vulnerability
    • Forneça informações detalhadas sobre a vulnerabilidade

O Que Precisamos de Você

  • Uma descrição da vulnerabilidade
  • Passos para reproduzir o problema
  • Impacto potencial
  • Quaisquer correções sugeridas (opcional)

Nosso Compromisso

  • Confirmaremos o recebimento do seu relatório em até 48 horas
  • Forneceremos atualizações regulares sobre nosso progresso
  • Creditaremos você pela descoberta (a menos que prefira permanecer anônimo)

Boas Práticas de Segurança

Ao usar este servidor:

  1. Nunca confirme credenciais: Sempre use variáveis de ambiente para dados sensíveis
  2. Mantenha as dependências atualizadas: Execute regularmente npm audit e atualize os pacotes
  3. Use privilégio mínimo: Conceda apenas as permissões mínimas necessárias
  4. Rotacione chaves regularmente: Altere suas Developer Secret Keys do PlayFab periodicamente

Suporte

Obtendo Ajuda

Se você encontrar problemas ou tiver dúvidas sobre o uso do PlayFab MCP Server, aqui estão as melhores maneiras de obter suporte:

  1. GitHub Issues: Para relatórios de bugs e solicitações de recursos, crie uma issue
  2. Discussions: Para perguntas gerais e suporte da comunidade, use GitHub Discussions
  3. Documentação: Consulte o README e os comentários do código para exemplos de uso

Antes de Criar uma Issue

Verifique se seu problema já foi relatado pesquisando nas issues existentes. Se encontrar um problema semelhante, você pode adicionar informações adicionais como comentário.

O Que Suportamos

  • Perguntas sobre instalação e configuração
  • Relatórios de bugs com passos reproduzíveis
  • Solicitações de recursos e sugestões
  • Melhorias na documentação

O Que Não Suportamos

  • Perguntas gerais sobre a API do PlayFab (consulte a Documentação do PlayFab)
  • Problemas com ferramentas ou serviços de terceiros
  • Solicitações de implementação personalizada

Licença

Este projeto é licenciado sob a Licença MIT - consulte o arquivo LICENSE para detalhes.