# XpaceOS · MCP — conecta con la red de retail media

> Servidor MCP de XpaceOS (v2.2.0): el puente para que agentes (silicio) y personas (carbono)
> se conecten al sistema operativo del comercio físico — la red de pantallas (flota, emisión en
> vivo, audiencia, proof-of-play, alta, publicar), el catálogo de 8.775 gemelos digitales,
> XpaceScan (3D desde el móvil), el motor de reglas XPL y la ayuda para humanos.

Ayuda para humanos: https://www.xpaceos.com/help/
La tool `help` y el resource xpaceos://help sirven una guía embebida en el backend;
no incorporan automáticamente los cambios de las páginas de ayuda.

Sitio / docs: https://www.xpaceos.com/mcp/
Manifest máquina: https://www.xpaceos.com/mcp/manifest.json
Registro de la Galaxia Admira: https://www.xpaceos.com/mcp/galaxia.json
Catálogo funcional numerado (JSON estático): https://www.xpaceos.com/mcp/funcionalidades.json
Catálogo funcional para humanos: https://www.xpaceos.com/help/funcionalidades/
Repo: https://github.com/csilvasantin/xpaceos

## Servidor MCP (cómo conectar)

- Endpoint: https://mcp.admira.store/mcp
- Transporte: MCP Streamable HTTP (JSON-RPC sobre POST /mcp); salud en GET /
- Auth: lecturas abiertas; ESCRITURAS (register_device, publish_asset) con la clave de flota AdmiraNeXT:
  `Authorization: Bearer <clave>` (persona+equipo; ver https://www.admiranext.com/mcp/#identidad). Quedan firmadas
  (firmado_por = NeoMacBookPro14, MorfeoMacMini…). `quien_soy` dice quién eres según la clave. Sin clave, el alta
  responde isError. Directorio de los MCP de la suite: https://www.admiranext.com/mcp/#directorio (FLT-2137).
- Claude Code: claude mcp add --transport http xpaceos https://mcp.admira.store/mcp
- Config de cliente (JSON):
  {"mcpServers":{"xpaceos":{"url":"https://mcp.admira.store/mcp","headers":{"Authorization":"Bearer <clave de flota>"}}}}
- Prueba rápida:
  curl -s https://mcp.admira.store/mcp -H "Content-Type: application/json" -d '{"jsonrpc":"2.0","id":1,"method":"tools/list"}'

## Catálogo funcional numerado · Good / Better / Best

- Fuente de documentación: https://www.xpaceos.com/mcp/funcionalidades.json
- Vista humana: https://www.xpaceos.com/help/funcionalidades/
- Contrato JSON schema_version 1.0; registros en features[]. Cada registro conserva
  un id estable (XP-F01, XP-F02…) y un número humano con formato 01.-, 02.-…
  Los IDs no dependen de la posición, los filtros, el modo visual ni el nombre traducido.
- Los campos good, better y best describen el estado por modo. Consulta su evidencia
  y limitaciones: una función enumerada no implica que esté implementada en los tres.
- Navegación local: Avanzado y el selector dentro de las vistas ofrecen Good · 8 bits,
  Better · 16 bits y Best · 32 bits. Better permite comparar con la proyección de Good
  o explorar en 3D de forma independiente; una cámara alineada no recupera controles.
- /modo best abre un escenario conceptual fijo con las personas del gemelo en vivo. Cuando la apertura tiene éxito,
  el resultado local incluye ok:true, preview:true y availability:"preview". Ese éxito
  confirma la navegación, no un gemelo Best operativo. Las 30 áreas Best siguen planned.
- Los nombres 8/16/32 bits son estilos artísticos; no indican profundidad de color.
  /modo y sus resultados pertenecen al navegador del gemelo, no a una herramienta MCP.
- Las referencias mcp apuntan a capacidades existentes. Un acceso de interfaz, un comando
  de la consola del juego o un piloto Blender no se convierten en herramientas MCP por
  aparecer en este catálogo.
- static_catalog en manifest.json y en el elemento xpaceos de galaxia.json enlaza el JSON.
  Se puede descubrir mediante galaxy({element:"xpaceos"}) o xpaceos://llms.txt; para leer
  el archivo completo, el cliente necesita acceso HTTP ordinario a la URL publicada.
- Esto no añade herramientas ni registra xpaceos://funcionalidades. El servidor sigue
  ofreciendo 16 herramientas y 4 recursos. tools/list y resources/list son la referencia
  para saber qué se puede invocar realmente en la conexión.
- La herramienta help y xpaceos://help conservan la guía embebida en el Worker hasta que
  se actualice ese backend. xpaceos://llms.txt y galaxy leen sus archivos web con caché;
  sus enlaces pueden tardar en reflejar una publicación reciente.

## Herramientas

- quien_soy — identidad persona+equipo que firma la conexión; sin clave, lector anónimo.
- fleet_status — visión general: pantallas/robots dados de alta y cuáles emiten ahora (asset + audiencia).
- list_screens — inventario de Xpaces activos: ubicación, id de pantalla, tipo y orientación.
- screen_now — qué emite AHORA una pantalla y su audiencia por cámara (personas · edad · género), y si está conectada.
- emission_report — proof-of-play de un circuito: pases, segundos, por tipo y por segmento.
- register_device — da de alta una pantalla o robot (auto-alta) y devuelve la URL del canal para emitir.
- publish_asset — publica una pieza de la biblioteca de Pixeria en una pantalla (el puente crear→distribuir).
- search_twins — busca en el catálogo de 8.775 gemelos (texto, marca, superficie, solo en vivo); devuelve el enlace de cada gemelo (/admira-xp/?loc=<id>).
- twin_detail — ficha de un gemelo: superficies con estado, coordenadas, enlace y reglas XPL resueltas.
- catalog_stats — totales del catálogo por marca, tipo de superficie y estado.
- list_scenes / scene_status — escenas de XpaceScan (vídeo 3D subido desde xpaceos.com/scan): estado, progreso, ficheros, visor.
- xpl_rules — reglas XPL (CUANDO·PARA·ENTONCES) resueltas para una pantalla en cascada global→circuito→pantalla.
- signage_feed — lo último que ha salido a la red de pantallas.
- help — guía embebida del backend por tema (gemelo, escanea, xpl, emite, alta, mcp, método).
- galaxy — directorio de servidores, hubs, identificadores y flujos de la Galaxia Admira; filtros opcionales element / flow.

## Resources

- xpaceos://help (text/markdown) — guía embebida del backend, sin sincronización automática con la web.
- xpaceos://llms.txt (text/plain) — este fichero.
- xpaceos://catalog/stats (application/json) — totales del catálogo.
- xpaceos://galaxy (application/json) — registro conectable de la Galaxia Admira.

## Privacidad

La audiencia se mide on-device (cámara del gemelo, @vladmandic/human): no se almacenan
imágenes ni datos personales, solo conteos agregados (presencia, género, edad). Las métricas
de género y edad son estimaciones estadísticas, no identificación de personas.

## Ecosistema

La Galaxia Admira comparte identidad de flota e identificadores canónicos entre productos:
- Crear: https://www.pixeria.com
- Operar: https://www.xpaceos.com
- Emitir: https://admira.tv
- Coordinar y probar: https://www.yokup.com
- Deliberar y orquestar: https://www.admira.live

### Conectar varios elementos en el mismo cliente

Directorio operativo: https://www.xpaceos.com/mcp/galaxia.json
Censo vivo de productos: https://www.yokup.com/mcp/galaxia.json
Directorio canónico de la suite: https://www.admiranext.com/mcp/#directorio

Config mínima para el flujo crear → operar → emitir → probar:

{"mcpServers":{"pixeria":{"url":"https://mcp-pixeria.admira.store/mcp"},"xpaceos":{"url":"https://mcp.admira.store/mcp","headers":{"Authorization":"Bearer <clave de flota>"}},"admiratv":{"url":"https://mcp-tv.admira.store/mcp","headers":{"Authorization":"Bearer <clave de flota>"}},"yokup":{"url":"https://yokup.com/mcp","headers":{"Authorization":"Bearer <credencial individual o clave de flota>"}}}}

La clave nunca se copia a documentación, prompts, commits ni capturas: se guarda en el almacén
seguro del cliente. Antes de escribir, llama a quien_soy / yokup_whoami y verifica persona+equipo.

### Contrato de relevo entre elementos

- Pixeria entrega asset_id / número / tags.
- XpaceOS recibe asset_id y screen_id; entrega twin_id, screen_id, circuit_id y scene_id.
- Admira.tv recibe asset_id + screen_id/circuit_id; entrega airtime_id y proof-of-play.
- Yokup recibe project_id + mission_id + proof_url y conserva la trazabilidad del trabajo.
- Admira.live coordina persona+equipo, decisiones, encargos y mensajes.

Flujo comprobable recomendado:
search_stock → publish_asset → screen_now → on_air → airtime_report → yokup_task_update.

## Federación

Misma convención /mcp/ en cada pata del ecosistema:
- Producción (Clear Channel): https://www.clearchannel.tv/mcp/
- Preproducción: https://www.admira.app/mcp/
- Consejo de Silicio: https://www.admira.live/mcp/

## Doctrina Xpaces · elementos (obligatoria)

En los Xpaces **todos los elementos tienen que ser movibles y sustituibles siempre**.

- **Movibles:** posición, escala y orientación viven en la configuración del Xpacio; nunca hardcodeadas en el motor.
- **Sustituibles:** se puede cambiar la representación (sprite → multivista → GLB → captura) o el propio activo sin reconstruir la sala.
- **Alcance:** mobiliario, pantallas, sensores, figuras, NPCs, zonas de interés y cualquier pieza del gemelo.
- Si un elemento no se puede reubicar o reemplazar desde datos, es un defecto de diseño — no una excepción aceptable.
- Método humano: https://www.xpaceos.com/ayuda/
- Ayuda para humanos: https://www.xpaceos.com/help/
- Comandos CLI layout/mobiliario: https://www.xpaceos.com/help/cli/

## Convenciones

- Avisos de cambios: Telegram grupo AdmiraXP, firmados "Admira IA".