Skip to main content
Glama
deenesjakoruzh
calvinchengx

data-agent-service

by calvinchengx
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Python
Hybrid

Data Agent Service

CI Docs release License: Apache 2.0

python coverage go coverage witnesses

데이터 웨어하우스에 영어로 질문하세요. 방어할 수 있는 답변을 얻으세요.

이미 보유한 웨어하우스, 데이터베이스, API — Fabric, Azure SQL, PostgreSQL, Databricks, 검색(retrieval) 서비스를 포함한 모든 REST 서비스 — 에 대해 자연어로 질문할 수 있으며, OpenMetadata에 저장된 용어집, 지표, 스키마를 기반으로 합니다. 각 쿼리는 두 번 승인됩니다. 먼저 서비스의 역할 규칙을 거친 다음, 호출자 본인의 자격 증명으로 소스 자체의 승인을 받습니다. 모든 MCP 클라이언트는 실제 Azure에 대해 변경 없이 작동합니다.

📖 문서 사이트 — 전체 참조 문서이며, docs/에서 Markdown으로도 열람할 수 있습니다.

왜 이 서비스가 필요한가

"어느 지원 팀이 티켓을 가장 빨리 해결할까?"라는 질문은 모두가 해결의 의미에 동의할 때만 올바른 답이 있습니다. 범용 SQL 에이전트를 웨어하우스에 연결하면 에이전트는 열 이름에서 그 의미를 유창하게 추론하며, 틀렸을 때 아무 경고도 하지 않습니다.

이 저장소의 자체 시드 데이터에서 그 추론은 잘못된 팀을 지목합니다. 실제 경과 시간(wall-clock)으로는 Frontline이 가장 빠르고 Billing이 가장 느립니다. 비즈니스의 실제 정의인 Resolution Time(고객을 기다리는 데 소요된 시간을 제외)은 그 결과를 뒤집어 Billing이 가장 빠릅니다. 잘못된 승자는 반올림 오류가 아니며, 답변 어디에도 그런 일이 발생했다는 표시가 없습니다.

이 서비스는 그런 종류의 오류가 단지 발생할 가능성이 낮은 것이 아니라 구조적으로 발생하기 어렵도록 설계되었습니다.

얻을 수 있는 것

방법

증명

의미는 모델이 아닌 카탈로그에서 나옵니다

용어집 항목, 지표 공식, 열 설명은 쿼리 시점에 OpenMetadata에서 읽어옵니다. 비즈니스 의미는 결코 프롬프트에 하드코딩되지 않습니다.

make eval — 카탈로그를 제외한 상태에서 동일한 질문을 평가하는 절제(ablation) 테스트

모든 답변은 질문한 사람의 자격으로 실행됩니다

사용자의 토큰은 엔진까지 사용자 대신(on-behalf-of) 방식으로 교환되므로 행·열 권한은 에이전트가 아닌 엔진이 결정합니다.

make test — 두 명의 페르소나, 동일한 질문, 다른 행

쓰기, 이탈, 거부 우회가 불가능합니다

패턴 매칭이 아닌 파싱된 단일 읽기 전용 SELECT, 스키마 허용 목록, 자동 적용되는 행 상한, 거부는 우회되지 않고 보고됩니다.

make conformance — 실행기가 충족해야 하는 28개 단언(assertion) 계약

추론 과정을 첨부하여 답변합니다

수치, 적용된 정의, 데이터가 나온 테이블, 카탈로그가 제기한 모든 주의사항

make ask Q="..."

맞춤 코드 없이 모든 MCP 클라이언트 지원

Claude, Cursor, VS Code 및 SDK는 OAuth 검색을 통해 표준 MCP로 연결됩니다.

docs/09-mcp-clients.md

노트북에서 실행되고, 변경 없이 실제 Azure에 배포됩니다

전체 스택은 에뮬레이터 제품군에서 실행되며, Fabric, APIM, Entra로 전환하는 것은 코드 경로가 아닌 구성 변경입니다.

docs/10-production.md

검증 수단 없이 주장되는 것은 없습니다

모든 기능에는 이를 증명하는 명령이 있으며, 설계만 되고 구현되지 않은 부분은 문서에 명시되어 있습니다.

모든 푸시마다 CI에서 실행되는 88개의 엔드투엔드 검증(witness)

상태: 0-16단계 완료 — docs/00-plan.md 참조.

Related MCP server: Interactive Database Analyst via MCP

빠른 시작

make doctor   # toolchain, docker, ~14 GB memory
make up       # entra, keyvault, arm, fabric (+ SQL Server), OpenMetadata 1.13.2, apim
make status   # "stack OK" is the verdict

그런 다음 make seed, make test, make eval, make load, make ask Q="…"를 실행하거나, CI가 실행하는 것과 동일하게 처음부터 전체를 기동하려면 make stack을 실행하세요.

구성 요소

경로

용도

docker-compose.yml

고정된 게시 이미지만 사용 — 종속성은 있는 그대로 사용

.env.example

모든 DAS_* 설정; .env(로컬) 또는 .env.prod(실제 Azure)로 복사

docs/00-plan.md

아키텍처, 결정 사항, 단계, 평가, 부하, 권한 부여, 확장

docs/

빠른 시작, 아키텍처, 권한 부여, 평가, 부하, MCP 클라이언트, 소스 추가, 프로덕션, CI

services/

웨어하우스 쿼리 실행기(Python 및 Go)와 양쪽이 따르는 계약

agent/, evals/, e2e/

에이전트, 정확도 테스트 스위트, 검증(witness)

seed/

데이터셋, 웨어하우스 프로비저닝, OpenMetadata 의미론, ID 설정

infra/terraform/

실제 Azure용 Terraform; docs/10-production.md가 런북

.github/workflows/ci.yml

4개 작업; 각 작업이 증명하는 내용은 docs/11-ci.md에 설명

website/

문서 사이트 — Astro + Starlight, docs/에서 생성되며 docs/가 진실의 원천(source of truth)

scripts/

doctor.sh, status.sh, check-discipline.sh, preflight.py

원칙

  1. 에뮬레이터와 OpenMetadata는 절대 수정하지 않습니다; 의심되는 버그는 docs/upstream-issues.md에 기록합니다.

  2. 에뮬레이터 전용 코드 경로는 없습니다. 표준 프로토콜만 사용합니다(OIDC/OAuth2(OBO 포함), 관리 ID App Service 프로토콜, TDS FedAuth, ARM, Graph, OM REST/MCP). ENV=prod는 .env만 교체하며 그 외에는 아무것도 변경하지 않습니다.

에뮬레이터 제품군

entra-emulator, azure-keyvault-emulator, arm-emulator, fabric-emulator, azure-apim-emulator 기반으로 구축되었으며, azure-emulators에 따라 구성됩니다. 계층: 리프(leaf).

라이선스

Apache-2.0.

This server cannot be deployed

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Maintenance

ActivityActive
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers

  • MCP-DB-Server

    sujalsamkaria0066
    F
    license
    Not graded
    quality
    D
    maintenance
    Enables natural language querying of SQL databases with robust safety guarantees including read-only enforcement, AST validation, and row caps.
    -

  • Interactive Database Analyst

    Viole07
    F
    license
    Not graded
    quality
    C
    maintenance
    Enables natural-language querying of PostgreSQL databases with schema grounding and self-correcting error recovery. Provides a live audit trace and verifies results through exploratory decomposition and empty-result sanity checks.
    -

  • Agent Harness Lab MCP Server

    ishanarya31
    F
    license
    Not graded
    quality
    C
    maintenance
    Provides a guarded semantic layer for text-to-SQL, offering tools for schema discovery, semantic profiling, and query verification to enable safe and reliable SQL generation on enterprise databases.
    -

  • Datum

    malharinamdar
    F
    license
    Not graded
    quality
    C
    maintenance
    Enables natural-language querying of SQLite databases through a governed semantic layer, with citations and typed abstention for PII or uncertified data.
    -