Sentinel MCP 数据治理代理

Sentinel 是一个小型自主数据治理代理，通过模型上下文协议 (MCP) 对 PostgreSQL 数据库进行审计。该项目没有直接给 LLM 提供数据库访问权限，而是通过一个受控的 FastMCP 网桥暴露了专门用于模式检查、空值分析和异常检测的工具。

该演示植入了一个故意存在脏数据的 raw_inventory 表，要求一个由 OpenAI 驱动的代理通过 MCP 工具对其进行检查，并将 Markdown 审计报告写入 LATEST_AUDIT.md。

它展示了什么

• 一个遵循 ReAct 风格（推理 -> 行动 -> 观察）工作流的 Python MCP 客户端。

• 一个充当代理与 PostgreSQL 之间治理网桥的 FastMCP 服务器。

• 用于安全、结构化数据库检查的 SQLAlchemy 后端工具。

• 针对缺失电子邮件、负库存计数和重复 SKU 的数据质量检查。

• 生成包含补救 SQL 的数据健康审计报告。

架构

flowchart LR
    U[User question] --> A[Python Agent<br/>MCP Client]
    A -->|tools/list and tools/call| M[FastMCP Server<br/>Sentinel-Bridge]
    M -->|SQLAlchemy queries| DB[(PostgreSQL 16<br/>raw_inventory)]
    DB -->|schema and quality metrics| M
    M -->|structured MCP tool results| A
    A -->|OpenAI analysis or local fallback| R[LATEST_AUDIT.md]

MCP 工具

inspect_schema() 返回用于结构审计的表名和列定义。

get_data_health_sample() 返回 raw_inventory 中 100 行最近的数据，用于行级审查。

check_null_ratios(table_name="raw_inventory") 返回每一列的空值计数和百分比。

find_logical_anomalies() 返回具有负 stock_count 值和重复 sku 组的行。

项目布局

agent.py              # MCP client and ReAct audit workflow
server.py             # FastMCP server exposing database audit tools
seed_data.py          # Faker-based dirty data generator
docker-compose.yml    # PostgreSQL 16 local database
architecture.md       # Mermaid architecture diagram
.env.example          # Safe environment variable template

设置

要求：

• Windows 11, macOS 或 Linux

• Docker Desktop

• 使用 uv 管理的 Python

• 具有可用 API 配额的 OpenAI API 密钥

创建您的本地环境文件：

Copy-Item .env.example .env

编辑 .env 并替换占位符值。请勿提交 .env。

安装依赖项：

uv sync

启动 PostgreSQL：

docker compose up -d

植入脏库存表：

uv run python seed_data.py

直接运行 MCP 服务器：

uv run python server.py

在另一个终端中，运行自主审计代理：

uv run python agent.py

代理将其报告写入：

LATEST_AUDIT.md

验证植入的数据

docker exec -it sentinel_postgres psql -U sentinel_user -d sentinel_db -c "SELECT COUNT(*) AS negative_stock_rows FROM raw_inventory WHERE stock_count < 0;"

植入后的预期结果：

30

安全说明

• .env 被 Git 忽略，绝不能提交。

• .env.example 仅包含占位符。

• LLM 不会直接接收原始数据库凭据；它与已批准的 MCP 工具进行交互。

• MCP 服务器是明确暴露数据库功能的策略边界。

• 轮换任何出现在日志、截图、终端输出或聊天记录中的 API 密钥。

为什么在代理中使用 MCP 而不是直接使用 SQLAlchemy？

MCP 为 LLM 提供了一个受限的工具接口，而不是不受限制的数据库访问。FastMCP 服务器定义了允许的操作，使治理边界变得明确且可审计。同一个代理以后可以通过 MCP 与目录、策略引擎、数据仓库和可观测性系统互操作，而无需围绕直接数据库连接重写代理。