venv-manager：为 AI 智能体提供 MCP 接口的 Python 虚拟环境工具

venv-manager 是一款用 Go 编写的 Python 虚拟环境（venv）管理工具，主打「一个静态二进制、零运行时依赖」的使用体验。它在传统 venv 命令行工具之上，专门为 AI 智能体暴露了 Model Context Protocol（MCP）服务器，让 Claude Desktop、Cursor、Zed 等 Agent 客户端能够通过结构化的 JSON-RPC 工具调用来创建、查询、运行临时 Python 环境，而不是依赖 shell 命令拼接。

解决的两类痛点

工具作者归纳出两类常见问题：

人类开发者：venv 散落在不同目录占满磁盘，跨 shell 的激活语法不一致，clone 一个能跑的 env 只能在终端之间反复 pip freeze。
AI 智能体：LLM 生成 Python 代码时经常 pip install 到错误的解释器、忘记设置 VIRTUAL_ENV、崩溃后留下半安装包，并且没有类型化 API，只能通过 shell 猜测环境状态。

venv-manager 用统一的 CLI 解决前者，用 MCP 服务器 + 类型化 JSON 快照 + 临时 venv + 文件监听来解决后者。

MCP 服务器集成

这是工具与 AI 生态最相关的部分。venv-manager 通过 stdio 上的 JSON-RPC 2.0 暴露了一组类型化工具，约 350 行代码、零第三方 MCP 依赖。主要工具包括：

list_venvs：列出所有受管 venv 名称。
create_venv / remove_venv：创建与递归删除 venv，配置 use_uv: true 时优先走 uv。
describe_venv：返回完整 JSON 快照——Python 版本、包列表、大小、pip freeze 的 sha256 哈希、各 shell 的激活命令。
install_packages / run_in_venv：在指定 venv 中安装包或执行命令，自动设置 VIRTUAL_ENV 并前置 PATH。
exec_ephemeral：一次性「创建 → 安装 → 运行 → 销毁」临时 venv，配合 --sandbox 可启用 OS 级沙箱。
snapshot_venv / rollback_venv：基于 pip freeze 快照回滚。
scan_imports：扫描脚本的第三方 import，识别 cv2 → opencv-python、sklearn → scikit-learn、PIL → Pillow 等 import-name 与 pip-name 的别名映射。
doctor：检查 PATH 上的 Python 版本、uv 可用性、损坏的 venv。

在 Claude Desktop 里只需在 claude_desktop_config.json 里加一段 mcpServers 配置即可接入。describe_venv 返回的 freeze_hash 让 Agent 用 O(1) 比较就能判断两个环境是否一致，避免逐包 diff。

临时执行与文件监听

exec 子命令支持 uvx 风格的临时运行模式，可选 --sandbox 启用沙箱：

macOS 使用 sandbox-exec，Linux 使用 bwrap，默认拒绝所有路径，仅放行 venv 路径、/tmp 与进程管理；网络走 unshare 隔离。

watch app.py --venv X 子命令基于 fsnotify 监听父目录（500 ms 防抖，能扛住编辑器的原子重命名），对 .py 文件做轻量 AST 风格扫描，跳过 docstring、相对导入以及 .venv、.git、__pycache__、node_modules 等目录，过滤标准库后把「缺失包」自动 pip install。venv 始终是当前脚本需求的超集，正好对应 LLM 迭代修改脚本的场景。

安装与命令一览

安装方式：curl -sSL https://raw.githubusercontent.com/jacopobonomi/venv_manager/main/install.sh | bash，或从源码 make install。
需要 Go 1.21+ 构建，运行时依赖 Python 3.x。

除 MCP 工具外，CLI 还覆盖常见的 create、list、remove、rename、clone、packages、install、upgrade、clean、size、activate、deactivate、run、describe、scan 等子命令，多数支持 --json 输出，方便脚本与 Agent 解析。

小结

venv-manager 本质上是一个为 Agent 时代重新设计的 Python 环境管理器：用 Go 把 venv 操作集中到一个二进制里，再用 MCP 把这些操作暴露为带 JSON Schema 的类型化工具，使 LLM 能可靠、可回滚、可沙箱地管理 Python 环境。其价值更多在于工程整合与可用性，而非模型或算法层面的突破。