Edu DB Readonly MCP — 教育教务只读数据库网关

一个面向教育教务业务数据库的安全只读查询网关 MCP。用官方 FastMCP SDK 把"教务库（学生 / 课程 / 成绩 / 选课）"暴露成一组 MCP 工具， 让 LLM Agent 能安全查询业务数据，但从协议层到数据库层都禁止一切写操作。

与 ChatGPT 套壳、通用 MCP Server、纯 RAG demo 不同，本项目专注 **"把业务库安全地开放给 Agent 读"**这条工程链路，是数据安全 + MCP 落地的硬核案例。

---

核心卖点（面试可讲）

安全维度	实现方式
写防护	SQL 词法静态校验：仅允许 SELECT/WITH，拦截 INSERT/UPDATE/DELETE/DROP/PRAGMA；禁止分号多语句注入
只读兜底	SQLite 以 mode=ro 打开，即使 SQL 漏判，数据库层面也无法落盘
防爆库	未写 LIMIT 自动强制追加上限（默认 100 行），防止 Agent 全表拖库
防注入	网关层全部走参数绑定，业务工具用固定查询白名单函数，天然免疫拼接注入
超时保护	慢查询超过阈值（默认 3s）自动终止，避免聪明 Agent 卡死
鉴权	可选 READONLY_GATEWAY_TOKEN，token 不匹配直接拒绝
审计	每次查询落盘 audit.log（时间/工具/SQL/行数/耗时），调用可追溯

---

工具清单（MCP）

工具	说明
list_tables	列出全部业务表及行数
describe_table	返回指定表字段 / 类型 / 主键
query	原始只读 SQL 网关（安全校验 + LIMIT + 超时）
get_student_profile	学生画像（基本信息 + 平均分 + 选课成绩明细）
get_course_stats	课程人数 / 均分 / 最高最低 / 及格率
get_enrollment_summary	选课成绩汇总报表，可按年份 / 学季过滤

query 展示"原始 SQL 网关"能力，其余是面向教务的行业化安全封装函数 （固定参数化查询，比裸 SQL 更安全、更贴合业务）。

---

快速开始

# 1. 安装依赖
pip install -r requirements.txt

# 2. 初始化教务演示库
python scripts/init_db.py

# 3. 运行命令行演示（连 stdio MCP，展示 6 个工具 + 写操作被拦截）
python scripts/demo_client.py

# 4. 启动为 MCP Server（供 Claude / Cursor / 任意 MCP 客户端接入）
python -m src.server
# 开启鉴权：
#   READONLY_GATEWAY_TOKEN=your_secret python -m src.server

示例查询：学生画像、CS205 课程统计、按学季汇总……

---

测试

pytest tests/            # 22 个用例：写防护/注入/多语句/截断/工具行为/审计

---

目录结构

edu-db-readonly-mcp/
├── README.md
├── pyproject.toml
├── requirements.txt
├── data/edu.db                 # 生成的教务演示库（只读打开）
├── scripts/
│   ├── init_db.py              # 建表 + 造种子数据（10学生/10课/32选课）
│   └── demo_client.py          # 命令行 MCP 演示
├── src/
│   ├── server.py               # FastMCP 入口，注册 6 个工具
│   ├── gateway/
│   │   ├── readonly_gateway.py # 核心：SQL 只读校验 + LIMIT + 超时
│   │   ├── auth.py             # token 鉴权
│   │   └── audit.py            # 审计日志
│   ├── db/connection.py        # mode=ro 连接 + 元数据读取
│   └── tools/
│       ├── query_tool.py       # 原始 SQL 网关
│       ├── schema_tools.py     # list_tables / describe_table
│       └── edu_workflows.py    # 教务业务封装工具
└── tests/
    ├── test_gateway_security.py   # 安全用例
    └── test_tools.py              # 工具行为用例

设计文档 → docs/DESIGN.md

---

简历描述（可粘贴）

教育教务只读数据库网关 MCP（FastMCP） 独立开发一个面向教育教务库的安全只读 MCP Server。设计轻量 SQL 只读网关：仅放行 SELECT/WITH 的静态校验拦截 DML/DDL 与分号 多语句注入、未带 LIMIT 自动强制限行、参数化查询防注入、线程超时 保护、SQLite mode=ro 只读兜底；提供表自省与教务业务封装工具并 支持 Token 鉴权与 audit.log 审计。22 个单元测试覆盖写防护、注入、 多语句、截断等安全场景，端到端 demo 验证写操作被协议层拦截。