Serveur PlayFab MCP

Qu'est-ce que c'est ? 🤔

Ce serveur est un intergiciel qui permet aux grands modèles linguistiques (comme Claude et VS Code) d'interagir directement avec les services PlayFab. Agissant comme un traducteur sécurisé et efficace, il connecte votre assistant IA avec diverses fonctionnalités PlayFab, telles que la recherche d'articles, les demandes de segment, les consultations de profils de joueurs, la gestion des stocks et la conversion des identifiants PlayFab.

Exemple rapide

Vous : "Montrez-moi les 10 derniers articles" Claude : *appelle l'API PlayFab search_items et renvoie les résultats en texte clair*

Comment cela fonctionne-t-il ? 🛠️

Ce serveur s'appuie sur le Model Context Protocol (MCP) pour établir une interface universelle entre les modèles d'IA et les services PlayFab. Bien que le MCP soit conçu pour prendre en charge n'importe quel modèle d'IA, il est actuellement disponible en tant qu'aperçu pour les développeurs.

Suivez les étapes suivantes pour commencer :

1. Configurez votre projet.
2. Ajoutez les détails de votre projet à la configuration de votre client LLM.
3. Commencez à interagir avec les données PlayFab naturellement !

Que peut-il faire ? 📊

Catalogue et recherche

• Recherchez des articles en utilisant l'API search_items de PlayFab.
• Gestion du catalogue (Economy v2)
  • Créer de nouvelles ébauches d'articles avec l'API create_draft_item.
  • Mettre à jour les éléments de brouillon existants avec l'API update_draft_item.
  • Supprimer des éléments du catalogue avec l'API delete_item.
  • Publier des brouillons pour les rendre disponibles avec l'API publish_draft_item.
  • Obtenir des informations détaillées sur les éléments avec l'API get_item.

Gestion des joueurs

• Récupération d'informations complètes sur les segments.
• Interroger les profils des joueurs dans les segments spécifiés.
• Convertir un identifiant PlayFab en un identifiant de compte de joueur de titre via l'API get_title_player_account_id_from_playfab_id.
• Obtenez des informations détaillées sur les comptes d'utilisateurs avec l'API get_user_account_info.

Gestion de l'inventaire

• Opérations d'obtention
  • Récupérer les éléments d'inventaire actuels avec l'API get_inventory_items.
  • Récupérer les identifiants des collections d'inventaire avec l'API get_inventory_collection_ids.
• Opérations d'ajout/suppression
  • Ajouter des articles à l'inventaire avec l'API add_inventory_items.
  • Supprimer des articles de l'inventaire avec l'API delete_inventory_items.
  • Soustraire des quantités spécifiques avec l'API subtract_inventory_items.
• Opérations de modification
  • Mettre à jour les propriétés des articles avec l'API update_inventory_items.

Administration d'Economy v2

• Exécuter des opérations d'inventaire par lots avec l'API execute_inventory_operations.
• Remarque : dans Economy v2, les monnaies virtuelles sont gérées comme des articles d'inventaire.

Administration des comptes d'utilisateurs

• Bannissez les joueurs par ID, IP ou adresse MAC avec l'API ban_users.
• Annulez complètement le bannissement des joueurs avec l'API revoke_all_bans_for_user.

Gestion des données des joueurs

• Récupération des données personnalisées des joueurs avec l'API get_user_data.
• Mettre à jour les données personnalisées des joueurs avec l'API update_user_data.

Gestion de la configuration des titres

• Définir les données de titre globales avec l'API set_title_data.
• Récupérer les données de titre avec l'API get_title_data.
• Définir les données internes réservées au serveur avec l'API set_title_internal_data.
• Récupérez les données internes avec l'API get_title_internal_data.

Démarrage rapide 🚀

Installation via Smithery

Pour installer PlayFab MCP Server pour Claude Desktop automatiquement via Smithery:

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

Pré-requis

• Node.js 18 ou supérieur.
• Un compte PlayFab valide (obtenez votre ID de titre et votre clé secrète de développeur via le gestionnaire de jeu PlayFab).
• Un client LLM supporté tel que Claude Desktop.

Configurer votre projet

Obtenez votre ID de titre PlayFab et votre clé secrète de développeur à partir du gestionnaire de jeu PlayFab, puis créez un fichier .env à la racine du projet avec le contenu suivant (remplacez les caractères de remplacement par vos informations d'identification réelles) :

PLAYFAB_TITLE_ID= PLAYFAB_DEV_SECRET_KEY=

Installation et configuration

1. Installation des dépendances

   À la racine du projet, exécutez la commande suivante pour installer toutes les dépendances nécessaires :

   npm install

2. Construire le projet

   Compilez le projet en exécutant la commande suivante

   npm run build

3. Démarrer le serveur

   Démarrez le serveur en exécutant : npm run build

   npm start

4. Message de confirmation

   Au démarrage, vous devriez voir ce message :

   PlayFab Server running on stdio (Serveur PlayFab en cours d'exécution sur stdio)

Configuration du développement

Outils de qualité du code

• ESLint: Configuré pour TypeScript avec des règles recommandées pour la cohérence du code
• Prettier: Formatage automatique du code avec des paramètres spécifiques au projet
• TypeScript: Mode strict activé pour une meilleure sécurité des types
• Jest: Cadre de test configuré pour TypeScript

Scripts disponibles

# Construire le projet npm run build # Mode développement avec observation des fichiers npm run watch # Vérification des types TypeScript npm run typecheck # Exécuter ESLint npm run lint # Exécuter ESLint et corriger les problèmes npm run lint:fix # Formater le code avec Prettier npm run format # Vérifier le formatage du code npm run format:check # Exécuter les tests npm test # Exécuter les tests en mode observation npm run test:watch # Exécuter les tests avec couverture npm run test:coverage

Configuration TypeScript

Ce projet utilise TypeScript avec le mode strict activé :

• Vérifications strictes des nullités
• Aucun type implicite
• Types de fonctions stricts
• Toujours en mode strict

Tests

Les tests sont écrits en utilisant Jest et peuvent être trouvés dans les répertoires __tests__ ou les fichiers avec l'extension .test.ts. Exécutez les tests avant de valider les modifications pour garantir la qualité du code.

Exécution avec curseur

Pour utiliser le serveur PlayFab MCP avec Cursor, suivez ces étapes :

1. Installez Cursor Desktop si vous ne l'avez pas déjà fait.
2. Ouvrez une nouvelle instance de Cursor dans un dossier vide.
3. Copiez le fichier mcp.json de ce dépôt dans votre dossier et mettez à jour les valeurs en fonction de votre environnement.
4. Lancez Cursor ; le serveur PlayFab MCP devrait apparaître dans la liste des outils.
5. Par exemple, essayez une invite telle que "Show me the latest 10 items" pour vérifier que le serveur traite correctement votre requête.

Ajout des détails de votre projet au fichier de configuration de Claude Desktop

Ouvrez Claude Desktop et allez dans Fichier → Paramètres → Développeur → Modifier la configuration. Ensuite, remplacez le contenu du fichier claude_desktop_config par l'extrait suivant :

{ "mcpServers" : { "playfab" : { "command" : "npx", "args" : ["-y", "@akiojin/playfab-mcp-server" ], "env" : { "PLAYFAB_TITLE_ID" : "Votre ID de titre PlayFab", "PLAYFAB_DEV_SECRET_KEY" : "Votre clé secrète de développeur PlayFab" } } } }

Avec ces étapes, vous avez configuré avec succès le serveur MCP PlayFab pour l'utiliser avec votre client LLM, permettant une interaction transparente avec les services PlayFab.

Contribuer

Convention de message d'engagement

Ce projet suit les Commits conventionnels pour une version et une publication automatisées.

Format du message de validation

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

Types de messages

• feat: Une nouvelle fonctionnalité (déclenche un saut de version MINOR)
• fix: Correction d'un bogue (déclenche un changement de version PATCH)
• docs: Changements dans la documentation uniquement
• style: Changements qui n'affectent pas la signification du code
• refactor: Une modification du code qui ne corrige pas de bogue et n'ajoute pas de fonctionnalité
• perf: modification du code qui améliore les performances
• test: Ajout de tests manquants ou correction de tests existants
• chore: Changements dans le processus de construction ou les outils auxiliaires

Règles de changement de version

• Version MAJOR: Lorsque le message de livraison contient BREAKING CHANGE dans le pied de page ou ! après type/scope
  • Exemple : feat! : remove deprecated API endpoints (supprimer les points d'extrémité d'API obsolètes)
  • Exemple : feat : new API\n\nBREAKING CHANGE : removed old endpoints
• Version MINOR: Lorsque le type de livraison est feat
  • Exemple : feat : ajout d'une nouvelle intégration API PlayFab
• Version PATCH: Lorsque le type de livraison est fix
  • Exemple : fix : correction de la gestion des erreurs dans les appels à l'API

Processus de publication

1. Mise à jour de la version et du Changelog

# Analyser les commits et mettre à jour CHANGELOG.md # Puis mettre à jour la version en fonction des changements : npm version patch # ou minor/major

2. Pousser les changements et l'étiquette

# Pousser le commit de version git push origin main # Pousser le tag de version créé par npm version git push origin --tags

3. Publication automatique

Lorsqu'une balise v* est poussée, le flux de travail release-and-publish.yml se met en place automatiquement :

• Crée une version GitHub avec des notes de version
• Publie le paquetage sur npm
• Attache les actifs de la version

Prérequis pour le dépôt

• Le secretNPM_TOKEN doit être défini dans les paramètres du référentiel pour la publication npm
• DEPENDABOT_PAT secret doit être défini pour l'auto-approbation des PRs de Dependabot
  1. Créer un jeton d'accès personnel (PAT) avec des permissions de repo et de flux de travail
  2. Allez dans Paramètres → Secrets et variables → Actions
  3. Ajoutez un nouveau secret nommé DEPENDABOT_PAT avec votre valeur PAT
• Les règles de protection des branches doivent être configurées pour que la fusion automatique fonctionne
  1. Allez dans Paramètres → Branches
  2. Ajouter une règle pour la branche principale
  3. Activer "Require a pull request before merging" (Requérir une demande d'extraction avant de fusionner)
  4. Activer "Require status checks to pass before merging" (Exiger que les vérifications d'état soient réussies avant de fusionner)
  5. Ajouter les vérifications d'état requises : build (18.x), build (20.x), build (22.x)

Référence des scripts

Sécurité

Nous prenons la sécurité au sérieux. Si vous découvrez une faille de sécurité dans ce projet, veuillez suivre les étapes suivantes :

Signaler des failles de sécurité

1. NE PAS créer de problème public sur GitHub pour les vulnérabilités de sécurité
2. Au lieu de cela, veuillez signaler les problèmes de sécurité via le système privé de signalement des vulnérabilités de GitHub
   • Allez dans l'onglet Sécurité de ce dépôt
   • Cliquez sur Signaler une vulnérabilité
   • Fournir des informations détaillées sur la vulnérabilité

Ce que nous attendons de vous

• Une description de la vulnérabilité
• Les étapes pour reproduire le problème
• L'impact potentiel
• Toute suggestion de correction (facultatif)

Notre engagement

• Nous accuserons réception de votre rapport dans les 48 heures
• Nous fournirons des mises à jour régulières sur nos progrès
• Nous vous créditerons pour la découverte (à moins que vous ne préfériez rester anonyme)

Meilleures pratiques en matière de sécurité

Lorsque vous utilisez ce serveur :

1. Ne communiquez jamais d'informations d'identification: Utilisez toujours des variables d'environnement pour les données sensibles
2. Gardez les dépendances à jour: Exécuter régulièrement npm audit et mettre à jour les paquets
3. Utiliser le moindre privilège: N'accorder que les autorisations minimales requises
4. Faites tourner les clés régulièrement: Changez périodiquement vos clés secrètes de développeur PlayFab

Support

Obtenir de l'aide

Si vous rencontrez des problèmes ou si vous avez des questions sur l'utilisation du serveur PlayFab MCP, voici les meilleures façons d'obtenir de l'aide :

1. GitHub Issues: Pour les rapports de bogues et les demandes de fonctionnalités, veuillez créer un problème
2. Discussions: Pour les questions générales et le soutien de la communauté, utilisez les discussions GitHub
3. Documentation: Consultez le README et les commentaires du code pour des exemples d'utilisation

Avant de créer un problème

Vérifiez si votre problème n'a pas déjà été signalé en recherchant les problèmes existants. Si vous trouvez un problème similaire, vous pouvez ajouter des informations supplémentaires dans un commentaire.

Ce que nous supportons

• Questions relatives à l'installation et à la configuration
• Rapports de bogues avec des étapes reproductibles
• Demandes de fonctionnalités et suggestions
• Amélioration de la documentation

Ce que nous ne prenons pas en charge

• Questions générales sur l'API PlayFab (veuillez vous référer à la documentation PlayFab)
• Problèmes avec des outils ou des services tiers
• Demandes d'implémentation personnalisée

Licence

Ce projet est sous licence MIT - voir le fichier LICENSE pour plus de détails.