README zh

# VirtualPC MCP Server (孵化中) *基于 Debian 的统一 MCP 工具运行时环境，具有会话级环境隔离、环境状态持久化、实时 UI 可视化、分布式架构和可扩展性* [![License: MIT][license-image]][license-url]

[English](./README.md) | [快速开始](#快速开始) | [开发](#开发) | [贡献](#贡献)

1. 概述¶

VirtualPC MCP Server 是一个综合性的 MCP（模型上下文协议）工具运行时环境，旨在为 AI 代理提供统一、隔离和可扩展的执行环境。基于 Debian 构建，它提供会话级环境隔离、跨多个会话的持久状态管理以及实时可视化功能。

1.1 特性¶

会话级环境隔离：每个 MCP 会话在其独立的隔离环境中运行
多会话状态持久化：在多个 MCP 会话之间维护环境状态
实时 UI 可视化：Agent MCP 操作的实时监控和可视化
分布式架构：支持本地 Docker 和 Kubernetes 集群部署
可扩展运行时：模块化设计，支持无缝集成新的 MCP 工具服务器

2. 快速开始¶

本项目支持本地 Docker 部署（适用于演示和调试）和 Kubernetes 集群部署（推荐用于生产和强化学习训练）。

2.1 本地 Docker 部署¶

前置要求¶

确保 Docker 和 Docker Compose 已正确安装并正常运行：

# 验证 Docker 安装
docker --version
docker compose --version

# 验证 Docker 守护进程是否运行
docker ps
docker compose ps

步骤 1：配置环境并准备 Gaia 数据集

复制环境模板并配置您的设置：

cp ./gaia-mcp-server/mcp_servers/.env_template ./gaia-mcp-server/mcp_servers/.env

编辑 ./gaia-mcp-server/mcp_servers/.env 文件，填入您的具体配置值。

从 Hugging Face 下载 gaia_dataset 并放置到 ./gaia-mcp-server/docker/gaia_dataset

步骤 2：启动 VirtualPC MCP Server

sh run-docker.sh

监控终端输出，查看启动过程中是否有任何错误。

生成本地 Bearer token，并将打印出的值复制到下面的 <local-debug-jwt>。如果你修改了 virtualpc-mcp/docker-compose.yaml 中的 MCP_GATEWAY_TOKEN_SECRET，请在运行此命令前导出相同的值。

python - <<'PY'
import base64, hashlib, hmac, json, os, time

def part(value):
    raw = json.dumps(value, separators=(",", ":")).encode()
    return base64.urlsafe_b64encode(raw).rstrip(b"=").decode()

signing_input = ".".join([
    part({"alg": "HS256", "typ": "JWT"}),
    part({"app": "local_debug", "version": 1, "time": time.time()}),
])
secret = os.getenv("MCP_GATEWAY_TOKEN_SECRET", "123321").encode()
signature = hmac.new(secret, signing_input.encode(), hashlib.sha256).digest()
print(f"{signing_input}.{base64.urlsafe_b64encode(signature).rstrip(b'=').decode()}")
PY

步骤 3：连接到 VirtualPC MCP Server

使用以下配置连接到 VirtualPC MCP Server：

{
    "virtualpc-mcp-server": {
        "type": "streamable-http",
        "url": "http://localhost:8000/mcp",
        "headers": {
            "Authorization": "Bearer <local-debug-jwt>",
            "MCP_SERVERS": "readweb-server,browser-server"
        },
        "timeout": 6000,
        "sse_read_timeout": 6000,
        "client_session_timeout_seconds": 6000
    }
}

注意：上述 Bearer token 仅用于本地测试。MCP_SERVERS 头部指定了当前连接的 MCP 服务器范围，应该是 gaia-mcp-server/mcp_servers/mcp_config.py 中定义的服务器名称的子集。

2.2 Kubernetes 集群部署¶

对于生产部署和强化学习训练场景，推荐使用 Kubernetes 集群部署。详细说明将在后续更新中提供。

3. 开发¶

3.1 向 VirtualPC MCP Server 添加自定义 MCP 工具¶

步骤 1：开发 MCP 工具（可选）

如果您需要开发自定义 MCP 工具并将其注册到 VirtualPC MCP Server，请在 gaia-mcp-server/mcp_servers 下创建您的 MCP 工具项目目录并实现 MCP 工具代码。参考 hello_world 目录的项目结构。

项目规范：

使用 pyproject.toml 管理项目依赖，用于 Docker 镜像构建

步骤 2：注册 MCP 工具

将您开发的 MCP 工具或第三方 MCP 工具注册到 VirtualPC MCP Server。

编辑 MCP 工具注册文件：

"STDIO_SERVER_DEMO": {
    "type": "stdio",
    "command": "python",
    "args": ["-m", "hello_world.main"],
    "cwd": "hello_world",
},
"{SSE/STREAMABLE-HTTP_SERVER_NAME}": {
    "type": "sse/streamable-http",
    "url": "{URL for sse/streamable-http mcp server}",
    "headers": {
        "Authorization": f"Bearer {token}"
    }
},

步骤 3：更新 MCP 工具模式

重要：VirtualPC MCP Server 使用预生成的工具模式数据用于 list_tools() 函数，因此您必须在修改 MCP 服务器配置后更新 mcp_tool_schema.json。

我们提供了一个 Python 脚本 build_mcp_tool_schema.py 来更新 mcp_tool_schema.json。在执行此脚本之前，请确保 MCP 服务器 .env 文件已正确配置。

cd ./gaia-mcp-server/mcp_servers/
pip install mcp
python build_mcp_tool_schema.py

步骤 4：构建 Docker 镜像并部署服务

完成上述步骤后，构建 Docker 镜像并部署服务。

4. 贡献¶

我们欢迎社区的贡献！请参考我们的贡献指南：

代码风格和标准
拉取请求流程
问题报告
开发设置说明

5. 参考资料¶

致谢¶

Magentic-UI 项目：我们已整合来自 magentic-ui 项目的 Docker Browser 源代码。特别感谢 magentic-ui 项目团队的出色工作。