PlayFab MCP Server

Un servidor intermediario que permite a los modelos de lenguaje grandes interactuar directamente con los servicios de PlayFab.

GitHub

Prueba este MCPPatrocinado

Documentación

Servidor MCP de PlayFab

¿Qué es esto? 🤔

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

Ejemplo rápido

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

¿Cómo funciona? 🛠️

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

Sigue estos pasos para comenzar:

Configura tu proyecto.
Agrega los detalles de tu proyecto a la configuración de tu cliente LLM.
¡Comienza 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 de catálogo (Economy v2):
- Crea nuevos artículos en borrador con la API create_draft_item.
- Actualiza artículos en borrador existentes con la API update_draft_item.
- Elimina artículos del catálogo con la API delete_item.
- Publica artículos en borrador para hacerlos disponibles con la API publish_draft_item.
- Obtén información detallada de artículos con la API get_item.

Gestión de jugadores

Recupera información completa de segmentos.
Consulta perfiles de jugadores dentro de segmentos específicos.
Convierte un ID de PlayFab a un ID de cuenta de jugador del título mediante la API get_title_player_account_id_from_playfab_id.
Obtén información detallada de cuentas de usuario con la API get_user_account_info.

Gestión de inventario

Operaciones de obtención:
- Recupera los artículos de inventario actuales con la API get_inventory_items.
- Obtén los ID de colecciones de inventario usando la API get_inventory_collection_ids.
Operaciones de agregar/eliminar:
- Agrega artículos al inventario con la API add_inventory_items.
- Elimina artículos del inventario con la API delete_inventory_items.
- Resta cantidades específicas con la API subtract_inventory_items.
Operaciones de modificación:
- Actualiza las propiedades de los artículos con la API update_inventory_items.

Administración de Economy v2

Ejecuta 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

Bloquea jugadores por ID, IP o dirección MAC con la API ban_users.
Desbloquea jugadores por completo con la API revoke_all_bans_for_user.

Gestión de datos de jugador

Recupera datos personalizados del jugador con la API get_user_data.
Actualiza datos personalizados del jugador con la API update_user_data.

Gestión de configuración del título

Establece datos globales del título con la API set_title_data.
Recupera datos del título con la API get_title_data.
Establece datos internos solo para servidor con la API set_title_internal_data.
Recupera datos internos con la API get_title_internal_data.

Inicio rápido 🚀

Requisitos previos

Node.js 18 o superior.
Una cuenta válida de PlayFab (obtén tu ID de título y clave secreta de desarrollador a través de PlayFab Game Manager).
Un cliente LLM compatible, como Claude Desktop.

Configura tu proyecto

Obtén tu ID de título y clave secreta de desarrollador de PlayFab desde PlayFab Game Manager, 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

Instalar dependencias

En la raíz del proyecto, ejecuta el siguiente comando para instalar todas las dependencias necesarias:
```
npm install
```
Compilar el proyecto

Compila el proyecto ejecutando:
```
npm run build
```
Iniciar el servidor

Inicia el servidor ejecutando:
```
npm start
```
Mensaje de confirmación

Al iniciar, deberías ver este mensaje:
```
PlayFab Server running on stdio
```

Configuración de desarrollo

Herramientas de calidad de código

ESLint: Configurado para TypeScript con reglas recomendadas para consistencia del código.
Prettier: Formateo automático de código con configuraciones específicas del proyecto.
TypeScript: Modo estricto habilitado para mayor seguridad de tipos.
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 usa TypeScript con modo estricto habilitado, lo que garantiza:

Comprobaciones estrictas de valores nulos.
Sin tipos implícitos any.
Tipos de función estrictos.
Siempre en modo estricto.

Pruebas

Las pruebas están escritas con Jest y se pueden encontrar en directorios __tests__ o archivos con extensión .test.ts. Ejecuta las pruebas antes de confirmar cambios para garantizar la calidad del código.

Desarrollo basado en especificaciones (Spec Kit, JP)

Instalar CLI: uv tool install specify-cli --from git+https://github.com/akiojin/spec-kit.git
Crear spec/plan/tareas: ./.specify/scripts/bash/create-new-feature.sh "feature summary" (por defecto no crea una rama. Si es necesario, --branch)
Recursos: .specify/templates/*, .specify/scripts/bash/*, especificaciones en specs/
Comandos de barra de Claude/Codex: /speckit.constitution, /speckit.specify, /speckit.plan, /speckit.tasks, /speckit.implement

Entorno de desarrollo con Docker

El repositorio incluye un contenedor de desarrollo ligero (Node 22, herramientas, 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

Los volúmenes mantienen tu espacio de trabajo (.), configuraciones de Codex/Claude e historial de shell. Establece PLAYFAB_TITLE_ID / PLAYFAB_DEV_SECRET_KEY en el entorno del contenedor al ejecutar el servidor.

Ejecutar con Cursor

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

Instala Cursor Desktop si aún no lo has hecho.
Abre una nueva instancia de Cursor en una carpeta vacía.
Copia el archivo mcp.json de este repositorio a tu carpeta y actualiza los valores según tu entorno.
Inicia Cursor; el Servidor MCP de PlayFab debería aparecer en la lista de herramientas.
Por ejemplo, prueba un mensaje como "Muéstrame los últimos 10 artículos" para verificar que el servidor procesa tu consulta correctamente.

Agregar los detalles de tu proyecto al archivo de configuración de Claude Desktop

Abre Claude Desktop y navega a Archivo → Configuración → Desarrollador → Editar configuración. Luego, reemplaza el contenido del archivo claude_desktop_config con el siguiente fragmento:

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

Con estos pasos, has configurado correctamente el servidor MCP de PlayFab para usarlo con tu cliente LLM, lo que permite una interacción fluida con los servicios de PlayFab.

Desarrollo basado en especificaciones con Spec Kit

Este repositorio sigue el flujo de trabajo SDD/TDD de Spec Kit utilizado en akiojin/gwt.

Requisitos: Python 3.11+ y uv
Instalar CLI: uv tool install specify-cli --from git+https://github.com/akiojin/spec-kit.git
Recursos: plantillas en .specify/templates, scripts en .specify/scripts/bash, especificaciones en specs/
Crear una nueva spec/plan: ./.specify/scripts/bash/create-new-feature.sh "feature summary" (agrega --branch si también quieres una rama)
Los archivos generados incluyen spec.md, plan.md, tasks.md; mantenlos revisados y confirmados junto con el código.
Comandos de barra de Claude/Codex (si están disponibles): /speckit.constitution, /speckit.specify, /speckit.plan, /speckit.tasks, /speckit.implement

Contribuciones

Convención de mensajes de confirmación

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

Formato del mensaje de confirmación

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

<body>

<footer>

Tipos

feat: Una nueva funcionalidad (genera un aumento de versión MENOR).
fix: Una corrección de errores (genera un aumento de versión PATCH).
docs: Solo cambios de documentación.
style: Cambios que no afectan el significado del código.
refactor: Un cambio de código que no corrige un error ni agrega una funcionalidad.
perf: Un cambio de código que mejora el rendimiento.
test: Agregar pruebas faltantes o corregir pruebas existentes.
chore: Cambios en el proceso de compilación o herramientas auxiliares.

Reglas de aumento de versión

Versión MAYOR: Cuando el mensaje de confirmación contiene BREAKING CHANGE en el pie de página o ! después del tipo/alcance.
- Ejemplo: feat!: remove deprecated API endpoints
- Ejemplo: feat: new API\n\nBREAKING CHANGE: removed old endpoints
Versión MENOR: Cuando el tipo de confirmación es feat
- Ejemplo: feat: add new PlayFab API integration
Versión PATCH: Cuando el tipo de confirmación es fix
- Ejemplo: fix: correct error handling in API calls

Proceso de publicación (develop → main, release-please)

Preparar PR de publicación: Ejecuta el flujo de trabajo prepare-release.yml para abrir un PR de develop a main
- Interfaz de Actions: Prepare Release → ejecutar con ref develop
- CLI: gh workflow run prepare-release.yml --ref develop
- Si ya existe un PR de develop, se reutilizará; los PR abiertos desde develop pueden fusionarse automáticamente mediante el flujo de trabajo.
Automatización de publicación: Cuando se actualiza main, release.yml ejecuta release-please (manifest) para aumentar versiones, actualizar CHANGELOG.md y crear la publicación/etiqueta de GitHub.
Publicar: El push de la etiqueta v* activa publish.yml para ejecutar pruebas, compilación, verificación de tipos y npm publish --access public.

Secretos requeridos:

PERSONAL_ACCESS_TOKEN (opcional; utilizado por prepare-release/release cuando se proporciona, recurre a GITHUB_TOKEN)
NPM_TOKEN (para publish.yml)

Protección de ramas: mantén las protecciones en main; los PR de publicación deben cumplir las verificaciones requeridas antes de fusionarse.

Referencia de scripts

Script	Descripción
`npm start`	Inicia el servidor MCP
`npm run build`	Compila TypeScript a JavaScript
`npm run watch`	Compila en modo de observación para desarrollo
`npm run typecheck`	Ejecuta la verificación de tipos de TypeScript
`npm run lint`	Ejecuta verificaciones de ESLint
`npm run lint:fix`	Corrige automáticamente problemas de ESLint
`npm run format`	Formatea el código con Prettier
`npm run format:check`	Verifica el formato del código
`npm test`	Ejecuta todas las pruebas
`npm run test:watch`	Ejecuta pruebas en modo de observación
`npm run test:coverage`	Genera informe de cobertura de pruebas

Seguridad

Nos tomamos la seguridad en serio. Si descubres una vulnerabilidad de seguridad dentro de este proyecto, sigue estos pasos:

Reportar vulnerabilidades de seguridad

NO crees un problema público de GitHub para vulnerabilidades de seguridad.
En su lugar, reporta problemas de seguridad mediante el reporte privado de vulnerabilidades de GitHub:
- Ve a la pestaña Seguridad de este repositorio.
- Haz clic en Reportar una vulnerabilidad.
- Proporciona información detallada sobre la vulnerabilidad.

Qué necesitamos de ti

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

Nuestro compromiso

Confirmaremos la recepción de tu informe dentro de 48 horas.
Proporcionaremos actualizaciones periódicas sobre nuestro progreso.
Te acreditaremos por el descubrimiento (a menos que prefieras permanecer anónimo).

Mejores prácticas de seguridad

Al usar este servidor:

Nunca confirmes credenciales: Usa siempre variables de entorno para datos sensibles.
Mantén las dependencias actualizadas: Ejecuta regularmente npm audit y actualiza los paquetes.
Usa el principio de privilegio mínimo: Solo otorga los permisos mínimos requeridos.
Rota las claves regularmente: Cambia tus claves secretas de desarrollador de PlayFab periódicamente.

Soporte

Obtener ayuda

Si encuentras problemas o tienes preguntas sobre el uso del Servidor MCP de PlayFab, estas son las mejores formas de obtener soporte:

Problemas de GitHub: Para informes de errores y solicitudes de funciones, crea un problema.
Discusiones: Para preguntas generales y soporte de la comunidad, usa Discusiones de GitHub.
Documentación: Consulta el README y los comentarios del código para ver ejemplos de uso.

Antes de crear un problema

Verifica si tu problema ya ha sido reportado buscando en los problemas existentes. Si encuentras un problema similar, puedes agregar información adicional como comentario.

Qué soportamos

Preguntas de instalación y configuración.
Informes de errores con pasos reproducibles.
Solicitudes de funciones y sugerencias.
Mejoras de documentación.

Qué no soportamos

Preguntas generales sobre la API de PlayFab (consulta 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; consulta el archivo LICENCIA para más detalles.