Lybic Docs
GUI 智能体

MCP 服务器参考

Agentic lybic MCP 服务器概述

本文档介绍了用于 GUI 智能体自动化的 MCP（模型上下文协议） 服务器。

MCP 服务器基于 Lybic 沙箱基础设施，为 GUI 自动化提供了标准化接口。它暴露了三个主要工具：

  1. create_sandbox - 创建新的沙箱环境
  2. get_sandbox_screenshot - 获取沙箱截图
  3. execute_instruction - 执行自然语言指令并实时流式返回

安装

MCP 服务器包含在 gui-agents 包中。安装并启用 MCP 支持：

pip install lybic-guiagents[mcp]

或源码安装：

git clone https://github.com/lybic/agent
cd agent
pip install -e .[mcp]

配置

环境变量

在 gui_agents/ 目录下创建 .env 文件，或设置如下环境变量：

# Lybic 云配置（必填）
LYBIC_API_KEY=你的_lybic_api_key
LYBIC_ORG_ID=你的_lybic_org_id
LYBIC_API_ENDPOINT=https://api.lybic.cn/  # 可选，默认为此值

# LLM 提供商配置（可选，也可每次请求单独传递）
OPENAI_API_KEY=你的_openai_key
ANTHROPIC_API_KEY=你的_anthropic_key
GOOGLE_API_KEY=你的_google_key

# 服务器配置（可选）
MCP_PORT=8000  # 默认端口
MCP_HOST=0.0.0.0  # 默认主机
LOG_LEVEL=INFO  # 日志级别

访问令牌

在 gui_agents/ 目录下创建 access_tokens.txt 文件，每行一个有效 Bearer 令牌：

token_abc123xyz
another_token_456
# 以 # 开头的行会被视为注释

使用方式

启动服务器

# 使用入口命令
lybic-guiagent-mcp

# 或直接用 Python 启动
python -m gui_agents.mcp_app

# 自定义端口
MCP_PORT=8080 lybic-guiagent-mcp

服务器默认启动在 http://0.0.0.0:8000。

API 接口

  • POST /mcp - MCP 流式 HTTP 接口（需 Bearer 令牌认证）
  • GET /health - 健康检查接口
  • GET / - 服务器信息及可用工具

认证

所有 MCP 接口请求都需 Bearer 令牌认证：

curl -H "Authorization: Bearer your_token" http://localhost:8000/health

MCP 工具

1. create_sandbox

创建新的 GUI 自动化沙箱环境。

参数：

  • apikey（字符串，可选）- Lybic API 密钥（未提供时用 LYBIC_API_KEY 环境变量）
  • orgid（字符串，可选）- Lybic 组织 ID（未提供时用 LYBIC_ORG_ID 环境变量）
  • shape（字符串，可选）- 沙箱配置，默认："beijing-2c-4g-cpu"

返回：

  • 沙箱 ID 及元数据

示例：

{
  "tool": "create_sandbox",
  "arguments": {
    "shape": "beijing-2c-4g-cpu"
  }
}

2. get_sandbox_screenshot

获取指定沙箱的截图。

参数：

  • sandbox_id（字符串，必填）- create_sandbox 返回的沙箱 ID
  • apikey（字符串，可选）- Lybic API 密钥
  • orgid（字符串，可选）- Lybic 组织 ID

返回：

  • 截图文件路径及尺寸

示例：

{
  "tool": "get_sandbox_screenshot",
  "arguments": {
    "sandbox_id": "SBX-01234567890"
  }
}

3. execute_instruction

在沙箱中执行自然语言指令，并实时流式返回执行过程。

参数：

  • instruction（字符串，必填）- 自然语言任务描述
  • sandbox_id（字符串，可选）- 使用已有沙箱或新建
  • apikey（字符串，可选）- Lybic API 密钥
  • orgid（字符串，可选）- Lybic 组织 ID
  • mode（字符串，可选）- Agent 模式："normal" 或 "fast"（默认："fast"）
  • max_steps（整数，可选）- 最大执行步数（默认：50）
  • llm_provider（字符串，可选）- LLM 提供商（如 "openai", "anthropic"）
  • llm_model（字符串，可选）- LLM 模型名（如 "gpt-4", "claude-3-sonnet"）
  • llm_api_key（字符串，可选）- LLM 提供商 API 密钥
  • llm_endpoint（字符串，可选）- 自定义 LLM 接口 URL

返回：

  • 执行结果及统计信息（步数、token数、费用、耗时等）

示例：

{
  "tool": "execute_instruction",
  "arguments": {
    "instruction": "打开计算器并计算 123 + 456",
    "mode": "fast",
    "max_steps": 50,
    "llm_provider": "openai",
    "llm_model": "gpt-4"
  }
}

客户端使用示例

使用 MCP SDK

import asyncio
from mcp.client.streamable_http import streamablehttp_client
from mcp import ClientSession
import os

LYBIC_MCP_SERVER_API_KEY = os.environ.get("LYBIC_MCP_SERVER_API_KEY", "default_token_for_testing")
async def main():
    # 连接到流式 HTTP 服务器
    async with streamablehttp_client('http://localhost:8000/mcp', headers={"Authorization": f"Bearer {LYBIC_MCP_SERVER_API_KEY}"}) as (
        read_stream,
        write_stream,
        _,
    ):
        # 用客户端流创建会话
        async with ClientSession(read_stream, write_stream) as session:
            # 初始化连接
            print("正在初始化连接")
            await session.initialize()
            print(await session.list_tools())
            # 调用工具
            print("调用工具")
            tool_result = await session.call_tool("execute_instruction", {"sandbox_id":"BOX-01KADMDC6TAE8NAJX82HMHSAQT","instruction":"打开浏览器"})
            print(tool_result)

if __name__ == "__main__":
    asyncio.run(main())

直接使用 HTTP

import httpx

BASE_URL = "http://localhost:8000"
TOKEN = "your_bearer_token"

headers = {
    "Authorization": f"Bearer {TOKEN}",
    "Content-Type": "application/json"
}

# 健康检查
response = httpx.get(f"{BASE_URL}/health", headers=headers)
print(response.json())

# MCP 通信需支持流式响应的客户端

智能体模式

Fast模式（推荐）

  • 直接生成动作，执行更快
  • token 消耗更低
  • 适合简单任务
  • 示例："mode": "fast"

Normal模式

  • 完整推理流程，支持分层规划
  • 支持 DAG 建模和记忆系统
  • 适合复杂多步任务
  • 示例："mode": "normal"

LLM 配置

每次请求可自定义 LLM 提供商：

{
  "tool": "execute_instruction",
  "arguments": {
    "instruction": "你的任务",
    "llm_provider": "anthropic",
    "llm_model": "claude-3-sonnet-20240229",
    "llm_api_key": "你的_anthropic_key"
  }
}

支持的提供商：

  • openai - GPT-4、GPT-3.5 等
  • anthropic - Claude 系列
  • google - Gemini 系列
  • doubao - 豆包系列
  • 以及你 tools_config 中配置的其它模型

安全性

  1. Bearer 令牌认证：所有请求需 access_tokens.txt 中的有效 Bearer 令牌
  2. 环境隔离：每个任务在独立沙箱环境中运行
  3. API 密钥管理：API 密钥可按请求传递或通过环境变量配置

故障排查

连接问题

# 检查服务器是否运行
curl http://localhost:8000/health

# 检查认证
curl -H "Authorization: Bearer your_token" http://localhost:8000/health

缺少依赖

# 安装全部依赖
pip install -e ".[mcp]"

# 或单独安装相关包
pip install mcp fastapi uvicorn

环境变量

验证 .env 文件是否正确加载：

python -c "import os; from dotenv import load_dotenv; load_dotenv(); print(os.getenv('LYBIC_API_KEY'))"

开发

以开发模式运行

# 自动重载
uvicorn gui_agents.mcp_app:app --reload --port 8000

# 调试日志
LOG_LEVEL=DEBUG lybic-guiagent-mcp

新增工具

编辑 gui_agents/mcp_app.py：

  1. 在 @mcp_server.list_tools() 中添加工具定义
  2. 实现处理函数
  3. 在 @mcp_server.call_tool() 注册

性能建议

  • 沙箱创建：新建沙箱约需 30-60 秒
  • 复用沙箱：传递 sandbox_id 可复用已有沙箱
  • 快速模式：推荐用 fast 模式，性能提升 50-70%
  • 并发任务：可用不同沙箱并发运行多个任务

监控

服务器通过 /health 接口提供指标：

{
  "status": "healthy",
  "server": "gui-agent-mcp-server",
  "active_sandboxes": 2,
  "active_tasks": 1
}

相关文档

gRPC 和服务部署

上一页

Restful API 服务器参考

下一页

本页内容

Agentic lybic MCP 服务器概述安装配置环境变量访问令牌使用方式启动服务器API 接口认证MCP 工具1. create_sandbox2. get_sandbox_screenshot3. execute_instruction客户端使用示例使用 MCP SDK直接使用 HTTP智能体模式Fast模式（推荐）Normal模式LLM 配置安全性故障排查连接问题缺少依赖环境变量开发以开发模式运行新增工具性能建议监控相关文档