# Agent Data Bridge

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

- FastAPI HTTP API：用于手工/系统直接调用。
- MCP Server（SSE Transport）：把能力以 Tool 的形式暴露给支持 MCP 的客户端。

目前实际实现包含：

- 通过两步 OAuth2（token -> query）调用 Spring Boot 接口获取数据（见 [src/app/services/springboot_client.py](src/app/services/springboot_client.py)）。
- 将返回结果中的首个 Markdown 表格解析为 DataFrame；小数据直接返回表格，大数据保存为 parquet 到沙盒目录并返回摘要（见 [src/app/main.py](src/app/main.py)）。
- 提供一个简易 Python “沙盒执行”入口：在指定的沙盒目录中运行脚本，支持超时与输出长度截断（见 [src/app/services/sandbox.py](src/app/services/sandbox.py)）。

## 运行要求

- Python >= 3.12
- 推荐使用 uv 管理依赖（见 [pyproject.toml](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，推荐）：

```powershell
$env:PYTHONPATH = "src"
uv run -- python -m app.mcp_server
```

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

```powershell
pushd src
uv run -- python -m app.mcp_server
popd
```

- macOS/Linux：

```bash
PYTHONPATH=src uv run -- python -m app.mcp_server
```

## 配置（.env）

复制 [\.env.example](.env.example) 为 `.env` 后按需修改。

当前代码实际会用到的配置（与 [.env.example](.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](src/app/services/springboot_client.py)）。

## HTTP API

### 健康检查

- `GET /health`

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

### 拉取数据并返回摘要

- `POST /api/fetch`

请求体：

```json
{
  "host": "http://192.168.10.21:3000",
  "userid": "Admin",
  "sql": "select ...",
  "dataset": "demo"
}
```

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

- 解析返回结果中的 `data.markdown`（Markdown 表格）。
- `Rows <= 15`：直接返回完整 Markdown 表格。
- `Rows > 15`：保存为 parquet 到 `SANDBOX_DIR`，并返回字段预览 + 前 5 行。

响应：

```json
{ "message": "..." }
```

示例（curl）：

```bash
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

```json
{ "filename": "anything.py", "code": "print(123)" }
```

方式 B：multipart/form-data

- 上传字段名 `file`（.py 文件）
- 或者传 `code` / `filename`

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

```json
{
  "filename": "script_xxx.py",
  "exit_code": 0,
  "stdout": "...",
  "stderr": "..."
}
```

## MCP Tools

MCP Server 目前提供以下 tools（见 [src/app/mcp_server.py](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 读取：

```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，并把沙盒目录挂载到宿主机）：

```bash
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 时，请先设置：

```powershell
$env:PYTHONPATH = "src"
uv run -- python -m app.mcp_server
```