# MCP Server

为阿里云百炼 AI 应用提供 PostgreSQL 只读查询能力的 MCP 服务。

## 用途

小程序端调用百炼 AI 应用时，百炼通过 MCP 协议连接本服务，读取 `etl_feiqiu` 数据库中的运营数据（会员、订单、支付、助教业绩、财务汇总等）。

## 架构

```
微信小程序 → 百炼 AI 应用 → MCP (Streamable HTTP) → 本服务 → PostgreSQL (etl_feiqiu)
```

## 暴露的 Tools

| Tool | 说明 |
|------|------|
| `list_tables` | 列出指定 schema 下的表 |
| `describe_table` | 查看单表结构 |
| `describe_schemas` | 批量返回多个 schema 的表结构（含主键） |
| `query_sql` | 在指定 schema 内执行只读 SQL |

## 可访问的 Schema

`ods` / `dwd` / `dws` / `core` / `meta` / `app`（etl_feiqiu 六层架构）

## 安全策略

- 仅允许 SELECT/WITH/SHOW/EXPLAIN，禁止 DDL/DML
- 正则 + sqlparse 双重校验
- 跨 schema 引用白名单限制
- 可选 Bearer Token 鉴权（`MCP_TOKEN` 环境变量）
- 生产环境建议使用只读数据库账号

## 配置

环境变量优先级：`MCP_PG_*` > `DB_*` / `ETL_DB_NAME` / `PG_NAME`（分离式回退） > 项目根 `.env`

| 变量 | 说明 | 默认值 |
|------|------|--------|
| `MCP_PG_HOST` | 数据库主机（优先） | 回退 `DB_HOST` |
| `MCP_PG_PORT` | 数据库端口（优先） | 回退 `DB_PORT`，默认 5432 |
| `MCP_PG_DATABASE` | 数据库名（优先） | 回退 `ETL_DB_NAME` → `PG_NAME`（分离式配置） |
| `MCP_PG_USER` | 数据库用户（优先） | 回退 `DB_USER` |
| `MCP_PG_PASSWORD` | 数据库密码（优先） | 回退 `DB_PASSWORD` |
| `MCP_TOKEN` | 鉴权 token（空则不启用） | 空 |
| `MCP_MAX_ROWS` | query_sql 最大返回行数 | 500 |
| `PORT` | 服务监听端口 | 9000 |

## 启动

```bash
cd apps/mcp-server
python server.py
```

百炼端 MCP 服务地址配置为：`https://mcp.langlangzhuoqiu.cn/mcp`