db_mcp_server: Instructions file for Codex

AGENTS.md — DB MCP Server

本文件是 AI 编码智能体迭代本仓库的入口指引。先读这里，再按引用深入具体文件。 面向「工具调用方」的规范见 .ide_mcp_rules.md / .cursor_mcp_rules.md，本文件面向「代码修改方」。

1. 项目是什么

企业级数据库访问代理（MCP Server）。客户端（AI IDE、HTTP 调用方）通过访问密钥 + 连接级授权访问 MySQL/PostgreSQL，不直接接触真实数据库凭证。凭证加密存放在独立的 PostgreSQL 管理库中。

核心能力：

• 标准 MCP 协议（SSE + JSON-RPC）+ 简化 HTTP API，同一 FastAPI 进程、同一端口
• 安全：SQL 风险拦截、连接级权限（只读/写/DDL）、IP 白名单、数据脱敏、审计日志
• 20 个 MCP 工具：元数据浏览、查询执行、文档/ER/数据流导出、SQL 审查、性能分析、Schema 对比、Mock 数据、报表上传 OSS 等
• 可选 LLM 增强（src/ai/）：SQL 审查、调优建议、ER 业务解读
• SvelteKit 管理后台（构建产物在 src/static/，与后端同源同端口）

2. 技术栈与运行

层	技术
后端	Python 3.13 · FastAPI · SQLAlchemy（Core 风格，Table+autoload）· Uvicorn
管理库	PostgreSQL（表结构由 src/admin/models.py: ensure_schema() 用 meta.create_all 管理，无迁移工具）
前端	SvelteKit 2 · Svelte 5（runes）· TypeScript · Tailwind 4 + DaisyUI · adapter-static
部署	Docker（python:3.13-slim，supervisord，非 root）· GitHub Actions 打 v* tag 推阿里云 ACR

常用命令：

# 后端（项目根目录，配置文件必需）
cp config/config.yml.example config/config.yml   # 改 master_key / admin_database
pip install -r requirements.txt
python src/init_admin_db.py                       # 初始化管理库（建表+默认admin/admin123）
uvicorn src.server:app --reload --host 0.0.0.0 --port 3000

# 前端（构建产物输出到 ../src/static/）
cd frontend && npm install && npm run build       # 改前端必须重新 build
cd frontend && npm run check                      # svelte-check 类型检查

# 验证（Makefile；Windows 下用 git-bash 跑 make，或直接跑下面的命令）
pytest test/                                      # Python 测试（目前仅占位+sql_guard）
flake8 src/ test/                                 # lint（仓库历史代码有既有告警，只保证不新增）
cd frontend && npm run check

# MCP 工具联调（需服务已启动且有有效密钥）
python script/mcp_call.py --tool list_connections

配置文件通过 CONFIG_PATH 环境变量可覆盖，默认 config/config.yml（相对项目根目录，src/config.py 用 dataclass 强校验加载）。

3. 目录结构（改动前先定位层）

src/
├── server.py            # FastAPI 应用工厂：静态挂载、/query、/sse/query、/metadata/*、/transaction/*、SPA 兜底
├── config.py            # YAML → dataclass 配置（新增配置项要改这里 + config.yml.example）
├── init_admin_db.py     # 管理库初始化脚本入口
├── logging_utils.py     # get_logger(name, log_dir)：滚动文件日志，日志时间走 timezone_util
├── timezone_util.py     # 时区序列化/日志时间
├── mcp/
│   ├── tools.py             # ★ 工具 schema 注册表 MCP_TOOLS（改工具定义改这里）
│   ├── server.py            # HTTP 协议路由 /mcp/tools、/mcp/call → _execute_tool 分发
│   ├── standard_protocol.py # ★ SSE 协议路由 /mcp/sse、/mcp/message → _execute_mcp_tool_inner 分发
│   └── permissions.py       # MCP 侧访问密钥/连接权限校验
├── security/            # sql_guard(权限分级) / sql_analyzer+interceptor(风险评分) /
│                        # ip_whitelist / data_masker / secret(Fernet加解密) / client_ip
├── tools/               # 20 个工具的业务实现，db_*_tool.py 命名；纯函数风格，接收 engine 参数
├── db/db_operations.py  # QueryProxy：engine 缓存池 + 事务管理（txn_map + 清理线程）
├── admin/
│   ├── web.py               # /admin/* 路由聚合入口（include 各子路由）
│   ├── context.py           # ★ AdminContext：engine/tbl/auth/日志器等共享依赖 + 测试连接 helpers
│   ├── schemas.py           # pydantic 请求模型
│   ├── routes/              # ★ 子路由按资源拆分：auth/users/keys/connections/permissions/
│   │                        #   whitelist/llm/logs/misc，各导出 build_router(ctx)
│   ├── models.py            # ensure_schema() 定义管理库全部表 + 默认数据初始化
│   ├── auth.py              # JWT + bcrypt 认证
│   └── schema_cache.py      # 管理库 Table 反射缓存（autoload_with 只反射一次）
├── ai/                  # llm_client(读库取激活配置) / service(llm_ask 统一入口) / context / llm_active
├── logging/             # audit_logger(写库) / llm_call_logger / system_logger
├── services/oss_sts_service.py  # STS 临时凭证上传
└── static/              # 前端 build 产物，勿手改

frontend/src/routes/     # (app)/ 下是受保护页面：connections/keys/audit/llm-logs/ai-settings/users；login/ 独立
frontend/src/lib/api.ts  # 同源 fetch 封装，Bearer token，401 自动跳登录
config/config.yml.example  # 配置模板，新增配置项必须同步更新
script/                # mcp_call.py(SSE测试) / redeploy.sh / release.sh / dockerbuild.ps1 / reset_admin_password.py
docs/                  # 面向使用者的中文文档
test/                  # pytest，测试基建很薄，新增逻辑请补测试
.github/workflows/     # build-deploy.yml：push v* tag → buildx → 阿里云 ACR