Sentinel MCP 데이터 거버넌스 에이전트

Sentinel은 MCP(Model Context Protocol)를 통해 PostgreSQL 데이터베이스를 감사하는 소규모 자율 데이터 거버넌스 에이전트입니다. 이 프로젝트는 LLM에 직접적인 데이터베이스 액세스 권한을 부여하는 대신, 스키마 검사, null 프로파일링 및 이상 탐지를 위한 전용 도구가 포함된 제어된 FastMCP 브릿지를 노출합니다.

이 데모는 의도적으로 오염된 raw_inventory 테이블을 시드(seed)하고, OpenAI 기반 에이전트가 MCP 도구를 통해 이를 검사하도록 요청한 다음, Markdown 감사 보고서를 LATEST_AUDIT.md에 작성합니다.

데모 내용

ReAct 스타일의 추론(Reason) -> 행동(Act) -> 관찰(Observe) 워크플로우를 따르는 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")는 모든 컬럼에 대한 null 개수와 백분율을 반환합니다.

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;"

시드 후 예상 결과:

보안 참고 사항

.env는 Git에서 무시되며 절대 커밋해서는 안 됩니다.
.env.example에는 자리 표시자만 포함되어 있습니다.
LLM은 원시 데이터베이스 자격 증명을 직접 받지 않으며, 승인된 MCP 도구와 상호 작용합니다.
MCP 서버는 데이터베이스 기능이 명시적으로 노출되는 정책 경계입니다.
로그, 스크린샷, 터미널 출력 또는 채팅에 나타난 API 키는 즉시 교체하십시오.

에이전트에서 직접 SQLAlchemy를 사용하지 않고 MCP를 사용하는 이유

MCP는 LLM에 제한 없는 데이터베이스 액세스 권한 대신 제약이 있는 도구 인터페이스를 제공합니다. FastMCP 서버는 허용된 작업을 정의하여 거버넌스 경계를 명시적이고 감사 가능하게 만듭니다. 동일한 에이전트는 나중에 직접적인 데이터베이스 연결을 중심으로 에이전트를 다시 작성할 필요 없이 MCP를 통해 카탈로그, 정책 엔진, 웨어하우스 및 관측 가능성 시스템과 상호 운용할 수 있습니다.