VMFramework MCP

VMFramework MCP es un paquete de Unity solo para Editor que añade herramientas de proyecto compatibles con VMFramework a VM Unity MCP. Funciona con los conceptos públicos de VMFramework (GamePrefabs, GeneralSettings, GameTags, paneles de UI, contenedores y propiedades) en lugar de pedir a los llamadores que editen campos serializados internos.

Las herramientas se unen al catálogo canónico vinculado al proyecto de VM Unity MCP. Una conexión de servidor acompañante se vincula de forma inmutable a un proyecto y publica el catálogo tipado completo en su primera lista de herramientas exitosa. La búsqueda y la inspección exacta de contratos operan sobre esa superficie ya anunciada, por lo que las herramientas específicas del proyecto nunca se filtran entre conexiones.

Instalación

VMFramework MCP es una extensión opcional para proyectos que ya usan VMFramework. Primero completa la configuración base de VM Unity MCP y el host MCP, incluida su verificación de estado. Este paquete reutiliza esa misma conexión de servidor y no requiere otra entrada de Codex, Claude Desktop u otro host MCP.

Requisitos

• Unity 6000.4 o superior.

• com.vm233.unity-mcp 10.x. El contrato del paquete requiere 10.0.0 o superior en esa línea mayor; la versión coincidente actual es 10.0.13.

• Las dependencias VMFramework, VMCore, VM Odin Extensions y Unity Localization declaradas por package.json.

El proyecto ya debe resolver la pila de dependencias de VMFramework desde su propio Packages/manifest.json o desde el registro configurado. Sigue la guía de instalación de VMFramework para el framework base; esta extensión no duplica esos pines de Git.

Añadir el paquete

En Unity, abre Window > Package Manager, elige Add package from git URL... e introduce:

https://github.com/VM233/VMFramework-MCP.git#v5.1.0

Para un pin de proyecto inmutable, usa el SHA completo del commit de la versión en Packages/manifest.json:

"com.vm233.vmframework-mcp": "https://github.com/VM233/VMFramework-MCP.git#3463cab5f5018ecfd7b9bc5414293c03f2b4c1dd"

Deja que Package Manager actualice Packages/packages-lock.json; no edites Library/PackageCache ni incrustes el paquete.

Verificar la extensión

Después de que Unity termine de resolver y compilar los paquetes, vuelve a conectar el host MCP si ya había publicado la lista de herramientas del proyecto. Llama a unity_tools_search con moduleId: vmframework, inspecciona un resultado exacto con unity_tools_get y llama directamente a esa herramienta tipada anunciada. La extensión está instalada correctamente cuando sus herramientas aparecen en el mismo catálogo vinculado al proyecto que las herramientas base de Unity.

Related MCP server: Registry Browser MCP

Herramientas del proyecto

Usa unity_tools_search del servidor acompañante con intención o moduleId: vmframework, y luego unity_tools_get para inspeccionar un resultado exacto. Llama directamente a la herramienta tipada anunciada con su esquema publicado. El paquete publica actualmente estas familias de capacidades:

• descubrimiento de configuración efectiva y de GeneralSettings;

• descubrimiento de tipos de GamePrefab, búsqueda, consulta de configuración, inspección, creación y actualización atómica;

• inspección de paneles de UI, bind-object, contenedor-panel y VisualElementPath;

• lecturas de PropertyManager, escrituras en tiempo de ejecución y trazas acotadas;

• listado de GameTag, upsert localizado y validación.

• sesiones de GameItem en tiempo de ejecución con ámbito de propietario, con colocación, propiedades, configuración opcional de facción en el dominio del proyecto, vinculación de Panel y limpieza de tokens;

• ciclo de vida de Panel en tiempo de ejecución, vinculación, visibilidad real y esperas de OnOpen/OnPostClose;

• esperas de estado de Procedure y consulta/control de Logic Tick;

• inspección de GameItem en tiempo de ejecución de una sola vez;

• trazado genérico de wrapper/GamePrefab/Prefab/componente/GameTag/localización/dependencia y de referencias inversas.

Los indicadores de capacidad del catálogo son cadenas de solo presencia en tags; la ausencia de una etiqueta significa falso. Los efectos exactos de asset/tiempo de ejecución permanecen en sideEffects, mientras que los resultados dinámicos de las herramientas, como la visibilidad real, una coincidencia de espera fallida o un tick que no se avanzó, siguen siendo booleanos explícitos porque false es un dato significativo en tiempo de ejecución.

El adaptador de dominio de GameItem en tiempo de ejecución es el único punto de extensión para los hechos del proyecto que VMFramework no posee. Las implementaciones del proyecto deben leer y mutar los componentes autoritativos de la jugabilidad; los nombres, las etiquetas, las rutas de Prefab, la jerarquía y el estado de la UI no son proxies válidos para la facción, las habilidades o el ciclo de vida.

Las esperas largas y los escaneos de referencias inversas usan runAsJob=true. Consulta el Job devuelto con jobs/get, cancélalo mediante jobs/cancel y llama a jobs/cleanup solo cuando el Job informe de un token de limpieza disponible. La creación de sesiones también acepta una sessionKey; reutilizarla solo es válido cuando todos los argumentos de creación coinciden.

Las herramientas de UI de panel único requieren exactamente un panelID o prefabPath. vmframework/validate-visual-element-paths acepta además allPanels: true para auditar todos los paneles registrados y los prefabs independientes de UIPanel. Los resultados agregados se paginan globalmente y notifican por separado los prefabs faltantes, los VisualTreeAssets faltantes, los paneles no válidos y las rutas no válidas. Las rutas deshabilitadas por una condición Odin ShowIf o HideIf resoluble se excluyen porque no forman parte de la configuración activa del componente.

Todos los esquemas rechazan argumentos de negocio desconocidos. Los selectores, las rutas, los IDs, las operaciones de transacción, dryRun, las opciones de sobrescritura y las opciones de registro permanecen explícitos en cada solicitud.

La creación de GamePrefab ahora tiene un producto de datos directamente componible: vmframework.game-prefab-ref. vmframework/add-game-prefab y vmframework/find-game-prefab producen esa referencia; vmframework/inspect-game-prefab y vmframework/update-game-prefab la requieren; la actualización devuelve la referencia actual verificada. Busca con fromTool o toTool en el servidor acompañante para obtener el enlace exacto de puntero JSON de resultado a entrada y pasa el objeto de referencia directamente entre las dos herramientas ordinarias. El paquete no expone un ejecutor de cadenas genérico ni acepta una cadena JSON reenviada. El descubrimiento falla de forma cerrada cuando un wrapper coincidente no está registrado en exactamente un GamePrefabGeneralSetting compatible con el tipo; los consumidores vuelven a validar el mismo registro antes de leerlo o mutarlo.

vmframework/query-game-prefab-configs mantiene separadas la selección y la proyección. id, filter y gamePrefabType seleccionan identidad y un tipo de framework asignable; gameTagsAll, gameTagsAny, gameTagsNone, hasName y hasDescription componen filtros de contenido. fields selecciona explícitamente gameTags, name o description, mientras que locales reduce los valores localizados. Cada fila sigue llevando vmframework.game-prefab-ref, de modo que los llamadores pueden pasar una coincidencia a inspect-game-prefab para obtener el objeto serializado acotado completo. Omitir fields produce la página mínima solo de identidad; la consulta masiva no duplica el inspector de objetos completos.

Los proyectos consumidores aportan sus propios nombres de tipo e ids de GameTag. Por ejemplo, un proyecto puede solicitar una locale de nombres para cualquier combinación de tipo/etiqueta sin que el paquete defina qué significa ese tipo o etiqueta:

{
  "gamePrefabType": "<full GamePrefab type>",
  "gameTagsAll": ["<tag-id>"],
  "hasName": true,
  "fields": ["name"],
  "locales": ["en-US"]
}

vmframework/update-game-prefab admite la migración semántica de ID mediante una operación de establecimiento del id raíz. Los tipos de operación son los valores tipados set, append, insert, remove y clear. La transacción valida y relee la nueva identidad, la devuelve en gamePrefab e incluye previousId cuando la identidad cambió.

La actualización toma una instantánea del wrapper y de los bytes meta antes de la mutación. Una confirmación exitosa devuelve terminalState="committed" con evidencia de confirmación SHA-256. En caso de fallo, el reemplazo atómico en el mismo directorio restaura la línea base, Unity lo importa sincrónicamente, y tanto la lectura de bytes como la semántica deben pasar antes de que la herramienta devuelva terminalState="rolled_back". El fallo de restauración se notifica como rollback_failed con los errores original y de rollback mantenidos por separado.

Configuración

Los valores predeterminados efectivos usan este orden:

1. argumento explícito de la herramienta;

2. Project Settings > VMFramework MCP;

3. Preferences > VMFramework MCP o el presupuesto de resultados compartido de Preferences > Unity MCP;

4. valor predeterminado del paquete.

ProjectSettings/VMFrameworkMCPSettings.json pertenece al equipo y contiene solo el contrato de cobertura de validación de GameTag:

{
  "schemaVersion": 1,
  "gameTagValidation": {
    "includeMissingTranslations": true,
    "includeGamePrefabReferences": true
  }
}

Preferences > VMFramework MCP contiene opciones de respuesta del operador: profundidad de inspección de GamePrefab, presupuesto de elementos por colección, instantáneas de actualización opcionales y la capacidad retenida de trazas de propiedades.

Las herramientas de una sola colección principal reutilizan la anulación opcional del límite de resultados en Preferences > Unity MCP > Tool Responses. VMFramework MCP no duplica esa preferencia.

Los detalles grandes o no deterministas permanecen bajo la propiedad de la solicitud y desactivados por defecto:

• includeGamePrefabDetails;

• includeRuntime;

• includeValid;

• includeLocalizations;

• includeSnapshots;

• includeValidation en upsert-game-tag.

Las proyecciones de consulta de configuración de GamePrefab también son de propiedad de la solicitud mediante fields; las proyecciones localizadas incluyen todas las locales de la tabla a menos que locales las reduzca.

Consulta Documentation~/configuration.md para la auditoría de propiedad por herramienta y las reglas de respuesta.

Desarrollo

Ejecuta las pruebas EditMode del paquete mediante la herramienta anunciada unity_testing_run_package_tests o filtra Unity Test Runner por VMFrameworkMCP.FullRegression. La suite de regresión verifica el catálogo exacto de VMFramework, las rutas directas, los metadatos de operación, los esquemas estrictos, el round-tripping de configuración y el comportamiento de conversión de GamePrefab/GameTag.

Este paquete no contiene ningún ensamblado en tiempo de ejecución.