Edu DB Readonly MCP — Education Administration Read-Only Database Gateway

A secure read-only query gateway MCP for education administration business databases. Using the official FastMCP SDK, it exposes the "administration database (students / courses / grades / enrollments)" as a set of MCP tools, allowing LLM Agents to safely query business data while prohibiting all write operations from the protocol layer down to the database layer.

Unlike ChatGPT wrappers, generic MCP Servers, or pure RAG demos, this project focuses on the engineering pipeline of "safely opening business databases to Agents for reading" — a hardcore case of data security + MCP implementation.

Core Selling Points (Interview-Ready)

Related MCP server: sql-safety-executor

Tool List (MCP)

query demonstrates the "raw SQL gateway" capability; the rest are industry-specific secure wrapper functions for administration (fixed parameterized queries, safer and more business-aligned than raw SQL).

Quick Start

# 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

Example queries: student profile, CS205 course statistics, summary by term...

Testing

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

Directory Structure

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              # 工具行为用例

Design document → docs/DESIGN.md

Resume Description (Copy-Paste Ready)

Education Administration Read-Only Database Gateway MCP (FastMCP) Independently developed a secure read-only MCP Server for education administration databases. Designed a lightweight SQL read-only gateway: static validation that only allows SELECT/WITH to block DML/DDL and semicolon multi-statement injection, automatic row limiting when LIMIT is missing, parameterized queries for injection prevention, thread timeout protection, and SQLite mode=ro read-only fallback; provided table introspection and administration business wrapper tools with Token authentication and audit.log auditing. 22 unit tests cover security scenarios including write protection, injection, multi-statement, and truncation; end-to-end demo verifies write operations are blocked at the protocol layer.