Agent Data Bridge

一个面向 Agent 的“数据桥接 + 轻量沙盒执行”服务，提供两种对外形态：

• FastAPI HTTP API：用于手工/系统直接调用。

• MCP Server（SSE Transport）：把能力以 Tool 的形式暴露给支持 MCP 的客户端。

目前实际实现包含：

• 通过两步 OAuth2（token -> query）调用 Spring Boot 接口获取数据（见 src/app/services/springboot_client.py）。

• 将返回结果中的首个 Markdown 表格解析为 DataFrame；小数据直接返回表格，大数据保存为 parquet 到沙盒目录并返回摘要（见 src/app/main.py）。

• 提供一个简易 Python “沙盒执行”入口：在指定的沙盒目录中运行脚本，支持超时与输出长度截断（见 src/app/services/sandbox.py）。

运行要求

• Python >= 3.12

• 推荐使用 uv 管理依赖（见 pyproject.toml）

快速开始

1. 安装依赖

• uv sync

1. 启动 HTTP API（FastAPI）

• uv run -- uvicorn app.main:app --reload --app-dir src

默认监听 http://127.0.0.1:8000。

如果希望“一条命令同时启动 REST + MCP”，可使用：

• uv run -- python -m app.run_all

1.（可选）启动 MCP Server（SSE）

本项目的 MCP Server 默认监听 0.0.0.0:9000（可通过 MCP_HOST/MCP_PORT 修改），并使用 SSE 传输：

• SSE 端点：GET /sse

• 消息端点：POST /messages/

启动命令：

• Windows（PowerShell，推荐）：

• 或者切换到 src 目录运行（一次性）：

• macOS/Linux：

配置（.env）

复制 .env.example 为 .env 后按需修改。

当前代码实际会用到的配置（与 .env.example 保持一致）：

• REST_HOST / REST_PORT：REST(FastAPI) 监听地址（用于 Docker 启动与一键启动脚本）。

• MCP_HOST / MCP_PORT：MCP(SSE) 监听地址。

• APP_ID / APP_SECRET：Spring Boot OAuth2 client credentials（默认 agent/agent）。

说明：

• SPRING_BOOT_BASE_URL / SPRING_BOOT_API_PATH 目前在代码中未被使用；/api/fetch 与 MCP 的 fetch_data 都会直接使用传入的 host 参数作为目标地址（见 src/app/services/springboot_client.py）。

HTTP API

健康检查

• GET /health

返回：{"status":"ok"}

拉取数据并返回摘要

• POST /api/fetch

请求体：

行为（与实现一致，见 src/app/main.py）：

• 解析返回结果中的 data.markdown（Markdown 表格）。

• Rows <= 15：直接返回完整 Markdown 表格。

• Rows > 15：保存为 parquet 到 SANDBOX_DIR，并返回字段预览 + 前 5 行。

响应：

示例（curl）：

运行沙盒脚本

• POST /api/sandbox/run

方式 A：JSON

方式 B：multipart/form-data

• 上传字段名 file（.py 文件）

• 或者传 code / filename

返回（与实现一致，见 src/app/services/sandbox.py）：

MCP Tools

MCP Server 目前提供以下 tools（见 src/app/mcp_server.py）：

• fetch_data(host, userid, sql, dataset) -> str

• sandbox_run(code, filename=None) -> dict

• sandbox_list_files() -> str

常见用法：先 fetch_data 生成 parquet 文件名，再用 sandbox_run 执行 Python 读取：

目录说明

• sandbox_storage/：默认沙盒数据目录（可通过 SANDBOX_DIR 覆盖）。

• sandbox_storage/_scripts/：沙盒执行时写入的临时脚本目录（自动创建）。

安全与限制

• 沙盒执行不是强隔离：只是把工作目录固定到 SANDBOX_DIR，并加了超时与输出截断；请勿在不可信输入场景直接暴露到公网。

• Spring Boot 的 client_id/client_secret 已改为从 .env 读取（APP_ID/APP_SECRET，默认 agent/agent）。

Docker

同时启动 REST + MCP（推荐使用 compose，并把沙盒目录挂载到宿主机）：

端口：

• REST: http://127.0.0.1:${REST_PORT:-8000}

• MCP(SSE): http://127.0.0.1:${MCP_PORT:-9000}/sse

数据卷：

• ./sandbox_storage -> /app/sandbox_storage

常见问题

Windows 下 ModuleNotFoundError: No module named 'app'

使用 PowerShell 运行 MCP Server 时，请先设置：