Pixeltable Developer

Pixeltable Developer MCP Server

用于构建和运行 Pixeltable 应用的本地 MCP 服务。Agent 通过 pxt CLI 创建单个 app.py 脚手架，将其中的表应用到目录中，插入和检查行，恢复失败的计算，并提供 HTTP 路由服务。这是一款 beta 开发工具：它会使用你的权限，并修改你指定的目录。

快速开始

安装 uv。该服务已发布到 PyPI，uvx 会下载并运行它。

Claude Code：

claude mcp add pixeltable -e PIXELTABLE_MCP_PROJECT_ROOT=/absolute/path/to/app -e PIXELTABLE_HOME=/absolute/path/to/.pixeltable -- uvx mcp-server-pixeltable-developer

其他客户端（Claude Desktop、Cursor、VS Code 等）：

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

应用目录必须存在。空目录也可以：服务可以在其中创建 app.py 脚手架。更改配置后，请重启客户端。

变量	必需	作用
PIXELTABLE_MCP_PROJECT_ROOT	是	存放 app.py 的目录。拒绝处理此目录之外的文件参数。
PIXELTABLE_HOME	是	服务读取和修改的目录。~/.pixeltable 是 pxt CLI 使用的目录；测试时请使用单独的目录。
PXT_PORT	否	服务 pxt 守护进程的端口，默认值为 22089。一个守护进程在每个端口上为一个项目提供服务；来自另一个项目的 pxt 命令会重启该进程，因此正在进行的调用会因 RemoteDisconnected 失败。如果你同时为另一个项目运行 pxt，请设置一个空闲端口，例如 22090。
PIXELTABLE_MCP_ENABLE_UNSAFE	否	1 会添加可运行任意 Python 代码和安装软件包的工具。请参阅不安全模式。
PIXELTABLE_MCP_PXT	否	指定一个 pxt 可执行文件。默认情况下，服务会使用与其一同安装的版本。

这两个路径在进程运行期间固定不变。应用架构或服务变更时，每个目录请运行一个服务。

其他运行方式

渠道	说明
官方 MCP Registry	io.github.pixeltable/mcp-server-pixeltable-developer。浏览该注册表的客户端会安装 PyPI 软件包。
Claude 插件	使用已打开的项目作为应用目录，~/.pixeltable 作为默认目录，端口为 22090。
Glama	包含质量评分的目录列表。
Docker	使用此仓库构建的镜像。请参阅下文。
克隆仓库	"command": "uv"、"args": ["run", "--directory", "/absolute/path/to/clone", "mcp-server-pixeltable-developer"]

Docker：挂载应用目录，并将目录存储在命名卷中以确保数据持久化。不要从 macOS 主机绑定挂载目录：Postgres 无法设置该目录的权限，因此 initdb 会失败。在 macOS 上，应用路径也必须与容器引擎共享，否则挂载会落在其虚拟机内。

docker build -t mcp-server-pixeltable-developer .
docker run --rm -i \
  -e PIXELTABLE_MCP_PROJECT_ROOT=/work/app -e PIXELTABLE_HOME=/work/catalog \
  -v /absolute/path/to/app:/work/app \
  -v pixeltable-catalog:/work/catalog \
  mcp-server-pixeltable-developer

服务端提供的内容

范围	工具
检查	pixeltable_list_catalog、pixeltable_describe、pixeltable_rows、pixeltable_get_row、pixeltable_errors
数据	pixeltable_insert_rows、pixeltable_recompute
应用脚手架	pixeltable_scaffold_app
架构生命周期	pixeltable_schema_check、pixeltable_schema_diff、pixeltable_schema_update、pixeltable_schema_prune
服务生命周期	pixeltable_service_check、pixeltable_service_diff、pixeltable_service_update、pixeltable_service_list、pixeltable_service_stop、pixeltable_service_prune

读取工具带有只读注释；变更工具会声明写入和破坏性行为。清理工具默认执行试运行。失败会作为 MCP 工具错误返回，因此客户端可以修正输入后重试。

资源	内容
pixeltable://status	服务端、Pixeltable 和 MCP 版本、传输方式及不安全模式状态
pixeltable://catalog	目录清单
pixeltable://guidance/app	下方的应用工作流
pixeltable://guidance/cloud	云端准备步骤；服务端不会部署任何内容

提示词：pixeltable_build_app、pixeltable_build_rag、pixeltable_build_agent 和 pixeltable_debug_computation。它们遵循 pixeltable-skill 2.12.0，该文档仍是提供商、多模态视图、索引、工具调用和服务的详细参考。

Pixeltable 工作流

这些是工具封装的命令：

pip install 'pixeltable[serve]>=0.7.10,<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 update app.py my_app
pxt service list

• my_app 是一个目录条目，而不是磁盘上的文件夹。pxt service list 会显示分配的 URL。
• 在 app.py 中，存储列使用注释声明，计算列使用赋值声明。 类型不可为空；可选列请写成 T | None。不要使用 pxt.Required。
• 若要更改计算表达式，请编辑表达式并更新架构。更新会保留现有值，因此请运行 pxt recompute my_app/docs COLUMN -f 以刷新这些值。无法原地更改类型；请改为重命名计算列。
• 云端使用相同的 app.py：运行 pxt login，在 pixeltable.toml 中添加 [[pixeltable.database]] 条目，并通过 pxt secret set 设置提供商密钥，切勿将密钥写入 TOML。 pixeltable://guidance/cloud 列出了操作顺序。服务端不会创建付费资源。

不安全模式

PIXELTABLE_MCP_ENABLE_UNSAFE=1 会添加 pixeltable_unsafe_execute_python、 pixeltable_unsafe_install_package 和 pixeltable_unsafe_display。这些工具可运行任意 Python、更改服务端环境、读取进程可访问的任何文件，并在浏览器画布中渲染 不可信内容。它们仅通过 stdio 提供：请仅在一次性环境中为可信的本地客户端启用。HTTP 不是受支持的传输方式。

兼容性

组件	支持情况
Python	3.11 或更高版本；CI 测试 3.11 至 3.14
Pixeltable	>=0.7.10,<0.8，带有 serve extra，锁定为 0.7.16
MCP Python SDK	>=2.2,<3，锁定为 2.3.0
传输方式	本地 stdio

发布

CHANGELOG.md 列出了各个版本的变更。0.2.1 是首次发布到 PyPI 的版本。

发布新版本：

1. 在 pyproject.toml、src/mcp_server_pixeltable_developer/__init__.py、 server.json（两处）、mcpb/manifest.json 以及 .github/workflows/ci.yml 和测试中的断言里更新版本号。 在 CHANGELOG.md 中添加 ## X.Y.Z 小节，并运行 uv lock。在所有版本号都一致之前， 测试会失败。
2. 合并后，推送标签 vX.Y.Z。CI 会重新运行所有检查，使用 可信发布功能发布到 PyPI，根据变更日志小节创建 GitHub Release，然后 通过 GitHub OIDC 将 server.json 发布到 MCP Registry。
3. 如果注册表步骤失败，无需创建新标签即可重新运行： gh workflow run mcp-registry.yml --repo pixeltable/mcp-server-pixeltable-developer --ref main。
4. PyPI 发布完成后，在单独的 PR 中更新插件：设置 plugin/.claude-plugin/plugin.json 中的版本号，以及 plugin/pyproject.toml 中的版本号和固定版本，然后运行 cp uv.lock plugin/uv.lock && uv lock --project plugin。先复制根目录的锁定文件，可确保依赖版本与经过测试的发布版本一致。 如果 plugin/uv.lock 达到 256 KiB（Claude 目录可读取的最大值），测试会失败。

Glama 会从 GitHub 同步。Docker MCP Catalog 条目（docker/mcp-registry 中的 servers/pixeltable/server.yaml） 固定了一个提交，因此每次发布都需要提交一个 PR。

开发和验证

uv sync --frozen --extra test --extra canvas
uv run pytest -q
PIXELTABLE_DISABLE_STDOUT=1 uv run pytest -q --run-slow
uv run ruff check . && uv run ruff format --check . && uv run pyright
./scripts/run-conformance.sh
./scripts/build-mcpb.sh

--run-slow 会在临时目录中运行真实目录和服务，每个服务都使用独立的守护进程端口。build-mcpb.sh 会将 Claude Desktop 安装包写入 dist/。如需手动测试，请针对服务运行 MCP Inspector： uv run mcp dev src/mcp_server_pixeltable_developer/server.py:mcp。

隐私政策

服务完全在启动它的机器上运行。它不会收集遥测数据或分析数据，也不会向 Pixeltable 或任何第三方发送任何信息。

处理的数据。 PIXELTABLE_HOME 中的 Pixeltable 目录，以及 PIXELTABLE_MCP_PROJECT_ROOT 下的应用文件，均由你选择。工具结果会返回给启动该服务的 MCP 客户端，助手正是通过客户端读取这些结果。不会向其他任何对象发送这些结果。

存储和保留。 服务不会存储自身数据。目录数据保留在你磁盘上的 PIXELTABLE_HOME 中，由你控制；删除目录时，数据也会一并删除。

机密信息。 命令输出会经过脱敏处理，在传递给客户端之前屏蔽常见凭据格式，包括 URL 密码和 API 令牌。

第三方。 如果你的应用声明了会调用模型提供商的计算列，Pixeltable 会使用你配置的凭据发起这些调用。这些流量属于你的应用，而非本服务。

不安全模式。 设置 PIXELTABLE_MCP_ENABLE_UNSAFE=1 后，新增工具可以执行任意 Python、安装软件包并读取服务进程可访问的文件。仅在可信的本地机器上启用此模式。

联系。 请通过 GitHub issues 提交隐私相关问题。

文档

• 变更日志
• 从 0.1 迁移到 0.2
• 0.2.0 实施审查和 0.1.0 证据审查
• Agent 评估协议
• Pixeltable 文档和 LLM 参考
• MCP Python SDK 2 文档

许可证

Apache-2.0。请参阅 LICENSE。