MCP 데이터 분석 에이전트

로컬 우선, 관리되는 SQLite 및 PostgreSQL 기반 MCP 클라이언트용 분석 환경입니다.

mcp-data-analysis-agent는 MCP 클라이언트에 직접 데이터베이스 접근 대신 작고 감사 가능한 데이터 접근 계층을 제공합니다. SQL 실행 전 검증, 읽기 전용 연결, 결과 및 실행 시간 제한, 영수증 기반 관찰 기록 작성, 자격 증명을 운영자 머신에 보관합니다.

존재 이유

MCP 클라이언트는 데이터를 추론할 수 있지만, 제한 없는 데이터베이스 자격 증명을 받거나 임의의 문을 조용히 실행해서는 안 됩니다. 이 프로젝트는 해당 경계에 대한 로컬 제어 지점을 제공합니다:

• 데이터베이스 경로, URL, 비밀번호, 토큰을 무시되는 .env 파일에 보관합니다.

• 단일 매개변수화된 SELECT 또는 WITH 문만 허용합니다.

• 변경, DDL, 명령, 첨부, 다중 문, 안전하지 않은 함수, 제한된 필드, 안전하지 않은 아티팩트 경로를 차단합니다.

• 애플리케이션 정책 외에도 데이터베이스 수준 읽기 전용 접근을 요구합니다.

• 정규화된 SQL, 타이밍, 작업 연결, 영수증, 해시, 이벤트 타임라인을 추후 감사를 위해 보존합니다.

서버는 stdio만 사용합니다. 공개 API를 호스팅하지 않으며, 소스 데이터를 업로드하지 않고, 원격 자격 증명을 저장하지 않으며, 프로덕션 데이터베이스 사용자를 생성하지 않습니다.

Related MCP server: sql-explorer-mcp

기능

• SQLAlchemy Core와 SQLGlot 정책 검증을 통한 SQLite 및 PostgreSQL 접근.

• 소스, 스키마, 관계, 프로필, 품질/신선도, 스키마 드리프트 탐색.

• 검증, 실행 계획 설명, 제한된 실행, 음수가 아닌 오프셋 페이지네이션, 취소, 시간 초과, 동시성 제한.

• 공개, 내부, 기밀, 제한된 필드/소스 분류.

• 승인된 의미론적 지표, Git 네이티브 레시피, 기간 비교, 변경 감지, 차트 추천.

• 오프라인 HTML 대시보드, CSV, Parquet, Typst PDF, 영수증 메타데이터, 안전한 원자적 출력 디렉터리.

• ClineFlow 컨텍스트 로딩, 작업 저널, 불변 쿼리/실행 기록, 이벤트 타임라인, 무결성 검증.

• 결정론적 소매, SaaS, 지원 픽스처(로컬 SQLite-to-PostgreSQL 패리티 픽스처 포함).

사전 요구 사항

• Python 3.11 이상 및 uv.

• 지원되는 보고서 렌더링 설치를 위한 Typst.

• 로컬 패리티 픽스처를 위한 createdb를 포함한 PostgreSQL 명령줄 도구.

• 대상 프로젝트의 정상적인 ClineFlow/OKF 번들.

mcp-data-cli preflight를 실행하여 사용 가능한 사용자 범위 패키지 관리자를 통해 필요한 로컬 도구를 설치하거나 보고합니다. 구성된 소스에 절대 접촉하지 않습니다. mcp-data-cli doctor는 로컬 설치를 검증합니다. 구성된 소스가 없으면 설치 실패가 아닌 configuration_pending으로 보고됩니다.

설치

현재 프로젝트에 이 저장소 설치

에이전트나 운영자가 이 GitHub 저장소를 프로젝트에 설치하도록 요청받은 경우, 단순한 uv tool install 명령이 아닌 저장소 설치 프로그램을 사용하세요:

cd /path/to/your-project
curl -fsSL https://raw.githubusercontent.com/hassanvfx/mcp-data-analysis-agent/main/install.sh | bash

설치 프로그램은 명령줄 도구를 설치하고 실행된 디렉터리를 초기화합니다. 무시되는 결정론적 소매 플레이그라운드를 생성하고, 단일 비공개 MCP_DATA_SOURCE_URL 값을 .env에 작성하고, 소스 정책을 작성하고, 감지된 모든 지원 클라이언트에 MCP 서버를 병합합니다. 패키지를 프로젝트에 복사하지 않으며, 데이터베이스 URL이나 자격 증명을 클라이언트 구성에 절대 넣지 않습니다. 클라이언트 신뢰/활성화 및 재시작 프롬프트는 각 클라이언트 애플리케이션의 제어 하에 유지됩니다.

uv tool install은 의도적으로 사용자 수준 실행 파일을 설치하며 프로젝트를 변경하는 사후 설치 훅을 실행하지 않습니다. 실행 파일을 별도로 설치하려는 경우에만 사용하고, 그런 다음 직접 mcp-data-cli init을 실행하세요.

PyPI 호환 워크플로

uv tool install mcp-data-analysis-agent
cd /path/to/your-project
mcp-data-cli preflight
mcp-data-cli init
mcp-data-cli doctor

패키지 릴리스 전에 현재 저장소 버전을 설치하려면 설치 명령을 다음으로 대체하세요:

uv tool install git+https://github.com/hassanvfx/mcp-data-analysis-agent.git

지원되는 MCP 클라이언트에서 서버를 처음 사용하면 에이전트가 .mcp-data/playground.sqlite에 결정론적 개발 전용 소매 SQLite 플레이그라운드를 생성하고 엽니다. 공유 MCP welcome 도구는 탐색 방법과 실제 소스로 전환하는 방법을 설명합니다. init은 동일한 플레이그라운드를 명시적 프로젝트 정책과 비공개 .env에 구체화한 다음, 한 번의 확인 후 안전한 MCP 클라이언트 항목을 병합합니다. 명시적 저장소 설치 프로그램은 init --yes를 사용합니다. 해당 설치 프로그램을 실행하는 것이 이러한 범위 지정 쓰기에 대한 단일 권한이기 때문입니다.

클라이언트 구성만 미리 보려면 setup --all을 사용하고, 한 번의 명시적 확인 후 mcp-data-analysis stdio 항목만 병합하려면 setup --all --apply를 사용하세요. 관련 없는 서버와 설정은 보존합니다. 감지 및 현재 구성 상태를 검사하려면 setup --status를 사용하세요.

설정은 MCP 정의만 구성합니다. 클라이언트의 신뢰/활성화 프롬프트를 우회하거나 IDE를 시작/재시작할 수 없습니다. VS Code 구성 세부 사항은 VS Code 및 VS Code의 GitHub Copilot에 문서화되어 있습니다. Continue는 MCP 가이드에서 프로젝트 MCP 프래그먼트를 문서화합니다.

체크섬 검증 릴리스 부트스트랩

버전이 지정된 휠과 게시된 SHA-256 체크섬의 경우:

MCP_DATA_RELEASE_URL='https://example.invalid/mcp_data_analysis_agent-0.1.0-py3-none-any.whl' \
MCP_DATA_RELEASE_SHA256='published-sha256' \
./install.sh

부트스트랩은 curl과 uv를 요구하며, sha256sum 또는 shasum으로 아티팩트를 검증하고 체크섬이 일치한 후에만 설치합니다. 그런 다음 저장소 설치 프로그램과 정확히 동일하게 현재 프로젝트를 초기화합니다. sudo를 사용하지 않으며 프로덕션 데이터베이스에 접촉하지 않습니다. 로컬 결정론적 데모 데이터만 생성합니다.

활성 소스 하나 구성

표준 설치는 정확히 하나의 활성 소스(data라는 이름)와 .env의 정확히 하나의 비공개 값(MCP_DATA_SOURCE_URL)을 사용합니다. 이는 패키지 상수나 테스트 값이 아닙니다. 운영자가 자신의 읽기 전용 데이터베이스를 가리키도록 변경하는 유일한 값입니다. .env를 비공개로 유지하세요. Git에서 무시됩니다.

첫 사용 시 data는 자동으로 생성된 소매 플레이그라운드를 가리킵니다. 프로젝트 .env에서 해당 선택을 구체화할 준비가 되면 mcp-data-cli init을 실행하세요. 다음을 작성합니다:

MCP_DATA_SOURCE_URL='/absolute/path/to/your-project/.mcp-data/playground.sqlite'

플레이그라운드는 개발 전용 합성 데이터입니다. 새 설치가 스키마 탐색, 관리되는 쿼리, 영수증, 보고서를 즉시 실행할 수 있게 합니다. 프로덕션 데이터가 아니며 이후 init 실행으로 덮어쓰지 않습니다. 모든 지원 클라이언트는 동일한 stdio 서버 환영 지침과 welcome MCP 도구를 받습니다.

# .mcp-data-agent.toml
[agent]
default_row_limit = 500
max_row_limit = 5000
query_timeout_seconds = 30

# The database dialect is inferred from MCP_DATA_SOURCE_URL.
[source]
env = "MCP_DATA_SOURCE_URL"
allowed_schemas = ["analytics"]
classification = "internal"

[classification.columns]
email = "restricted"

# .env — never commit this file. Change this single value for your own source.
MCP_DATA_SOURCE_URL='postgresql://readonly_user:password@localhost:5432/analytics'

SQLite의 경우 동일한 단일 변수를 절대 파일 경로 또는 SQLite URL로 만드세요. PostgreSQL의 경우 postgres:// 또는 postgresql:// URL을 사용하세요. 수동 방언 설정이 필요 없습니다:

MCP_DATA_SOURCE_URL=/absolute/path/to/your.sqlite
# or: MCP_DATA_SOURCE_URL='postgresql://readonly_user:password@localhost:5432/analytics'

CLI 호출에서 소스 인수로 data를 사용하세요(예: mcp-data-cli schema data). 에이전트는 지원되지 않는 URL 체계, 상대 SQLite 경로, URL과 충돌하는 레거시 선언 방언을 거부합니다. 기존 다중 소스 정책은 읽을 수 있지만 init은 의도적으로 다시 쓰기를 거부합니다. 수동으로 마이그레이션하거나 새 단순화된 프로젝트를 시작하세요.

PostgreSQL의 경우 쓰기 또는 DDL 권한이 없는 전용 최소 권한 계정을 사용하세요. 에이전트는 또한 읽기 전용 세션을 활성화하고 구성된 스키마 검색 경로를 적용하지만, 데이터베이스 측 접근 제어는 필수입니다.

일반적인 워크플로

실행 전에 검증한 다음 계획을 검사하고 제한된 쿼리를 실행하세요:

mcp-data-cli sql data 'SELECT id, name, stock FROM products WHERE id = :id' --params '{"id": 1}'
mcp-data-cli explain data 'SELECT id, name, stock FROM products WHERE id = :id' --params '{"id": 1}'
mcp-data-cli query data 'SELECT id, name, stock FROM products ORDER BY id' --limit 25 --offset 0

여러 작업이 하나의 분석에 속할 때 명시적 작업을 생성하세요:

mcp-data-cli task-begin 'Inventory review' 'Identify stockout risk.'
mcp-data-cli observe <task-id>
mcp-data-cli task-complete <task-id> 'Findings recorded.'
mcp-data-cli evaluate-task <task-id>

호출자가 선택한 새 디렉터리에 보고서를 생성하세요. 기존 디렉터리와 심볼릭 링크 탐색은 거부됩니다.

mcp-data-cli report data 'SELECT id, name, stock FROM products' outputs/inventory --pdf --parquet

각 보고서에는 오프라인 HTML, CSV, 선택적 Parquet/PDF 아티팩트, 영수증 메타데이터, 경로, 콘텐츠 해시가 포함됩니다. 생성된 아티팩트, 소스, 자격 증명은 커밋해서는 안 됩니다.

개발 픽스처 및 PostgreSQL 패리티

init은 위에서 설명한 작은 소매 플레이그라운드만 생성합니다. 기여자는 추가 결정론적 합성 픽스처를 명시적으로 생성할 수 있습니다:

mcp-data-cli dataset retail /tmp/retail.sqlite --tier unit --seed 1
mcp-data-cli dataset-postgres retail mcp_data_parity --tier unit --seed 1
# Seed an already-created disposable test database; creates only mcp_seed_<domain>.
MCP_DATA_TEST_POSTGRES_URL='postgresql://mcp_data_test@localhost:5432/mcp_data_parity' \
  mcp-data-cli seed-postgres retail --seed 1

dataset-postgres는 로컬 createdb를 사용하고, 기존 데이터베이스 이름을 거부하며, SQLite 데이터를 임시 디렉터리에만 생성한 다음 mcp_parity 스키마 아래의 새 PostgreSQL 데이터베이스에 복사합니다. 수동으로 제공된 일회용 PostgreSQL URL이 필요하지 않습니다.

seed-postgres는 이미 프로비저닝된 격리된 테스트 데이터베이스를 위한 것입니다. 환경에서 비공개 테스트 URL을 읽고 예약된 mcp_seed_retail, mcp_seed_saas 또는 mcp_seed_support 스키마만 대체합니다. 공개/애플리케이션 스키마에는 절대 접촉하지 않습니다.

어댑터 동작을 개발할 때 격리된 PostgreSQL 인스턴스로 전체 로컬 품질 스위트를 실행하세요. CI는 린팅, 타입 검사, 테스트, 커버리지 게이트, 실제 Typst 렌더링, SQLite/PostgreSQL 패리티, 비밀 스캐닝, 의존성 감사, SBOM 생성, 신뢰된 게시 릴리스 자동화를 다룹니다.

uv run ruff check src tests scripts
uv run mypy src
uv run pytest --cov=mcp_data_agent --cov-branch
uv run python scripts/check_coverage.py coverage.json
./validate-okf

안전에 중요한 구성, 컨텍스트, 원장, SQL 정책 모듈은 100% 라인 및 분기 커버리지를 요구합니다. 전체 게이트는 최소 90% 라인 커버리지와 85% 분기 커버리지를 요구합니다.

보안 및 운영 계약

• 쿼리는 매개변수화되어야 하며 데이터베이스 연결/실행 전에 검증됩니다.

• 결과 제한과 오프셋은 프로젝트 정책에 의해 관리됩니다. 호출자 SQL이 이를 우회할 수 없습니다.

• 제한된 열은 실행 전에 거부되고 비밀 유사 매개변수는 관찰 기록에서 수정됩니다.

• 작업 저널, 쿼리 영수증, 실행, 이벤트는 knowledge/ 및 observability/ 아래에 저장됩니다. 데이터베이스 URL, 원시 비밀, 소스 데이터베이스, 결과 캐시, 보고서 바이너리는 제외됩니다.

• 로컬 합성 데이터셋은 개발 인프라 전용이며 프로덕션 온보딩이 아닙니다.

전체 운영 및 공개 계약은 운영 가이드, 보안 정책, MIT 라이선스를 참조하세요.

기여 및 릴리스

집중된 커밋을 사용하고 주석이 달린 checkpoint-* 태그를 보존하세요. 이는 전달 마일스톤에 대한 명시적 롤백 지점입니다. 활성 ClineFlow 엔지니어링 저널과 지식 로그를 중요한 변경 사항으로 업데이트하고, OKF 검증을 실행한 다음 구현과 지식 증거를 함께 커밋하세요.

GitHub Actions는 릴리스 게시 시 배포를 빌드하고 검증합니다. 릴리스 엔드포인트와 게시 자격 증명은 저장소 구성입니다. 이 코드베이스에 절대 저장되지 않습니다.