Pixeltable

Tornar a criação de aplicativos de IA multimodal extremamente simples

Documentação

Servidor MCP para Desenvolvedores Pixeltable

Um servidor local de Model Context Protocol para construir, inspecionar e operar aplicações Pixeltable. A versão 0.2 segue o fluxo de trabalho application-first em pixeltable-skill 2.8.3: gere um app.py, aplique seu schema e sirva suas rotas com a CLI pxt.

Compatibilidade

Componente	Linha suportada
Python	3.11 ou mais recente
Pixeltable	`>=0.7.6,<0.8` com o extra `serve`
MCP Python SDK	`>=2.2,<3`
Pixeltable skill	2.8.3
Transporte de produção	`stdio` local

O servidor é uma ferramenta de desenvolvedor em beta. Ele executa com as permissões do processo que o iniciou e pode modificar o catálogo Pixeltable selecionado. Aponte PIXELTABLE_MCP_PROJECT_ROOT para o diretório da aplicação e PIXELTABLE_HOME para o catálogo pretendido antes da inicialização. Ambos os locais são fixos durante a vida do processo. Use um catálogo separado para avaliação e testes automatizados.

Instalar e conectar

Instale uv e, em seguida, instale o 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 desenvolvimento reproduzível a partir de um clone:

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

Configure um cliente para iniciar o servidor via stdio. Substitua o repositório, o projeto da aplicação e os caminhos do catálogo por caminhos absolutos:

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

Reinicie o cliente após alterar sua configuração MCP. Mantenha um processo de servidor por catálogo ao realizar mutações de schema ou de serviço.

Interface padrão

A versão 0.2 expõe uma interface focada em vez de espelhar toda a API Python do Pixeltable.

Ferramentas

Área	Ferramentas
Inspecionar	`pixeltable_list_catalog`, `pixeltable_describe`, `pixeltable_rows`, `pixeltable_get_row`, `pixeltable_errors`
Dados	`pixeltable_insert_rows`, `pixeltable_recompute`
Estrutura do aplicativo	`pixeltable_scaffold_app`
Ciclo de vida do schema	`pixeltable_schema_check`, `pixeltable_schema_diff`, `pixeltable_schema_update`, `pixeltable_schema_prune`
Ciclo de vida do serviço	`pixeltable_service_check`, `pixeltable_service_diff`, `pixeltable_service_update`, `pixeltable_service_list`, `pixeltable_service_stop`, `pixeltable_service_prune`

As ferramentas de leitura declaram anotações MCP somente leitura. As ferramentas de mutação declaram seu comportamento de escrita e destrutivo. Argumentos e resultados usam schemas tipados, e falhas recuperáveis são retornadas como erros de ferramenta MCP para que os clientes possam tentar novamente com entrada corrigida.

Recursos

URI	Finalidade
`pixeltable://status`	Status do servidor, dependências, transporte, catálogo e modo inseguro
`pixeltable://catalog`	Inventário atual do catálogo
`pixeltable://guidance/app`	Fluxo de trabalho de aplicação Pixeltable 0.7.6
`pixeltable://guidance/cloud`	Orientação de preparação para Cloud; não implanta recursos

Prompts

pixeltable_build_app
pixeltable_build_rag
pixeltable_build_agent
pixeltable_debug_computation

Os prompts são guias curtos de tarefas alinhados com pixeltable-skill 2.8.3. A skill continua sendo a fonte detalhada para formatos de saída de provedores, visualizações multimodais, índices, chamada de ferramentas, serviço, depuração e fluxos de trabalho em Cloud.

Modo inseguro

A execução de código host, instalação de pacotes e exibição em navegador estão desabilitadas por padrão. Um usuário local confiável pode optar por ativá-las antes de iniciar o servidor:

export PIXELTABLE_MCP_ENABLE_UNSAFE=1

Isso adiciona:

pixeltable_unsafe_execute_python
pixeltable_unsafe_install_package
pixeltable_unsafe_display

Essas ferramentas estão disponíveis apenas em stdio. Elas podem executar Python arbitrário, alterar o ambiente do servidor, ler arquivos disponíveis para o processo do servidor e renderizar conteúdo não confiável. Ative-as apenas para um cliente MCP local confiável e um ambiente de desenvolvimento descartável. Não exponha o modo inseguro por meio de um transporte HTTP.

O repositório pode usar um harness em processo ou HTTP nos testes. HTTP não é um transporte de produção suportado para a versão 0.2. Uma futura versão HTTP deve adicionar autorização, limites de concorrência e de requisições, validação de origem e host, isolamento por principal e um modelo de ameaças explícito antes de ser suportada.

Fluxo de trabalho recomendado do Pixeltable

Inicie uma aplicação com a CLI atual do 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 é um diretório de catálogo. Não é um diretório do sistema de arquivos. Edite app.py e aplique o schema novamente quando o modelo mudar. Aplique o serviço novamente após alterações de rotas. Use pxt service list para descobrir a URL atribuída.

O arquivo da aplicação deve declarar classes TableModel e, quando rotas HTTP forem necessárias, um FastAPIRouter. Colunas armazenadas usam anotações. Colunas calculadas usam atribuições. Os tipos são não anuláveis por padrão; escreva T | None para uma coluna opcional. Não use pxt.Required.

Atualizações de schema exigem intencionalmente uma etapa de revisão. schema_check valida o arquivo, schema_diff pré-visualiza alterações no catálogo e schema_update aplica as alterações. Operações de poda são separadas porque podem remover objetos do catálogo. Alterar uma expressão de coluna calculada existente no lugar não é suportado pelo Pixeltable; renomeie a coluna, ou remova e adicione-a novamente em atualizações separadas.

Para Cloud, prepare o mesmo app.py, defina PIXELTABLE_API_KEY, configure o pxt://org:db de destino e revise pixeltable://guidance/cloud. O servidor MCP não cria recursos pagos nem implanta em Cloud automaticamente.

Desenvolver e verificar

Use um catálogo descartável:

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

Execute o MCP Inspector apenas como um harness de teste local:

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

Antes do lançamento, execute também o job de compatibilidade de dependências mais recentes, os testes de contrato em memória do MCP, o teste de fumaça stdio em subprocesso, lint, verificações de tipos e a verificação de build do pacote descritos no relatório de revisão.

Política de Privacidade

O servidor executa inteiramente na máquina que o inicia. Ele não coleta telemetria nem análises, e não envia nada para a Pixeltable ou para terceiros.

O que ele manipula. O catálogo Pixeltable em PIXELTABLE_HOME e os arquivos da aplicação em PIXELTABLE_MCP_PROJECT_ROOT, ambos escolhidos por você. Os resultados das ferramentas são retornados ao cliente MCP que iniciou o servidor, que é como seu assistente os lê. Nada mais os recebe.

Armazenamento e retenção. O servidor não armazena nada próprio. Os dados do catálogo permanecem em PIXELTABLE_HOME no seu disco, sob seu controle, e são removidos quando você os remove.

Segredos. A saída de comandos passa por um redator que mascara formas comuns de credenciais, incluindo senhas em URLs e tokens de API, antes de chegar ao cliente.

Terceiros. Se sua aplicação declarar colunas calculadas que chamam provedores de modelos, a Pixeltable fará essas chamadas com as credenciais que você configurou. Esse tráfego é da sua aplicação, não deste servidor.

Modo inseguro. Com PIXELTABLE_MCP_ENABLE_UNSAFE=1, as ferramentas adicionadas executam Python arbitrário, instalam pacotes e leem arquivos disponíveis para o processo do servidor. Ative-o apenas em uma máquina local confiável.

Contato. Relate questões de privacidade por meio de problemas no GitHub.

Documentação

Licença

Apache-2.0. Consulte LICENSE.