一个模型上下文协议（MCP）服务器，能够自主扫描无文档记录的遗留数据库，为每张表生成 CRUD 工具，创建解释如何连接表的提示词，并通过将 LLM 限制为仅使用经过预验证的 SQL 模板来实施零知识安全。
Related MCP server: sqlite-mcp
MCP（模型上下文协议）是这里的传输和接口层——它负责处理 LLM 如何调用工具、传递参数以及接收结果。这是一个经过深思熟虑的选择，而非成就本身。
该项目真正的工程价值在于其底层的模式自省与安全流水线：
Database → PRAGMA Introspection → Schema Registry → Template Engine → Security Validator → MCP Tools每个阶段对下一阶段都一无所知。自省器对 MCP 一无所知。模板引擎对安全一无所知。CRUD 生成器对 SQL 一无所知——它只处理模板 ID。这种严格的分离意味着你可以将 MCP 传输层替换为 REST API 或 gRPC 服务，而无需改动安全层的任何一行代码。
选择 MCP 而非直接调用 OpenAI 函数，是因为 MCP 与传输层无关（本地使用 stdio，网络使用 SSE），支持超越原始工具调用的资源和提示词，并且是 LLM 工具生态系统中正在被广泛采用的开源标准。但安全层——预验证模板、纵深防御净化、不可变模板注册表——无论其前端使用何种协议，都以相同方式工作。
自主模式发现 — 使用 PRAGMA 自省扫描任何 SQLite 数据库，无需任何先验知识
动态 CRUD 工具 — 为发现的每张表自动生成 Create、Read、Update、Delete、List 和 Search 工具
连接提示词 — 分析外键关系并生成解释如何连接表的提示词
零知识安全 — 所有 SQL 执行均限制为经过预验证的参数化模板
审计日志 — 每次数据库操作均记录时间戳、模板 ID 和参数
模式资源 — MCP 资源公开已发现的模式供 LLM 参考
Python 3.10+
pip
# Clone the repository
git clone https://github.com/shubhtiwari65/Self-Documenting-Zero-Knowledge-MCP-Server.git
cd "MCP SERVER"
# Install dependencies
pip install -r requirements.txt
# Or install in editable mode with dev tools (recommended)
pip install -e ".[dev]"# Create a sample e-commerce legacy database
python server.py --seed这将创建包含 6 张表的 legacy_store.db：categories、customers、orders、order_items、products、reviews——包含完整的外键关系和示例数据。
# Run with stdio transport (default — for Claude Desktop)
python server.py
# Run with SSE transport (for network access)
python server.py --transport sse --port 8080
# Use a custom database
python server.py --db /path/to/your/database.db添加到你的 Claude Desktop 配置（claude_desktop_config.json）中：
{
"mcpServers": {
"zk-database": {
"command": "python",
"args": ["C:/path/to/MCP SERVER/server.py", "--db", "C:/path/to/legacy_store.db"]
}
}
}mcp dev server.py服务器启动时，会自省数据库并自动生成：
工具 | 描述 |
| 插入新行，附带自动生成的参数文档 |
| 按主键读取一行 |
| 按主键更新一行 |
| 按主键删除一行 |
| 带 limit/offset 的分页列表 |
| 跨文本列的全文搜索 |
提示词 | 描述 |
| 解释如何连接两张相关表 |
| 完整的数据库探索指南 |
| 完整的自动发现模式展示 |
资源 URI | 描述 |
| 完整模式概览 |
| 每张表的模式详情 |
| 最近的查询审计日志 |
| 安全摘要报告 |
| 所有已注册的 SQL 模板 |
零知识安全模型确保 LLM 永远不会构造或看到原始 SQL：
仅模板执行 — 只能执行来自预生成模板注册表的 SQL。不存在原始 SQL 端点。
参数验证 — 所有参数在执行前都会根据自省得到的模式进行类型检查。
输入净化 — 纵深防御黑名单可捕获参数值中的 SQL 注入模式（尽管参数化查询本身已能防止注入）。
审计追踪 — 每次操作都会记录时间戳、模板 ID、参数、成功/失败状态。
禁止模式操作 — 仅允许对现有表执行 SELECT、INSERT、UPDATE、DELETE。无法执行任何 DDL 操作。
完整安全模型（包括已知的范围边界，如传输层认证）请参阅 SECURITY.md。
本演示特意选择 SQLite，原因有三：
零配置 — 无需单独的服务器、凭据或网络配置；数据库就是一个文件
原生 PRAGMA 自省 — PRAGMA table_info()、PRAGMA foreign_key_list() 正是零知识发现所依赖的精确工具
仅标准库 — 无 ORM 依赖；import sqlite3 随 Python 自带
生产环境中会改变的内容：
关注点 | 当前（SQLite） | 生产路径 |
并发性 | 单写入者 | PostgreSQL + |
自省 | PRAGMA 语句 |
|
审计日志 | 内存列表 | 仅追加的数据库表或结构化 JSON 日志 |
数据库路径配置 | CLI 标志 |
|
迁移 | 重新填充 |
|
该架构在设计上与数据库无关——只有 src/introspector.py 包含 SQLite 特定代码（约 80 行）。更换底层数据库只需替换这一个文件；安全层、CRUD 生成器和 MCP 注册完全不受影响。
所有架构决策记录请参阅 docs/DECISIONS.md。
# Run all tests
python -m pytest
# Run with coverage report
python -m pytest --cov=src --cov-report=term-missing
# Run specific test files
python -m pytest tests/test_security.py -v
python -m pytest tests/test_introspector.py -vMCP SERVER/
├── .github/workflows/ci.yml # CI pipeline (pytest + ruff + coverage)
├── .gitignore # Git ignore rules
├── .env.example # Environment variable template
├── CHANGELOG.md # Version history
├── CONTRIBUTING.md # Dev setup and contribution guide
├── Makefile # Developer convenience commands
├── README.md # Project documentation
├── SECURITY.md # Security model + transport scope boundary
├── server.py # Main MCP server entry point
├── requirements.txt # Python dependencies
├── pyproject.toml # Project metadata, ruff + pytest + coverage config
├── src/
│ ├── __init__.py
│ ├── introspector.py # PRAGMA-based schema discovery
│ ├── schema_registry.py # In-memory schema registry
│ ├── sql_templates.py # Pre-validated SQL template engine
│ ├── security.py # Zero-Knowledge security validator
│ ├── crud_generator.py # Dynamic MCP tool generator
│ └── join_analyzer.py # FK analysis & prompt generator
├── sample_data/
│ └── seed_legacy_db.py # Demo legacy database seeder
├── tests/
│ ├── conftest.py # Shared pytest fixtures
│ ├── demo_client.py # Standalone verification demo
│ ├── test_introspector.py # Schema discovery tests
│ ├── test_crud.py # CRUD operation tests
│ ├── test_security.py # Security validation tests
│ └── test_joins.py # Join analysis tests
└── docs/
├── APPROACH.md # Full technical approach write-up
├── DECISIONS.md # Architectural Decision Records (ADRs)
└── MCP_architecture.png # Architecture diagramMIT
This server cannot be deployed
Text-to-SQL MCP server: read-only queries on PostgreSQL, MySQL and SQL Server with your real schema
Hosted SQL Server MCP server for Claude, ChatGPT and Cursor, with each action switched per account.
MCP server for secureFlows: token-free URL builders and integration-linting tools for AI agents.
