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）
快速开始
- 安装依赖
uv sync
- 启动 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，推荐）：
$env:PYTHONPATH = "src"
uv run -- python -m app.mcp_server
- 或者切换到
src目录运行（一次性）：
pushd src
uv run -- python -m app.mcp_server
popd
- macOS/Linux：
PYTHONPATH=src uv run -- python -m app.mcp_server
配置（.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
请求体：
{
"host": "http://192.168.10.21:3000",
"userid": "Admin",
"sql": "select ...",
"dataset": "demo"
}
行为（与实现一致，见 src/app/main.py）：
- 解析返回结果中的
data.markdown（Markdown 表格）。 Rows <= 15：直接返回完整 Markdown 表格。Rows > 15：保存为 parquet 到SANDBOX_DIR，并返回字段预览 + 前 5 行。
响应：
{ "message": "..." }
示例（curl）：
curl -X POST http://127.0.0.1:8000/api/fetch \
-H "Content-Type: application/json" \
-d '{"host":"http://192.168.10.21:3000","userid":"Admin","sql":"select 1","dataset":"demo"}'
运行沙盒脚本
POST /api/sandbox/run
方式 A：JSON
{ "filename": "anything.py", "code": "print(123)" }
方式 B：multipart/form-data
- 上传字段名
file（.py 文件） - 或者传
code/filename
返回（与实现一致，见 src/app/services/sandbox.py）：
{
"filename": "script_xxx.py",
"exit_code": 0,
"stdout": "...",
"stderr": "..."
}
MCP Tools
MCP Server 目前提供以下 tools（见 src/app/mcp_server.py）：
fetch_data(host, userid, sql, dataset) -> strsandbox_run(code, filename=None) -> dictsandbox_list_files() -> str
常见用法：先 fetch_data 生成 parquet 文件名，再用 sandbox_run 执行 Python 读取：
import pandas as pd
df = pd.read_parquet("<file_name>")
print(df.head())
目录说明
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，并把沙盒目录挂载到宿主机）：
docker compose up --build
端口：
- 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 时，请先设置：
$env:PYTHONPATH = "src"
uv run -- python -m app.mcp_server