Pixeltable

Haz que construir aplicaciones de datos de IA multimodal sea increíblemente simple.

Documentación

Servidor MCP para Desarrolladores de Pixeltable

Un servidor local de Protocolo de Contexto de Modelo (MCP) para construir, inspeccionar y operar aplicaciones de Pixeltable. La versión 0.2 sigue el flujo de trabajo centrado en la aplicación de pixeltable-skill 2.8.3: genera un app.py, aplica su esquema y sirve sus rutas con la CLI de pxt.

Compatibilidad

Componente	Línea compatible
Python	3.11 o más reciente
Pixeltable	`>=0.7.6,<0.8` con el extra `serve`
SDK de Python para MCP	`>=2.2,<3`
Habilidad de Pixeltable	2.8.3
Transporte de producción	`stdio` local

El servidor es una herramienta de desarrollador en versión beta. Se ejecuta con los permisos del proceso que lo lanzó y puede modificar el catálogo de Pixeltable seleccionado. Apunta PIXELTABLE_MCP_PROJECT_ROOT al directorio de la aplicación y PIXELTABLE_HOME al catálogo previsto antes del inicio. Ambas ubicaciones quedan fijas durante la vida del proceso. Usa un catálogo separado para la evaluación y las pruebas automatizadas.

Instalación y conexión

Instala uv y luego instala el servidor:

uv tool install --from git+https://github.com/pixeltable/mcp-server-pixeltable-developer.git mcp-server-pixeltable-developer
mcp-server-pixeltable-developer --version

Para un desarrollo reproducible desde un clon:

git clone https://github.com/pixeltable/mcp-server-pixeltable-developer.git
cd mcp-server-pixeltable-developer
uv sync --frozen --extra test

Configura un cliente para lanzar el servidor a través de stdio. Reemplaza las rutas del repositorio, del proyecto de la aplicación y del catálogo con rutas absolutas:

{
  "mcpServers": {
    "pixeltable": {
      "command": "uv",
      "args": [
        "run",
        "--directory",
        "/absolute/path/to/mcp-server-pixeltable-developer",
        "mcp-server-pixeltable-developer"
      ],
      "env": {
        "PIXELTABLE_MCP_PROJECT_ROOT": "/absolute/path/to/pixeltable-app",
        "PIXELTABLE_HOME": "/absolute/path/to/.pixeltable"
      }
    }
  }
}

Reinicia el cliente después de cambiar su configuración de MCP. Mantén un proceso de servidor por catálogo al realizar mutaciones de esquema o de servicio.

Interfaz predeterminada

La versión 0.2 expone una interfaz enfocada en lugar de reflejar toda la API de Python de Pixeltable.

Herramientas

Área	Herramientas
Inspección	`pixeltable_list_catalog`, `pixeltable_describe`, `pixeltable_rows`, `pixeltable_get_row`, `pixeltable_errors`
Datos	`pixeltable_insert_rows`, `pixeltable_recompute`
Andamiaje de aplicación	`pixeltable_scaffold_app`
Ciclo de vida del esquema	`pixeltable_schema_check`, `pixeltable_schema_diff`, `pixeltable_schema_update`, `pixeltable_schema_prune`
Ciclo de vida del servicio	`pixeltable_service_check`, `pixeltable_service_diff`, `pixeltable_service_update`, `pixeltable_service_list`, `pixeltable_service_stop`, `pixeltable_service_prune`

Las herramientas de lectura declaran anotaciones de MCP de solo lectura. Las herramientas de mutación declaran su comportamiento de escritura y destructivo. Los argumentos y resultados usan esquemas tipados, y los fallos recuperables se devuelven como errores de herramienta de MCP para que los clientes puedan reintentar con entrada corregida.

Recursos

URI	Propósito
`pixeltable://status`	Estado del servidor, dependencias, transporte, catálogo y modo inseguro
`pixeltable://catalog`	Inventario actual del catálogo
`pixeltable://guidance/app`	Flujo de trabajo de aplicaciones de Pixeltable 0.7.6
`pixeltable://guidance/cloud`	Guía de preparación para la nube; no despliega recursos

Indicaciones

pixeltable_build_app
pixeltable_build_rag
pixeltable_build_agent
pixeltable_debug_computation

Las indicaciones son guías breves de tareas alineadas con pixeltable-skill 2.8.3. La habilidad sigue siendo la fuente detallada para las formas de salida de los proveedores, las vistas multimodales, los índices, la llamada a herramientas, el servicio, la depuración y los flujos de trabajo en la nube.

Modo inseguro

La ejecución de código del host, la instalación de paquetes y la visualización en el navegador están deshabilitadas de forma predeterminada. Un usuario local de confianza puede optar por activarlas antes de iniciar el servidor:

export PIXELTABLE_MCP_ENABLE_UNSAFE=1

Esto añade:

pixeltable_unsafe_execute_python
pixeltable_unsafe_install_package
pixeltable_unsafe_display

Estas herramientas están disponibles solo en stdio. Pueden ejecutar Python arbitrario, cambiar el entorno del servidor, leer archivos disponibles para el proceso del servidor y renderizar contenido no confiable. Actívalas solo para un cliente MCP local de confianza y un entorno de desarrollo desechable. No expongas el modo inseguro a través de un transporte HTTP.

El repositorio puede usar un arnés en proceso o HTTP en las pruebas. HTTP no es un transporte de producción compatible para la versión 0.2. Una futura versión HTTP debe añadir autorización, límites de concurrencia y de solicitudes, validación de origen y host, aislamiento por principal y un modelo de amenazas explícito antes de ser compatible.

Flujo de trabajo recomendado de Pixeltable

Inicia una aplicación con la CLI actual de Pixeltable:

pip install 'pixeltable[serve]>=0.7.6,<0.8'
pxt init
pxt service example --out app.py
pxt schema check app.py
pxt schema diff app.py my_app
pxt schema update app.py my_app
pxt service check app.py
pxt service update app.py my_app
pxt service list

my_app es un directorio de catálogo. No es un directorio del sistema de archivos. Edita app.py y vuelve a aplicar el esquema cuando el modelo cambie. Vuelve a aplicar el servicio después de los cambios de rutas. Usa pxt service list para descubrir la URL asignada.

El archivo de la aplicación debe declarar clases TableModel y, cuando se necesiten rutas HTTP, un FastAPIRouter. Las columnas almacenadas usan anotaciones. Las columnas calculadas usan asignaciones. Los tipos no admiten valores nulos de forma predeterminada; escribe T | None para una columna opcional. No uses pxt.Required.

Las actualizaciones de esquema requieren intencionalmente un paso de revisión. schema_check valida el archivo, schema_diff previsualiza los cambios del catálogo y schema_update los aplica. Las operaciones de poda son separadas porque pueden eliminar objetos del catálogo. Cambiar una expresión de columna calculada existente en su lugar no es compatible con Pixeltable; renombra la columna, o elimínala y vuelve a añadirla en actualizaciones separadas.

Para la nube, prepara el mismo app.py, establece PIXELTABLE_API_KEY, configura el pxt://org:db objetivo y revisa pixeltable://guidance/cloud. El servidor MCP no crea recursos de pago ni despliega en la nube automáticamente.

Desarrollo y verificación

Usa un catálogo desechable:

export PIXELTABLE_MCP_PROJECT_ROOT="$PWD"
export PIXELTABLE_HOME="$(mktemp -d)/catalog"
uv sync --frozen --extra test
uv run pytest -q
PIXELTABLE_DISABLE_STDOUT=1 uv run pytest --run-slow -q
uv run python list_tools.py
./scripts/run-conformance.sh

Ejecuta el Inspector de MCP solo como un arnés de prueba local:

uv run mcp dev src/mcp_server_pixeltable_developer/server.py:mcp

Antes del lanzamiento, también ejecuta el trabajo de compatibilidad de dependencias más reciente, las pruebas de contrato en memoria de MCP, la prueba de humo del subproceso stdio, el lint, las comprobaciones de tipos y la verificación de construcción del paquete descritas en el informe de revisión.

Política de privacidad

El servidor se ejecuta completamente en la máquina que lo inicia. No recopila telemetría ni análisis, y no envía nada a Pixeltable ni a terceros.

Qué maneja. El catálogo de Pixeltable en PIXELTABLE_HOME y los archivos de aplicación bajo PIXELTABLE_MCP_PROJECT_ROOT, ambos elegidos por ti. Los resultados de las herramientas se devuelven al cliente MCP que lanzó el servidor, que es como tu asistente los lee. Nada más los recibe.

Almacenamiento y retención. El servidor no almacena nada propio. Los datos del catálogo permanecen en PIXELTABLE_HOME en tu disco, bajo tu control, y se eliminan cuando tú los eliminas.

Secretos. La salida de comandos pasa por un redactor que enmascara formas comunes de credenciales, incluidas contraseñas en URL y tokens de API, antes de llegar al cliente.

Terceros. Si tu aplicación declara columnas calculadas que llaman a proveedores de modelos, Pixeltable realiza esas llamadas con las credenciales que configuraste. Ese tráfico es de tu aplicación, no de este servidor.

Modo inseguro. Con PIXELTABLE_MCP_ENABLE_UNSAFE=1, las herramientas añadidas ejecutan Python arbitrario, instalan paquetes y leen archivos disponibles para el proceso del servidor. Actívalo solo en una máquina local de confianza.

Contacto. Reporta preguntas sobre privacidad a través de problemas de GitHub.

Documentación

Licencia

Apache-2.0. Consulta LICENCIA.