Servidor PlayFab MCP

¿Qué es esto? 🤔

Este servidor es un middleware que permite a grandes modelos lingüísticos (como Claude y VS Code) interactuar directamente con los servicios de PlayFab. Actuando como un traductor seguro y eficiente, conecta tu asistente de IA con varias funcionalidades de PlayFab, como la búsqueda de artículos, consultas de segmentos, búsquedas de perfiles de jugadores, gestión de inventario y conversión de ID de PlayFab.

Ejemplo rápido

A usted: "Muéstrame los últimos 10 artículos" Claude: *llama a la API search_items de PlayFab y devuelve los resultados en texto plano*

¿Cómo funciona? 🛠️

Este servidor aprovecha el Protocolo de Contexto de Modelo (MCP) para establecer una interfaz universal entre los modelos de IA y los servicios de PlayFab. Aunque el MCP está diseñado para soportar cualquier modelo de IA, actualmente está disponible como vista previa para desarrolladores.

Sigue estos pasos para empezar:

1. Configura tu proyecto.
2. Añade los detalles de tu proyecto a la configuración de tu cliente LLM.
3. Empieza a interactuar con los datos de PlayFab de forma natural

Qué puede hacer? 📊

Catálogo y Búsqueda

• Busca artículos usando la API search_items de PlayFab.
• Gestión del catálogo (Economy v2)
  • Crear nuevos elementos de borrador con la API create_draft_item.
  • Actualice los borradores existentes con la API update_draft_item.
  • Elimine elementos del catálogo con la API delete_item.
  • Publicar borradores para que estén disponibles con la API publish_draft_item.
  • Obtener información detallada de los elementos con la API get_item.

Gestión de jugadores

• Recuperar información exhaustiva de segmentos.
• Consulte los perfiles de los jugadores dentro de los segmentos especificados.
• Convierta un ID de PlayFab en un ID de cuenta de jugador de título mediante la API get_title_player_account_id_from_playfab_id.
• Obtenga información detallada de la cuenta de usuario con la API get_user_account_info.

Gestión de inventario

• Obtener operaciones
  • Recupere los artículos del inventario actual con la API get_inventory_items.
  • Obtenga los ID de las colecciones de inventario mediante la API get_inventory_collection_ids.
• Operaciones de adición/eliminación
  • Añadir artículos al inventario con la API add_inventory_items.
  • Eliminar artículos del inventario con la API delete_inventory_items.
  • Restar cantidades específicas con la API subtract_inventory_items.
• Modificar operaciones
  • Actualizar las propiedades de los artículos con la API update_inventory_items.

Administración de Economy v2

• Ejecutar operaciones de inventario por lotes con la API execute_inventory_operations.
• Nota: En Economy v2, las monedas virtuales se gestionan como artículos de inventario.

Administración de cuentas de usuario

• Prohibir jugadores por ID, IP o dirección MAC con la API ban_users.
• Anule la prohibición de jugadores por completo con la API revoke_all_bans_for_user.

Gestión de datos de jugadores

• Recupere los datos personalizados de los jugadores con la API get_user_data.
• Actualice los datos personalizados de los jugadores con la API update_user_data.

Gestión de la configuración de títulos

• Establezca los datos globales del título con la API set_title_data.
• Recupere los datos del título con la API get_title_data.
• Establecer datos internos sólo del servidor con la API set_title_internal_data.
• Recuperar datos internos con la API get_title_internal_data.

Inicio rápido

Instalación a través de Smithery

Para instalar PlayFab MCP Server para Claude Desktop automáticamente a través de Smithery:

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

Requisitos previos

• Node.js 18 o superior.
• Una cuenta PlayFab válida (obtenga su Title ID y Developer Secret Key a través de PlayFab Game Manager).
• Un cliente LLM soportado como Claude Desktop.

Configure su proyecto

Obtén tu ID de Título PlayFab y Clave Secreta de Desarrollador desde el Gestor de Juegos PlayFab, luego crea un archivo .env en la raíz del proyecto con el siguiente contenido (reemplaza los marcadores de posición con tus credenciales reales):

PLAYFAB_TITLE_ID= PLAYFAB_DEV_SECRET_KEY=

Instalación y configuración

1. Instalación de dependencias

   En la raíz del proyecto, ejecute el siguiente comando para instalar todas las dependencias necesarias:

   npm install

2. Compilar el proyecto

   Compile el proyecto ejecutando

   npm run build

3. Iniciar el servidor

   Inicie el servidor ejecutando

   npm start

4. Mensaje de confirmación

   Al iniciar, debería ver este mensaje:

   Servidor PlayFab ejecutándose en stdio

Configuración de desarrollo

Herramientas de calidad de código

• ESLint: Configurado para TypeScript con reglas recomendadas para la consistencia del código
• Prettier: Formateo automático del código con ajustes específicos del proyecto
• TypeScript: Modo estricto activado para mejorar la seguridad tipográfica
• Jest: Marco de pruebas configurado para TypeScript

Scripts disponibles

# 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

Configuración de TypeScript

Este proyecto utiliza TypeScript con el modo estricto activado, asegurando:

• Comprobaciones null estrictas
• Ningún tipo any implícito
• Tipos de función estrictos
• Siempre en modo estricto

Pruebas

Las pruebas se escriben utilizando Jest y se pueden encontrar en los directorios __tests__ o en archivos con extensión .test.ts. Ejecute las pruebas antes de confirmar los cambios para asegurar la calidad del código.

Ejecutar con Cursor

Para usar el servidor PlayFab MCP con Cursor, siga estos pasos:

1. Instale Cursor Desktop si aún no lo ha hecho.
2. Abra una nueva instancia de Cursor en una carpeta vacía.
3. Copie el archivo mcp.json de este repositorio en su carpeta y actualice los valores de acuerdo a su entorno.
4. Inicie Cursor; el Servidor PlayFab MCP debería aparecer en la lista de herramientas.
5. Por ejemplo, intente una consulta como "Muéstreme los últimos 10 elementos" para verificar que el servidor procesa su consulta correctamente.

Añadir los detalles de su proyecto al archivo de configuración de Claude Desktop

Abra Claude Desktop y vaya a Archivo → Configuración → Desarrollador → Editar Config. A continuación, sustituya el contenido del archivo claude_desktop_config por el siguiente fragmento:

{ "mcpServers": { "playfab": { "command": "npx", "args": [ "-y", "@akiojin/playfab-mcp-server" ], "env": { "PLAYFAB_TITLE_ID": "Tu ID de título de PlayFab", "PLAYFAB_DEV_SECRET_KEY": "Su clave secreta de desarrollador de PlayFab" } } }

Con estos pasos, habrás configurado correctamente el servidor MCP de PlayFab para utilizarlo con tu cliente LLM, permitiendo una interacción perfecta con los servicios de PlayFab.

Contribución

Convención de Mensajes Commit

Este proyecto sigue la Conventional Commits para el versionado y publicación automatizados.

Formato del mensaje de confirmación

<tipo>(<ámbito>): <asunto> <cuerpo> <pie>

Tipos

• feat: Una nueva característica (provoca un aumento MENOR de la versión)
• fix: Una corrección de errores (activa un cambio de versión PATCH)
• docs: Cambios sólo en la documentación
• estilo: Cambios que no afectan al significado del código
• refactorización: Un cambio de código que no corrige un error ni añade una característica
• perf: cambio de código que mejora el rendimiento
• test: Añadir pruebas que faltan o corregir pruebas existentes
• core: Cambios en el proceso de compilación o en las herramientas auxiliares

Reglas para el cambio de versión

• Versión MAYOR: Cuando el mensaje de confirmación contiene BREAKING CHANGE en el pie de página o ! después de type/scope
  • Ejemplo: feat: eliminar puntos finales de API obsoletos
  • Ejemplo: feat: new API\n\nBREAKING CHANGE: removed old endpoints
• Versión MINOR: Cuando el tipo de confirmación es feat
  • Ejemplo: feat: añadir nueva integración API PlayFab
• Versión PATCH: Cuando el tipo de confirmación es fix
  • Ejemplo: fix: corrección de errores en las llamadas a la API

Proceso de publicación

1. Actualizar versión y registro de cambios

# Analiza los commits y actualiza CHANGELOG.md # A continuación, actualiza la versión en función de los cambios: npm version patch # o minor/major

2. Empujar cambios y etiquetas

# Empujar el commit de versión git push origin main # Empujar la etiqueta de versión creada por npm version git push origin --tags

3. Publicación automática

Cuando se empuja una etiqueta v*, el flujo de trabajo release-and-publish.yml automáticamente:

• Crea una publicación en GitHub con notas de publicación
• Publica el paquete en npm
• Adjunta activos de publicación

Requisitos previos del repositorio

• El secretoNPM_TOKEN debe estar configurado en los ajustes del repositorio para la publicación npm
• DEPENDABOT_PAT secreto debe ser establecido para la auto-aprobación de Dependabot PRs
  1. Crear un Token de Acceso Personal (PAT) con permisos de repositorio y flujo de trabajo
  2. Ve a Configuración → Secretos y variables → Acciones
  3. Añade un nuevo secreto llamado DEPENDABOT_PAT con tu valor PAT
• Las reglas de protección de ramas deben estar configuradas para que funcione la fusión automática
  1. Vaya a Configuración → Ramas
  2. Añadir regla para la rama principal
  3. Activar "Requerir un pull request antes de fusionar"
  4. Habilitar "Requerir que las comprobaciones de estado pasen antes de fusionar"
  5. Añade las comprobaciones de estado requeridas: build (18.x), build (20.x), build (22.x)

Referencia de scripts

Seguridad

Nos tomamos la seguridad muy en serio. Si descubre una vulnerabilidad de seguridad en este proyecto, siga estos pasos:

Informar sobre vulnerabilidades de seguridad

1. NO cree una incidencia pública en GitHub sobre vulnerabilidades de seguridad
2. En su lugar, por favor, informe de los problemas de seguridad a través de la notificación privada de vulnerabilidades de GitHub
   • Ve a la pestaña Seguridad de este repositorio
   • Haz clic en Informar de una vulnerabilidad
   • Proporcione información detallada sobre la vulnerabilidad

Qué necesitamos de usted

• Una descripción de la vulnerabilidad
• Pasos para reproducir el problema
• Impacto potencial
• Cualquier solución sugerida (opcional)

Nuestro compromiso

• Acusaremos recibo de su informe en un plazo de 48 horas
• Le informaremos periódicamente de nuestros progresos
• Le daremos crédito por el descubrimiento (a menos que prefiera permanecer en el anonimato)

Buenas prácticas de seguridad

Cuando utilice este servidor

1. Nunca comprometa credenciales: Utilice siempre variables de entorno para los datos sensibles
2. Mantenga las dependencias actualizadas: Ejecute regularmente npm audit y actualice los paquetes
3. Utilice el mínimo privilegio: Conceda sólo los permisos mínimos necesarios
4. Rote las claves con regularidad: Cambia tus claves secretas de desarrollador de PlayFab periódicamente

Soporte

Obtener Ayuda

Si se encuentra con algún problema o tiene alguna pregunta sobre el uso del Servidor MCP de PlayFab, estas son las mejores formas de obtener ayuda:

1. Problemas en GitHub: Para los informes de errores y solicitudes de características, por favor cree un problema
2. Discusiones: Para preguntas generales y apoyo de la comunidad, utilice GitHub Discussions
3. Documentación: Consulte el LÉAME y los comentarios del código para ver ejemplos de uso

Antes de crear una incidencia

Comprueba si ya se ha informado de tu problema buscando en los problemas existentes. Si encuentra un problema similar, puede añadir información adicional como comentario.

Asistencia técnica

• Preguntas sobre instalación y configuración
• Informes de errores con pasos reproducibles
• Peticiones y sugerencias de funciones
• Mejoras en la documentación

Lo que no apoyamos

• Preguntas generales sobre la API de PlayFab (consulte la documentación de PlayFab)
• Problemas con herramientas o servicios de terceros
• Solicitudes de implementación personalizada

Licencia

Este proyecto está licenciado bajo la Licencia MIT - ver el archivo LICENSE para más detalles.